12 - 效率最佳实践

1. 定位

前面 11 份文档定义了体系的"骨骼和器官"。这份文档是"血液"—— 贯穿在日常操作中的高效习惯和模式，不属于任何一个子系统，但决定了整套体系的实际效率。

来源：AI 辅助开发实战中反复验证过的模式和反模式。

2. 锚定文件模式（效率提升最大的单个技巧）

问题

AI 从零生成代码时，风格、结构、错误处理方式都是"猜"的。即使 CLAUDE.md 写了规范， AI 也经常产出和项目现有代码风格不一致的代码。

解决

给 AI 一个项目中已有的类似实现作为"锚点"：

❌ "实现用户删除 API"

✅ "参考 /app/api/users/route.ts 中创建用户的实现方式，
   实现用户删除 API。保持相同的：
   - 请求校验方式（zod schema）
   - 错误处理模式（AppError）
   - 响应格式（{ data, error }）"

效果

AI 输出和现有代码风格高度一致
不需要在 CLAUDE.md 里写过于细节的规范
减少审查负担（输出格式可预期）

适用场景

场景	锚定文件
新增 API Route	参考现有的一个 Route
新增 Service	参考现有的一个 Service
新增组件	参考现有的一个类似组件
新增测试	参考现有的一个测试文件
新增页面	参考现有的一个页面

写入 CLAUDE.md 的规则

markdown

## 代码风格

新增代码时，优先参考项目中已有的类似实现，保持风格一致。
不要凭空创造新的模式，先搜索项目中是否有可参考的实现。

3. 契约先行工作流

问题

先写实现再写测试，测试容易变成"验证实现细节"而非"验证行为正确"。重构时测试全部报红，不是因为行为变了，而是因为实现细节变了。

解决：Types → Tests → Implementation

第一步：定义类型契约
  ↓
  // types/document.ts
  export type CreateDocumentInput = {
    title: string
    content: string
    tags: string[]
  }

  export type CreateDocumentOutput = {
    id: string
    title: string
    createdAt: Date
  }

第二步：基于契约写测试
  ↓
  // 测试只依赖输入输出类型，不依赖实现
  test('should create document', async () => {
    const input: CreateDocumentInput = { ... }
    const result = await createDocument(input)
    expect(result.id).toBeDefined()
    expect(result.title).toBe(input.title)
  })

第三步：实现代码
  ↓
  // 让类型和测试都通过
  export async function createDocument(
    input: CreateDocumentInput
  ): Promise<CreateDocumentOutput> { ... }

给 AI 的提示词

"先定义这个功能的输入输出类型（放到 types/ 目录），
然后基于类型契约写测试（不要看实现），
最后实现代码让测试通过。"

为什么对 AI 开发特别有效

AI 有明确的目标（让类型检查通过 + 让测试通过）
类型契约是"可验证的规范"，比自然语言描述精确
重构时只要契约不变，测试自动保护你

3.5 按规模选择开发模式

不同规模的功能适用不同深度的流程。小功能不需要 PRD，大功能不能跳过设计。

规模	判断标准	推荐流程
小	改动 < 3 文件，无新数据模型	`/plan`（轻量）→ 实现 → `/review` → `/commit`
中	跨模块，有新 API 或数据模型	`/plan`（含精简 PRD + 契约先行）→ 分模块实现 → `/review`
大	新子系统，> 5 文件，跨多个会话	`/plan`（含 PRD + 技术设计 + 实现顺序）→ 按模块分会话 → 每模块 `/review` → 最终 `/review`

大功能的实现顺序模式

大功能按依赖关系分 4 个阶段推进，每个阶段完成后提交并验证：

Phase 1 — Foundation：数据模型、数据库迁移、共享类型
Phase 2 — Core：      核心业务逻辑，一次一个模块，边写边测
Phase 3 — Integration：模块连接、集成测试、对照验收标准验证
Phase 4 — Polish：     错误处理改善、日志、性能优化、文档更新

规模判断时机

在 /plan 的步骤 1"理解需求"中自然完成。不需要额外流程——当 /plan 发现功能满足中大规模条件时，自动切换到结构化需求采集路径（详见 02-Skills 技能体系）。

4. 会话规划策略

问题

大量效率损失来自漫无目的的会话。常见模式：

开始 → 聊了 20 分钟 → 跑偏了 → 上下文满了 → 没做完 → 重来

解决：每个会话开始前花 30 秒回答三个问题

1. 这个会话要完成什么？（一句话目标）
2. 会涉及哪些文件？（大致范围）
3. 完成标志是什么？（怎么判断做完了）

