Claude Code · 最佳实践

所有最佳实践，都来自一条约束：上下文会填满

Claude Code 会自己探索、规划、实现。你要做的是给它一条能自己跑的检查，并在不相关任务之间把上下文清干净。

来源 · code.claude.com《Claude Code 最佳实践》 · 阅读约 5 分钟

30 秒速览

记住这五句就够了

  • 验证

    没有检查，“看起来完成”就是唯一信号——你就成了验证循环。给它测试、构建退出码或截图。

  • 上下文

    最重要的资源。不相关任务之间 /clear；同一问题纠正两次还没对，清空重写提示。

  • 计划

    大改动用 Plan Mode 先探索再规划；一句话能说清 diff 就跳过计划，直接让它做。

  • CLAUDE.md

    它每次会话都加载，只写 Claude 猜不到的东西；域知识交给 skills 按需加载。

  • 规范

    大功能先让 Claude 采访你，写进 SPEC.md，然后开一个干净会话去实现。

约束

窗口填满，能力就下降

Claude Code 是代理式编码环境：它读你的文件、运行命令、做出修改，可以在你看着、指挥或完全离开时继续。代价是它受上下文约束——context window 保存整个对话，每条消息、每个读过的文件、每条命令输出都在里面。

一次调试会话或一次代码库探索，就可能吃掉数万 token。窗口快满时，Claude 会开始忘掉早期指令、犯更多错误。手册里几乎所有做法，都是为了让这个窗口更干净。

CONTEXT WINDOW · 整个对话 单个调试会话 ≈ 数万 token 剩余空间 窗口快满时，最早的指令最先被忘掉 CLAUDE.md 每次会话 读取的文件 每个文件全文都进来 命令输出 测试与构建日志 对话与纠正 每条消息都在里面 性能 下降
Fig. 1一次调试或一次探索就能塞进数万 token；窗口越满，Claude 越容易忽略早期指令、犯更多错误。

所以先看清自己的占用：配置一个显示 context 的自定义状态栏，就能随时看到这一条约束在真实会话里怎么起作用。

原文另附“context window 交互式演练”，用来看启动时加载了什么、每次读文件花多少。

最高价值的一条

给它一个能自己跑的检查

工作看起来完成时，Claude 就停下了。没有它能运行的检查，“看起来完成”是唯一可用的信号，于是你成为验证循环——每个错误都在等你发现。给它一个能产出通过或失败的东西，循环就自动闭合：完成、运行检查、读结果、迭代，直到通过。

未通过 · 迭代修正 运行 结果 通过 Claude 工作 运行检查 测试 · 构建 · lint · 截图 读取结果 通过 / 失败 报告证据 输出 · 截图
Fig. 2检查是一条能返回信号的任何东西（测试套件、构建退出码、linter、与固定用例输出对比的脚本、和设计图对比的浏览器截图）。有了它，闭环不再需要你。
  • 提供验证标准

    别只说“实现一个校验邮箱的函数”；说“写 validateEmail，user@example.com 为真、invalid 为假、user@.com 为假，实现后跑测试”。

  • 视觉验证 UI

    贴一张设计图：“按这个实现，截图对比，列出差异并修复”。/verify 让你在检查通过后自己确认运行中的应用。

  • 修根因

    贴构建错误：“修好并验证构建成功，解决根因，不要抑制错误”。

每一步用设置换取关注：越往上，越不需要你盯着 换取：更少的关注 ① 提示内迭代 同一条消息里跑到通过 ② /goal 条件 独立评估器每次 转换后重新检查 ③ Stop hook 脚本作确定性门： 不通过就不许结束 ④ 第二意见 验证子代理在新鲜 上下文里尝试反驳
Fig. 3提示内迭代今天就能用在任何任务上；/goal 与 Stop hook 让无人值守的运行自己收敛，第二意见让做工作的代理不给自己打分。
看证据，不听结论

让 Claude 显示证据：测试输出、它跑过的命令及其返回内容，或结果截图。审查证据比你自己重跑一遍快，而且对没在看的会话同样有效。

顺序

先探索，再规划，最后编码

