Claude Code 真实工作流：设计 → 计划 → 执行，把 AI 当同事而不是补全工具

一、背景：两种烂文章之外的第三种

关于 AI 编程有两种烂文章：一种是生成个排序函数就宣布程序员完蛋了，一种是抓个弱智 bug 就宣布这玩意儿没用。两种都跟真实工作日没关系。

本文是第三种：作者用 Claude Code 在自己真实站点（React+Vite 前端、Sanity CMS、Vercel Functions 小后端）上的完整工作流，三个真实委派任务、仓库里的真实痕迹，以及跟“哪里好用”一样长的“哪里翻车”。先说清 Claude Code 是什么：跑在终端、跑在仓库里的 agent，读文件、跑命令、改代码、做提交。它不是编辑器补全，也不是贴来贴去的聊天框。能看到整个仓库、能跑测试读输出的 agent，才能接走一整块任务——咨询和外包的区别。

二、原理：为什么“规格先行”赢

直接喊“给我加个管理后台”，600 行落地才发现不是自己想要的——返工最贵。把流程切成设计、计划、执行三段且互不重叠，解决的是三个不同的失败：

• 设计解决“做错事”：问题定义、两三个方案及其代价、选哪个及为什么。产出 docs/plans/ 下的短设计文档。
• 计划解决“做偏”：设计变逐任务计划——每个任务动哪些文件、先写哪个测试、用什么命令验证、何时提交。偏离计划在第 4 步就能发现，而不是 600 行之后。
• 执行解决“遗忘”：计划落字进文件而非留在对话里。长会话上下文会退化，早半小时的决策会变模糊，文件不会忘。

书面计划把“agent 干了件怪事”变成“agent 在第 4 步偏离了脚本”——前者没法修，后者好修。这就是全部秘密。

一句话纪律：大事无书面计划不开工（Nothing big gets written without a written plan first）。

三、环境准备

# 仓库布局（照抄即可）
mkdir -p docs/plans .claude
# docs/plans/ 下文件名示例：
# 2026-04-28-slice-2-vercel-migration.md
# 2026-04-29-portfolio-audit-implementation.md

• .claude/ 放本项目配置与权限。
• 大任务开 git worktree，跟当前工作区隔离，炸了直接扔。
• 分支策略：agent 永远在分支/worktree 里干，不碰 main。

四、分步实战

步骤 1：设计——先聊透再动手（附模板）

# docs/plans/2026-05-01-xxx-design.md
## 问题
一句话：解决什么、为谁。
## 方案 A/B/C
- 怎么做 / 代价 / 否决条件
## 决议
选 X，因为……；放弃 Y，因为……
## 非目标
这次明确不做的三件事。
## 验证标准
做完后跑什么命令、看到什么输出算成。

跟 Claude Code 的对话起手式（直接复制改）：

先别写代码。问题是<…>，给我 2~3 个方案，各自的缺点，
然后推荐一个并说明为什么。写入 docs/plans/<日期>-<任务>-design.md。

关键：明确要“缺点/代价”。默认它是什么都说好的老好人，不点名要替代方案，替代方案永远不出现。

步骤 2：计划——切碎到“每步可验证”（TDD 内置）

设计定稿后让它转计划，要求每个任务五件套：动哪些文件、先写哪个测试、验证命令、提交点、回滚条件。测试先行（TDD）：测试存在且先失败，实现再让它变绿。

按 design 文档拆成逐任务计划，每个任务注明：涉及文件、
先写的测试、验证命令、提交信息。写入 docs/plans/<日期>-<任务>-plan.md。
计划没确认前不许写实现代码。

读计划 30 秒就能判断它有没有理解你，改计划免费，改实现昂贵。计划示例骨架：

# plan: Express 迁 Vercel Functions
- [ ] T1 helper 搬迁：src/server/ga.js -> api/_utils/ga.js，原样搬
      验证：node -e "import('./api/_utils/ga.js').then(m=>console.log(Object.keys(m)))"
