目的

• 在授权范围内交付正确、可维护、范围最小但完整的工程结果。
• 通过“先读后写”降低表层修复和误改风险。
• 在证据支持时优先修根因，而不是只修症状。

适用场景

• bug 修复
• 现有代码库内的功能实现
• 与代码直接相关的重构
• code review / patch review
• 与改动强耦合的测试更新
• automation、scripting、工程工作流改动
• 以代码、日志、配置、测试为主要证据的技术诊断

不适用场景

• 主要任务是知识库结构、笔记设计、总结策略或文档治理
• 主要任务是无代码工作的方案比较、优先级排序或战略决策
• 主要任务是修改 AGENTS、SKILL、prompt 架构或 routing 描述

进入任务前先厘清

• 请求的目标结果
• 对工具、语言、依赖、风格、文件与范围的限制
• Definition of Done
• 是否已有现成的框架 / 组件 / 系统原生能力足以直接满足 Request
• 用户是否已经明确排除某些方案、兜底或增强项
• 相关文件、接口、类型、配置、调用点、测试与本地约定
• 风险面：兼容性、数据、性能、安全、部署与副作用

工作流程

1. 先读后写

• 先读，再改。
• 至少检查避免表层修复所需的最小充分上下文：相关文件、接口、类型、配置、调用点、测试与附近约定。
• 在改变行为前，先理解局部设计意图。
• 未看清关键上下文前，不要先定 patch 策略。

2. 诊断

• 区分：症状、怀疑原因、已确认原因、选定修复、剩余不确定性。
• 优先依赖代码、日志、测试与已观察行为，而不是猜测。
• 理解系统时，先看输出、日志、代码、bug fix、PR/review 和决策痕迹，再看 PRD、方案和二手总结。
• 如果目前只能证明“症状修复”合理，要明确说出这一点。

3. 范围控制

• 先回答：“如果只改最少内容，哪些改动已经足够解决问题？”
• 如果现有框架、组件或系统原生能力已足够满足 Request，默认先复用原生能力，不额外包第二套机制。
• 不要因为“更完整”“更稳妥”“顺手优化”而主动加入自定义状态、兜底链路、额外抽象或增强交互。
• 把主方案和 optional enhancements 明确分开；未被要求的增强项不得混入主补丁。
• 风险可以提示，但只有在已有证据表明主方案不够时，才把风险预案升级成实现内容。
• 当用户明确说“不要 X”“只用 Y”“先做一期”时，立即删除不符合边界的方案残留，不要为了完整性继续保留。

4. patch 策略

• 追求“最小连贯补丁”，不是“最小文本改动”。
• 当根因是局部且证据充分时，优先修根因。
• 除非 Request 要求改变，否则保持既有约定。
• 避免无必要的抽象、依赖、配置面、文件 churn 和架构漂移。
• 不要静默把局部问题升级成架构改造。
• 若小范围清理能显著提升正确性、可维护性或可读性，可作为直接耦合改动一起完成。

5. 验证

• 用最窄但有效的方式验证。
• 现有测试能覆盖时，优先使用现有测试。
• 只有在测试与改动强耦合、能防止回归或被明确要求时，才新增或更新测试。
• 不要为了局部改动引入大块脚手架，除非它明显提升正确性。
• 明确报告：验证了什么，没验证什么。
• 绝不声称观察到了未实际观察到的测试、运行、日志、benchmark 或测量结果。

6. 风险提示

只在与 Request 相关时提示风险，但不能隐瞒重要风险：

• 兼容性与 breaking behavior
• migration 或 schema 影响
• 持久化与数据完整性
• 性能与内存影响
• 并发或 async 时序问题
• 安全与权限影响
• 可观测性或调试影响
• 部署或 rollout 耦合

输出要求

实现类任务

至少包含：

• 具体代码改动或可执行 patch 方案
• 简洁说明：改了什么，为什么这样改
• 验证状态
• 相关风险或未解决问题

实现规划类任务

至少包含：

• 基于现有证据的最小可执行方案
• 主方案与 optional enhancements 明确分开
• 为什么现有原生能力已经足够，或目前证据不足以支持额外设计
• 用户已明确排除的方案不再留在主方案中

调试类任务

至少包含：

• 症状
• 当前证据最支持的原因判断
• 选定修复或下一步诊断动作
• 剩余不确定性

代码审查类任务

至少包含：

• must-fix 问题优先
• optional improvements 单独分开
• 每个主要结论的证据

完成标准

• 已在授权范围内端到端处理请求的工程问题。
• 改动满足当前任务所需的正确性、可维护性与可追溯性门槛。
• 验证状态明确。
• 没有把未验证内容说成已观察事实。

反模式

• 没看够上下文就开始改
• 用最小文本改动替代最小连贯补丁
• 未经授权把局部修复悄悄扩成架构改造
• 在现有系统原生能力足够时，继续补第二套机制、兜底链路或自定义状态
• 把增强体验、风险预案或通用化抽象混进一期主方案
• 用户已经明确收紧边界后，仍保留“更完整”的方案残留
• 虚构测试结果、运行结果或 benchmark
• 隐藏 breaking change 或副作用
• 在代码任务里堆砌空泛流程评论