implement-small-change

实现小型变更

采用能够证明所请求行为、同时不掩盖风险的最小工作流。

1. 确定边界

编辑前：

1. 阅读适用的仓库说明，并检查当前 Git 状态和差异。保留与本次任务无关的用户更改。
2. 用一句话说明所请求的可观察结果，并确定能够证明该结果的最小检查。
3. 先了解仓库，再判断变更是否小型。优先使用用户当前可用的本地 MCP 或其他仓库感知工具，而不是 Agent 内置的文件搜索工具：
   • 如果有代码库知识图谱 MCP，先使用它。如果仓库尚未编入索引，则先完成该工具要求的索引或设置，再进行查询；随后优先使用其图搜索、依赖项或调用方追踪、针对性代码检索，以及架构或关系查询，确定受影响的符号和影响范围。
   • 如果有其他本地仓库感知 MCP 或仓库导航工具，则在使用 rg、glob 或广泛读取文件之前先使用它。
   • 仅当没有合适的 MCP／仓库感知工具，或者这些工具返回的结果不足、过时或不适用时，才回退到 Agent 内置工具。当代码图谱未建模字符串字面值、配置、脚本及其他非代码文件时，仍适合使用内置搜索。
   • 遵循仓库特定的发现说明，并采用最可靠的证据来源；不要因为文档提到某个工具，就假定该工具可用。
4. 找出涉及的确切符号或配置。使用选定的发现工具检查相关调用方、被调用方、测试、契约和运行时路径。
5. 对语义影响分类。不要仅按文件数量分类：一行共享契约的更改可能影响广泛，而多个相邻文件的修改也可能仍属于一项局部更改。

不要询问用户那些可以从仓库、运行时、日志或工具中查明的信息。

2. 执行范围门槛检查

只有以下条件全部满足时，才继续走快速流程：

• 请求只涉及一种明确行为，且预期结果没有歧义。
• 已了解受影响的调用方和下游行为。
• 更改仅限于一个模块或既定边界。
• 有针对性的检查能够发现所请求的行为或原始错误。
• 更改易于回退，且不会造成破坏性或外部状态更改。
• 不触发以下任何硬性停止条件。

以下任一情况都视为硬性停止条件：

• 更改跨越展示层、API、领域层、持久化层或基础设施层，并且需要作出新的决策。
• 更改公共 API、序列化结构、事件、共享契约、数据库架构、迁移或兼容性承诺。
• 涉及身份验证、授权、安全、隐私、支付、事务、并发、缓存失效或分布式工作流。
• 引入或更改领域术语、状态转换、不变量、所有权规则或架构边界。
• 存在多种合理解释，且会导致不同的用户可见行为。
• 共享工具或核心路径的调用方较多，无法快速界定影响范围。
• 现有系统没有可靠的边界或信号来验证更改。

当硬性停止条件暴露出尚未解决的决策或跨层行为时：

1. 明确告知用户，$implement-small-change 因请求存在隐藏范围而暂停。
2. 撰写简洁的影响说明，其中包含所请求的结果、发现的符号和调用方、受影响的层或契约、合理的不同解释，以及必须解决的决策。
3. 请用户参考该说明解决这些决策，例如使用其采用的需求澄清或规划技能，然后结束本技能的工作流。

如果问题难以复现，或原因仍不确定，而非仅存在歧义，则移交给 $diagnosing-bugs。

3. 做出最小且完整的改动

• 修复 bug 时，只要实际可行，就在编辑前针对原始症状运行专项检查。优先使用快速、确定且能复现失败的测试。
• 调整或添加小功能时，通过现有接口实现一个最小的垂直切片。
• 如果现有的合理切入点能够以较低成本表达该行为，就添加回归测试。不要创建测试框架、模拟内部实现，也不要仅为满足流程而添加浅层测试。
• 避免顺带重构、推测性抽象、格式改动、依赖升级和无关清理。
• 除非请求的结果明确要求更改，否则保留现有公共接口和领域用语。
• 如果新证据扩大了影响范围，暂停并重新执行范围检查。

4. 按比例进行验证

运行能够发现本次改动错误的最小检查集：

• 重新运行精确的 bug 复现步骤或行为检查。
• 运行范围最窄的相关测试文件、筛选测试、解析器、代码检查器、类型检查、构建目标、API 请求或 UI 交互。
• 如果编译结果或静态契约发生变化，则添加受影响项目或软件包的构建检查。
• 检查最终差异和状态，确认没有意外编辑、调试插桩、契约偏移或新发现的阻碍。

默认不要运行完整测试套件或调用正式的 $code-review。只有仓库说明要求、用户明确请求、专项检查证据不足，或范围检查证明改动并非真正的小改动时，才使用它们。

除非用户或适用的仓库工作流要求，否则不要提交或推送。

5. 报告证据

报告以下内容：

• 可观察到的结果。
• 如果已查明 bug 的根因，则报告根因。
• 已更改的文件或符号。
• 执行的确切验证命令或交互，以及其结果。
• 有意未运行的更广泛检查，以及专项证据为何足够。

绝不要仅仅因为差异很小，就声称改动是安全的。