incremental-implementation

增量式实现

概述

通过精简的垂直切片逐步构建——实现一部分、测试、验证，然后再扩展。避免一次性实现整个功能。每次增量都应让系统保持可运行、可测试的状态。这种执行纪律能让大型功能更易于管理。

适用场景

• 实现涉及多个文件的更改
• 根据任务拆分构建新功能
• 重构现有代码
• 任何你想在测试前编写超过约 100 行代码的情况

不适用场景： 范围已经很小的单文件、单函数更改。

增量周期

┌──────────────────────────────────────┐
│                                      │
│   Implement ──→ Test ──→ Verify ──┐  │
│       ▲                           │  │
│       └───── Commit ◄─────────────┘  │
│              │                       │
│              ▼                       │
│          Next slice                  │
│                                      │
└──────────────────────────────────────┘

对于每个切片：

1. 实现——完成最小且完整的功能部分
2. 测试——运行测试套件（如果没有测试，则编写测试）
3. 验证——确认切片按预期工作（测试通过、构建成功、手动检查）
4. 提交 -- 使用描述性消息保存进度（有关原子提交的指导，请参阅 git-workflow-and-versioning）
5. 进入下一个切片——接续推进，不要重新开始

切片策略

垂直切片（首选）

构建一条贯穿整个技术栈的完整路径：

Slice 1: Create a task (DB + API + basic UI)
    → Tests pass, user can create a task via the UI

Slice 2: List tasks (query + API + UI)
    → Tests pass, user can see their tasks

Slice 3: Edit a task (update + API + UI)
    → Tests pass, user can modify tasks

Slice 4: Delete a task (delete + API + UI + confirmation)
    → Tests pass, full CRUD complete

每个切片都能交付可端到端运行的功能。

契约优先切片

当后端和前端需要并行开发时：

Slice 0: Define the API contract (types, interfaces, OpenAPI spec)
Slice 1a: Implement backend against the contract + API tests
Slice 1b: Implement frontend against mock data matching the contract
Slice 2: Integrate and test end-to-end

风险优先切片

优先处理风险最高或最不确定的部分：

Slice 1: Prove the WebSocket connection works (highest risk)
Slice 2: Build real-time task updates on the proven connection
Slice 3: Add offline support and reconnection

如果切片 1 失败，你可以在投入切片 2 和 3 之前发现问题。

实现规则

规则 0：简单优先

编写任何代码之前，先问：“能正常工作的最简单方案是什么？”

编写代码后，根据以下问题进行检查：

• 能否用更少的代码行实现？
• 这些抽象是否值得其复杂性？
• 资深工程师看到这段代码会不会说“为什么不直接……？”
• 我是在为假设的未来需求构建，还是在解决当前任务？

SIMPLICITY CHECK:
✗ Generic EventBus with middleware pipeline for one notification
✓ Simple function call

✗ Abstract factory pattern for two similar components
✓ Two straightforward components with shared utilities

✗ Config-driven form builder for three forms
✓ Three form components

三行相似的代码胜过过早抽象。先实现朴素且显然正确的版本。只有在通过测试证明正确后，才进行优化。

规则 0.5：严格控制范围

只处理任务要求的内容。

不要：

• “清理”与你的更改相邻的代码
• 重构未修改文件中的导入语句
• 删除你尚未完全理解的注释
• 因为“看起来有用”而添加规格中没有的功能
• 仅仅因为在阅读文件，就更新其中的语法

如果你发现任务范围之外有值得改进的地方，记下来——不要直接修改：

NOTICED BUT NOT TOUCHING:
- src/utils/format.ts has an unused import (unrelated to this task)
- The auth middleware could use better error messages (separate task)
→ Want me to create tasks for these?

规则 1：一次只做一件事

每次增量只更改一项逻辑内容。不要混杂不同关注点：

不佳： 一次提交中新增一个组件、重构一个现有组件，并更新构建配置。

良好： 分成三次提交，每次提交对应一项更改。

规则 2：保持可编译

