duck-patch

补丁执行 🦆。优先采用最小且安全的差异。

用途

在修复方向明确后，执行范围严格限定的代码更改。

理念护栏（技能级）

继承 references/GUARDRAILS.md 中的共享护栏。

注释和文档完整性

• 记录持久的约束、不变量、契约和行为。
• 不要在代码注释或常规文档中叙述开发历史。
• 移除或标记被否决的方案、“过去是这样”的历史、近期更改背景，以及仅用于解释更改如何产生的评审、测试或会话引用。
• 不要在持久性产物中保留仅属于会话的决策、审批标记或临时标记。
• 仅在 ADR 或变更日志等用于记录历史的持久性产物中保留历史背景。
• 仅当测试或评审引用说明持久约束或验证要求时才予以保留。

技能特定补充：

• 仅执行范围明确的实现；产品和架构决策仍由用户负责。

启用条件

当用户要求进行有针对性的代码编辑，且范围明确（或能快速澄清）时使用。

方法

子 Agent 执行模式

在没有用户频道的情况下作为子 Agent 运行时（例如通过 duckling）：不要应用编辑或运行命令。通过分析执行范围澄清、Duck Ladder 和补丁推导；将“应用最小安全差异”和“运行最小范围的约定检查”替换为审批材料，其中包含按文件整理的差异块和验证计划。按照宿主包装器的契约输出（预检 + 差异 + 审批请求 + 状态页脚）。

1. 澄清范围（如不完整）

• 当上下文不完整时，提出 1～3 个有针对性的澄清问题
• 缺少证据时，明确说明假设

变更操作门槛： 工作区变更操作（根据变更类型需要审批）：

语义变更（需要完整执行审批）：

• 代码/逻辑更改
• 文档/规划更改（README、Markdown 文档、ADR、CONTEXT.md、运行手册、设计说明；非代码文本文件中的纯错别字修复除外）
• 配置/架构更改（设置、环境变量、构建配置）
• 依赖项更改（package.json、requirements.txt 等）
• 文件操作（创建、删除、移动）
• 变更性命令（git commit、install、build、deploy）
• 委派实现/补丁任务

外观更改（需要轻量确认）：

• 仅格式/空白字符更改
• 非代码文本文件中的错别字修复
• 确认语句：“确认继续进行[格式更改/错别字修复]？”

边缘情况：

• 代码文件中的 JSDoc/docstring 更改属于语义更改（会影响生成的文档和代码契约）
• 解释代码逻辑的注释属于语义更改（会影响对代码可维护性的理解）
• 配置注释属于语义更改（会影响内容解读）
• 文档更新（ADR、CONTEXT.md）属于语义更改
• README 中的代码示例属于语义更改（用户会复制粘贴）

审批流程： 进行任何语义更改之前，必须获得执行审批：

1. 预检（每次请求批准时都必须提供；如果缺少任何字段，请提出一个澄清问题）：
   • 目标阶段：
     • Phase 1：存根／骨架／接口
     • Phase 2：连接／集成
     • Phase 3：具体实现
   • 阶段适配说明（解释此差异为何符合阶段限制）
   • 目标文件（限定在所选阶段的范围内）
   • 预期行为变更
   • 最小验证检查
2. 按文件列出变更，并以格式化差异呈现
   • 文件已存在：统一差异格式（---/+++/@@ 区块，使用 -/+ 前缀）
   • 文件不存在：在围栏代码块中提供完整内容，并以文件路径作为标题
   • 每个差异块只包含一个文件
   • 在差异区块上方添加内联注释，说明每项变更
   • 如果任何文件违反阶段限制，请拆分提案，并在请求批准前重新提出
3. 请求批准：批准此范围吗？（例如：approve/ok/confirm）
4. 等待批准：在用户明确表示批准之前，不得继续编辑、运行命令或委派任务

规则：

• 未经用户批准／确认，不得执行任何会更改工作区的操作 批准意向词：

• 接受以下内容作为批准意向："approve"、"approved"、"ok"、"go ahead"、"confirm"、"yes"

• 也接受明确引用选项的批准句子："Proceed with option B in files X and Y."、"Approved. Run verification plan as proposed."

• 示例并非穷举。任何清楚表达批准意向的内容都可接受。

• 不要将非批准式的继续信号视为批准：单独的 "continue"、选项字母（"B"）、"next"。没有批准动词，也未提及范围，不算批准。

范围规则：

• 阶段上限（默认值）：

  • Phase 1（存根／骨架／接口）：最多 6 个文件
  • Phase 2（连接／集成）：最多 4 个文件
  • Phase 3（具体实现）：最多 2 个文件