四种会话类型

明确会话类型，不要混用：

类型	目标	时长	结束标志
探索会话	理解代码、调研方案	短	输出分析报告或方案
实现会话	写代码、实现功能	中	测试通过、代码提交
审查会话	审查代码、找问题	短	输出审查报告
修复会话	修 Bug、解决问题	短	Bug 修复、回归测试通过
架构决策会话	分析系统问题、规划重构	中	输出决策文档或 ADR

不要在实现会话中做探索，不要在审查会话中写代码。 混合类型的会话效率最低。

架构决策会话的使用时机：当 /health-report 显示系统性问题、同一模块反复出 Bug、或新功能需要跨多个模块协调时。这类会话只分析不写码，输出是决策和计划。

会话开场模板

探索会话：
"我需要理解 [模块名] 的架构和数据流。
请阅读相关代码，给我一份总结。不要写任何代码。"

实现会话：
"这个会话的目标：实现 [功能名]。
涉及文件：[列出]。
完成标志：[描述] + 测试通过。
先出方案，确认后开始。"

审查会话（新开会话）：
"审查 git diff main..feature/xxx 中的所有改动。
以资深审查者角色，重点关注 [具体关注点]。"

修复会话：
"Bug 描述：[现象]。
请先定位根因，确认后再修复。
修复时必须先写回归测试。"

会话中的效率技巧

1. 用 @ 引用文件代替粘贴代码
   ✅ "参考 @src/services/user.service.ts 的模式"
   ❌ 粘贴 200 行代码到对话中

2. 用 git diff 给 AI 精确上下文
   "看一下 git diff --stat，基于变更内容做审查"

3. 单一职责
   ✅ "实现用户删除功能"（一个任务）
   ❌ "实现用户删除，顺便优化一下列表页性能"（两个不相关任务）

4. 及时提交
   每完成一个可工作的状态就 commit，不要等"全部做完"
   好处：给你回滚点，给 AI 的 git diff 更有意义

5. Prompt 反模式（绝对不要做的事）

3 条致命反模式（立即停止）：

反模式	正确做法
"帮我做这个系统"	拆解为 5-10 个独立子任务，逐个完成
不给约束让 AI 自由发挥	给技术栈、文件范围、风格参考
连续给 20 条指令不看输出	每 1-2 步看一次输出，确认正确再继续

3 条低效反模式（显著降低效率）：

反模式	正确做法
每次从零描述项目背景	写好 CLAUDE.md，AI 自动加载
在一个会话里做完所有事	不同类型任务用不同会话
AI 犯了错只是口头纠正	写入 CLAUDE.md 常见陷阱

完整的反模式分析见 15-Prompt 工程实战 §4，场景级提示词模板见 Prompt Cookbook。

6. 错误恢复工作流

AI 改崩了代码怎么办

按严重程度分级处理：

Level 1：AI 改了一个文件，改错了
  → git checkout -- [文件路径]      恢复单个文件
  → 告诉 AI 哪里改错了，重新改

Level 2：AI 改了多个文件，部分改错了
  → git diff 看清楚哪些改动是对的
  → git stash                       先暂存所有改动
  → git stash show -p               查看暂存内容
  → 手动或让 AI 挑选正确的改动重新应用

Level 3：AI 大面积改崩，测试全红
  → git stash 或 git reset HEAD     回到最后一次提交
  → /clear 开新会话
  → 拆解为更小的步骤重新执行
  → 这次每步都跑测试

Level 4：AI 改了你不理解的东西，不确定对不对
  → 不要合并！
  → 新开审查会话让 AI 解释每个改动
  → 不理解的改动一律不要

预防比恢复更重要

1. 频繁提交（每个可工作状态都 commit）
   → 回退成本从"丢失 2 小时工作"降为"丢失 10 分钟工作"

2. 功能分支（不在 main 上开发）
   → 最坏情况：删掉整个分支重来

3. 小步快跑
   → 每次只让 AI 改一个函数/一个文件
   → 改完跑测试确认再继续

写入 CLAUDE.md 的规则

markdown

## 安全操作

- 每完成一个可工作的状态就 git commit
- 如果测试失败，立即停下告诉我，不要自行猜测修复
- 如果需要改超过 5 个文件，先列出改动计划等我确认
- 改动共享类型时，先搜索所有引用点

7. 项目词汇表

问题

AI 经常误解业务领域的术语。比如你说"文档"，AI 可能理解为"代码文档"而不是"知识库里上传的文件"。

解决

在 CLAUDE.md 中加一个词汇表章节：

