Claude Code 最佳实践：官方的七类建议，每条在本站哪一篇做过

这篇教程解决一个问题：官方那页最佳实践写了几十条建议，哪些要紧，每条具体怎么做，做了会怎样。

官方的 Best practices 一页有三万多字符，里面的内容本站有三十多篇文章分头讲过、测过。这一篇按官方的七类重新排一遍：每条用一两句话讲清要点，后面接本站细讲它的那一篇；那篇在服务器上实测过的，附上测出来的结果，尤其是文档里没写、照着做会碰到的地方。不逐条翻译，原文的例子换成了本站做过的例子。

这篇本身没有新做实测。文中标“实测”的，是链到的那一篇在服务器上做过，Claude Code 的版本和日期写在那篇开头；标“整理”的，那一篇也只按文档写。

读这个系列到这里，前七篇讲的是装好、用起来、配规矩、选权限、管会话、省用量和换入口。这一篇把它们串起来，也是往后几个系列的索引。

先记住一条：上下文是最要紧的资源

官方的建议几乎都从一个约束出发：上下文窗口很快会满，越满表现越差。 对话里的每条消息、它读的每个文件、每条命令的输出都占地方，一次调试或读一遍代码就能用掉几万 token。快满的时候，它会“忘掉”前面的指示，出错也更多。

另一页官方文档（How Claude Code works）把上下文里有什么列得更全：

• 你的对话、读过的文件、命令输出；
• CLAUDE.md、自动记忆、用到的 skill、系统指令；
• Claude Code 自己加的东西：输出风格的说明，“之前读过的文件在磁盘上变了”的提示，提交和 PR 的署名行。提交里的 Co-Authored-By 就是从这里来的，用 attribution 设置可以改掉。

快满时它会先清掉旧的工具输出，不够再把对话压成摘要。你的要求和关键的代码片段会留下，前面交代的细节可能丢。所以一直要生效的规矩写进 CLAUDE.md，不要指望它在对话里记一路。

本站的几篇：

• 会话和上下文（实测）：用 /context 看过前后的变化。/clear 之前合计 37k，之后 27.9k，其中对话部分从 9.2k 降到 106，剩下的是每次都有的固定开销。压缩之后，它会把读过或改过的文件重新放回最多五个，超过 5,000 token 的只留一个路径。
• 状态栏（实测）：把上下文的进度条放到输入框下面，一直看得见。官方也建议这样做。
• 怎么省用量（整理）：一个任务的钱花在哪，上下文和缓存怎么管。

一、给它一个能自己跑的检查

官方把这条放在第一位。Claude 觉得“看起来做完了”就会停；没有能跑的检查，“看起来做完了”就是它唯一的信号，你就成了那个验证环节，每个错都等着你去发现。给它一个返回通过或失败的东西：测试、构建的退出码、lint、拿输出和样本比对的脚本、和设计稿对比的截图，它就会自己做、自己查、自己改到通过。

检查有了，再定它管得多严，官方分了四档：

档位	做法	适合
一条提示里	让它改完跑检查，不过就接着改	什么任务都能用
整个会话	用 /goal 定一个条件，另一个模型每轮结束后检查，没满足就接着做；一直没进展的话最终会停下，目标仍留着	你不盯着的长任务
硬性关卡	Stop hook 跑你的检查脚本，不过就不让这一轮结束	同上，而且要确定性
第二意见	让一个验证用的子代理或动态工作流去反驳结果	不想让做事的给自己打分

另外一条：让它拿出证据，不要只说“好了”。 测试的输出、它跑了什么命令、返回了什么、结果的截图。看证据比你自己重跑快，你没盯着的会话也能这样查。

本站做过的：

