Code Refactor｜代码重构技能

先建立行为基线，再做最小结构变更；未经验证不得宣称行为保持。

• 标识：code-refactor
• 版本：0.1.0
• 分类：development
• 作者：Keying Dev
• 类型：Agent Skill（指令与工作流定义，不自动授予工具权限）

1. 目标与交付

面向代码结构改进和技术债治理的重构技能，通过行为基线、影响分析、小步变更和回归验证降低维护成本，并明确区分重构与功能变更。

以可核验信息支持工程决策。证据不足时明确保留未知；工具未执行时不能描述为已执行。

2. 适用场景

• 保持功能不变，拆分这个过长的函数。
• 清理重复代码并改善可维护性。
• 整理模块边界，控制重构风险。
• 为遗留模块制定分阶段重构计划。

3. 不适用及与其他 Skill 的边界

• 需要新增用户可见功能 → 实现任务。
• 故障根因尚不清楚 → bug-investigator。
• 只需指出代码问题，不需修改 → code-reviewer。
• 主要是宏观架构选型评估 → architecture-reviewer。

4. 工作模式与权限

• 分析模式（默认）：读取、检索、规划、给出建议；不自动修改源文件、配置、锁文件或远端系统。
• 执行模式：仅在用户请求且工具权限、环境隔离、安全评估通过后执行必要操作；仍遵循最小副作用原则。
• 强只读模式：用户说“只分析/不要修改”时，任何写入、安装、格式化、部署或提交都禁止。
• 未知环境：没有权限、没有工具或证据不足时说明限制并输出可执行的下一步，不臆造结果。

5. 标准工作流

5.1 定义重构契约

明确哪些可观察行为必须保持：输入输出、异常、API/ABI、持久化格式、权限、时间敏感行为和性能约束。

5.2 定位重构目标

基于具体异味和证据，例如重复逻辑、循环依赖、过大职责；记录范围和不包含的模块。

5.3 建立行为基线

检查已有测试、接口契约和关键边界；无法覆盖时优先建议特征测试（characterization test），未执行则不能声称基线已验证。

5.4 规划小步变更

按依赖顺序列出可独立回滚的变更步骤，每步配套验证与回退方案；避免无关格式化。

5.5 执行受控重构

用户授权修改后才编辑；不改公共接口或数据迁移语义，除非明确批准并单独标记行为变更。

5.6 验证差异

查看 diff，执行相关测试（如安全可用），比较关键输入输出和失败路径；无法验证则列为残余风险。

5.7 交付变更说明

说明改动文件、预期收益、验证结果、兼容性风险、未验证项及回滚点。

6. 安全和证据约束

• 默认分析/规划优先；修改代码必须符合用户明确任务及环境授权。
• 严禁把新增功能、修复 Bug、格式迁移悄悄混进“纯重构”。
• 禁止未经授权的大规模依赖升级、数据库迁移、删除数据及生产发布。
• 重构前后测试均须真实执行才能声称已验证；失败时优先隔离变更。
• 用户明确只读时不得修改任何文件，亦不得自动格式化。

7. 事实、推断与结果标注

• Verified：有直接代码、配置、工具输出或可复现验证支持；写明来源、范围与时间。
• Likely：多条证据支持但尚缺关键验证；须标注缺口。
• Needs Verification：合理怀疑，缺乏核验；不得作为既成事实。
• Unknown：证据不足或不可访问；说明所需信息。

不得以模型推理取代真实测试、测量、漏洞公告或运行结果。引用文件时尽量标注路径与行号；引用命令时记录退出码与环境。

8. 默认输出格式

重构目标/动机：
行为保持契约：
当前结构问题及证据：
影响范围与依赖：
前置测试基线（已执行/未执行）：
分步重构计划及回滚点：
实际代码变更（如获授权）：
验证证据/兼容性结论：
剩余风险：

如果不存在明确发现，报告“本次范围内未发现足够证据支持的重大问题”，不得暗示全局零风险。

9. 结束与移交

• 已形成与证据匹配的结论，且风险和未验证事项清楚；或
• 剩余验证需额外权限、环境、用户输入，继续操作风险高；或
• 当前范围已经覆盖，继续扩展无法明显提高结论质量。

与其他 Skill 协作时只传递任务相关的证据、范围及未解决问题，不自动启动无关全仓库扫描。

10. 参考资料

详见 references/guide.md；评估设计见 ANALYSIS_REPORT.md。本文件的权限与证据约束优先于补充指南。