Claude Code 最佳实践:官方使用技巧中文整理

本文是对 Anthropic 官方文档 Best practices for Claude Code 的中文要点摘要与整理,便于中文读者快速吸收。完整内容与代码示例请以官方原文为准。

一切的核心:管理上下文窗口

Claude Code 是一个自主编码环境——它能读文件、跑命令、改代码,自己推进问题,而不只是回答你的提问。官方指出:几乎所有最佳实践,都来自同一个约束——

上下文窗口会很快填满,而模型表现会随着上下文变满而下降。

上下文窗口装着整段对话:每条消息、每个被读的文件、每条命令的输出。一次调试或代码库探索就可能吞掉数万 token。窗口快满时,Claude 会开始「忘掉」早先的指令、犯更多错。因此,上下文是最需要主动管理的资源——后面所有技巧本质上都在为它服务。

一、给 Claude 一个能自己验证的「检查」

Claude 在「看起来做完了」时就会停。如果没有它能自己跑的检查,「看起来完成」就是唯一信号,而你就成了那个验证循环——每个错误都得等你发现。

给它一个能产出通过/失败信号的东西,循环就能自己闭合:Claude 做事 → 跑检查 → 读结果 → 迭代,直到通过。检查可以是测试套件、构建退出码、linter、把输出和固定基准 diff 的脚本,或把浏览器截图和设计稿比对。

几种「卡停」的强度,按需选择:

• 写在一条提示里:让 Claude 在同一条消息里跑检查并迭代。
• 作为会话级目标:设成 /goal 条件,每轮后由独立评估器复查,不满足就继续。
• 作为确定性闸门:用 Stop hook 把检查做成脚本,不通过就不许结束这一轮。
• 找第二意见:用验证 subagent 或动态 workflow,让一个全新的模型去尝试反驳结果——干活的人别自己给自己打分。

要让 Claude 拿证据(测试输出、跑了什么命令、返回了什么、结果截图)而不是口头声称成功。审阅证据比你自己重跑验证快得多。

二、先探索,再计划,后编码

让 Claude 直接开写,容易写出「解决了错误问题」的代码。推荐的四阶段工作流:

1. 探索(Explore):进入 plan mode,Claude 只读文件、回答问题,不做改动。
2. 计划(Plan):让它产出详细实现计划。可按 Ctrl+G 在编辑器里直接改计划。
3. 实现(Implement):切出 plan mode,让它照计划写代码并对照验证。
4. 提交(Commit):让它写清晰的提交信息并开 PR。

计划虽好但有开销。改个 typo、加行日志、重命名变量这种范围明确的小修,直接让它做就行。计划最值的时候是:你拿不准方案、改动跨多个文件、或你对要改的代码不熟。如果你能用一句话描述这个 diff,就跳过计划。

三、在提示里给出具体上下文

Claude 能推断意图,但读不了你的心。指令越精确,你要纠正的次数越少。官方给的几组对比很典型:

• 圈定范围:不是「给 foo.py 加测试」,而是「给 foo.py 写测试,覆盖用户已登出的边界情况,别用 mock」。
• 指向出处:不是「这个 API 为什么这么怪」,而是「翻 ExecutionFactory 的 git 历史,总结它的 API 是怎么演变成现在这样的」。
• 参照现有模式:不是「加个日历控件」,而是「看看首页现有控件怎么实现的,HotDogWidget.php 是好例子,照这个模式做一个日历控件……」。
• 描述症状:不是「修登录 bug」,而是「用户反馈会话超时后登录失败,查 src/auth/ 里的 token 刷新,先写一个能复现的失败测试,再修」。

提供丰富内容:用 @ 引用文件、直接粘贴截图/图片、给文档 URL(用 /permissions 把常用域名加白名单)、用 cat error.log | claude 把数据管道喂进去,或让 Claude 自己去取它需要的上下文。

四、配好你的环境

几步一次性配置,能让 Claude 在你所有会话里都更高效:

