07 - 人的操作手册
1. 定位
这是整套体系中最重要的一份文档。工具再好，如果人不知道自己该做什么、该看什么、该在哪里介入，整套体系就是摆设。
核心认知：你 80% 的时间花在"看"上 — 看方案、看代码、看测试结果、看审查报告。你是审查者，不是旁观者，也不是搬运工。
2. 三个角色定位
你 = 审查者 把控全局、定方向、审输出、做决策
AI = 执行者 快速但需约束的开发者
工具链 = 裁判 测试 + Lint + 类型检查 + Hooks（确定性保障）3. 人的五项核心职责
| 职责 | 具体动作 | 为什么不能交给 AI |
|---|---|---|
| 定方向 | 决定做什么功能、不做什么、优先级 | AI 不了解业务优先级和商业约束 |
| 审输出 | 逐行看 AI 生成的代码，判断合理性 | AI 无法评估自己的盲区 |
| 断风险 | 决定是否合并、是否部署、是否回滚 | 责任归属问题，不是能力问题 |
| 纠偏差 | 发现 AI 走偏时及时打断，重新引导 | AI 不知道自己偏了 |
| 沉淀规则 | 把 AI 犯过的错写入 CLAUDE.md | 需要人的经验判断 |
3.5 阶段级路线图
从"拿到一个需求"到"功能上线"的完整阶段流程。§4 日常循环是单个任务内部的微观操作，本节是跨阶段的宏观路线。
全流程总览
需求定义 ──→ 工程规格 ──→ 产品设计 ──→ 方案设计 ──→ 编码实现 ──→ 验证交付
/spec /prd /product- /plan §4 循环 /review + /test
│ │ design │ │ │
▼ ▼ │ ▼ ▼ ▼
spec.md prd.md ▼ plan.md + 代码变更 审查通过
product-spec 任务列表 → commit
design-spec
┌─────────────────────┐
│ /tech-research │
│ 可选旁路：任何阶段 │
│ 发现技术不确定性时 │
│ 按需触发 │
└─────────────────────┘各阶段操作要点
| 阶段 | 触发 Skill | 确认点（人审批后才进下一阶段） | 产出物 |
|---|---|---|---|
| 需求定义 | /spec | 清晰度评分 ≥ 90，用户确认 | docs/spec.md |
| 工程规格 | /prd | 数据模型、API 合约、状态机完整 | docs/prd.md |
| 产品设计 | /product-design | 页面注册表 + 状态矩阵 + 权限矩阵 + Token 系统完整 | docs/product-spec.md + docs/design-spec.md |
| 方案设计 | /plan | 实现路径合理，任务列表可执行 | 实现方案 + 任务列表 |
| 编码实现 | 按 §4 日常循环执行 | 每个任务通过验证闭环 | 代码变更 |
| 验证交付 | /review + /test | 审查通过 + 测试绿灯 | commit / PR |
/tech-research不是固定阶段，而是可选旁路。在需求定义或工程规格阶段发现技术不确定性时按需触发，调研结论写入 spec 或 prd。
阶段跳过规则
不是每个需求都走完五阶段。根据改动规模选择起始点：
| 改动规模 | 起始阶段 | 典型场景 |
|---|---|---|
| < 3 文件 | 直接动手或 /plan | Bug 修复、小功能、配置调整 |
| 需求明确 + 无技术不确定性 | /plan | 跳过 /spec、/prd、/product-design |
| 需求明确 + 涉及数据模型/API | /prd | 跳过 /spec |
| 有 UI + 多页面 | /product-design | 跳过 /spec（如需求已明确） |
| 需求模糊或全新领域 | /spec | 完整走一遍 |
阶段衔接
每个阶段的产出物是下一阶段的输入：
/spec → spec.md → 喂给 /prd
/prd → prd.md（数据模型 + API 合约）→ 喂给 /product-design
/product-design → product-spec.md + design-spec.md → 喂给 /plan 和 /ui-page
/plan → 任务列表 → 逐个进入 §4 日常循环
每个任务完成 → /review 审查 → /test 验证 → commit
全部完成 → /checkpoint 保存进度4. 日常操作循环
不是"指挥官的一天"那种理想化叙事，而是实际的操作序列：
┌─ 1. 启动任务 ──────────────────────────────────────────┐
│ 人：用一段话描述要做什么（清晰的 prompt） │
│ AI：读代码 → 出方案 │
│ 人：看方案 → 说"行"或"不行，改这里" │
├─ 2. 执行实现 ──────────────────────────────────────────┤
│ AI：写代码 │
│ 人：看 diff（这是最耗时的环节） │
│ 人：发现问题 → 指出来 → AI 改 │
│ 循环直到满意 │
├─ 3. 验证质量 ──────────────────────────────────────────┤
│ AI：跑测试、Lint │
│ 人：看结果，关注失败项 │
│ 人：（可选）在新会话中让 AI 审查 │
├─ 4. 提交（按逻辑单元，非按对话轮次）─────────────────────┤
│ 每个 commit = 一个可理解的、自洽的变更单元 │
│ AI：生成 commit message，执行提交 │
│ 人：如果 AI 犯了错，把教训写入 CLAUDE.md │
└────────────────────────────────────────────────────────┘4.5 验证优先工作流
官方最佳实践的第一条：给 AI 验证手段。没有验证闭环的代码生成就是在制造技术债。
4.5.1 原则
AI 生成的代码必须经过验证才算完成。"写完了"不是完成标志，"写完了 + 验证通过了"才是。
验证不仅是发现错误，更是建立信心的过程——你对代码的信心来自于看到测试绿灯，而不是"看起来对"。
4.5.2 三层验证体系
自动层（零成本，Hooks 触发）：
- tsc --noEmit → 类型检查
- eslint → 代码规范
- prettier → 格式化
每次文件保存自动执行，不需要人工干预
测试层（低成本，手动或 Hook 触发）：
- 单元测试 → 每改一个函数跑一次
- 集成测试 → 每完成一个模块跑一次
- 全量测试 → 提交前必跑
人工层（高成本，关键节点）：
- Diff 审查 → 每次 AI 修改后看 diff
- 三会话隔离 → 高风险改动开新会话审查
- 对抗性测试 → 让另一个会话尝试"打破"代码4.5.3 提示词模板
将验证嵌入到给 AI 的指令中：
"改完跑 [npm run test]，把结果告诉我。"
— 强制 AI 执行验证，而不是只报告"改完了"
"如果测试失败，停下来报告失败原因，不要自行修复。"
— 防止 AI 在错误方向上越走越远
"修改前后各截一次 UI 截图，让我对比。"
— UI 变更的视觉验证4.5.4 验证节奏
不同阶段的验证频率不同：
方案确认后 → 跑现有测试全绿（确认改动起点是干净的）
↓
每改一个模块 → 跑相关测试（及时发现问题）
↓
全部完成 → 全量测试 + lint + tsc（确认没有破坏其他模块）
↓
提交前 → /review（人工审查兜底）4.5.5 CLAUDE.md 规则模板
markdown
## 验证纪律
- MUST 每完成一个函数的修改就运行相关测试
- MUST 提交前运行 `npm run lint && npx tsc --noEmit && npm run test`
- MUST 测试失败时立即报告，不要自行猜测修复
- NEVER 跳过测试直接提交
- NEVER 修改测试来让它通过（除非测试本身有 Bug）5. 写好 Prompt 的要领
好 prompt 的四要素（速记：栈 + 范围 + 参考 + 指令）：
| 要素 | 作用 | 示例 |
|---|---|---|
| 技术栈约束 | 避免 AI 自选框架 | 用 Next.js App Router，不用 Pages Router |
| 具体范围 | 限制改动边界 | 只改 /app/api/users/route.ts |
| 参考上下文 | 保持代码风格一致 | 参考 @src/services/user.service.ts |
| 行动指令 | 明确下一步动作 | 先出方案不写代码 / 直接改 |
最常用的 5 条提示词：
"先读 [文件/目录]，理解上下文，然后再动手。"
"先出方案，列出要修改的文件和改动点，不要写代码。"
"只改 [具体文件/函数]，不要动其他地方。"
"改完跑一下测试，告诉我结果。"
"不要一次性重写整个模块。先做最小可验证的改动。"完整的场景级提示词模板见 Prompt Cookbook，进阶技巧见 15-Prompt 工程实战。
6. 审查 Diff 的优先级
不是每行代码都需要同等注意力：
必须仔细看 ──────────────────────────
安全相关：认证、权限、输入校验
数据操作：数据库写入、删除、迁移
外部调用：API URL、请求参数、错误处理
共享类型：接口定义、类型变更
快速扫过 ────────────────────────────
UI 组件：样式、布局（视觉上对就行）
测试代码：关注场景覆盖是否全面
可以跳过 ────────────────────────────
自动格式化产生的 diff
import 顺序调整
纯注释变更7. 何时打断 AI
必须在以下时刻立即打断（Ctrl+C 或 Esc）：
| 信号 | 说明 |
|---|---|
| 修改了你没提到的文件 | AI 在"擅自做主" |
| 引入了新的依赖包 | 需要评估是否在白名单中 |
| 删除了现有代码而不是修改 | 可能破坏现有功能 |
| 方案和你预期方向不同 | 越早纠正成本越低 |
| 开始重复犯同一个错 | 上下文可能退化了 |
| 生成了大段你看不懂的代码 | 复杂度失控的信号 |
打断后的标准动作：
- 明确告诉 AI 哪里不对
- 给出正确方向
- 如果是上下文退化，执行
/compact或/clear
8. 上下文管理
何时用新会话 vs 继续当前会话
继续当前会话：
- 同一个功能的后续工作
- 修复刚才代码的问题
开新会话：
- 切换到不同功能
- 审查自己刚写的代码（三会话隔离）
- 当前会话出现上下文退化信号
- 任务完成，开始下一个任务上下文退化的信号
| 信号 | 对策 |
|---|---|
| 重复之前被否决的方案 | /compact 带保留指令 |
| 忘记 CLAUDE.md 中的规则 | /compact 或 /clear 重新开始 |
| 同一个错误修了又犯 | /clear，在新会话中重新描述任务 |
| 回答变得笼统、不具体 | /compact 或 /clear |
| 开始产生幻觉（编造不存在的 API） | 立即 /clear |
主动压缩
上下文达到约 70% 时：
/compact 保留所有已修改文件路径、当前任务进度、测试命令和架构决策上下文管理的系统性策略详见 13-上下文管理策略。
9. CLAUDE.md 维护纪律
这是唯一需要人主动写的文件。
何时更新
每次 AI 犯错，花 30 秒加一条规则：
markdown
## 常见陷阱
- 不要用 moment.js，用 date-fns（2026-02-10 犯过）
- Prisma 的 findUnique 返回 null 不是 undefined（2026-02-12 犯过）
- Next.js App Router 中 API Route 不要用 req.body，用 req.json()（2026-02-15 犯过）定期清理
每月花 10 分钟：
- 删除不再适用的规则
- 合并重复条目
- 确认总指令数不超过 150 条
更新提示词
回顾我们这次对话中你犯的错误和我纠正过的地方，
把需要长期记住的教训更新到 CLAUDE.md 的"常见陷阱"章节。
只加真正有价值的条目，不要加显而易见的东西。10. 认知管理
10.1 信任校准
AI 在不同任务类型上的可信度不同，审查力度应匹配：
| 可信度 | 任务类型 | 审查策略 |
|---|---|---|
| 高 | 格式转换、模板生成、重构（保持行为不变）、测试生成 | 快速扫过，关注边界条件即可 |
| 中 | 新增独立功能、Bug 修复、API 实现 | 逐个 diff 审查，重点看逻辑 |
| 低 | 业务规则实现、安全边界、数据迁移、架构决策 | 逐行审查 + 对抗性测试 |
实操：对高可信度任务不必逐行看；对低可信度任务不要因为"AI 写的看起来对"就跳过审查。
10.2 认知负载预算
人的审查质量会随负载下降。以下是实战中观察到的阈值：
单次会话审查上限：
- 新增代码：~300 行（超出后注意力显著下降）
- 修改代码：~10 个文件（超出后容易漏审）
- 连续审查时长：~45 分钟（之后强制休息）
超出阈值的处理：
- 拆分为多个会话，每个会话一个聚焦点
- 会话之间留 5 分钟间隔切换心理状态
- 把最关键的审查放在精力最好的时段10.3 跨会话学习
每次会话结束时，花 2 分钟回答三个问题（可以只在脑中过一遍）：
1. 哪个 prompt 效果好？ → 考虑沉淀为 Skill 或记入 CLAUDE.md
2. 哪里浪费了时间？ → 下次避免（如：没先读代码就让 AI 改）
3. AI 犯了什么新错？ → 写入 CLAUDE.md 常见陷阱这三个问题是认知层面最落地的实践。不需要写下来，但需要有意识地做。
11. 提交与审查的粒度
提交粒度：按逻辑单元
核心原则：小步频繁提交，每个 commit 是一个可理解的、自洽的变更单元。
| 场景 | 策略 |
|---|---|
| 完成一个完整功能点或修复一个 bug | 立即 commit |
| 重构了一段代码且测试通过 | 立即 commit |
| 连续迭代同一个功能（框架→细节→样式） | 积累到功能完成再 commit |
| 探索性修改，方案未定 | 暂不 commit，定型后再提交 |
判断标准：commit message 能用一句话说清做了什么；不相关的改动不混入同一个 commit。
审查粒度：按功能单元
- Review 在 PR/MR 级别进行，覆盖一组相关的 commit
- 关注最终结果是否正确，而非中间重构步骤
- 不需要逐 commit 审查（除非团队明确要求）
一句话总结：按逻辑单元提交，按功能单元 review。
12. 每日开发检查清单
□ 任务已拆解为可独立验证的子任务
□ 已创建功能分支（不在 main 上直接开发）
□ 现有测试全部通过后才开始写新代码
□ AI 的方案已审查并确认再执行
□ 每完成一个逻辑单元就运行测试
□ 新代码已补充测试用例
□ 代码 diff 已审查（重点：安全、数据操作、外部调用）
□ 按逻辑单元 commit，message 清楚说明 why
□ 如果 AI 犯了错 → 更新 CLAUDE.md