markdown

## 项目词汇表

以下术语在本项目中有特定含义，不要按通用理解解释：

| 术语 | 本项目含义 | 不是 |
|------|-----------|------|
| 文档（Document） | 知识库中上传的文件（PDF/DOCX/MD） | 不是代码注释或 README |
| 空间（Space） | 一组相关文档的容器，类似文件夹 | 不是物理空间 |
| 成员（Member） | 有账号的内部员工 | 不是外部用户 |
| 标签（Tag） | 文档的分类标记 | 不是 HTML 标签 |

为什么有效

AI 在整个会话中都会使用正确的术语含义，减少沟通歧义。特别是在有中英文混用的项目中，这个词汇表能避免大量误解。

8. @ 引用策略

@文件路径 将文件内容引入上下文。用对了省时间，用错了浪费上下文。

✅ 用 @ 引用：锚定文件、要修改的目标文件、类型定义文件
❌ 不用 @ 引用：大文件（> 500 行）、整个目录、不确定的文件

选择依据：
  明确知道哪个文件 → @ 引用（最快）
  大致知道在哪     → 让 AI 用 Glob/Grep（准确）
  完全不知道       → 让 AI 用 Explore Agent（全面）

9. 检查点提交模式

核心原则：每个可工作的状态都提交，不等"全部做完"。

提交节奏示例（用户 CRUD）：
  feat(user): add User type and Prisma schema    → 可编译
  feat(user): add createUser service              → 测试通过
  feat(user): add POST /api/users route           → API 可调用
  feat(user): add user creation form              → 前端可用

好处：每个 commit 都是回滚点；git diff HEAD~1 让审查更聚焦；git bisect 精确定位引入 Bug 的 commit。

10. "先读后写"强制执行

问题

AI 最常见的错误：没读现有代码就开始写，导致和现有模式不一致，或者重复造轮子。

解决

CLAUDE.md 中已有"先查后建"原则，但需要更具体的执行方式：

markdown

## 先读后写

修改任何文件之前，MUST 先用 Read 工具阅读该文件的完整内容。
实现新功能之前，MUST 搜索项目中是否已有类似功能。
引用任何类型或函数之前，MUST 确认其确实存在于项目中（不要编造）。

实际效果

防止 AI 最常见的三类错误：

编造不存在的 API / 函数 / 类型
和现有代码风格不一致
重复实现已有的功能

11. Skill 使用频率预判

基于实战经验，11 个 Skill 的实际使用频率预测：

每天用：
  /plan          开始新任务
  /commit        提交代码
  /review        审查变更
  /retro         会话回顾（沉淀经验）
  code-standards 自动参考（不用手动调用）

每周几次：
  /test          补测试
  /debug         修 Bug
  /impact        改动前分析

偶尔用：
  /doc           更新文档
  /ui-page       新增页面
  /check         合规体检
  /health-report 健康度报告
  /takeover      接管项目（一次性）

建议：先配前 5 个就开始用（plan + commit + review + retro + code-standards）。其余按需逐步添加。不要一次配 14 个然后不知道用哪个。

11.5 成本意识

AI API 调用有真实成本。个人开发者应该了解不同工作模式的开销，做出理性取舍。

成本量级参考

基于 2026 年初定价（每百万 token）：Opus 4.6 $5/$25（1x）、Sonnet 4.6 $3/$15（~0.6x）、Haiku 4.5 $1/$5（~0.2x）。

典型场景的大致费用：

工作模式	Sonnet 4.6	Opus 4.6
单次 /plan（小功能）	~$0.05	~$0.08
单次实现会话（1 个功能）	~$0.24	~$0.40
/review + 三会话隔离审查	~$0.33	~$0.55
完整日开发（3-5 个功能）	~$1.35	~$2.25

注：以上为估算值，实际消耗取决于项目规模、上下文长度和交互轮数。

成本优化策略

高 ROI（优先做）：
  - CLAUDE.md 写好     → 减少每次重复描述背景的 token
  - 会话规划 + 单一职责 → 减少跑偏和重来的浪费
  - 锚定文件模式       → 减少 AI 试错的轮数
  - 频繁提交           → 出错回退成本低，不用整个会话重来

低 ROI（按需使用）：
  - 三会话隔离审查     → 成本是单会话的 3 倍，仅对高风险改动使用
  - Explore Agent 广泛搜索 → token 消耗大，明确目标时用 Grep/Glob 替代
  - /health-report     → 每两周一次够了，不需要每天跑

模型选择策略

