第 7 章：心法层

Boris Cherny 的 9 条实战心法与团队推广经验

Boris Cherny 是 Anthropic Claude Code 团队的工程师，他在 Anthropic 官方博客发表的 "Claude Code Best Practices"（2025 年 4 月）成为 AI 协作领域被引用最广的实战指南之一。该文章与他后续的多次公开演讲、社区分享共同构成了"Claude Code 工程心法"的事实基础。本节将其浓缩为 9 条可立即落地的心法，并补充本人在多个团队推广 Claude Code 时积累的经验。

需要先澄清一点：这 9 条心法不是从 Boris Cherny 原文逐字复述——原文以英文写作、带有大量的具体场景细节，并不直接对应 9 条编号。本节做的是结构化提炼：把 Boris 多篇文章与公开演讲中反复出现的核心主张，归纳为 9 条便于团队记忆与推广的心法。每一条都标注其在 Anthropic 公开材料中的对应章节或观点，确保不偏离原意。读者需要原文细节时，建议直接阅读延伸阅读中的 Anthropic 官方博客与演讲录像。

本节的另一个目的是——把"工程师心法"翻译成"团队推广方法论"。一个工程师懂得 9 条心法是个人能力，让一个 8 人团队全员实践 9 条心法是组织能力。后者远比前者难，本节后半部分的"团队推广经验"专门讨论这部分。

为什么是 9 条而不是 10 条或 5 条：心法数量的选择本身就是一种刻意的设计权衡——5 条太少（覆盖不全工程实践的全貌）、15 条太多（团队记不住）、9 条恰好覆盖"基础 + 机制 + 价值观"三大层次（每层 3-4 条）、且符合人类短期记忆的"7±2"边界（通常被称为 Miller's Law）。读者在传播这些心法时也建议保持 9 条编号，便于团队内的统一引用——"我们违反了第 8 条"比"我们违反了人类决策权那条"更精确、更易在压力情境下被识别。这种"编号即简称"的设计，是任何团队规范在长期演化中保持不变形的关键。

第一条：CLAUDE.md 是项目记忆的根基

心法：每个项目都应当维护一份 CLAUDE.md，作为团队与 AI 共享的"项目记忆"。它不是设计文档，也不是 README——它是"高频偏差校正器"，专门记录 AI 反复犯错的点、团队反复达成的共识。

Anthropic 官方观点（来自 Claude Code Best Practices）：CLAUDE.md 在每次会话开始时自动注入，是塑造 Claude 行为最直接的杠杆。它应当包含：项目结构概览、命令惯例、风格约定、关键技术决策。

PM 视角

PM 不需要懂 Markdown 语法，但需要理解：你写在 CLAUDE.md 里的每一条业务规则，都会在工程师每次与 Claude 协作时被自动注入。这意味着 CLAUDE.md 的质量直接决定 AI 协作的"语义底色"。一份描述清晰的 CLAUDE.md 让 Claude 知道"这个产品给谁用"、"哪些数据是敏感的"、"哪些边界不能跨"——业务约束转化为代码约束的转换效率会显著提升。

PM 在 CLAUDE.md 维护中的具体角色：很多 PM 会把"维护文档"理解为工程师的事，但 CLAUDE.md 是少数 PM 应当主动参与的工程产物——

业务规则段落：PM 直接撰写、明确措辞、举具体例子。例如"用户邮箱必须唯一"、"批量操作必须支持中断恢复"。这些规则工程师未必清楚业务源头，但写下去后会直接影响 Claude 生成的代码。
优先级声明：在功能开发期，PM 可以临时加一条"本周优先 user 模块、其他模块的修改请等下周"。这种"焦点声明"让 Claude 自动避开非优先模块。
客户/法务红线：PM 经常是第一手知道"哪些数据不能让 AI 处理"、"哪些动作有合规风险"的人。把这些红线写进 CLAUDE.md，比让工程师"猜"高效得多。

PM 与工程师协作维护 CLAUDE.md 的健康节奏——工程师每周更新技术细节，PM 每两周更新业务规则。两个角色在同一份文档上协作，让 Claude 同时理解"代码该怎么写"与"产品该往哪走"。这种 PM-工程师在工程产物上的深度协作，是传统软件工程罕见的——但在 AI 协作时代会变得越来越普遍。

工程师视角

CLAUDE.md 的反模式是过度膨胀——把所有"可能用得上"的信息都塞进来。500 行以上的 CLAUDE.md 不仅占用上下文 Token，而且会稀释 Claude 对每条规则的关注度。本人推荐的健康长度是 200-400 行，分为以下几个部分：

# Project: [项目名]

## Tech Stack（技术栈）
- TypeScript 5.x + Vue 3 + Vite
- Vitest for unit, Playwright for e2e
- ESLint flat config + Prettier

## Conventions（约定）
- 命名：camelCase for vars, PascalCase for types
- 文件：feature-based 目录结构
- 测试：每个模块独立 __tests__/ 子目录

## Critical Rules（铁律）
- 所有自定义错误继承 BaseError
- API 路径以 /api/v1/ 开头
- 永远不直接修改生产数据库

## Recent Decisions（近期决策）
- 2026-04-15: 切换到 Drizzle ORM（之前是 Prisma）
- 2026-04-20: 启用 strict mode

