很多人把 Claude Code 的 Best Practices 当成功能说明书：CLAUDE.md 怎么写、plan mode 怎么开、-p 怎么跑。读完以为「功能都知道了」，上线两周却发现：会话越聊越飘、改完不敢合、自动化一开就埋雷。
本文记录我们如何把 Anthropic 公开文档读成一套工程决策，而不是条目清单。母本是官方 Best Practices（文档 ），不编造内部数据；关键论断均可回溯。上一篇 6 个偷懒技巧 讲「怎么省」；这篇讲为什么官方几乎所有建议，都在回答同一个矛盾。
经验一：Agent 最稀缺的不是智商，是上下文有效带宽。
经验二：没有可跑的 pass/fail，你就永远是验证环。
经验三：建议写进 CLAUDE.md，零例外必须写进 hook。
〇、Agent 开发心法：上下文不是聊天记录，是整机内存
元问题
在传统软件里，你加一个同事、加一台机器，吞吐近似线性上去。
在 Claude Code 里，你加的每一轮对话、每一次读文件、每一段命令输出，都挤进同一块会「变蠢」的内存——上下文窗口。
官方把这句话写在 Best Practices 开篇：
Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills.
这不是文案。窗口里装的是：消息历史 + 读过的文件 + 工具输出。调试一次、探索一遍仓库，轻松烧掉几万 token。窗口越满，早期约束越容易被挤掉，模型越像失忆的外包。
所以真正的矛盾不是：
- 「要不要用 AI」
- 「prompt 写得漂不漂亮」
而是：
自主性要求 Agent 多看、多试、多迭代；上下文有限要求你少装、快验证、勤隔离。
忽略它会发生什么？一线最常见的三种现场：
- 厨房水槽会话：一个窗口里修登录、改文档、顺便问架构，上下文被无关噪声灌满。
- 纠错螺旋：同一 bug 纠正 3～5 次，失败路径比正确路径还长，模型开始「复读错误」。
- 看起来做完了：没有测试/构建信号，Agent 在「观感完成」处停下，你变成唯一验收机。
Agent 开发的第一原则：把 context 当预算，不当无限对话框。
后面每一节，都是在回答：这笔预算花在哪、谁来验收、何时必须清零。
为什么这不是「省 token」的小技巧
省 token 听起来像抠门。工程上它对应三件事：
- 保智力：窗口越满，指令遵循越差——不是模型突然变笨，是有效约束被噪声淹没。
- 保可回放：失败路径一旦写进历史，后续推理会「继承错误假设」。
- 保协作带宽：团队共享 CLAUDE.md / hooks，是在共享「什么不该进上下文」。
我们在维护多语言 Hugo 站点与 Agent 工具链时，反复验证过同一现象：同一个模型，干净会话一次过；脏会话纠三轮仍飘。 差别几乎从不在「再强调一遍要认真」，而在上下文是否干净、验收是否可跑。
一、验证闸门：人盯 vs 可跑信号
传统软件里的答案
传统交付默认有 CI：测试红了合不进去。人可以不盯全过程，因为闸门在流水线里。
Agent 语境下的错觉
Claude 会在工作「看起来完成」时停下。若没有它自己能跑、能读的检查，唯一信号就是「看起来行」。
官方原话的工程含义是：
没有 check，你就是验证环；每个错误都要等你发现。
方案对比
| 方案 A：靠人盯 | 方案 B：给可跑信号 | |
|---|---|---|
| 做法 | 「改完告诉我」 | 测试/构建/lint/截图对比/diff fixture |
| 优点 | 零配置 | 闭环可自转 |
| 代价 | 人必须在线 | 要写得出验收 |
淘汰 A 的原因： Agent 的价值在于你能走开；A 把「走开」变成不可能。
决策：任何要合并的改动，至少 L1 闸门。
官方四级闸门（硬度递增）
| 级别 | 机制 | 适合 | 配置成本 |
|---|---|---|---|
| L1 | 同 prompt 要求：实现 + 跑测试 + 失败继续改 + 贴输出 | 日常 | 几乎为 0 |
| L2 | /goal 条件，每轮复查 | 长会话 | 低 |
| L3 | Stop hook 脚本硬拦截（连续拦截有上限） | 零例外门禁 | 中 |
| L4 | 第二意见：verification subagent / 对抗评审 | 无人值守、合并前 | 中高 |
中文 L1 模板：
实现 src/auth/validateEmail.ts。
验收：user@example.com→true；invalid→false；user@.com→false。
写测试并运行；失败继续修到全绿。
最后贴命令与完整输出，禁止只说「已完成」。
要证据，不要口号。 测试输出、退出码、截图对比——复查证据比你自己重跑快。
→ 影响：后面所有「自动化 / auto mode / CI -p」若没有闸门，只是在自动化埋雷。
现场对照：同一需求两种问法
低效（人盯模式）
帮我把登录超时修好。
Agent 改完说「好了」。你本地跑一下挂了。你贴报错。它再改。三轮后上下文里塞满失败补丁，正确约束反而模糊。
高效（闸门模式）
用户反馈 session 超时后登录失败。
范围：src/auth/，重点 token refresh。
先写能复现的失败测试，再修到测试绿。
贴：测试命令、失败→成功的输出、改动文件列表。
不要改范围外文件。
第二种不是「更啰嗦」，是把 完成定义 从自然语言感觉，改成 Agent 可读的信号。这正是官方表格里 before/after 的工程实质。
二、Plan mode：先探索 vs 直接开写
传统答案
资深工程师改多文件前会先摸清调用链；改一行日志则直接动。
Agent 语境
让 Claude 直接写，容易「完美实现错误目标」。官方推荐 Explore → Plan → Implement → Commit。
方案对比
| 方案 A：凡事先写长 plan | 方案 B：按不确定性切换 | |
|---|---|---|
| 做法 | 所有任务 plan mode | 多文件/不熟/路径不清才 plan |
| 风险 | 流程表演、浪费上下文 | 小任务过度设计？ |
官方自己说：plan 有开销。一句话能描述的 diff（typo、加日志、重命名）应直接做。
淘汰「凡事 plan」的原因： plan 本身也占窗口；对确定性小改动是负收益。
决策：不确定性计费，不按仪式计费。
触发 plan 的信号：
- 要动 ≥2 个模块
- 你说不清改哪些文件
- 需求里有「顺便」「重构一下」
跳过 plan 的信号：
- 能一句话说清 diff
- 已有失败测试，只差实现
→ 影响：plan 阶段产出的文件清单与验收步骤，应直接写进 L1 prompt，而不是聊完就丢。
三、CLAUDE.md vs Hooks：建议与零例外
传统答案
规范写 Wiki，靠 code review 盯着。
Agent 语境
CLAUDE.md 每会话加载，是「入职手册」；但官方警告：写太长会被忽略一半。
筛选法则极狠：
删掉这一行，Claude 会不会因此犯错？不会就删。
| ✅ 写 | ❌ 别写 |
|---|---|
| 猜不到的 Bash 命令 | 读代码就知道的结构 |
| 偏离默认的风格 | 标准语言常识 |
| 单测命令与 runner | 长篇 API 文档 |
| 分支/PR 约定 | 频繁变动的信息 |
| 环境坑 | 「写干净代码」 |
方案对比
| 方案 A：全塞 CLAUDE.md | 方案 B：建议 vs 零例外分流 | |
|---|---|---|
| 做法 | 3000 行百科 | 短 CLAUDE.md + hooks + skills |
| 结果 | 重要规则被淹没 | 关键路径确定性执行 |
淘汰 A 的原因： 模型对超长说明书的遵循率会塌；你以为写了=生效。
决策：
- 建议、偏好、命令 → CLAUDE.md（短）
- 零例外动作（每次改文件跑 eslint、禁止写 migrations）→ hooks
- 偶尔才用的领域知识/工作流 → skills（按需加载，不污染每会话）
最小 CLAUDE.md：
# Commands
- Typecheck: `npm run typecheck`
- Single test: `npm test -- --grep "pattern"`
- Build: `npm run build`
# Workflow
- Prefer single-test while iterating
- Typecheck after a batch of edits
- Don't touch files outside requested scope
权限侧同理：点同意点到第十次你已不审。用 auto mode / allowlist / sandbox 降低打断，而不是取消边界。
CLI 比裸 API 更省上下文：gh、aws 等把鉴权与分页封装掉；不会用就先 --help 再干。
→ 影响：skills/subagents/plugins 都是「扩展能力」；若 CLAUDE.md 已臃肿，先做减法再加扩展。
四、会话与 Subagent：主上下文的污染与隔离
传统答案
开分支、开 PR，工作流隔离。
Agent 语境
会话是持久且可回滚的，但持久不等于该无限堆。
官方失败模式几乎全是上下文病：
| 病 | 现场 | 处方 |
|---|---|---|
| 厨房水槽 | 一会话多无关任务 | 任务间 /clear |
| 反复纠正 | 同题纠 >2 次 | clear + 更好首轮 prompt |
| 无限探索 | 「调查一下」读爆文件 | 收窄范围或 subagent |
| 信任-验证缺口 | 看起来对、边界全挂 | 回到第一节闸门 |
方案对比
| 方案 A：主会话自己读遍仓库 | 方案 B：调查交给 subagent | |
|---|---|---|
| 代价 | 主窗口被文件内容灌满 | 只要摘要回报 |
| 收益 | 「都在一个对话里」 | 实现上下文保持干净 |
淘汰 A 的原因： 探索的 token 会挤掉实现与约束。
决策：只读大调查默认 subagent；实现留在主会话。
纠偏工具箱：
Esc：停，上下文还在/rewind：回到检查点（注意：Bash/外部改动不进 checkpoint，不能替 git）/clear、/compact：清或摘要/btw：旁路问题不进主历史/rename+ resume：长任务当分支用
同一问题纠正超过两次：清会话。 干净窗口 + 更好首轮 prompt，几乎总是打得过又臭又长的纠错局。
→ 影响：Writer/Reviewer 双会话、对抗评审，本质上都是「新鲜上下文当第二意见」。
影响链：一次错误探索如何拖垮整个下午
主会话里说「全面调查认证模块」→ 读 40 个文件 → 窗口 70% 被占满 → 再实现 OAuth 时忘记「不要动支付模块」→ 你纠正 → 再纠正 → 此时失败路径已比需求还长。
若第一步改为 subagent 调查、主会话只收摘要，实现阶段仍有空间装约束与测试输出。隔离不是流程洁癖，是保护实现期的有效内存。
五、规模化：何时自动化，何时别自动化
传统答案
能进 CI 的就进 CI。
Agent 语境
claude -p、fan-out、auto mode 能成倍放大产出，也成倍放大错误。
方案对比
| 方案 A：无闸门全自动 | 方案 B：闸门先行再放大 | |
|---|---|---|
| 做法 | -p + auto 直接扫全库 | 先 2～3 样本打磨 prompt + --allowedTools |
| 风险 | 批量埋雷 | 慢半拍，但可控 |
淘汰 A 的原因： 自动化没有验证闭环，是在工业级复制 bug。
决策：L1/L3 闸门就绪前，不上 fan-out。
可用形态：
claude -p "列出所有 API endpoints" --output-format json
claude --permission-mode auto -p "fix all lint errors"
批量迁移：
for file in $(cat files.txt); do
claude -p "迁移 $file：只返回 OK 或 FAIL" \
--allowedTools "Edit,Bash(git commit *)"
done
合并前对抗评审（新鲜上下文）：
用 subagent 对照 PLAN.md 审查 diff：
需求是否落地、边界是否有测、是否改出范围。
只报正确性缺口，不报风格。
官方提醒：被要求「找缺口」的评审者往往会报一堆——只追正确性与需求，否则会过度工程化。
→ 影响：规模化是第一节～第四节的乘子，不是替代品。
总结
工程决策
| 设计问题 | 方案 A（淘汰） | 方案 B（采用） | 淘汰原因 |
|---|---|---|---|
| 如何判断做完 | 人盯「看起来行」 | 可跑 pass/fail + 证据 | 人成验证环，无法走开 |
| 是否先 plan | 凡事长 plan | 按不确定性切换 | 小改动浪费上下文 |
| 规范放哪 | 百科全书 CLAUDE.md | 短手册 + hooks + skills | 过长被忽略 |
| 大调查 | 主会话狂读文件 | subagent 回报摘要 | 主上下文被污染 |
| 自动化 | 无闸门 fan-out | 样本打磨 + 闸门 + allowedTools | 批量复制错误 |
| 纠错策略 | 同会话死磕 | 两次后 clear 重开 | 失败路径污染推理 |
Agent 开发原则
| 原则 | 含义 | 本文落点 |
|---|---|---|
| 上下文是硬通货 | 多看多试也要付内存税 | 〇、四 |
| 闸门先于自主 | 能走开的前提是可验收 | 一、五 |
| 建议与强制分离 | 偏好进 md，零例外进 hook | 三 |
| 隔离探索与实现 | 调查别挤占主会话 | 二、四 |
| 放大前先样本 | 自动化是乘子不是魔法 | 五 |
今天就能做的 5 步
- 把当前 CLAUDE.md 砍到「删了会犯错」的行
- 下一条任务强制 L1：跑什么 + 贴输出
- 复杂需求 plan；一句话 diff 直接干
- 调查默认 subagent
- 同题纠两次 →
/clear重写首轮 prompt
官方最后一节叫 Develop your intuition：指南是起点不是教条。有时该让上下文累积，有时该跳过 plan。注意它什么时候表现好——那是你自己的最佳实践。
上一篇：Claude Code 与 Codex CLI 的 6 个偷懒技巧
母本：Anthropic · Best practices for Claude Code
如果你也在用 Claude Code
你现在最痛的是上下文被污染，还是没有闸门不敢走开？欢迎留言交换现场。全栈之巅 · 梦兽编程