直接跳到编码，可能写出解决错误问题的代码。Plan Mode 把探索和执行分开：按 Shift+Tab 直到状态栏显示 ⏸ plan mode on，Claude 只读文件、只回答问题，不做任何更改。

产计划 批准后 验证过 01 探索 plan mode · 只读 02 规划 Ctrl+G 改计划 03 实现 写测试 · 跑套件 04 提交 commit · PR ① 一句话能说清 diff → 跳过计划 ② 方法不确定 / 跨多文件 / 代码不熟 → 计划最值钱 Plan Mode 有开销：拼写、日志行、重命名这类小改动，直接让它做。
Fig. 4规划的价值在于避免“解决了错误的问题”；代价是额外一轮来回。改多个文件、方法不确定、代码不熟时才值得。

提示越精确，你需要纠正的次数越少。Claude 会推断意图，但不会读心。

  • 限定范围

    不写“给 foo.py 加测试”，而写“写测试，覆盖用户已登出的边界情况，避免 mock”。

  • 指向来源

    不问“ExecutionFactory 的 api 为什么这么怪”，而说“看它的 git 历史，总结 api 是怎么变成这样的”。

  • 参照现有模式

    “看主页上现有小部件的写法，HotDogWidget.php 是个好例子；照这个模式做日历小部件，只用代码库已有的库”。

  • 描述症状

    不问“修登录错误”，而说“会话超时后登录失败；查 src/auth/ 的 token 刷新，先写一个失败的测试复现，再修”。

也可以直接喂素材：用 @ 引用文件，粘贴或拖入截图，给文档 URL（常用域加进 /permissions 允许列表），或用管道送数据——cat error.log | claude -p "explain this error"。

探索阶段的模糊提示反而有用，比如“这个文件你会改什么？”——它能说出你没想到要问的东西。

大功能：先让它采访你

要求 Claude 用 AskUserQuestion 采访你：技术实现、UI/UX、边界情况、权衡，不问显而易见的问题。采访完让它把完整规范写进 SPEC.md，然后新开一个会话执行——干净上下文、专注实现、有书面规范可对。最有用的规范是自包含的：点名涉及的文件和接口，说明什么在范围之外，以端到端验证步骤收尾。

环境

CLAUDE.md 只写每次都会用到的东西

CLAUDE.md 在每个对话开始时加载，所以它只能装广泛适用的内容：Claude 猜不到的 Bash 命令、与默认值不同的代码风格、测试怎么跑、分支与 PR 约定。对每一行问一句：删掉它 Claude 会犯错吗？不会就删——膨胀的 CLAUDE.md 会让 Claude 忽略你真正的指令。

每次会话都付代价

膨胀的 CLAUDE.md

CLAUDE.md 每次会话全量加载 任务与对话 规则淹没在噪音里 → 被忽略
按需才付出

精简 CLAUDE.md + skills

CLAUDE .md skills 按需载入 任务与对话 相关时才加载 按需加载，会话不膨胀
Fig. 5同一扇窗口的两种装法：CLAUDE.md 每次会话都加载，skills 只在相关时进来。图中分段宽度为示意，不代表真实比例。

仅有时相关的域知识和流程放进 skills：.claude/skills/<名字>/SKILL.md，Claude 在相关时自动应用，也可以用 /skill-name 直接调用。带副作用、你想手动触发的工作流，标上 disable-model-invocation: true。剩下的能力按“要花多少上下文”来选：

环境四件套：谁在最省上下文的前提下解决什么
工具做什么什么时候用
hooks在固定节点自动跑脚本，确定性执行，不像指令那样可能被忽略必须每次发生、没有例外的事：每次编辑后跑 eslint、禁止写迁移目录
gh 等 CLI与外部服务交互最 context 高效的方式创建 issue、开 PR、读评论；没有 gh 时未认证的 API 请求会撞速率限制
MCP servers接入结构化外部工具，如 Notion、Figma、数据库需要从问题跟踪器实现功能、查库、分析监控数据
subagents在自己的上下文里跑，自带一套被允许的工具要读很多文件、或需要专门注意力而不想弄脏主对话
plugins把 skills、hooks、subagents、MCP 打成一个可安装单元用类型化语言时装代码智能插件，拿到符号导航与改后报错
权限的另一种失败