## Common Mistakes Claude Makes Here（这里 Claude 容易犯的错）
- 写 SQL 时容易漏 transaction wrapper
- 测试时容易忘记 mock 外部 API

最后一节"Common Mistakes"是本人加的——它专门记录"在这个项目里 Claude 反复犯过的错"。每次发现新错误就追加一条，半年后这部分就成了团队最宝贵的"AI 协作教训库"。

实战示例

# 反模式：CLAUDE.md 写成抽象规则
"代码要规范、错误要处理、测试要全面"

# 正确：CLAUDE.md 写成具体约束
"所有自定义错误继承 src/errors/BaseError.ts；
错误必须含 field 与 resource 上下文；
单元测试覆盖率 ≥ 90%、单个测试时长 ≤ 2 秒"

CLAUDE.md 维护的"减法心法"：

CLAUDE.md 的最大反模式不是"写得太少"，而是"写得太多但都没人看"。本人见过 1500 行的 CLAUDE.md——前两年攒下的所有规则都在里面，但 70% 已经过时、20% 互相冲突、只有 10% 在真正影响 Claude 行为。这种状态比"没有 CLAUDE.md"还糟糕——因为它给了团队"我们已经把规范写下来了"的错觉。

每月一次"减法 review"——逐条审视：

这条规则过去 30 天有没有被违反过？ 如果没有，可能已经内化为团队习惯，可以删除。
这条规则与其他规则有没有矛盾？ 矛盾的规则必须二选一或合并。
这条规则是否已被工具自动化？ 例如已被 Hook 拦截的规则可以从 CLAUDE.md 删除。

减法 review 的目标——让 CLAUDE.md 始终保持"100% 活跃服役"的状态。每条规则都在真正塑造 Claude 行为，没有一条是装饰。

第二条：把"一个会话只做一件事"内化为习惯

心法：单次会话的边界应当与单个迭代单元对齐——一次会话只做一件事，做完就开新会话。

Anthropic 官方观点：长会话会因上下文累积、注意力稀释而导致质量下降。Claude Code 的 /compact 与 /clear 命令是为这条心法设计的工具。

PM 视角

PM 看工程师工作时，有时会困惑为什么"明明在做同一个功能、却频繁切换会话"。这条心法的本质是注意力资源的纪律性管理——每次会话开新等同于"工程师把脑子从旧任务清空、聚焦到新任务"。这种"主动清场"听起来繁琐，但带来的输出质量差异是数倍级的。理解这条之后，PM 在 sprint planning 时会更主动地把"功能"拆成"故事"再拆成"任务"——拆得越细，AI 协作的边际效益越高。

工程师视角

判断"是否该开新会话"的标准：

✅ 应该开新会话：换主题（从 user 模块切到 order 模块）、上一任务完成、上下文已超 30K Token
❌ 不要开新会话：还在做同一个函数的迭代、还在调试同一个 bug、距离开始才 5 分钟

参考 7.2 节的"15 分钟到 90 分钟"原则——这是会话的甜蜜区。

判断"会话该结束"的四个隐性信号：

Claude 开始重复确认早前已经说过的事实——说明它的注意力开始稀释
Claude 输出的代码风格突然偏离项目惯例——说明 CLAUDE.md 的位置效应失效
工程师开始觉得"再交代一遍很麻烦"——说明上下文已经混乱到工程师都不愿意维护
工具调用结果开始被自动截断——说明上下文窗口接近上限

任何一个信号出现都应当主动结束会话。不要心疼"投入的对话历史"——更宝贵的是当下的判断力。

实战示例

# 反模式：一个会话从早到晚
"帮我做用户管理模块" → 写代码 → 调试 → 写测试 → 写文档 → 修 bug → ...
（4 小时后 Claude 已经混淆了字段名、写出错误代码）

# 正确：拆成多次会话
会话 1（45 分钟）：定义类型 + CRUD
会话 2（45 分钟）：补单元测试
会话 3（30 分钟）：补集成测试
会话 4（30 分钟）：写文档

第三条：Plan 模式优于乐观执行

心法：高风险变更前，先让 Claude 输出 Plan、人工审批后再执行——比"先执行再 review"安全得多。

Anthropic 官方观点：Claude Code 内置的 Plan 模式（--permission-mode plan）是为了对抗"AI 乐观执行"的反面机制。在该模式下，任何写文件、跑命令的动作前都会被强制中断、要求审批。

PM 视角

PM 不需要使用 Plan 模式，但需要理解它的存在意义——它把"AI 自动决策"降级为"AI 提议、人类审批"。这条机制的价值在高风险场景下尤为明显：架构重构、数据迁移、生产部署。让 Claude 先输出一份"我打算做的所有动作"，PM 也可以参与 review，从业务视角识别"这个 plan 是否符合需求"。

工程师视角

什么时候用 Plan 模式：

✅ 涉及生产环境
✅ 涉及数据库 schema
✅ 跨 5 个以上文件的变更
✅ 首次进入陌生代码库
✅ 任何让你"心里不踏实"的操作

切换方式：

# 启动时
claude --permission-mode plan

# 会话中临时
/plan

Plan 模式的"心理成本"与对抗策略：很多工程师在尝试 Plan 模式后会反馈"太繁琐了、每一步都要确认"。这种感受合理但需要被对抗——繁琐不是 Bug，是 Feature。Plan 模式刻意让"自动执行"变得不那么轻松，目的是让工程师在按下"批准"前停下来思考一秒。这一秒的延迟正是它的价值所在——大部分错误都是"想得不够清楚就动手"造成的。