• 写好 CLAUDE.md:它在每次对话开头都会被读取。用 /init 生成初版再逐步打磨。只放删掉就会出错的内容——「该不该留」的判断标准是:「去掉这行,Claude 会不会犯错?」不会就删。过长的 CLAUDE.md 会让真正的规则被噪声淹没,反而被忽略。可以加 IMPORTANT / YOU MUST 强调关键项;把它当代码一样定期审阅和修剪。
• 配置权限:默认每个可能改动系统的操作都要批准,很烦。三种减少打断的方式——auto 模式(分类器模型只拦危险操作)、权限白名单(放行你确定安全的命令)、沙箱(OS 级隔离)。
• 用 CLI 工具:CLI 是与外部服务交互最省上下文的方式。用 GitHub 就装 gh;也可以让 Claude 用 foo-cli --help 现学一个它不会的工具。
• 接 MCP 服务器:claude mcp add 连上 Notion、Figma、数据库等。
• 设置 hooks:对「每次都必须发生、零例外」的动作用 hooks——它是确定性的,而 CLAUDE.md 只是建议性的。
• 创建 skills:在 .claude/skills/ 放 SKILL.md,给 Claude 项目/团队/领域专属知识与可复用工作流,按需加载,不撑爆每次对话。
• 自定义 subagents:在 .claude/agents/ 定义专职助手(独立上下文 + 独立工具集),适合读很多文件或需要专注的任务。
• 安装插件:/plugin 浏览市场,把 skills/hooks/subagents/MCP 打包安装。

五、高效沟通

• 问代码库问题:上手新代码库时,像问资深同事那样直接问 Claude——「日志是怎么工作的?」「怎么加一个新 API 端点?」「第 134 行的 async move 在干嘛?」。这是很好的 onboarding 方式,无需特殊提示。
• 让 Claude 反过来采访你:做较大功能时,给一句最简描述,让它用 AskUserQuestion 工具就技术实现、UI/UX、边界、取舍反复追问你没想到的硬骨头,最后写出完整 SPEC.md。然后开新会话用干净上下文去执行这份 spec。

六、管理你的会话

对话是持久且可回退的,要善用:

• 尽早纠偏:发现跑偏立刻纠。Esc 中断(保留上下文)、Esc Esc 或 /rewind 打开回溯菜单恢复对话/代码状态、「撤销刚才那步」、/clear 在不相关任务间重置上下文。在同一问题上纠正超过两次,就说明上下文已被失败的尝试污染——/clear 重来,配一条更具体的提示,几乎总是胜过一段堆满纠正的长会话。
• 积极管理上下文:任务之间频繁 /clear;接近上限时会自动 compact;也可 /compact <指令> 定向压缩;用 /btw 问不需要进上下文的小问题。
• 用 subagent 做调研:调研要读大量文件、吃掉主上下文,交给 subagent 在独立窗口里探索、只回报摘要。
• 用 checkpoint 回溯:每条提示都会建检查点,可只恢复对话、只恢复代码或两者。于是你可以大胆让它「试个有风险的方案」,不行就回滚。(注意:checkpoint 只跟踪 Claude 自己的改动,不能替代 git。)

七、自动化与横向扩展

熟练用好一个 Claude 之后,用并行会话成倍放大产出:

• 非交互模式:claude -p "提示" 用于 CI、pre-commit hook、脚本;--output-format json / stream-json 便于程序解析。
• 多会话并行:worktrees(隔离 git 检出,互不冲突)、桌面/网页端多会话、agent teams。一个经典模式是 Writer/Reviewer:一个会话写、另一个全新上下文的会话复核——新鲜上下文不偏袒刚写的代码,代码审查质量更高。
• 跨文件 fan-out:大规模迁移时,让 Claude 列出待处理文件清单,再用脚本循环对每个文件调 claude -p,用 --allowedTools 限定权限;先在 2~3 个文件上试、调好提示再全量跑。
• 加一步对抗式复核:收工前,让一个 subagent 在全新上下文里只看 diff + 你给的标准去找缺口。注意:被要求「找缺口」的复核者总会报一些,即使工作没问题——告诉它只标影响正确性或既定需求的缺口,其余当可选,避免过度工程。

常见翻车模式

• 大杂烩会话:一个会话里混入不相关任务 → /clear 分开。
• 反复纠正:纠正两次还不对 → /clear,重写更好的初始提示。
• 过度膨胀的 CLAUDE.md:太长就被忽略 → 狠狠精简,能转成 hook 的转成 hook。
• 信任但不验证:看似可用却没处理边界 → 永远提供验证,验证不了就别发。
• 无限探索:不圈范围地「调研」会读上百个文件填满上下文 → 收窄范围或交给 subagent。

最后:培养你自己的直觉

官方强调,这些模式是起点而非铁律。有时你该让上下文积累(深陷一个复杂问题、历史很有价值);有时该跳过计划(任务本就是探索性的);有时含糊的提示恰恰合适(你想先看 Claude 怎么理解)。留意什么管用、什么不管用,慢慢你会形成任何指南都给不了的直觉。

---

延伸阅读(官方):How Claude Code works · Extend Claude Code · Common workflows · CLAUDE.md / memory