Skip to main content
一份综合指南，将”多轮闲聊改代码”升级为”文档先行、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 未达成（不是”感觉不对”） 失败后：
  1. 归档六件套
  2. 新时间戳目录写第二轮 PLAN
  3. 把”失败原因 → 修正假设 → 变更点”写进注意事项
  4. 白黑名单与 DoD 原则上不变（变更需明示理由）
  5. 再跑短投喂提示：先澄清，后出 diff
  6. 直到”一轮命中” ⸻

​
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：
  1. 任务目标/DoD 是否清晰？
  2. diff 是否在白名单/是否超限？
  3. 测试与脚本是否覆盖关键路径？ ⸻

​
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 辅助开发工作流
  • Claude Code 就是我的电脑 - 深入探讨如何在无提示模式下使用 Claude Code 进行日常开发任务。学习如何利用 AI 进行内容发布、代码提取、自动化和系统管理。
  • 掌握 Claude Code 的 33 个必知设置技巧 - 通过 33 个基础到高级的技巧全面掌握 Claude Code，涵盖快捷键、提示技巧、MCP 服务器、项目规则和自动化钩子。从新手到专家级生产力的完整指南。