减少 Plan 模式繁琐感的几个技巧：

批量审批：让 Claude 一次输出完整 plan（10 步、20 步），不要分次产出。一次审批整个 plan 比分 20 次审批省时间。
Plan 模板化：要求 Claude 用统一模板输出 plan（"动作清单 / 预期效果 / 风险点 / 回滚方案"），工程师审阅时按模板对照，速度更快。
Plan 模式仅限高风险任务：日常迭代不开 plan 模式，只在涉及生产、数据、架构时切换。低风险任务用 default 或 acceptEdits 模式保持高效。

实战示例

# 反模式：直接让 Claude 重构
"帮我把整个 user 模块重构为 hexagonal architecture"
→ Claude 一次性改了 18 个文件，工程师审查时疲惫漏掉关键 bug

# 正确：先 Plan 再 review
"我想把 user 模块重构为 hexagonal architecture。
请先进入 plan 模式，输出：
1. 涉及的文件清单（保留 / 新增 / 删除）
2. 每个文件的关键变更
3. 重构的执行顺序
4. 每一步的验证方式

输出 plan 后等我审批，不要直接动手。"

第四条：Skills 让团队最佳实践跨项目复用

心法：高频任务模式应当封装为 Skills，让最佳实践跨成员、跨项目复用。

Anthropic 官方观点：Skills 是 Claude Code 提供的"可复用提示词资产"，每个 Skill 是一个 SKILL.md 文件 + 可选的辅助资源。它们在被显式调用时才占用上下文，平时不消耗 Token。

PM 视角

PM 可以把 Skills 理解为"团队的 SOP（标准操作流程）"——每一份 Skill 都是团队对某一类任务的"最佳做法"沉淀。当团队对"用户调研报告应该有哪些段落"有共识，就可以做一个 user-research-report skill；当工程师对"如何起草一份 ADR"有共识，就可以做一个 adr-draft skill。Skills 让团队的隐性知识显性化、显性知识可执行化。

工程师视角

Skills 的设计三原则：

小而专：每个 Skill 只解决一个清晰场景
示例先行：在 SKILL.md 中放 2-3 个真实运行示例
可被人类阅读：100-300 行之间，结构清晰

# .claude/skills/crud-repository/SKILL.md
---
name: crud-repository
description: 为某个领域实体生成完整的 CRUD repository（含类型、校验、测试）
---

## 适用场景
- 新增一个领域实体的存储层
- 需要完整 CRUD + 边界处理 + 单元测试

## 输入要求
- 实体名（PascalCase）
- 字段列表（含类型与约束）

## 步骤
1. 在 src/<entity>/ 下创建 types.ts、repository.ts、errors.ts
2. 写 4 个 repository 函数：create / get / update / delete
3. 在 src/<entity>/__tests__/ 下创建对应测试
4. 测试覆盖率必须 ≥ 90%

## 验收标准
- pnpm typecheck 通过
- pnpm test 全部通过
- 与项目现有 repository 风格一致

## 已知边界
- 不处理跨实体事务
- 不处理软删除（如需要走单独 skill）

Skills 库的"生命周期管理"：Skills 不是一次写好就一劳永逸——它需要持续维护、淘汰、迭代。本人推荐的生命周期：

创建（New）：首次发现某个高频模式时，由发现者起草 SKILL.md。
试用（Trial）：试用 1-2 周，至少被 3 名工程师在不同场景使用。
稳定（Stable）：通过试用，进入团队 Skills 库正式维护。
演化（Evolved）：根据使用反馈持续优化（每月 review 一次）。
淘汰（Deprecated）：当原有需求消失或被新 Skill 覆盖时主动淘汰。

把这五个状态写在 SKILL.md 的 frontmatter 里：

---
name: crud-repository
status: stable    # new / trial / stable / evolved / deprecated
created: 2026-01-15
last-reviewed: 2026-04-01
---

每月做一次"Skills 健康度 review"——检查哪些处于 stable 状态但 6 个月没被调用过（可能可以淘汰）、哪些处于 trial 状态但已被广泛使用（应当转 stable）。这种纪律让 Skills 库始终保持"高有效率"，避免变成"什么都有但没人用"的代码博物馆。

实战示例

调用 Skill 一行搞定：

请用 crud-repository skill 为 Order 实体生成 CRUD。
字段：id(uuid)、userId(uuid)、amount(number)、status(enum)、createdAt(Date)

Claude 会基于 SKILL.md 的指引，加上项目 CLAUDE.md 的风格约束，输出一致性远超"每次重新描述"的代码。

第五条：Hooks 是工程文化的代码化

心法：把团队的"我们应该这样做"沉淀为 Hooks——让工具自动执行而非依赖人类自觉。

Anthropic 官方观点：Hooks 是 Claude Code 在工具调用前后插入自定义脚本的机制。它把"提醒"升级为"强制执行"，把"风险点"升级为"自动守卫"。

PM 视角

PM 可以把 Hooks 理解为"工程团队的自动化纪律"——每条 Hook 都是团队对某种行为的明确规定（例如"提交前必须跑 lint"），并由工具自动执行而非依赖工程师记忆。Hooks 的存在让团队规范从"墙上的口号"变成"流水线的强制门"——任何违反规范的行为会被工具自动拦下。

