AI Agent / 系统课时
分阶段实施功能
分阶段实施功能
复杂功能最容易在一次“大改”中同时混入代码、配置和测试变更,导致出错后难以判断是哪一步造成的。本节把 Claude Code 的执行过程切成最小可验证增量,让每一阶段都有明确边界、验证证据和继续条件。
学习目标
- 把一个跨文件功能拆成可以独立验证的实施阶段
- 用受限指令约束 Claude Code 每次只完成当前阶段
- 在进入下一阶段前通过差异与定向测试建立检查点
先把功能切成可验证增量
分阶段不是按“先改一个文件、再改另一个文件”机械拆分,而是按可验证能力切分。以“给现有 CLI 增加 --dry-run”为例,可以先让参数解析接受新选项并补测试,再让业务执行层读取该选项并跳过真实写入,最后才补帮助文本或配置说明。每一阶段都应该能回答:改了什么、怎么证明它正确、失败时回退到哪里。
对涉及多个文件的任务,可以先进入 /plan,或用 Shift+Tab 切到 Plan mode。此时让 Claude Code 读取代码、定位影响范围并提出计划,不要直接实施。计划里最好显式写出每阶段允许修改的文件、验收命令和禁止触碰的范围。
先不要修改文件。为“给现有 CLI 增加 --dry-run”制定分阶段计划。
要求每个阶段都是最小可验证增量,列出允许修改的文件、对应测试,以及进入下一阶段前必须满足的验收条件。
不要顺手重构日志、错误处理或无关模块。预期结果:Claude Code 先给出分阶段方案,而不是立即编辑文件;每个阶段都能单独验证,并明确哪些改动不属于本次功能。

一次只实施当前阶段
计划确认后切回可编辑的执行模式,只下达当前阶段的指令。关键是把“完成整个功能”改成“完成阶段 A 并停下”,同时写清允许改动和停止条件。这样 Claude Code 不会为了自认为的完整性提前实现后续逻辑。
现在只实施阶段 A:让 CLI 解析器接受 --dry-run,并补齐这一层的单元测试。
允许修改 src/cli.ts 和 test/cli.test.ts。
不要修改执行层、日志、README 或其他文件。
完成后运行这一层的测试,并停下等待我审查,不要继续阶段 B。预期结果:本轮只出现参数解析和对应测试的改动;执行层行为保持不变,Claude Code 在测试完成后停止扩展范围。
每个阶段都用证据决定是否继续
Claude Code 报告“已完成”只能作为线索,不能替代验证。先看改动文件,再检查补丁格式,最后运行与当前阶段直接相关的测试。以下以 Jest 项目和前述两个文件为例:
printf 'CHANGED FILES\n'
git diff --name-only
printf '\nDIFF CHECK\n'
git diff --check && echo OK
printf '\nTARGETED TEST\n'
npx jest test/cli.test.ts --runInBand预期输出
CHANGED FILES
src/cli.ts
test/cli.test.ts
DIFF CHECK
OK
TARGETED TEST
PASS test/cli.test.ts
Tests: 3 passed, 3 total实际测试数量可能不同,但应满足三个条件:改动文件没有越界、git diff --check 无错误、当前阶段的定向测试通过。任一条件失败,都先让 Claude Code 只修复当前阶段,不要带着失败状态继续实现下一阶段。
把通过的阶段变成检查点
一个阶段通过后再进入下一阶段。团队习惯允许时,可以用独立提交保存检查点,例如 git add src/cli.ts test/cli.test.ts 后执行 git commit -m "feat: parse dry-run option"。这样后续阶段出现问题时,差异范围和回退边界都更清楚。
不要为了制造“阶段感”把本来必须一起验证的代码强拆开。例如新增数据库字段却不提供读取兼容逻辑,虽然文件改动更少,但中间状态不可用,也就不是合格的最小增量。真正的最小单位是能独立验证的行为,而不是最少文件数。
当每个阶段都遵循“限定范围、实施、验证、通过后再继续”,Claude Code 的长任务就从一次不可控的大修改,变成一串可审查、可停止、可回退的小修改。