手动模式在每个可能改动系统的操作前问你：安全，但到第十次批准时，你已经在点通过而不是审查。用 /permissions 预先批准你信任的工具，用 /sandbox 限制文件系统与网络；auto mode 让分类器模型替你挡掉范围升级、未知基础设施和由敌对内容驱动的操作。

会话

尽早纠偏，积极清上下文，然后并行

对话是持久且可逆的，用它：Esc 停下但保留上下文，Esc Esc 或 /rewind 回到之前的检查点，/clear 在不相关任务之间重置。

什么时候用什么
命令或做法解决什么注意
/clear厨房水槽式会话：无关信息填满窗口不相关任务之间清空；同一问题纠正两次后也清空重来
/compact长会话接近上限，自动压缩会丢细节带指令压缩：/compact Focus on the API changes；也可在 CLAUDE.md 里规定压缩时保留什么
Esc Esc · /rewind回到某个对话与代码状态，或只压缩一部分历史“从这里总结”保留较早上下文，“总结到这里”保留最近消息
/btw只想问个细节，不想让答案进历史侧问的答案永远不进对话
subagent 调查研究代码库读的几百个文件会吃掉主上下文“use subagents to investigate X”，它只回报总结
--continue · /rename任务跨多个会话，不必重新解释背景把会话当分支命名，如 oauth-migration
检查点不等于 git

检查点只跟踪通过 Claude 文件编辑工具做的改动。Bash 命令或外部进程改的文件不会被捕获。它让你敢尝试冒险的做法——不行就 rewind——但不能替代版本控制。

扩展：并行、非交互、扇出

一个会话跑对之后，靠并行和非交互模式放大产出。

把一个人的产出变成多个
方式怎么用适合
claude -pclaude -p "…"，输出可选 json 或 stream-jsonCI、pre-commit、任何脚本化流程
并行会话Worktree 隔离检出、跨会话传递发现、桌面应用、claude agents多个功能同时推进；新鲜上下文也让代码审查更客观
/batch拆成 5–30 个子代理，各自在自己的 worktree 里改跨文件的大迁移或批量分析
循环扇出先让它把待迁移文件写进 files.txt，再 for 循环调用 claude -p，用 --allowedTools 预批工具、--permission-mode dontAsk 拒绝其余操作无人值守的批量作业；先在前 2–3 个文件上试跑，改好提示再全量跑
对抗性审查的边界

收尾时让子代理在新鲜上下文里审查差异（/code-review 就是内置的那种）：它只看差异和你给的标准，不知道产生这些改动的推理，所以能按自己的条件评估。但被要求找缺陷的审查者总会找到一些——全追下去就是过度工程：多余的抽象层、防御性代码、为不可能发生的情况写的测试。告诉它只标记影响正确性或明确要求的缺陷。

风险

五个模式，越早认出来越省时间

上下文污染

厨房水槽会话

任务 A 无关问题 回到 A

修复不相关任务之间 /clear

上下文污染

一次又一次地改正

正确部分 失败方法 再纠正

修复两次失败后 /clear 并重写提示

指令噪音

过度指定的 CLAUDE.md

CLAUDE.md 全量 任务

修复无情修剪，或把确定性的事改成 hook

验证缺口

信任后再验证的差距

看起来完成 检查：缺失

修复始终提供验证；不能验证就不要发布

上下文耗尽

无限探索

读取的数百个文件

修复狭隘地限定调查，或交给 subagent

Fig. 6五个模式都在同一扇窗口上留下痕迹：前两个是无关信息和失败方法占位，第三个是指令被噪音吞掉，第四个是检查位置空着，第五个是探索本身把窗口读满。

最后记住：这些模式不是铁律。有时就该让上下文累积，因为你在深挖一个复杂问题；有时跳过计划、用一句模糊的提示正是你想要的，因为你想先看看 Claude 怎么理解。注意什么有效——提示结构、你给的上下文、你所在的模式——直觉就是这么攒出来的。

来源

原文：Claude Code 最佳实践（code.claude.com）。本篇为 5 分钟精华版，删去了原文的代码示例、配置片段与文档链接；数量与限定条件均按原文保留，未引入外部信息。