工程师视角

常见 Hook 用法：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm lint --max-warnings=0 --quiet"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/check-secret-leak.js"
          }
        ]
      }
    ]
  }
}

Hooks 失败会阻断该次工具调用，并把错误信息回送给 Claude——Claude 会自然地进入"修复或绕开"的对话模式。

实战示例

把以下规则全部 Hook 化：

编辑/写入后自动 lint：PostToolUse + Edit/Write
任何 git commit 前先跑 typecheck：PreToolUse + Bash(git commit*)
任何包含密钥的 prompt 自动拦截：UserPromptSubmit hook
任何修改 CLAUDE.md 的动作走 plan 模式：PreToolUse + Edit(CLAUDE.md)

Hooks 设计的"三层金字塔"：

底层（必装）：拦截灾难性操作（rm -rf、secret leak）。这些 Hook 失败就阻断动作，不容协商。
中层（推荐）：自动化质量门（lint、typecheck、test）。这些 Hook 失败让 Claude 自己修复，提升流水线质量。
顶层（可选）：流程优化（自动添加 audit 日志、自动生成 PR 描述）。这些 Hook 失败不阻断，仅记录。

新团队应当从底层开始装——优先保证不出灾难性事故。中层在使用 1-2 个月后再加，让团队感受 Hooks 的价值。顶层是锦上添花，不必强求。

Hooks 与 CI 的边界：Hooks 在本地工程师机器上跑，CI 在团队服务器上跑。两者职责不同——

Hooks：快速反馈——本地 lint 失败立即知道，避免 push 出去才发现
CI：最终守门——即使本地 hooks 被绕过，CI 兜底拦截

健康的工程团队两者兼有、互不替代：Hooks 给开发者快速反馈、CI 给团队可信保证。本人见过的常见反模式——只装 Hooks 不装 CI（Hooks 被绕开就放行）、只装 CI 不装 Hooks（每次 push 才知道、本地反馈延迟）。两端都需要才能形成完整防御。

第六条：信任建立在"我清楚 AI 在做什么"基础上

心法：工程师对 AI 的信任不应来自"AI 看起来很聪明"，而应来自"我能观察、验证、回滚 AI 的每一个动作"。

Anthropic 官方观点：透明度（Transparency）是 AI 协作的根基。Claude Code 的设计哲学是"让 AI 的每一个动作都对工程师可见"——工具调用、文件修改、命令执行都会显式展示。

PM 视角

PM 在与工程师讨论"我们应该信任 AI 多少"时，常常陷入"是不是要把更多事交给 AI 自动做"的讨论。这个讨论的隐含假设错了——信任不是"给多少权限"的问题，而是"我能否观察"的问题。一个高度可观测的系统即使把 90% 的动作交给 AI，依然安全；一个不可观测的系统即使只交 10% 也充满风险。PM 应当推动团队建立"可观测性优先"的工作文化，而不是无脑追求"自动化最大化"。

工程师视角

可观测性的三个维度：

当下可见：Claude 正在做什么——通过 Plan 模式、确认提示展示。
事后可查：Claude 做过什么——通过 git log、审计日志、.claude/incidents.md 记录。
可被回滚：Claude 做错了能否撤回——通过 git、Feature Flag、备份还原。

任何缺一项的协作模式都不应进入生产工作流。

信任的"渐进式建立"：信任不是非黑即白，而是按以下五个层级逐步建立——

层级	工程师对 AI 的信任程度	典型工作模式
0：陌生	完全不信任	Plan 模式、每步审批
1：观察	看 AI 做、不让独立做	default 模式、单步确认
2：辅助	让 AI 做小事、自己做大事	acceptEdits + 严格 deny
3：协作	AI 做大部分、自己做关键	acceptEdits + 完善 Hooks
4：默契	AI 大部分自动、自己专注创造	acceptEdits + 自动化全栈

新人入职从层级 0 起步，半年到一年逐步过渡到层级 3 或 4。任何"跳级"都是危险信号——例如新人第一周就开 acceptEdits，那不是高效，是事故温床。

实战示例

# 把 Claude 的所有工具调用记录到日志
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "echo \"[$(date)] $TOOL_NAME: $TOOL_INPUT\" >> .claude/audit.log"
      }]
    }]
  }
}

.claude/audit.log 半年累积下来，是排查"AI 协作事件"最直接的证据链。

第七条：测试先行——让 Claude 写测试再写实现

心法：把 TDD（测试驱动开发）的"红绿重构"循环与 Claude Code 协作结合——让 Claude 先写测试、再写实现。

Anthropic 官方观点：让 Claude 先写测试再写实现的模式有两个好处：(1) 测试是契约，约束 Claude 的实现路径；(2) 测试是审查工具，工程师只需读测试就能判断 Claude 对需求的理解是否正确。

PM 视角

PM 可以参与测试编写吗？答案是肯定的——验收测试（Acceptance Test）就是 PM 视角的测试。PM 把验收标准用结构化方式写出（"用户输入正确密码后应当能登录"），让 Claude 翻译为可执行的 Playwright/Cypress 测试。这种"PM 写测试 + AI 翻译 + 工程师审查"的模式比传统的"PM 写需求文档 → 工程师独自实现 → QA 独自测试"高效得多。

