> ## Documentation Index
> Fetch the complete documentation index at: https://cc.cyber101.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 生产级工作流

> 将混乱的 AI 辅助开发转化为结构化的文档先行、差异驱动工作流，通过系统化规划和执行实现可预测的结果。

*一份综合指南，将"多轮闲聊改代码"升级为"文档先行、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. 文档先行](#1-文档先行)

任何任务先写 PLAN.md，再让模型执行。

### [2. Diff 驱动](#2-diff-驱动)

只接受 unified diff，禁止整文件重写/"扫库"。

### [3. 范围收敛](#3-范围收敛)

白名单文件 + 黑名单目录 + 最大改动行数上限。

### [4. 可验证](#4-可验证)

以 DoD（Definition of Done）配套测试/脚本判定成败，并留痕。
⸻

## [1. 仓库结构与命名（唯一化约束）](#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](#2-把7-层提示词栈固化到-planmd)

工具/语言/项目/人设/组件/任务/查询，七层入文档，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. 一段非常短的投喂提示（贴进对话就够）](#3-一段非常短的投喂提示贴进对话就够)

```
读取 ./CLAUDE_CODE_LOG/20250827_083000__add-auth-mw/PLAN.md
严格按"白名单/DoD/步骤"执行：
1) 如不确定，先给 ≤3 条澄清问题；
2) 然后只输出 unified diff 补丁；
3) 附 ≤120 字变更摘要。
```

⸻

## [4. "边读边做"的 10 分钟跑通脚本](#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](#5-四类常见任务的-prompt-recipes)

### [实现类](#实现类)

```
读取 PLAN.md
若不确定，提出 ≤3 个澄清点
仅在白名单文件内最小化实现，输出 unified diff
```

### [重构类](#重构类)

```
目标：不改变对外行为，仅改善内部结构
保留所有导出 API 与测试不变
分步给 diff（先小再大），每步都能独立通过测试
```

### [缺陷修复类](#缺陷修复类)

```
先给"复现单测"的最小 patch（红）
再给修复 patch（绿）
两段 diff 分开发送
```

### [文档/脚本类](#文档脚本类)

```
仅对 README/脚本做有限改动
给出本地验证命令，产出写入 RUN_LOG.md
```

⸻

## [6. 改动范围与安全护栏（务必启用）](#6-改动范围与安全护栏务必启用)

**必备保护措施：**

* **白名单**：只列允许修改的文件/目录
* **黑名单**：infra/、migrations/、.env\*、部署脚本等敏感区
* **改动上限**：例如单轮 ≤300 行；触顶必须停下并提问
* **风格一致**：ESLint/Prettier 强制；TS 显式类型
* **只收补丁**：禁止整文件重写与跨仓重构
* **依赖锁定**：保留 lockfile；新增/升级依赖须在 PLAN 中显式声明
  ⸻

## [7. 冷启动迭代，而非长聊"修修补补"](#7-冷启动迭代而非长聊修修补补)

**失败判定** = DoD 未达成（不是"感觉不对"）
**失败后：**

1. 归档六件套
2. 新时间戳目录写第二轮 PLAN
3. 把"失败原因 → 修正假设 → 变更点"写进注意事项
4. 白黑名单与 DoD 原则上不变（变更需明示理由）
5. 再跑短投喂提示：先澄清，后出 diff
6. 直到"一轮命中"
   ⸻

## [8. 质量度量与看板（把体感变成数据）](#8-质量度量与看板把体感变成数据)

每轮在 `EVAL_REPORT.md` 记录：

* **一次通过率**（round-1 pass %）
* **改动行数**（中位数/分布）
* **澄清问题数**（与失败率相关性）
* **回滚率**（revert 次数）
* **失败原因分类**：需求不清/上下文缺失/接口冲突/测试断言不当/超范围修改/依赖问题...
  用这些指标反推模板与规则：需要更细的白名单？更硬的 DoD？repo\_map 是否缺关键入口？
  ⸻

## [9. 团队级资产化（Playbook）](#9-团队级资产化playbook)

在根目录建立 `CLAUDE_CODE_PLAYBOOK/`：

* **PLAN.template.md**：七层提示词映射的统一骨架
* **PROMPT.recipes.md**：实现/重构/缺陷/文档四类范式
* **BOUNDS.checklist.md**：白/黑名单示例、行数上限
* **EVAL.metrics.md**：指标定义与采集方法
* **RISK.cases.md**：真实踩坑与回滚策略
  下次同类任务，只改三处：目标、白名单、DoD。其余全部复用。
  ⸻

## [10. CI/评审对接（让机器"冷酷执法"）](#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. 反模式警示（越线即红灯）](#11-反模式警示越线即红灯)

**红灯警告（立即停止）：**

* **在同一长对话里来回修改**：上下文漂移、指令稀释、幻觉上升
* **让模型"扫全仓找入口"**：高风险 + 低确定性
* **一次性大改**：回滚难、定位难
* **无 DoD**：验收口径不统一，无法复现
* **把源码搬进存档**：破坏路径/构建链，后患无穷
  ⸻

## [模板：可直接使用的 PLAN.template.md](#模板可直接使用的-plantemplatemd)

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