• 阶段内容限制（硬性门槛）：

  • Phase 1（存根／骨架／接口）只能包含：
    • 文件／模块骨架结构（文件夹、导出、章节布局）
    • 类型／接口声明
    • 函数／类签名
    • 占位返回值／错误／TODO 标记
    • 不包含业务逻辑的最简无操作连接
  • Phase 1 不得包含：
    • 完整功能／业务逻辑
    • 有副作用的流程（数据库／网络／身份验证／文件写入）
    • 超出占位内容的完整 UI 行为
  • Phase 2（连接／集成）可以包含：
    • 路由注册、DI／容器连接、模块组合、事件挂接
    • 现有组件之间的适配胶水代码
  • Phase 2 不得包含：
    • 大量新增业务逻辑代码块
  • Phase 3（具体实现）包含：
    • 业务逻辑、算法、副作用、完整行为实现

• 新文件引导规则：

  • 如果范围涉及新增功能文件，首次审批必须仅包含 Phase 1 的存根／骨架／接口。
  • 在后续 Phase 2/3 审批中实现函数体。
  • 如果新文件超出存根／骨架的意图，先将该文件拆分为存根，再在后续审批中实现。

• 如果某个阶段超出其上限，执行前应拆分为更小、范围明确的审批。

• 审查疲劳触发条件（客观标准）：

  • Phase 1（存根／骨架／接口）：
    • 如果单次审批中拟议的差异超过 180 行变更（新增行数 + 删除行数），则当前阶段上限至少减少 1 个文件（最少上限为 1 个文件）。
    • 如果任何单个文件超过 90 行变更（新增行数 + 删除行数），则将该文件拆分为单独审批，或拆分为更小的连续编辑。
  • Phase 2（接线／集成）：
    • 如果单次审批中拟议的差异超过 120 行变更（新增行数 + 删除行数），则当前阶段上限至少减少 1 个文件（最少上限为 1 个文件）。
    • 如果任何单个文件超过 60 行变更（新增行数 + 删除行数），则将该文件拆分为单独审批，或拆分为更小的连续编辑。
  • Phase 3（具体实现）：
    • 如果单次审批中拟议的差异超过 80 行变更（新增行数 + 删除行数），则当前阶段上限至少减少 1 个文件（最少上限为 1 个文件）。
    • 如果任何单个文件超过 40 行变更（新增行数 + 删除行数），则将该文件拆分为单独审批，或拆分为更小的连续编辑。
  • 如果审查者在同一批次中对超过 2 个文件要求澄清，则下一批次至少减少 1 个文件。

• 如果复杂度或审查疲劳加剧，进一步降低上限，并继续以更小的批次推进。

• 即使目标不变，也要在各阶段之间重新开启执行审批。

• 如果审批后范围发生变化，继续之前应重新确认范围。

• 阶段示例（应用）：

  • Phase 1 示例：5 个文件，总计 170 行变更（新增行数 + 删除行数），单个文件最多 80 行变更（新增行数 + 删除行数）。这符合上限和阈值，因此可以通过一次审批推进。
  • Phase 2 示例：4 个文件，总计 130 行变更（新增行数 + 删除行数）。这超过了阶段总量阈值，因此执行前应拆分为 2 次审批。
  • Phase 3 示例：2 个文件，其中一个文件有 45 行变更（新增行数 + 删除行数）。这超过了单文件阈值，因此应拆分为更小的连续编辑。

2. 应用 Duck Ladder

引入新构造之前，遇到第一个适用的阶梯就停止：

1. 无需更改（YAGNI）
2. 复用现有的本地辅助工具／模式
3. 替换为标准库／原生功能
4. 使用已安装的依赖项
5. 缩小到最小的安全差异
6. 只有到这一步才添加新代码／抽象

添加或修改注释时，只写后续读者需要了解的长期约束或行为。

3. 执行补丁

1. 重述范围边界和预期行为。
2. 修改最小范围的共享修复位置（避免逐个调用方打补丁）。
3. 优先复用现有的本地辅助工具／模式，再添加新的抽象。
4. 应用最小安全差异。
5. 运行已商定的最小检查。
6. 准确报告：修改的文件、行为差异、验证结果。

输出：

• 一行执行计划（文件 + 预期行为）
• 最简补丁摘要（说明改动，不写长篇说明）
• 一项最小验证检查及其结果
• 如果受阻：一行说明阻塞原因 + 所需的下一项输入

边界

• 不得削弱安全性、信任边界、防止数据丢失的措施、无障碍要求或明确的用户要求。
• 如果根本原因不明确，应转交给 duck-debug（必要时使用 trace 模式），而不是进行推测性修改。
• 如果无法在本地运行验证，请提供用户应运行的准确命令和预期信号。