每次增量完成后，项目都必须能够构建，现有测试也必须通过。不要在切片之间让代码库处于损坏状态。

规则 3：未完成的功能使用功能开关

如果功能尚未准备好向用户开放，但你需要合并增量：

// Feature flag for work-in-progress
const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';

if (ENABLE_TASK_SHARING) {
  // New sharing UI
}

这样你就可以将小幅增量合并到主分支，而不暴露未完成的工作。

规则 4：采用安全的默认行为

新代码应默认采用安全、保守的行为：

// Safe: disabled by default, opt-in
export function createTask(data: TaskInput, options?: { notify?: boolean }) {
  const shouldNotify = options?.notify ?? false;
  // ...
}

规则 5：便于回滚

每次增量都应能够单独回滚：

• 增量式更改（新文件、新函数）易于回滚
• 对现有代码的修改应尽量精简并聚焦
• 数据库迁移应配有相应的回滚迁移
• 避免在同一次提交中删除某项内容后又将其替换——应拆分为不同提交

与 Agent 协作

指示 Agent 逐步实现时：

"Let's implement Task 3 from the plan.

Start with just the database schema change and the API endpoint.
Don't touch the UI yet — we'll do that in the next increment.

After implementing, run the repository's test and build commands to
verify nothing is broken."

明确说明每次增量的范围，以及不在范围内的内容。

增量检查清单

每次增量完成后，使用仓库自身的命令进行验证（参见 test-driven-development 技能中的 Discover the Stack First 部分）：

• 此次更改只做一件事，并将其完整实现
• 所有现有测试仍然通过（仓库的测试命令：npm test、./gradlew test、pytest……）
• 构建成功（仓库的构建命令）
• 类型检查通过（适用的技术栈中有此检查时；例如 npx tsc --noEmit、mypy……）
• Lint 检查通过（仓库的 lint 命令）
• 新功能按预期运行
• 更改已使用描述性消息提交

注意： 完成可能影响某项检查的更改后，运行相应的验证命令。成功运行后，除非代码有过更改，否则不要重复运行相同命令——对未更改的代码重复运行不会提供新信息。

常见借口

借口	事实
“我会在最后统一测试”	Bug 会层层叠加。第 1 个切片中的 Bug 会导致第 2 到第 5 个切片都出错。每完成一个切片就进行测试。
“一次性全做完更快”	只有在出错后找不到 500 行改动中的哪一行导致问题时，才会觉得之前更快。
“这些更改太小，不值得分别提交”	小型提交几乎没有成本。大型提交会掩盖 Bug，也会让回滚变得痛苦。
“我稍后再添加功能开关”	如果功能尚未完成，就不该让用户看到。现在就添加开关。
“这个重构足够小，可以一起做”	将重构和功能混在一起，会让两者都更难审查和调试。请分开处理。
“我再运行一次构建命令，确保万无一失”	成功运行后，除非代码有过更改，否则重复运行相同命令毫无意义。后续编辑后再运行，而不是为了安心而重复运行。

危险信号

• 写了超过 100 行代码，却没有运行测试
• 一次增量中包含多个无关更改
• “我顺手再快速加上这个”导致范围扩大
• 为了加快进度而跳过测试或验证步骤
• 增量之间构建或测试处于失败状态
• 未提交的更改不断累积，规模越来越大
• 在第三个用例提出需求之前就开始构建抽象
• “既然我已经在这里”就改动任务范围之外的文件
• 为只需执行一次的操作创建新的工具文件
• 中间没有任何代码更改，却连续运行相同的构建或测试命令两次

验证

完成任务的所有增量后：

• 每个增量都已单独测试并提交
• 完整测试套件通过
• 构建无误
• 功能端到端地按规格运行
• 没有遗留未提交的更改

另请参阅

逐增量验证是局部检查。在宣布任务完成前，应将项目范围内的完成定义作为最终关卡；这是每个增量都必须达到的长期标准，无论任务内容如何。参见 ../../references/definition-of-done.md。