工程师视角

TDD 与 Claude 协作的标准对话：

我要实现 createUser 函数。

先帮我写 Vitest 测试，覆盖以下场景：
- 正常输入返回 User，含 id 与 createdAt
- email 不合法抛 ValidationError
- name 长度超 100 抛 ValidationError
- 同一 email 二次 create 抛 DuplicateError

写完测试后停下来，等我确认再写实现。

Claude 先写测试，工程师 review 测试是否覆盖了所有边界，确认后 Claude 才写实现。这条流程把"Claude 是否理解需求"前置到测试阶段就发现，避免了"实现完才发现需求理解偏差"。

TDD 与 AI 协作的"双重红利"：

第一重红利：测试质量提升——当工程师审查测试是否覆盖足够边界时，往往会发现自己原先没想到的场景。AI 的"穷举式列举"能力在这一步特别有用——让 Claude 列出 10 个边界场景，工程师从中挑选最关键的 5 个。这种"AI 列举 + 人类筛选"模式比"工程师独自冥想"覆盖度高得多。
第二重红利：实现质量提升——当 Claude 看到一份完整测试套件时，它的实现会自动遵循测试的契约。本人观察到，先写测试再写实现的 Claude 输出代码 bug 率比"直接写实现"低 50% 以上。这不是因为 Claude 变聪明了，而是因为它的目标变清晰了——从"实现你描述的需求"升级为"通过这些具体测试"。

ATDD（验收测试驱动开发）进一步把这条延伸到验收层。让 Claude 把产品经理写的"用户故事"翻译成可执行的验收测试，再下推到单元测试和实现：

PM 提供以下用户故事：[贴用户故事]

请把它翻译为：
1. Playwright e2e 验收测试（覆盖关键路径）
2. 单元测试清单（覆盖每个组件的边界）
3. 实现的伪代码框架（不要真实代码）

输出后等我和 PM review，确认后再写真实代码。

实战示例

# 反模式：先实现再补测试
"实现 createUser 函数"
（Claude 写完实现，又被催着补测试，测试质量差）

# 正确：测试先行
1. "请先写 createUser 的测试，不要写实现"
2. [审查测试是否覆盖足够边界]
3. "现在写实现，让所有测试通过"
4. [Claude 实现，自动跑测试，全部通过]
5. "做一次 refactor，提高可读性，确保测试仍通过"

第八条：永远保留人类对关键决策的最终决定权

心法：AI 可以是"高级巡航辅助"，但每一次"接管方向盘"的动作都必须由人类拍板。

Anthropic 官方观点：Claude Code 的设计哲学是 Human-in-the-Loop（人类介入循环）——AI 提议，人类决策。这不是 AI 能力的限制，而是责任分配的必然要求。

PM 视角

PM 在与高管讨论"用 AI 能不能完全自动化某些流程"时，会反复遇到这个问题。本条心法的答案是：绝对不能。原因不在 AI 能力，而在于责任。任何重大决策（架构、合规、用户隐私、商业模型）出错后，必须有一个人类承担责任——法律责任、商业责任、伦理责任。把"按按钮"这件事交给 AI，等同于让责任链断裂。这条原则是工程伦理的底线。

工程师视角

哪些决策不能让 AI 拍板（参见 7.3 节的"决策层"）：

部署到生产环境
执行数据库 schema 迁移（含数据迁移）
删除分支、强制推送
操作密钥、Token、生产配置
选择架构方向、技术栈、商业模型
处理用户隐私、合规相关代码

这些动作 Claude 可以"提议 plan"，但最终执行由人类手动按下按钮。

实战示例

# 反模式：让 Claude 自动 deploy
"deploy 到 production"
（Claude 直接执行 deploy，半小时后线上挂掉）

# 正确：Plan + 人工执行
"我想 deploy v1.5.0 到 production。
请进入 plan 模式输出：
1. deploy 命令清单
2. 每一步的预期效果
3. 万一失败的回滚步骤
4. 上线后的健康检查清单

我审阅 plan 后手动执行 deploy。"

人类决策权的"心理建设"：保留人类决策权听起来理所当然，但实际操作中工程师常常会"不知不觉地让出"——例如疲劳、deadline 压力、Claude 表现得"很自信"——都可能让工程师在该停下时没停下。对抗这种"决策权侵蚀"的几条具体做法：

明确"红线动作清单"贴在工位：把不能让 AI 自动决定的动作写在便签贴在显示器边缘——deploy、migration、push --force、修改密钥、删除分支。每天看见，强化记忆。
结对审批高风险动作：任何 L3 级别的动作要求两个工程师共同审批。结对的 friction 让工程师在执行前自然会停下来。
疲劳时启用更严格的模式：如果你已经工作 8 小时以上、或处于事故响应高压下，主动切到 plan 模式——AI 不会累，但你会，让工具替你保持谨慎。
反思日志（Decision Log）：每周末花 10 分钟回顾本周的所有"决策点"——哪些是我自己想清楚的？哪些是顺着 AI 建议走的？后者占比超过 30% 就是警讯——说明决策权正在被悄然转移。