• 在提示里写上检查。 修 bug（实测）用同一个 bug 试了两种问法。随口一句“修一下”也修对了，但没有加回归测试；把现象、复现办法和“做完”的标准说清楚，多花半分钟左右，换来一个先确认会失败的测试。
• 要求测试证明自己有用。 补测试（实测）要求每个新用例在代码改坏时必须失败。它补的 6 个用例都过了这一关，我们自己又改坏一处，新用例确实拦得住。
• 截图对比。 看图（实测）里照设计稿写的页面和原图几乎重合。要它自己开浏览器截图验证，见前端联调（整理），但这条走中转站用不了。
• /goal 和 Stop hook。 怎么搭见 Harness 工程和 Loop 工程（整理）。/goal 在中转站兼容性（实测）里经中转站跑通。写 Stop hook 要知道，按文档它在每次答完时都会触发，不只是任务做完时，见 Hooks 实战。
• /verify。 官方建议它的检查通过之后，你自己再跑一次 /verify，对着跑起来的应用确认。按文档，内置的 /verify 只在你手动输入时运行，Claude 不会自己调它，见 Harness 那篇。

第二意见放在第七类“对抗式审查”里讲。

二、先探索，再计划，再动手

直接让它写代码，容易写出一个解决错了问题的方案。官方推荐四步：

1. 探索：按 Shift+Tab 切到 plan 模式（状态栏显示 ⏸ plan mode on），或者用 claude --permission-mode plan 启动。这时它只读文件、回答问题，不改东西。
2. 计划：让它出一份详细的计划。按 Ctrl+G 可以在编辑器里直接改计划。
3. 实现：批准计划或再按 Shift+Tab 退出 plan 模式，让它照计划做，做完跑测试。
4. 提交：让它写提交说明、开 PR。

计划也有成本。官方的判断标准很好记：这次的 diff 你能一句话说清，就跳过计划。 改错字、加一行日志、改个变量名，直接让它做。不确定怎么做、要改好几个文件、或者你对这块代码不熟，才值得先出计划。

本站做过的：

• 权限模式（实测）：Shift+Tab 的切换顺序，plan 模式怎么出方案。
• 重构和迁移（实测）：plan 模式下它查出 222 处声明和两处不能直接替换的地方，文中也讲了批准计划时几个选项怎么选。两件事值得记住。一是计划也要抽查：我们对着源码核对，发现其中一处它说要改的代码本来就是 const，照做就会顺手多改一处。二是它读到 CLAUDE.md 里的约定和这次任务对不上，没有自己挑，而是停下来问了两个问题。
• 第一个小时（实测）：在一个陌生仓库里先让它讲清项目结构和怎么跑测试，再修 bug、提交。

三、提示词里给具体的上下文

它能猜你的意图，但读不了你的心。官方给了四种写法：

写法	意思	本站的例子
限定范围	哪个文件、什么场景、测试有什么偏好	补测试那篇先让它只找缺口、按风险排序，再补
指向来源	告诉它去哪找答案，比如某个类的 git 历史	—
指向现有写法	点名仓库里一个照着写的例子	补测试那篇新加的用例和文件里原有的写法一致
描述现象	现象、可能的位置、“修好”是什么样	修 bug 那篇有一份提 bug 的模板

这和另一页文档说的“委派，不要指挥”并不矛盾。那一页的意思是：像交给一个能干的同事，给背景和方向，不用规定它读哪些文件、跑哪些命令。具体要具体在目标、现象和约束上，不在步骤上。模糊的提示也有用处：只想看看它会怎么理解一个问题，或者问一句“这个文件你会改哪里”，正好能发现你没想到的地方。

把材料交给它，官方列了五种：用 @ 引用文件，直接粘贴或拖进图片，给文档的网址（常用的域名用 /permissions 放行），用管道送数据（cat error.log | claude -p "..."），或者让它自己用命令、MCP 工具去取。

本站做过的：

• 看图（实测）：报错截图它能对上代码找到根因，架构图全读对了。但 4K 截图会先被缩到 2000 像素再发，小字会抄错，而且不标问号；把那一块裁出来再给，就全对了。
• 脚本和 CI（实测）：管道前面的命令失败、没有输出时，claude -p 照样跑，还会自己去找内容来审。你以为它审的是你送进去的东西，其实不是。脚本里要加 set -o pipefail，调用前检查输入是不是空的。

四、把环境配好

这几样配一次，以后每个会话都受益。一项一项来。

CLAUDE.md

用 /init 生成一份起步的，再慢慢改。只写它从代码里猜不到、而且每次都用得上的：猜不到的命令、和默认不同的代码风格、测试怎么跑、分支和 PR 的约定、项目特有的架构决定、必须设的环境变量、不显眼的坑。它能从代码里看出来的、语言的通用规范、详细的接口文档、经常变的信息，都不要写。