- [ ] T2 路由改 handler：api/stats.js，契约不变（状态码/字段/错误形状）
      先写测试：tests/api-stats.test.js（含旧契约快照）
- [ ] T3 环境变量迁移 + 本地 `vercel dev` 联调
- [ ] T4 前端零改验证：同一套请求打新旧两端 diff
- [ ] T5 提交：squash 为一条，message 含契约说明

步骤 3：执行——三个真实任务长什么样

任务 A：全站审计（机器找、人定）。 指令是“像接了个客户站一样审计：走读公开组件、移动+桌面路由、构建分包体积、Sanity 真实文章数”。回来 20 个发现分 4 类，每条带优先级和工作量：993KB 未优化插图、sitemap 里 9 篇文章一篇没有、404 页卡死在“Loading post…”。刻意只给发现不给修——修什么、扔什么是人的权。20 条里扔了 3 条。

任务 B：Express 迁 Vercel Functions（委派最赚的一类）。 Railway 上一个包 Google Analytics 的小 Express 服务，24 小时在线只为几乎没人看的仪表盘。迁移是教科书式体力活：helper 收进 api/_utils/、路由改 handler、环境变量搬家、验证外部契约不变。前端零感知，账单归零。判断标准：机械、定义清晰、有客观成功判据、连续 20 个细节不能错——机器半夜 11 点比你靠谱。

任务 C：sitemap 改 Sanity 自动生成（最赚的是“小任务”）。 原来是手写静态文件，发文就忘改。用 80 行 Node 脚本（零新依赖）在 prebuild 跑 GROQ 查 Sanity 全量文章+真实日期写文件。省时间最多的不是大任务，是 40 分钟、拖了半年的小事——启动成本降到足够低，欠账才会被清掉。

执行期命令示例：

git worktree add ../site-task-b -b task/vercel-migration
# agent 在 worktree 里按 plan 逐项执行，每项绿了才下一步
npm test && npm run build
git diff --stat   # 你逐项读 diff

步骤 4：验收——diff 全读 + 契约 diff

• 所有 diff 全读。不读就不委派——署你名的提交就是你的，不管谁敲的键盘，跟审人类同事一个标准。
• 有外部契约的（API/页面/构建产物），新旧输出做 diff，字段、状态码、字节数对不上不合入。
• 视觉项亲手看：它能写出正确、可访问、测试全绿但丑的组件，审美是你的活，CSS 该重写就重写。

五、失败模式全清单（跟成功一样长）

1. 它太快接受你的前提：“修这个 CSS bug”——它真去修 CSS，哪怕病根是路由顺序。以后只描述行为不给诊断，诊断是它的活，误诊率断崖降。
2. 它对你的馊主意太客气：你指条错路，它帮你修得漂漂亮亮。对策见步骤 1：永远先要 2~3 个带缺点的选项。
3. 长会话上下文退化：几小时后早期的决策变模糊。对策：计划在文件里，不在对话里；超长任务切新会话+重读 plan 文件续跑。
4. 它不知道什么叫丑：正确≠好看，视觉终审留给人。
5. 责任还在你：每个合入都读一遍，这是底线不是信任问题。
6. 负收益任务清单：10 分钟内你本来就会的、单行改动、讲清上下文比动手还累的——写 prompt 就是净亏损，直接自己改。

补充三条作者没写但你一定会踩的：并行开两个 agent 改同一片文件必然冲突CALC，一片区域一次只许一个写者；让它“顺手重构周边”等于给返工开无上限信用卡，重构单独立项；测试全绿不等于契约没变，上线前跑一遍真实链路。

六、明天就能用的五步启动法

1. 从无聊且定义清晰的任务起手：格式迁移、给现存代码补测试、升依赖。别拿旗舰功能开刀。
2. 再小的任务也要先出计划：30 秒读计划判断理解度，改计划不花钱。
3. 分支或 worktree 里干：随时可扔，不心疼才敢放手。
4. diff 全读：不读就不配委派。
5. 决策落字进仓库：对话里的决策活不过三天，docs/plans/ 里的三个月后还找得到为什么。