AI 决策权与工程伦理的更深一层：保留人类决策权不只是为了"防止 AI 出错"，更深一层是为了保持工程师作为"有担当的专业人士"的身份。一个工程师如果习惯于"什么都让 AI 决定"，半年后他会发现自己的决策能力在退化——这不是 AI 的问题，是个体在 AI 协作时代的"主动选择"。保留决策权本质上是工程师对自己的尊重——不让自己沦为 AI 的执行人。这一层意义远超"安全合规"，触及职业身份的核心。理解这一层的工程师，会在 AI 协作时代变得越来越强大；只把 AI 当"代写机"的工程师，会在职业道路上慢慢失去声音。

第九条：把每次失败沉淀为团队资产

心法：每一次 AI 协作的失败（误操作、幻觉、上下文溢出）都是团队的学习机会——把它沉淀为 CLAUDE.md / Skills / Hooks 的更新。

Anthropic 官方观点：失败的真正成本不是"这次出错了"，而是"下次还会出同样的错"。把失败资产化能阻断这条复发链路。

PM 视角

PM 在与工程团队 review 周报时，可以加上一栏"本周 AI 协作失败事件"——不是为了追责，而是为了让失败的教训可见。每周的失败列表逐渐形成"团队的 AI 协作教训库"，新人入职第一天读这份教训库，能跳过老员工"踩过一遍才知道"的所有坑。这是组织级别的复利效应。

工程师视角

失败资产化的标准流程：

记录：在 .claude/incidents.md 追加一条事件描述（时间、现象、根因、影响）。
分类：是 Prompt 问题？上下文问题？权限问题？还是 Skill 问题？
沉淀：根据分类更新对应资产——
- Prompt 问题 → 更新 CLAUDE.md 的"Common Mistakes"
- 上下文问题 → 更新 .claude/state.md 维护流程
- 权限问题 → 更新 settings.json 的 deny 规则
- Skill 问题 → 修复对应 Skill 的 SKILL.md
传播：在团队周会上 1 分钟分享这次失败与改进，让全员同步。

实战示例

# .claude/incidents.md

## 2026-04-15: Claude 在 user 模块复用了 order 模块的 status 枚举
- 现象：Claude 写 createUser 时把 OrderStatus.PENDING 当成 UserStatus 用，类型错误
- 根因：长会话累积，Claude 上下文中两个枚举混淆
- 影响：CI 失败，浪费 15 分钟修复
- 沉淀：
  1. CLAUDE.md 加一条 "Common Mistakes": "user 与 order 模块的 status 枚举不要混用"
  2. 团队周会同步：长会话超 30K Token 主动开新会话

把每次失败都按这个模板记录，半年后 incidents.md 就会变成全队最宝贵的"AI 协作错误博物馆"——比任何外部教程都更贴合本团队实际。

事件分级与响应：本人把 AI 协作事件分为三级，对应不同的响应深度——

级别	描述	响应方式
L1：小坑	浪费 < 30 分钟、不影响 PR	个人记录、月底批量沉淀
L2：中坑	浪费 30-120 分钟、影响 PR 或 CI	立即记录、当周沉淀到 CLAUDE.md
L3：大坑	浪费 > 2 小时 / 涉及生产 / 涉及合规	立即停下、全团队 Postmortem、永久写入 CLAUDE.md

按级别响应能避免两种极端——一种是"什么都记录"导致维护负担过重、另一种是"只记录重大事故"导致小问题反复发生。L1 攒到月底批处理，L2 当周处理，L3 立即处理——这种节奏让团队的"事件吸收能力"始终跟得上"事件产生频率"。

事件资产化的"长尾效应"：第一个月你会觉得 incidents.md 像"问题清单"——满是麻烦。半年后你会发现它变成了"团队的护城河"——所有新人入职第一天读 incidents.md 就能跳过老员工踩过的所有坑。三年后你会发现它已经是公司级别的"AI 协作工程文化资产"——可以作为对外分享、招聘吸引、品牌建设的素材。事件资产化的真正价值在长尾——短期看像负担，长期看是复利。

团队推广经验

工程师懂得 9 条心法是个人能力，让 8 人团队全员实践 9 条心法是组织能力。本人在多个团队推广 Claude Code 时积累了一些经验，归纳为下面三个部分。

推广的"三阶段"模型

第一阶段：种子培养（第 1 个月）

选定 1-2 名"种子工程师"——通常是对新技术好奇、愿意尝试、影响力强的成员。让他们先深度使用 Claude Code 1 个月，期间：

给他们配备最好的工具（Claude Code 订阅、外部资源）
让他们记录所有"惊喜时刻"与"踩坑时刻"
月底产出"种子报告"——量化收益、列出问题、建议团队接入路径

种子阶段的目的不是"立即推全员"——而是积累团队特定的实战素材，避免推广时全靠"网上别人的经验"。

第二阶段：双周迭代（第 2-3 个月）

种子报告 review 后，团队进入双周迭代阶段：

每两周引入 1-2 名新成员加入实践
每两周的周会上分享"上一周期的最佳实践"与"踩过的坑"
持续维护团队 wiki 的"Claude Code 实践指南"

双周节奏的好处是——既不会让不情愿的成员被强迫推动、又不会让全员等待太久才能感受变化。

第三阶段：全员对齐（第 4-6 个月）

到第 4 个月，团队 80% 以上成员应当已经在日常使用 Claude Code。这时进入全员对齐：