官方给的检验办法是每一行都问一句：删了它，它会不会出错？ 不会就删。文件太长，要紧的规则会被淹没。它总是不照某一条做，多半是文件太长；它问你的问题明明写在文件里，多半是写得含糊。反复被跳过的那一条可以单独加 IMPORTANT 强调，强调的行多了就都不显眼了。签入仓库的 CLAUDE.md，可以跑 /doctor，它会把能从代码里推出来的内容列出来，建议删掉。

本站做过的：CLAUDE.md 怎么写（实测）在 Express 的源码上加了三条规矩，三条都照做了：没有规矩时它修完 bug 把 1261 个测试全跑了一遍，加了“只跑对应的测试文件”之后只跑一个文件。但这只是一次的结果，文档写得很清楚，CLAUDE.md 是交给它的上下文，不是强制的配置。必须每次都执行的，写成 hook。

权限

从 2.1.283 版起，终端和 VS Code 里的交互会话默认从 auto 模式开始：另一个分类模型替你审大部分操作，只拦看起来有风险的。在 Manual 模式下，改文件、跑命令、调 MCP 工具之前都会问你，安全但烦，点到第十次你就不是在审，是在点。两样东西能少点几次，在 auto 模式下也一样起作用：用 /permissions 把信得过的操作加进允许列表，比如 npm run lint、git commit；用 /sandbox 打开沙箱，让命令在操作系统划好的边界里跑，不用每次问。

本站做过的：

• 权限模式（实测）：在 auto 模式下要求强制推送、git reset --hard，两次都是模型自己先停下来讲清后果，我们没有看到分类器拦截的提示；明确确认之后它照做了。走中转站时会多弹一个分类器计费的提示，按回车继续就行，见第一个小时。
• 沙箱（实测）：Ubuntu 24.04 上要多做一步；Linux 上沙箱里的 git add -A 会失败。
• 大仓库和 monorepo（实测）：拒绝读某些文件的规则挡得住 Read 工具和 cat，挡不住 grep -r。
• 用 API key 或中转站 key 的读者要知道一件事。 按 10 月 21 日的官方文档，机器上没有托管设置、会话凭据也不是 Team 或 Enterprise 的登录时，装了的 mod 能放行 deny 规则拒绝的调用和 PreToolUse hook 拦下的调用。装 mod 之前，先看Mods 是什么里讲的安不安全。

命令行工具

和外部服务打交道，让它用命令行工具：gh、aws、gcloud、sentry-cli。官方说这是最省上下文的办法。用 GitHub 的话装上 gh，开 issue、开 PR、读评论它都会；没有 gh 它也能直接调 GitHub 的接口，但不登录的请求很容易碰到限流。它不认识的工具，让它先跑一遍 --help 自己学。

本站的两处观察：代码审查那台服务器没装 gh，状态栏一直提示 install gh for PR status，创建 PR 那一步就没测。GitLab CI/CD（整理，作业部分在服务器上跑过）里，它两次都先试着用 glab 读 issue，机器上没装才改用提示词里的描述。

MCP、hook、skill、子代理、插件

官方的建议	本站的那一篇	测出来的
用 claude mcp add 接上工单、数据库、设计稿这类外部工具	MCP 实战（实测）	接一个现成的、自己写一个、改成项目级给团队共用，每一步的真实输出
每次都必须发生、不能有例外的动作，写成 hook；CLAUDE.md 只是建议，hook 是确定的	Hooks 实战（实测）、Hooks 速查（实测）	改完自动 eslint --fix、拦住受保护的文件；33 个事件里实际触发到 27 个
只在某些时候用到的知识和流程，写成 .claude/skills/ 里的 skill，用到时才加载；有副作用、只想手动触发的，加 disable-model-invocation: true	skills 怎么写（整理）	—
要读很多文件、或者要专门盯一件事的，交给 .claude/agents/ 里的子代理，它有自己的上下文和工具清单	子代理实战（实测）、子代理进阶（实测）	工具清单是硬约束；走中转站时定义里写 model: haiku 会报 404
用 /plugin 装插件；写类型语言的，装一个代码智能插件	插件进阶（上）（实测）	TypeScript 的插件连踩三个坑才跑通；第一次编辑的诊断要到下一步才到