六、设计文档怎么写好与隔离执行实操

设计文档最怕写成需求复读机，好设计只回答四个问题：问题的一句话定义、候选方案各自的代价、选择与放弃的理由、这次明确不做的事。非目标清单与决议同等重要，它是三个月后你回看时不重蹈覆辙的凭据，也是执行阶段挡住范围蔓延的盾牌。验证标准要写成命令加期望输出，而不是形容词，形容词无法执行，命令可以。计划文档的颗粒度以单步可验证为准绳，每一步都要能回答测什么、用什么命令测、挂了回滚到哪里，答不上来就继续拆。测试先行的顺序不能反：先写断言旧契约的快照测试，再动手搬迁，这样契约漂移在第一时间就会变红，而不是上线后被用户发现。

隔离执行的具体操作是：大任务单独开工作树，与当前工作区物理隔离，分支命名带任务前缀，炸了直接删除整个目录，不心疼才敢真正放手让智能体跑全程。执行过程中要求它每完成一步就停下汇报验证输出，你确认后再走下一步，关键步骤的提交信息写清契约变化，方便回滚时定位。验收阶段除了读全量差异，还要对外部契约做新旧输出对比，字段、状态码、产物字节数三项对不上就不合入。视觉类产物必须亲眼看，正确可访问测试全绿只是及格线，顺眼才是上线标准。并行纪律也要立住：同一片文件一次只许一个写者，两个智能体同时改一处必然冲突；顺手重构要单独立项，搭车重构等于给返工开无上限的信用卡。

再补一次真实的翻车复盘。某次让它顺手把旧的分析脚本一起迁移，计划里没写，口头追加了一句，结果新 handler 的错误码映射被它按旧脚本的习惯改了名，测试全绿因为断言只覆盖了成功路径，上线后监控报警才发现错误归因全错。根因三条：计划外追加、契约测试缺失、验收只看绿不看 diff。从此立规矩：计划外事项一律补计划再执行，契约变化必须有快照测试，每个合入 diff 逐行读。另一条教训是视觉项不要指望它：某次生成的落地页组件，语义、响应式、可访问性全对，就是丑，最终手工重写了样式。结论是把它放在它擅长的位置，机械迁移、批量审计、脚手架生成放手给它，品味与取舍留在人手里，分工越清晰，合作越顺滑。启动阶段的任务选择也有讲究：优先挑定义清晰的无聊任务，比如格式迁移、依赖升级、给现存代码补测试，这些任务成功标准客观，翻车半径小，适合建立信任。旗舰功能与核心链路改造往后放，等你对它的脾气足够了解再说。会话管理同样重要，超长任务主动切新会话，用计划文件续跑，不要考验上下文的记忆力。每个会话开始时先让它读计划文件确认进度，这个习惯能省掉大量重复沟通。分支策略上，智能体永远在分支里干活，主分支只接受你亲手合入的提交，这条红线没有任何例外。复盘习惯也要建起来：每次任务结束花十分钟写三行，哪里超预期，哪里翻车，下次改什么，攒够二十篇就是你自己的工作流手册。工具层面把常用起手式存成模板，设计文档模板、计划文档模板各一份，新任务复制即用，避免每次从零组织语言，模板本身也要随经验迭代。

七、总结

它没让我更快，只是磨掉了无聊部分的摩擦力——而无聊部分恰是工作的大头。sitemap 拖了几个月、审计拖了更久，不难，就是烦；烦的事成本降下来，欠账就清掉了。没变的是：建什么我定，每行合入我审，线上炸了我背。喜欢的正是这部分——决策权还在人手里，agent 只是把执行成本打了下来。 点击阅读原文

参考资料：dev.to 上 gabbs279《How I Actually Code with Claude Code》。 点击阅读原文