出台正式的"团队 Claude Code 工作公约"（参考 7.2、7.3 节示例）
团队 CLAUDE.md / Skills / Hooks 库正式上线维护
新人 onboarding 包含 Claude Code 培训环节

到第 6 个月时，团队整体的 AI 协作能力应当形成质变——交付速度、代码质量、知识沉淀都有可观测的提升。

三阶段模型的"反向工程"：以上是从"零基础"到"全员对齐"的正向路径。但很多团队是"已经有人在用、缺乏统一规范"的中间状态。对这种状态的正确做法是反向工程三阶段——

先做现状审计：调研团队中谁在用、用得怎样、有哪些自发形成的规范？
挑出"事实上的种子"：从已经在用的成员中挑选 1-2 名，把他们的实践提炼为团队基线。
从"种子的基线"出发推广：基线已经存在，推广就变成"对齐 + 完善"而非"从零建立"。

这种反向路径比正向路径快得多——因为团队已经有了真实素材，不需要从理论起步。正向适合从零项目，反向适合现有团队——选错路径会让推广效率打对折。

常见阻力与化解

阻力 1：资深工程师的"不需要"心态

部分资深工程师认为"我已经写代码很快了，不需要 AI 帮忙"。化解方式：不强求他们使用，但要求他们参与 review。让他们 review 用 AI 协作的成果，慢慢会发现"AI 协作产出的代码质量比想象的高"。一旦这层心理障碍打破，他们往往会成为最高效的 AI 协作者——因为他们的工程功底深，能精准引导 AI。

阻力 2：初级工程师的"依赖"心态

部分初级工程师过度依赖 AI，停止思考、复制粘贴。化解方式：强制"先思考再问 AI"的纪律——例如规定"提任何问题前先尝试自己解决 5 分钟"。同时让他们参与 review 资深工程师的 AI 协作过程，看到"AI 协作不是甩锅、而是协作"。

阻力 3：管理层的"安全"焦虑

部分管理层担心 AI 会"泄漏代码"、"产生不可控代码"、"让团队失去技术能力"。化解方式：用具体的安全设计回应抽象的焦虑——例如展示 settings.json 的 deny 列表、Hooks 的守卫机制、.claude/incidents.md 的事件记录。当管理层看到"工程团队对风险的认知比管理层还细致"，他们的焦虑会转化为信任。

阻力 4：团队"风格统一"的担忧

部分团队担心"每个人用 Claude 的风格不同，代码会越来越散乱"。化解方式：用 CLAUDE.md + Skills + Hooks 三层机制把"风格"代码化。当工程师都用同一份 CLAUDE.md 与 Skills 时，他们与 AI 协作产出的代码风格自然趋同——比"每个人凭手感"还更一致。

阻力 5：新人的"焦虑"心态

新人入职时如果发现"全队都在用 AI 协作"，可能会陷入"我会不会被 AI 取代"的焦虑。化解方式：让新人理解"AI 协作不是替代工程师、而是放大工程师能力"。具体做法——在 onboarding 中安排一个"对照练习"：让新人独立完成一个小功能、再用 AI 协作完成另一个相似难度的功能，比较两者的耗时、质量、学到的内容。这种亲身对比远比"理论安抚"有说服力——新人会发现 AI 协作的工程师反而需要更深的技术素养，因为他们承担"审查与决策"的角色。

阻力 6：客户/合规方的"信任"问题

部分行业客户（金融、医疗、政府）会要求"代码必须由人类编写"。化解方式：用透明度回应——展示 AI 协作的全部审计日志、人类 review 流程、最终决策权。让客户看到"AI 协作的代码经过比纯人工编写更严格的审查"，往往能化解这层担忧。如果客户合规要求"绝对不能用 AI"，则应该在合同中明确约定，并在该项目中关闭 AI 协作工具——这是合规优先于效率的明确选择。

阻力 7：成本敏感团队的"投入产出比"质疑

部分团队（特别是小公司、初创团队）会质疑"Claude Code 订阅的钱花得值不值"。化解方式：用具体数字回应抽象担忧——例如展示"上月 8 名工程师的会话数 × 平均节省时间 × 时薪"对比订阅成本。本人见过的真实数据——一个月订阅成本约 $200/人，一个月节省工程师时间约 30-50 小时（按时薪 $50 算节省 $1500-2500）。ROI 通常 7-12 倍，质疑会自然消解。需要警觉的反例是——如果 ROI 计算下来不到 2 倍，说明团队 AI 协作能力还没建立起来，应当先投资培训而不是急着扩大订阅。

阻力 8：行业法规变动的"未知"恐惧

近两年 AI 相关法规快速演化（欧盟 AI Act、中国生成式 AI 管理办法等），部分团队担心"今天用了未来违规怎么办"。化解方式：建立"合规追踪机制"——指定一名工程师或法务每月扫描相关法规更新、整理团队应对动作。把法规变动从"恐惧"转化为"流程化的关注"。Anthropic 在合规方面的投入一直处于行业前列，跟随它的官方指引通常能避免大部分法规风险。

度量推广成果

度量指标：

使用率：每周使用 Claude Code 的工程师比例（目标 80% 以上）
效率：相同复杂度任务的平均交付时间（目标减少 30-50%）
质量：单元测试覆盖率、CI 失败率、生产 bug 率（目标持续下降）
知识沉淀：CLAUDE.md / Skills / Hooks 的累积条数（目标稳定增长）
事件率：.claude/incidents.md 的事件密度（目标先升后降——升说明开始注意、降说明真的解决了）