这几样该先用哪个，见 六种扩展各管什么（整理）。官方的建议是不用一开始就配齐，等某个信号出现了再加。

五、像问同事一样问它，大功能先让它采访你

刚接手一个代码库，就问你会问一个资深同事的问题：日志是怎么做的，加一个接口要改哪些地方，这一行为什么调 foo() 不调 bar()。不需要特别的写法，直接问。

做比较大的功能，官方建议反过来，让它先采访你，问完写一份规格说明，再开一个新会话照着做。提示词的意思是这样的（官方示例的大意，改成了中文）：

我想做 [一句话描述]。用 AskUserQuestion 工具详细地采访我：技术实现、界面和交互、边界情况、顾虑和取舍。
不要问显而易见的，挖那些我可能没想到的难点。一直问到都问清楚为止，然后把完整的规格写进 SPEC.md。

规格写完就开新会话，新会话的上下文干干净净，只装实现要用的东西。官方说最有用的规格是自成一体的：写明涉及哪些文件和接口、哪些不在范围里，最后一步是一个能证明功能真的能用的端到端验证。把规格写准花的时间，比盯着它实现划算。

本站做过的：

• 找出自己不知道的（实测）：让它“一次只问一个问题，先问答案会改变整体设计的”。三个问题问下来，原本要新加的一个属性，变成了“先确认是不是改一个设置就够了”。
• 重构和迁移（实测）：它在出计划之前主动问了两个问题，因为任务和 CLAUDE.md 的约定对不上。

六、管好会话

对话可以接着来，也可以退回去。官方要你好好用这一点。

发现走偏就马上纠正。 Esc 让它停下，上下文还在，可以换个方向；连按两次 Esc 或输入 /rewind 打开回退菜单；也可以直接说“撤销刚才的改动”；换不相干的事就 /clear。另一页文档补了一种：不按 Esc，直接打字回车，消息会排队，它手上的工具调用一结束就读到，在同一轮里调整。

两页文档的语气不太一样。How Claude Code works 说不用写完美的提示词，第一次不对就接着说；最佳实践一页说，同一个问题纠正了两次还不对，就 /clear，带着学到的东西重写一条更具体的提示。 合起来理解：小偏差接着说，同一件事说了两次还不对，上下文里已经堆满失败的尝试，重来更快。会话和上下文里有一节专门讲，退回去重新提示为什么比接着纠正好（按官方博客整理）。

积极地管上下文。 官方列的办法和本站测出来的：

办法	本站测出来的
换一件事就 /clear	清掉的会话没有丢，同一次运行里连按两次 Esc 还能找回来
/compact 带一句要求，告诉它摘要里留什么	在一个很短的对话里试的，对话部分从 12.8k 降到 9.3k，本来就短的对话没什么可压
在回退菜单里选一条消息，Summarize from here 或 up to here，只压一部分	没有实测
在 CLAUDE.md 里写压缩时要保留什么	没有实测
不需要留在对话里的小问题用 /btw	它不能用工具，对话里没读过的文件答不了

调查交给子代理。 让它读一大堆文件去弄清一件事，这些文件都会占你的上下文。说一句“用子代理去查……”，子代理在自己的上下文里读，只交回一份总结。见子代理实战。

用检查点退回去。 每发一条提示就有一个检查点，可以只退对话、只退代码或者都退。官方提醒：检查点只记录它用文件编辑工具做的修改，命令改的、别的进程改的都不记录，不能代替 git。本站测出来这条限制比想象中常碰到：

• 权限模式（实测）：只说“加一行注释”时它用了命令，回退菜单里没有恢复代码的选项；要求“用 Edit 工具”之后才能退。它用哪种方式改文件，你事先不一定知道。
• 重构和迁移（实测）：批量替换是 eslint --fix 做的，回退菜单显示 No code changes。真正的退路是 git，所以计划里要求每步一个提交。

