把随机对话变成可复现的产线：Claude Code 高阶实战指南
将混乱的 AI 辅助开发转化为结构化的文档先行、差异驱动工作流，通过系统化规划和执行实现可预测的结果。
把随机对话变成可复现的产线：Claude Code 高阶实战指南
一份综合指南，将"多轮闲聊改代码"升级为"文档先行、Diff 驱动、一次命中"的工作法。
实验成果概览
最初的火花来自一条经验帖：与其在编辑器里让模型反复修改，不如先写一份可执行的 PLAN.md，把目标、边界、步骤、验收讲清楚，再让 Claude Code按文档执行。失败就冷启动开新一轮，不在同一串对话里"修修补补"。
当我把这套方法落到团队里，我们发现三件事会立刻改变：
- 回滚不再痛苦，因为一切都以统一补丁（unified diff）交付
- 评审变得轻松，因为只需对照 PLAN 与 DoD 看补丁
- 模型的"不确定性"被装进了文件结构与流程里，而不是散落在聊天记录里
⸻
一个小任务，跑通整条轨道
我们要给 API v2 加一层认证中间件。不同于老习惯（先问模型"怎么做"），我们先铺好轨道：
- 仓库根目录下有一个
CLAUDE_CODE_LOG/ - 每一轮尝试都是一个唯一时间戳__任务名的文件夹
- 每轮都有
PLAN.md/PROMPT_USED.md/0001.patch/RUN_LOG.md/COMMIT_SHA.txt/EVAL_REPORT.md六件套 - Claude Code 只被允许输出 unified diff，并受文件白名单约束
- 失败后归档并冷启动下一轮（新时间戳目录），而不是在同一对话里加料续聊
第一次跑，Claude 给出补丁；我们 git apply --3way，跑测试，DoD 未过——于是把真实投喂的提示词、补丁、日志与commit 指纹全部落库，写清失败原因，开第二轮。重复几次后，你会看到成功率和速度都上来了：模型在"窄轨道"里发挥，自由但不失控。
⸻
核心方法论：四句箴言
1. 文档先行
任何任务先写 PLAN.md，再让模型执行。
2. Diff 驱动
只接受 unified diff，禁止整文件重写/"扫库"。
3. 范围收敛
白名单文件 + 黑名单目录 + 最大改动行数上限。
4. 可验证
以 DoD（Definition of Done）配套测试/脚本判定成败，并留痕。
⸻
1. 仓库结构与命名（唯一化约束）
project-root/
.claude/
templates/PLAN.template.md
rules/ # 代码规范/错误码/安全红线
repo_map.md # 关键目录/入口/数据流
CLAUDE_CODE_LOG/
20250827_083000__add-auth-mw/ # 时间戳__任务-kebab
PLAN.md
PROMPT_USED.md
0001.patch
RUN_LOG.md
COMMIT_SHA.txt
EVAL_REPORT.md命名约定：
- 时间戳：
YYYYMMDD_HHMMSS - 任务名：kebab-case，不含空格
- 分支：
feature/<task>-<timestamp> - 失败打 tag：
cc-fail-<task>-<timestamp> - 重要：不要移动源码入存档，只归档文档/补丁/日志/指纹，避免破坏路径与构建链
⸻
2. 把"7 层提示词栈"固化到 PLAN.md
工具/语言/项目/人设/组件/任务/查询，七层入文档，Claude 读取文件即可拥有稳定上下文。
# Task Title
Auth middleware for API v2
## 0. Metadata
- Timestamp: 2025-08-27 08:30
- Branch: feature/auth-mw-20250827-0830
- Issue: #123
## 1) Tool Conventions（工具约定）
- 使用 Claude Code / Cursor（Claude）
- **只输出 unified diff（patch）**
- **仅允许修改**：server/middleware/auth.ts, server/routes/*.ts, tests/auth.test.ts
## 2) Language Conventions（语言/栈）
- Node 20 + TypeScript strict
- ESLint/Prettier 强制，显式类型
## 3) Project Context（项目）
- 目录/数据流见 .claude/repo_map.md
- 禁改：infra/, migrations/, .env*
- 依赖：jsonwebtoken@^9
## 4) Persona（人设）
- 资深后端+测试工程师：先最小可行，再补测试与文档
## 5) Component Scope（组件）
- API v2 中间件层；契约：Authorization: Bearer <JWT>
## 6) Task & DoD（任务与验收）
- 校验 JWT，注入 req.user；区分 401/403
- **DoD**：
- `npm test` 全绿
- `GET /v2/ping` 返回 200
- 改动行数 < 300 且只在白名单文件中
## 7) Query / Action（执行指令）
- 如不确定，先提出 ≤3 条澄清问题
- 然后输出 **unified diff**（新增文件含 `--- /dev/null`）
- 最后附 ≤120 字变更摘要
## Risks & Rollback
- 风险：路由顺序导致中间件未生效
- 回滚：revert 当前补丁；接口不变
## Evaluation（验证）
- 运行：`npm i && npm test`
- 记录：输出写入 `RUN_LOG.md`
## Debrief（执行后填写）
- 成功/失败；原因分类；下一轮假设与修正⸻
3. 一段非常短的投喂提示（贴进对话就够）
读取 ./CLAUDE_CODE_LOG/20250827_083000__add-auth-mw/PLAN.md
严格按"白名单/DoD/步骤"执行：
1) 如不确定，先给 ≤3 条澄清问题；
2) 然后只输出 unified diff 补丁；
3) 附 ≤120 字变更摘要。⸻
4. "边读边做"的 10 分钟跑通脚本
# 1) 开轮
TS=$(date +"%Y%m%d_%H%M%S"); TASK=add-auth-mw
ROUND="CLAUDE_CODE_LOG/${TS}__${TASK}"
mkdir -p "$ROUND" && git checkout -b "feature/${TASK}-${TS}"
# 2) 生成 PLAN 草稿
cp .claude/templates/PLAN.template.md "$ROUND/PLAN.md"
echo -e "\n\nBranch: feature/${TASK}-${TS}\nTimestamp: ${TS}" >> "$ROUND/PLAN.md"
# 3) 让 Claude 输出补丁 → 粘贴保存为：
cat > "$ROUND/0001.patch"
# 4) 应用与验证留痕
git rev-parse HEAD > "$ROUND/COMMIT_SHA.txt"
git apply "$ROUND/0001.patch" --3way
npm i && npm test | tee "$ROUND/RUN_LOG.md"
# 5) 提交或归档
git add -A && git commit -m "cc: ${TASK} @ ${TS}"⸻
5. 四类常见任务的 Prompt Recipes
实现类
读取 PLAN.md
若不确定，提出 ≤3 个澄清点
仅在白名单文件内最小化实现，输出 unified diff重构类
目标：不改变对外行为，仅改善内部结构
保留所有导出 API 与测试不变
分步给 diff（先小再大），每步都能独立通过测试缺陷修复类
先给"复现单测"的最小 patch（红）
再给修复 patch（绿）
两段 diff 分开发送文档/脚本类
仅对 README/脚本做有限改动
给出本地验证命令，产出写入 RUN_LOG.md⸻
6. 改动范围与安全护栏（务必启用）
必备保护措施：
- 白名单：只列允许修改的文件/目录
- 黑名单：infra/、migrations/、.env*、部署脚本等敏感区
- 改动上限：例如单轮 ≤300 行；触顶必须停下并提问
- 风格一致：ESLint/Prettier 强制；TS 显式类型
- 只收补丁：禁止整文件重写与跨仓重构
- 依赖锁定：保留 lockfile；新增/升级依赖须在 PLAN 中显式声明
⸻
7. 冷启动迭代，而非长聊"修修补补"
失败判定 = DoD 未达成（不是"感觉不对"）
失败后：
- 归档六件套
- 新时间戳目录写第二轮 PLAN
- 把"失败原因 → 修正假设 → 变更点"写进注意事项
- 白黑名单与 DoD 原则上不变（变更需明示理由）
- 再跑短投喂提示：先澄清，后出 diff
- 直到"一轮命中"
⸻
8. 质量度量与看板（把体感变成数据）
每轮在 EVAL_REPORT.md 记录：
- 一次通过率（round-1 pass %）
- 改动行数（中位数/分布）
- 澄清问题数（与失败率相关性）
- 回滚率（revert 次数）
- 失败原因分类：需求不清/上下文缺失/接口冲突/测试断言不当/超范围修改/依赖问题...
用这些指标反推模板与规则：需要更细的白名单？更硬的 DoD？repo_map 是否缺关键入口？
⸻
9. 团队级资产化（Playbook）
在根目录建立 CLAUDE_CODE_PLAYBOOK/：
- PLAN.template.md：七层提示词映射的统一骨架
- PROMPT.recipes.md：实现/重构/缺陷/文档四类范式
- BOUNDS.checklist.md：白/黑名单示例、行数上限
- EVAL.metrics.md：指标定义与采集方法
- RISK.cases.md：真实踩坑与回滚策略
下次同类任务，只改三处：目标、白名单、DoD。其余全部复用。
⸻
10. CI/评审对接（让机器"冷酷执法"）
CI 强制校验：
git apply --check CLAUDE_CODE_LOG/**/0001.patch
npm test / pytest -q / go test ./...PR 模板挂 PLAN.md 与 EVAL_REPORT.md：
- 任务目标/DoD 是否清晰？
- diff 是否在白名单/是否超限？
- 测试与脚本是否覆盖关键路径？
⸻
11. 反模式警示（越线即红灯）
红灯警告（立即停止）：
- 在同一长对话里来回修改：上下文漂移、指令稀释、幻觉上升
- 让模型"扫全仓找入口"：高风险 + 低确定性
- 一次性大改：回滚难、定位难
- 无 DoD：验收口径不统一，无法复现
- 把源码搬进存档：破坏路径/构建链，后患无穷
⸻
模板：可直接使用的 PLAN.template.md
# 任务标题（≤60字）
## 1. 任务目标 / DoD（必须可验证）
- 验收命令：
- `npm i && npm test`
- `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/v2/ping == 200`
- 改动边界：
- 仅允许：<列出文件或通配>
- 禁止：infra/, migrations/, .env*
- 单轮改动 ≤300 行（超限先停下并提问）
## 2. 执行步骤（最小可行）
1) <最小实现点>
2) <接入/注册位置>
3) <补单测或脚本>
4) 本地跑测并记录日志
## 3. 注意事项
- **只输出 unified diff（patch）**；新增文件用 `--- /dev/null`
- 保持导出 API 不变（若变更需明示）
- ESLint/Prettier；TS 显式类型
## 4. 补充信息
- 依赖：<name@ver>
- 契约：<协议/头/错误码>
## 5. 风险与回滚
- 风险：<潜在失效点>
- 回滚：revert 当前补丁，接口不变
## 6. 执行约定（给 Claude）
- 如不确定，先给 ≤3 条澄清问题
- 然后输出补丁 + ≤120 字摘要
## 7. 本轮总结（执行后填写）
- 成功/失败：
- 失败原因分类：
- 下一轮修正计划：⸻
收束：让模型成为"守规矩的结对程序员"
这篇文章刻意把叙事与编号清单放在一起：前半段告诉你"为什么这条路更稳"，后半段把每一个"步骤"都补齐到可以立即执行。经验帖给了我们方向，而流程、模板、脚本与指标让方向变成了可复制的生产力。
从现在起，试着把下一个小需求装进这套轨道里。让 Claude Code 在窄而清晰的轨道内发挥——先澄清、后产出，只交补丁、严格验收。你会很快感到：代码库仍由你掌舵，而模型，终于成了那位自律可靠的搭档。
核心要点：
- 将 AI 对话从混乱转为系统化
- 用文档驱动开发而非即兴发挥
- 实施可验证的成功标准和完整追溯
- 在结构化流程中控制模型不确定性
- 构建团队级可复现的 AI 辅助开发工作流