新增功能：设计先行、小步实现、配套测试

新增功能比修 Bug 更需要边界控制。推荐节奏是设计先行、小步实现、配套测试、对照验收，避免"边写边加需求"导致的大而失控的改动。

一、设计先行：先方案后代码

• 进入计划模式调研：可按 Shift+Tab 切换到计划模式，或启动时使用计划权限模式；此时代理只读文件、给出实现方案而不修改。
• 方案应覆盖：功能目标与边界、涉及的接口/数据结构、主要流程、对既有功能的兼容影响、关键决策取舍。
• 需求存在歧义时，让代理通过澄清提问逐项确认（如输入来源、默认行为、错误处理、边界条件），而不是替用户猜测。
• 把验收标准写成可判定条目（什么输入得到什么输出、哪些行为必须保持不变），作为后续完成判据。

二、小步实现，每步可验证

1. 先搭最小骨架：接口/函数签名、目录与类型契约，让整体结构先成立。
2. 再按职责分块填充：核心路径 → 边界与错误处理 → 配套测试 → 文档与提示文案。
3. 每完成一小步就运行可用的检查（测试、构建、静态检查），保持改动始终处于可运行状态。
4. 一次提交聚焦一件事，避免把多个功能点混在一次大改动里。

三、给代理一个能自动判定的验收门

代理在没有可运行检查时，只能凭"看起来完成"收尾；提供测试、构建、lint 或可对比的输出后，它可以在同一轮里反复执行、读取结果并迭代直到通过。设计任务时建议明确：

• 运行哪条测试/构建命令、期望退出成功；
• 需要覆盖的关键输入样例（含合法、非法、边界值）；
• UI 类改动可用截图对比或人工核对作为补充信号；
• 要求代理展示实际执行结果作为完成证据。

四、完成前的对照检查

检查项	确认要点
功能范围	实现的内容与方案一致，未私自扩大需求
验收标准	逐条对照，每条都有对应实现与证据
兼容影响	既有行为、接口字段、配置格式未被破坏
错误处理	非法输入、缺失依赖、失败分支有合理反馈
改动范围	diff 聚焦本功能，无调试残留与无关重写
文档同步	必要的使用说明、配置项与示例已更新

五、控制范围蔓延

实现过程中发现的新需求、优化建议应记录为后续任务，不在当前功能中夹带；若确需调整范围，先回到方案层面确认再改代码。发现方案与现实约束冲突时，先反馈取舍选项，而不是擅自改变设计。

六、小白照抄：一次功能交付的对话推进顺序

不依赖任何高级配置，按下面六个回合顺序与代理协作即可稳定完成一个小功能，每一步都有明确产出，避免一上来就让代理"直接写完"：

1. 回合 1 交代目标与约束：说明功能目的、目标用户场景、不能改动的既有行为、可用的测试与构建命令；要求先不要写实现代码。
2. 回合 2 出方案：按 Shift+Tab 进入计划模式，请代理给出模块划分、改动文件清单、关键流程与验收标准；对模糊点逐条追问澄清。
3. 回合 3 搭骨架：确认方案后先实现类型/函数签名与目录结构，运行一次构建确认骨架可编译、可运行。
4. 回合 4 填主路径：按"核心逻辑 → 错误处理 → 边界输入"顺序实现，每完成一块就运行对应测试，保持改动可运行。
5. 回合 5 补测试与自检：补齐正常、非法、边界三类用例；让代理展示测试命令与实际输出作为证据，再用 /review 或独立只读审查复核差异。
6. 回合 6 对照验收清单收口：逐条核对第二节、第四节的检查项，确认无夹带改动、无调试残留、文档同步后，再由人工决定是否提交。

七、常见问题 FAQ

问题	处理建议
需求本身不清楚，代理一直追问怎么办	先补输入来源、默认行为、错误处理与边界条件四项；仍无法确定时列出 2–3 个候选方案与取舍，由人裁决后再实现，不要让代理替人猜需求。
写了一半发现原方案行不通	停止扩写，回到计划模式说明约束变化，给出替代方案与影响面，经确认后再改；避免在错误方向上持续堆代码。
测试没全绿但功能看起来正常	以测试与构建结果为准，不接受"看起来对"；先让代理解释失败用例与根因，区分是新功能破坏旧行为还是测试本身需要更新。
实现过程中冒出很多"顺手优化"	记入待办清单，当前迭代只交付本功能；优化项另起任务，防止 diff 膨胀导致审查失控。
代理一次性改了十几个文件	警惕范围失控；让它先输出改动文件与理由清单，按依赖关系拆成小步，分批验证后再合并。

八、动手练习

• 练习 1：选一个你熟悉的小项目，为"新增一个输入校验规则"走一遍六回合流程，保留每回合的方案、骨架、测试与审查产出，复盘哪一步返工最多。
• 练习 2：找一段既有实现，练习只新增错误分支处理而不改动主路径，并用既有测试证明对外行为未变；把改动文件数量控制在最小集合。