接着上次干。 claude --continue 接最近一个会话，claude --resume 从列表里挑。官方建议用 /rename 给会话起名，像分支一样一件事一个会话。本站在会话和上下文（实测）里碰到两处：/clear 开的新会话沿用了原来的名字，重名之后按名字恢复会打开选择器让你挑；claude -p 的会话不在选择器里，但按 ID 能恢复。

七、自动化和扩大规模

一个会话用顺手了，再考虑并行、脚本和批量。

不带界面运行。 claude -p "提示词" 可以放进 CI、pre-commit hook 和脚本，输出可以是纯文本、JSON 或流式 JSON。脚本和 CI（实测）里最要记住的一条：操作被拒绝、事没办成时，退出码仍然是 0，脚本要看输出里的 permission_denials，或者让它按 --json-schema 返回一个明确的成败字段。另外，--bare 不加载项目和个人的配置，一次最简单调用的估算花费从 0.14 美元降到 0.008 美元。

同时开几个会话。 官方按你想自己协调多少列了几种：

做法	本站的那一篇	测出来的
worktree：每个会话一份自己的文件和分支	worktree（实测）	两个会话同时改同一个文件，各自提交，最后合并没有冲突
跨会话消息：你开的几个会话互相传话	agent view（实测）的第九节	用 /list-agents 看够得着谁，用平常的话让它去问另一个会话
桌面应用：在一个窗口里管几个本地会话	桌面应用（整理）	—
云端会话：跑在 Anthropic 的机器上	云端会话（整理）	—
agent view（研究预览）：claude agents 派发后台会话，一屏看全	agent view（实测）	派发、回答提问、进入对话、删除会话，走中转站都能用
代理团队（实验功能，默认关闭）：组长加几个能互发消息的队友	代理团队（实测）	三个队友互发 20 条消息，推翻了组长清单里的一条错误结论，估算 1.51 美元

多开几个会话不只是为了快。官方举了“一个写、一个审”的例子：A 会话实现，B 会话在全新的上下文里审，它不会偏向自己刚写的代码；B 的意见再交回给 A 去改。测试也可以这样分：一个写测试，另一个写让测试通过的代码。

把一件活分到很多文件上。 大规模迁移和分析，官方给了两条路：/batch <要求> 让它把改动拆给 5 到 30 个子代理，各在自己的 worktree 里做；或者自己写循环逐个调 claude -p，用 --allowedTools 事先放行要用的工具，用 --permission-mode dontAsk 拒绝其余要确认的调用。先拿两三个文件试，按出的问题改提示词，再跑全部。这两条本站都没有实测，写法见重构和迁移的“文件更多的时候”一节和大规模代码迁移（整理）。上面那条 mod 的例外在这里也适用：走中转站时，装了的 mod 仍可能放行 dontAsk 本来要拒绝的调用。

无人值守用 auto 模式。 claude --permission-mode auto -p "修好所有 lint 错误"。按权限模式那页文档，交互式会话里分类器连续拦 3 次或累计拦 20 次，auto 模式会暂停、改回逐个问你；-p 里（没有配 --permission-prompt-tool 时）没人可问，拦下的操作不执行，它接着干，不会停下这次运行。和上面“退出码仍是 0”放在一起看：无人值守的结果要从输出里查，不能只看它跑完了没有。

做完之前加一道对抗式审查。 它自己干得越久，越需要一个独立的检查。官方建议让子代理在新的上下文里只看 diff 和你给的标准，不看产生这些改动的思路。查正确性用自带的 /code-review；要对照计划查，自己写审查的提示词，意思是这样的：

用一个子代理，对照 PLAN.md 审限流器的改动：每条需求都实现了没有，列出的边界情况有没有测试，
任务范围以外有没有改动。只报缺口，不报风格偏好。

官方还提醒了反方向的问题：让它找缺口，它总能找出一些，哪怕活干得没问题。每条都去改，会改出多余的抽象层、防御性代码和根本不会发生的测试。要告诉审查的子代理只报影响正确性和需求的缺口，其余的当作可选。

本站做过的三次，正好印证了这两面：

