多文件功能开发时如何用薄切片增量实现并逐步验证

在实现任何涉及多文件的功能、重构或从计划中领取任务时，按可独立验证的小切片逐步实现、测试、提交，避免一次性写完大量代码。

适用场景

解决思路

1. 按增量循环推进每个切片：实现最小完整功能 → 运行测试（无测试则先写测试）→ 验证切片按预期工作（测试通过、构建成功、手动检查）→ 用描述性信息提交 → 进入下一个切片，继续推进而非重来。
2. 优先使用垂直切片：每个切片打通一条完整的端到端路径（如 Slice 1 创建任务含 DB+API+基础 UI，Slice 2 列出任务，Slice 3 编辑任务，Slice 4 删除任务含确认），每个切片交付可工作的端到端功能。
3. 当后端与前端需并行开发时使用契约优先切片：Slice 0 定义 API 契约（类型、接口、OpenAPI spec），Slice 1a 按契约实现后端并写 API 测试，Slice 1b 按契约用 mock 数据实现前端，Slice 2 集成并端到端测试。
4. 使用风险优先切片：先攻克风险最高或最不确定的部分（如 Slice 1 先验证 WebSocket 连接可用，Slice 2 再基于已验证连接构建实时任务更新，Slice 3 添加离线支持与重连），以便在投入后续切片前发现失败。
5. Rule 0 简单优先：写代码前先问“能工作的最简单方案是什么”；写完后检查能否用更少行完成、抽象是否值得其复杂度、资深工程师是否会质疑、是否在为假设的未来需求而非当前任务构建；三行相似代码优于过早抽象，先实现朴素且明显正确的版本，测试证明正确后再优化。
6. Rule 0.5 范围纪律：只触碰任务所需内容；不要“顺手清理”相邻代码、不要重构未修改文件的 import、不要删除不完全理解的注释、不要添加规格外“看起来有用”的功能、不要现代化只读文件的语法；发现范围外可改进项时只记录不修复，并询问是否要为其创建任务。
7. Rule 1 一次只做一件事：每个增量只改变一个逻辑事项，不要把新增组件、重构现有组件、更新构建配置混在同一次提交中，应拆成三次独立提交。
8. Rule 2 保持可编译：每个增量后项目必须能构建且现有测试必须通过，不要在切片之间让代码库处于损坏状态。
9. Rule 3 用功能开关处理未完成功能：若功能尚未对用户就绪但需要合并增量，使用功能开关（如 const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';）以便向主分支合并小增量而不暴露未完成工作。
10. Rule 4 安全默认值：新代码应默认采用安全、保守的行为（如 options?.notify ?? false，默认关闭、需显式开启）。
11. Rule 5 便于回滚：每个增量应可独立回滚；新增性改动（新文件、新函数）易于回滚，对现有代码的修改应最小且聚焦，数据库迁移应有对应的回滚迁移，避免在同一提交中删除某物又替换它，应分开提交。
12. 指导 agent 增量实现时明确说明每次增量的范围内与范围外内容，例如“先只做数据库 schema 变更和 API 端点，暂不碰 UI，下个增量再做；实现后运行仓库的测试与构建命令验证未被破坏”。
13. 每个增量后按仓库自身命令核对清单：改动只做一件事且做完整；所有现有测试仍通过（npm test、./gradlew test、pytest 等）；构建成功；类型检查通过（npx tsc --noEmit、mypy 等）；lint 通过；新功能按预期工作；改动已用描述性信息提交。
14. 仅在可能受影响的改动之后运行对应验证命令；某命令成功运行后，若代码未再变化就不要重复运行同一命令，重复运行不增加信息。
15. 警惕常见合理化借口：不要“最后再一起测”（bug 会累积，Slice 1 的 bug 会让 Slice 2-5 出错）；不要“一次做完更快”（出问题时无法从 500 行改动中定位）；不要“改动太小不值得单独提交”（小提交免费，大提交藏 bug 且回滚痛苦）；不要“稍后再加功能开关”（未完成功能不应用户可见）；不要“这个重构小到可以顺带”（重构与功能混合使审查和调试都更难）；不要“再跑一次构建确认”（无代码变化时重复运行无意义）。
16. 警惕红旗信号：写超过 100 行代码未运行测试；单个增量含多个不相关改动；“让我顺手再加这个”的范围扩张；为求快跳过测试/验证步骤；增量之间构建或测试损坏；大量未提交改动累积；在第三个用例出现前就构建抽象；以“既然来了”为由触碰任务范围外文件；为一次性操作创建新工具文件；无中间代码变化却连续两次运行同一构建/测试命令。
17. 任务全部增量完成后做最终验证：每个增量都单独测试并提交；完整测试套件通过；构建干净；功能按规格端到端工作；无未提交改动残留。
18. 在宣布任务完成前，应用项目级 Definition of Done 作为最终关卡（见 ../../references/definition-of-done.md），这是每个增量无论任务如何都需达到的固定标准。

适用边界 · 注意事项

• 单文件、单函数的改动，范围本身已最小。
• 范围已经极小的改动，无需再切片。