用 Sonnet 4.6（默认）：日常开发、/commit、/doc、/test、子代理
用 Opus 4.6：         架构设计、安全审查、复杂 Bug 诊断、/plan（大功能）
用 Haiku 4.5：        分类/路由/高吞吐后台任务

Opus 4.6 成本约为 Sonnet 4.6 的 1.67 倍（旧款 Opus 4 曾高达 5 倍）。编码基准测试上两者差距已很小（SWE-bench 80.8% vs 79.6%），但 Opus 在长上下文推理和复杂指令跟随上仍有优势。当 Sonnet 反复出错需要纠正时，切换到 Opus 反而更省——少走弯路省下的 token 远超模型差价。

月度成本预期

轻度使用（每天 1-2 小时）：$20-50 / 月
中度使用（每天 3-4 小时）：$60-120 / 月
重度使用（全天开发）：    $150-300 / 月

控制成本的核心不是少用 AI，而是每次交互都高质量——好的 prompt、清晰的约束、及时的打断。

12. 总结：十条效率军规

从全部 12 份设计文档中提炼，每条都对应一个可操作的习惯：

 1. 锚定文件  每次新增代码，先给 AI 一个现有的类似实现做参考
 2. 契约先行  先定类型 → 再写测试 → 最后实现
 3. 会话规划  开始前 30 秒：目标、范围、完成标志
 4. 单一职责  一个会话一个任务，不混合
 5. 小步验证  改一个函数跑一次测试，不积累
 6. 频繁提交  每个可工作的状态都 commit
 7. 先读后写  AI 修改任何文件前必须先读
 8. 及时打断  AI 跑偏立即 Ctrl+C，越早纠正成本越低
 9. 错误沉淀  AI 犯的错写入 CLAUDE.md，不犯第二次
10. 不要过度  能用就行，不要让 AI "顺手优化"

何时可以打破军规： 规则服务于效率，不是反过来。当严格遵守军规的成本明显高于违反时（如紧急线上修复不必走完整 /plan 流程），可以跳过，但事后必须补齐（补测试、补审查）。判断标准：跳过是有意识的决策，不是因为懒。

12 - 效率最佳实践 ​

1. 定位 ​

2. 锚定文件模式（效率提升最大的单个技巧） ​

问题 ​

解决 ​

效果 ​

适用场景 ​

写入 CLAUDE.md 的规则 ​

3. 契约先行工作流 ​

问题 ​

解决：Types → Tests → Implementation ​

给 AI 的提示词 ​

为什么对 AI 开发特别有效 ​

3.5 按规模选择开发模式 ​

大功能的实现顺序模式 ​

规模判断时机 ​

4. 会话规划策略 ​

问题 ​

解决：每个会话开始前花 30 秒回答三个问题 ​

四种会话类型 ​

会话开场模板 ​

会话中的效率技巧 ​

5. Prompt 反模式（绝对不要做的事） ​

6. 错误恢复工作流 ​

AI 改崩了代码怎么办 ​

预防比恢复更重要 ​

写入 CLAUDE.md 的规则 ​

7. 项目词汇表 ​

问题 ​

解决 ​

为什么有效 ​

8. @ 引用策略 ​

9. 检查点提交模式 ​

10. "先读后写"强制执行 ​

问题 ​

解决 ​

实际效果 ​

11. Skill 使用频率预判 ​

11.5 成本意识 ​

成本量级参考 ​

成本优化策略 ​

模型选择策略 ​

月度成本预期 ​

12. 总结：十条效率军规 ​

12 - 效率最佳实践

1. 定位

2. 锚定文件模式（效率提升最大的单个技巧）

问题

解决

效果

适用场景

写入 CLAUDE.md 的规则

3. 契约先行工作流

问题

解决：Types → Tests → Implementation

给 AI 的提示词

为什么对 AI 开发特别有效

3.5 按规模选择开发模式

大功能的实现顺序模式

规模判断时机

4. 会话规划策略

问题

解决：每个会话开始前花 30 秒回答三个问题

四种会话类型

会话开场模板

会话中的效率技巧

5. Prompt 反模式（绝对不要做的事）

6. 错误恢复工作流

AI 改崩了代码怎么办

预防比恢复更重要

写入 CLAUDE.md 的规则

7. 项目词汇表

问题

解决

为什么有效

8. @ 引用策略

9. 检查点提交模式

10. "先读后写"强制执行

问题

解决

实际效果

11. Skill 使用频率预判

11.5 成本意识

成本量级参考

成本优化策略

模型选择策略

月度成本预期

12. 总结：十条效率军规