• 代码审查（实测）：测试和 lint 都过、但条件写反的改动，/code-review 第一轮 24 秒查出来；修完再审，又查出一个要人来定的设计问题。审查不会自己收敛到零。
• 子代理实战（实测）：只读的测试评审员发现，补测试那篇里第 3 个用例的请求实际以 500 结束，测试没有检查出来。这个分歧只有换一个“人”来看才会出现。
• 长任务 harness（实测）：一轮独立验收找出了 7 处需求没写到的问题，是整套里最有用的一环；但修完再验收又挖出 2 处，不给及格线它会一直挑下去。

八、五种常见的失败

官方列了五种，早点认出来能省很多时间：

失败	官方的办法	本站对应的一篇
一个会话什么都往里塞：做着一件事，插问一件不相干的，再回来	换不相干的事就 /clear	会话和上下文
一遍遍纠正：错了纠正，还错，再纠正	纠正两次还不对，/clear，重写一条更好的提示	同上
CLAUDE.md 写得太长：要紧的规则被淹没，一半被忽略	狠删。没有这条它也做得对的，删掉或改成 hook	CLAUDE.md 怎么写
看着对就信了：写得像模像样，边界情况没处理	永远给它验证的办法：测试、脚本、截图。验证不了的不要上线	修 bug、补测试
没有边界的调查：只说“查一下”，它读了几百个文件	把范围说窄，或者交给子代理	子代理实战、大仓库和 monorepo

九、这些不是死规矩

官方最后一节说得很实在：上面这些是大多数时候好用的起点，不是每种情况都最好。有时候就该让上下文攒着，因为你正深挖一个复杂问题，前面的记录有用；有时候该跳过计划，因为任务本来就是探索；有时候模糊的提示正合适，你想先看它怎么理解。

办法是留意什么管用。效果好的时候，回头看你做了什么：提示怎么写的、给了什么上下文、在哪个模式下。效果不好的时候问为什么：上下文太乱？提示太含糊？任务太大，一次做不完？

按任务找：官方“常见工作流”对应本站哪篇

官方另有一页 Common workflows，按日常任务给了提示词的套路。本站对应的文章：

任务	本站的那一篇
读懂一个新代码库	第一个小时；仓库很大时看大仓库和 monorepo
修 bug	修 bug
重构	重构和迁移
写测试	补测试
开 PR	代码审查和 PR 描述
处理图片	看图
定时运行	关了电脑也要跑的，用云端定时任务（原 routine）；要用本机文件的，用桌面版定时任务（同一篇）；跟着仓库事件走的，用 GitHub Actions；会话开着时轮询一下，用 /loop，见 Harness 和 Loop
接着上次干、并行、先计划、交给子代理、接进脚本	上文第二、六、七类

这一页对定时任务的提示词有一句提醒值得抄下来：它是自己跑的，没法反过来问你，所以要写明“做成”是什么样、结果交到哪里。

走中转站时要多留意的几处

上面提到的、和直连不一样的地方，集中列一下：

• auto 模式会多弹一个分类器计费的提示，什么都没坏，按回车继续。见第一个小时。
• 让它自己开浏览器验证的 Chrome 集成用不了。见前端联调。
• /goal 能用。见中转站兼容性。
• 子代理的定义里写 model: haiku 会报 404，要换成你的中转站能用的模型。见子代理进阶。
• 用 API key 或中转站 key、机器上又没有托管设置时，装了的 mod 能放行 deny 规则拒绝的调用。见权限模式和Mods 是什么。
• agent view 和跨会话消息都能用。见 agent view。

这篇没有覆盖到的

• 这篇没有新做实测。 标“实测”的结论来自链到的那一篇，各篇的测试日期和 Claude Code 版本不同，最早的是 10 月 11 日。之后官方改过的行为，以各篇里的补测说明为准。
• 官方这页里本站还没单独测过的：/batch 和循环调 claude -p 的批量改法，“一个写、一个审”的两个会话，/doctor 对 CLAUDE.md 提出的删减建议，在回退菜单里只压一部分对话，/verify。
• 不逐条翻译。 官方每一类下面的原话和例子没有全部照录，要看原文见文末的来源。

相关文章

• 系列的上一篇：在 VS Code、JetBrains 和桌面应用里用 Claude Code。这是入门系列的最后一篇。
• 接下来按要做的事读：日常开发任务系列从修 bug 开始；想加规矩、加工具，从六种扩展各管什么开始；想并行和自动化，从 worktree 开始。