把这些指标做成月度仪表板，让全员都能看到"我们在哪里、我们要去哪里"。透明的指标比模糊的口号更能推动行为改变。

反指标（如果出现说明推广有问题）：

工程师人均代码量飙升但 PR 大小也飙升（说明在凑工作量、缺乏审查）
AI 协作故障率持续上升（说明权限设计或培训不到位）
CLAUDE.md 半年不更新（说明没有失败资产化的习惯）
Skills 库零增长（说明没有把高频任务沉淀的意识）

发现反指标后立即介入——往往是某个环节走偏，而不是整个体系失败。

度量框架的"三层模型"：上述指标可以归类到三层——

使用层（使用率）：回答"团队是否真的在用？"
价值层（效率、质量）：回答"用了之后产生了价值吗？"
沉淀层（知识沉淀、事件率）：回答"这些价值能不能传递与复利？"

三层之间是渐进关系——光有使用层不够（用了但没产生价值），光有价值层不够（短期有效但无法持续）。完整的"AI 协作团队成熟度"必须三层都健康。

每月输出"三层报告"作为高管沟通材料：

## Claude Code 团队成熟度月报 — 2026-04

### 使用层
- 周活跃工程师：8/8（100%）
- 平均会话数/人/天：12 次

### 价值层
- 相比 3 月份：单功能交付时间减少 35%
- CI 失败率：从 4.2% 降至 2.8%
- 生产 bug：本月 3 起（vs 上月 5 起）

### 沉淀层
- CLAUDE.md 新增条款：5 条
- Skills 库新增：2 个
- 已记录事件：4 起（已全部转化为规则）

### 风险信号
- 暂无（详见 .claude/incidents.md）

这种结构化月报让高管即使不懂技术细节，也能从指标变化看到推广效果。让 AI 协作的价值从"工程团队内部知道"升级为"全公司可见"——是推广能持续获得资源支持的关键。

总结

Boris Cherny 的 9 条心法本质上回答了一个根本问题——在 AI 协作时代，工程师与 AI 的协作关系应当如何设计。9 条心法可以归纳为三个层次：

基础层（1、2）：建立项目记忆、管好任务边界。
机制层（3、4、5）：用 Plan、Skills、Hooks 把工程文化代码化。
价值观层（6、7、8、9）：可观测性、测试先行、人类决策权、失败资产化。

这三层缺一不可。基础层不打扎实，机制层是空中楼阁；机制层不健全，价值观再美好也落不了地；价值观若错位，前两层做得再好也会偏离正确方向。读者在团队推广时应当按这三层的顺序循序渐进，不要试图一次性把 9 条全部推广——抓住第一层，机制层会自然涌现，价值观层会在反复的实践中内化。

心法落地的"60 天计划"：本人推荐工程师与团队 leader 用一份"60 天计划"把 9 条心法逐步落地——

Day 1-7：建立 CLAUDE.md 与 task 拆分习惯（心法 1、2）
Day 8-21：引入 Plan 模式 + 开始建 Skills 库（心法 3、4）
Day 22-35：装好 Hooks + 建立 audit 日志（心法 5、6）
Day 36-49：实践 TDD 与 AI 协作 + 强化人类决策边界（心法 7、8）
Day 50-60：建立事件资产化机制 + 输出团队心法手册（心法 9）

60 天后回头看，团队的 AI 协作能力一定会有显著的质变——这种节奏既不会让团队感到压力骤增、又能在 2 个月内系统性建立完整的协作体系。比"一次性推广所有规则"或"放任自流不做规划"都好得多。

第十一章"最佳实践与效率心法"到此落幕。从 7.1 提示词、7.2 上下文、7.3 安全到 7.4 心法，四节合起来构成了"AI 协作时代的工程师心法体系"。把这套心法贯彻到日常工作中，团队的 AI 协作能力会形成可观测的复利曲线——半年后、一年后、三年后回头看，最大的差距不在于"我们用了多先进的模型"，而在于"我们的团队心法是否已经内化"。

附录 A、B、C 提供命令速查表、AI 术语表与延伸阅读资源。建议读者把它们当作日常工具书，遇到具体问题随手查阅。

留给读者的两个习题：

在你当前项目里，挑一条本节的心法，与团队对齐后立即实践 1 周。1 周后回头评估：哪些奏效？哪些遇到阻力？为什么？
在你团队的下一次周会上，分享一次"AI 协作失败事件"——按 .claude/incidents.md 的模板记录、归类、沉淀。半年后回头看你的 incidents.md，它将是全团队最宝贵的"AI 协作教训库"。

这两个习题做完，你就把 9 条心法从"读过的内容"真正变成了"做过的事情"。心法的真正价值不在记忆，而在实践，更在持之以恒地反复实践与持续打磨。读者可以把本节内容打印出来贴在工位旁，每周对照检查自己的工作方式——这种简单粗暴的"显式提醒"在 AI 协作早期是最有效的"自我训练机制"。半年后心法已经内化为肌肉记忆，便可以从墙上撤下来——但那时你已经成为团队中"AI 协作能力"最强的那批人之一。