Claude Code 最佳实践

Claude Code: Best practices for agentic coding（现为文档《Best practices for Claude Code》）

• claude-code
• coding-agents
• context-window
• subagents
• workflows
• permissions

⚠️ 重要说明：原博文已改为持续更新的官方文档（Best practices for Claude Code），原 URL 会自动跳转到文档页。本笔记依据 2026-10-17 读取的文档版本撰写，并不代表 2025 年 4 月原博文的内容。文档会持续变化，命令、参数、版本号和“实验性 / 研究预览”等状态请以官方文档为准。

一句话总结#

用好 Claude Code 的关键，是围绕“上下文会很快填满、越满越差”这个约束来工作：让它能自我验证，先想清楚再动手，喂精准的上下文，及时清理和纠偏，然后再通过并行和自动化扩大规模。

为什么重要#

• 把前几篇的概念落到日常工具里：上下文工程（压缩、子智能体、即时检索）、工具设计（CLI 优先）、评测思维（可运行的检查）都在这里变成了具体操作。
• 最适合边学边练：大部分建议都能在一个真实仓库里立即尝试。
• 它是一份“活文档”：本身就在演示 Anthropic 如何随产品变化持续更新实践指南。

核心概念（中英对照）#

方法 / 步骤#

0. 根本约束：上下文#

上下文窗口装着整个会话：每条消息、每个读过的文件、每次命令输出。一次调试或一次代码库探索就可能用掉数万 token；窗口越满，模型越容易“忘记”早先的指令或犯错。文档里的绝大多数建议都由此推出。

1. 让 Claude 能验证自己的工作#

• 没有可运行的检查，“看起来完成了”就是唯一信号，你就成了验证环节；有了能返回通过 / 失败的检查，循环就能自己闭合。
• 提示写法对比（概括）：与其说“实现一个校验邮箱的函数”，不如给出若干测试用例并要求实现后运行测试；改 UI 时贴设计截图，并要求截图对比差异；报构建失败时贴出错误，要求修根因而不是压掉报错。
• 检查的“把关强度”由弱到强：同一条提示里要求运行检查并迭代 → 设为会话级目标条件（文档中的 /goal，每轮后由独立评估者复查）→ 用 Stop hook 以脚本强制把关 → 由验证子智能体或另一个全新模型尝试推翻结果，让“干活的”和“打分的”不是同一个。
• 让 Claude 出示证据（测试输出、运行的命令与返回、截图），而不是只说“成功了”。

2. 先探索，再规划，再编码#

规划有开销：改错字、加一行日志、改个变量名这类小事直接做。文档的判断标准是：如果你能用一句话描述 diff，就跳过规划。

3. 提示要具体，并提供丰富素材#

• 四种具体化方式：限定范围（哪个文件、什么场景、测试偏好）；指向信息源（例如让它查某个类的 git 历史）；引用已有模式（指出仓库里可模仿的组件）；描述症状（现象、可能位置、怎样算修好，并先写一个能复现的失败测试）。
• 探索阶段可以故意问得模糊，看它会提出什么。
• 素材：用 @ 引用文件、直接粘贴图片、给文档 URL、用管道把数据传进去、让它自己用 Bash / MCP 去取。

4. 配置环境#

5. 有效沟通#

• 像问资深同事一样问代码库问题，这也是很好的新人上手方式。
• 大功能先让 Claude 采访你，把技术实现、UI/UX、边界情况、权衡都问清楚，写成 SPEC.md，再开一个新会话按规格实现。好的规格是自包含的：点明涉及的文件和接口、写清不做什么、最后有端到端验证步骤。

6. 管理会话#

• 尽早纠偏：Esc 中断（上下文保留）；双击 Esc 或 /rewind 回退对话 / 代码；让它“撤销”；无关任务之间 /clear。
• 同一问题纠正超过两次，说明上下文里堆满了失败尝试——清空，带着学到的东西写一个更好的初始提示重来。
• 积极管理上下文：任务间频繁 /clear；自动压缩会保留代码模式、文件状态、关键决策；可用带说明的 /compact 或只压缩部分对话；可以在 CLAUDE.md 里规定压缩时必须保留的内容；不需要留在上下文里的小问题用 /btw。
• 调查交给子智能体：它们在独立窗口里读大量文件，只回报摘要。
• 检查点：每轮自动快照，可以大胆尝试再回退；但检查点只跟踪 Claude 文件编辑工具做的改动，不记录 Bash 或外部进程的修改，不能替代 git。
• 恢复会话：给会话命名，像分支一样管理，用 --continue / --resume 接着做。

7. 自动化与规模化#

• 非交互模式 claude -p：用于 CI、pre-commit、脚本，支持纯文本、JSON、流式 JSON 输出。
• 多会话并行：git worktree、会话间消息、桌面应用、云端会话，以及文档中标为研究预览或实验性的 agent view、agent teams。
• 写者 / 评审者模式：一个会话实现，另一个全新会话评审（不偏向自己刚写的代码）；测试同理，一个写测试，一个写代码去通过测试。
• 扇出：让 Claude 先生成任务清单 → 写脚本循环调用 claude -p，用 --allowedTools 预批准所需工具、拒绝其余 → 先在 2–3 个文件上调好提示再全量跑；也可以用内置的批量命令拆给多个子智能体。
• auto mode 无人值守运行，由分类器在后台拦截越权、未知基础设施、恶意内容驱动的操作。
• 对抗式评审：收尾前用全新上下文的子智能体对照计划审查 diff；但要告诉它只报影响正确性或需求的缺口，否则“为找问题而找问题”会导致过度工程。

8. 五种常见失败模式#

文档最后强调这些都是起点而非铁律：有时就该让上下文累积、跳过规划、或故意给模糊提示；要观察什么有效，逐渐培养直觉。

图解#

图 1：带验证的工作循环（以及把关强度的阶梯）#

flowchart LR
    T[任务 + 可运行的检查] --> W[Claude 实现]
    W --> C{运行检查}
    C -- 失败 --> W
    C -- 通过 --> E[出示证据<br/>测试输出 / 命令结果 / 截图]
    E --> H[人审阅证据]

    subgraph G["把关强度（由弱到强）"]
        direction TB
        g1[同一提示内要求自检] --> g2[会话级目标条件] --> g3[Stop hook 脚本强制] --> g4[独立子智能体尝试推翻]
    end

图 2：探索 → 规划 → 实现 → 提交#

flowchart LR
    Q{能用一句话<br/>描述 diff 吗？} -- 能 --> D[直接让它改]
    Q -- 不能 --> X[探索<br/>规划模式只读]
    X --> P[规划<br/>输出计划，人可编辑]
    P --> I[实现<br/>按计划编码 + 跑测试]
    I --> M[提交<br/>提交信息 + PR]
    D --> M

图 3：上下文管理工具箱#

flowchart TD
    S[上下文在变满] --> A{情况？}
    A -- 换了不相关的任务 --> C1["/clear 清空"]
    A -- 同一问题已纠正两次以上 --> C2["/clear + 重写更好的提示"]
    A -- 长任务仍需历史 --> C3["自动或带说明的压缩<br/>（CLAUDE.md 可规定必须保留的内容）"]
    A -- 需要大量读文件调研 --> C4[交给子智能体<br/>只回摘要]
    A -- 只想问个小问题 --> C5["/btw 不进历史"]
    A -- 走错了方向 --> C6["Esc 中断 / /rewind 回退"]

图 4：规模化的几种方式#

flowchart TB
    One[单会话用熟] --> NI["非交互 claude -p<br/>CI / 脚本 / 管道"]
    One --> PAR[多会话并行<br/>worktree / 桌面 / 云端]
    PAR --> WR[写者-评审者模式]
    NI --> FAN["扇出：任务清单 → 循环调用<br/>先试 2–3 个再全量"]
    FAN --> AUTO[auto mode / 预批准工具<br/>无人值守]
    AUTO --> REV[收尾：对抗式评审子智能体]

关键原话#

“Claude’s context window fills up fast, and performance degrades as it fills.” —— Claude 的上下文窗口很快就会填满，而且越满表现越差。

“If you can’t verify it, don’t ship it.” —— 无法验证的东西，就不要发布。

实践建议#

• 每个任务都附一个可运行的检查（测试、构建、lint、截图对比），并要求 Claude 贴出运行证据。
• 用 /init 生成 CLAUDE.md 后立刻删减到只剩“删了会出错”的内容；提交到 git，团队共同维护。
• 把“必须每次做”的规则从 CLAUDE.md 挪到 hooks。
• 不熟悉的代码先用规划模式；一句话能说清的改动直接做。
• 养成任务间 /clear 的习惯；纠正两次不行就重开。
• 大功能：采访 → SPEC.md → 新会话实现 → 子智能体对照 SPEC 评审。
• 批量迁移：先在少量文件上试跑调好提示，再扇出；无人值守时只预批准必需工具。
• 检查点不能替代 git：重要节点手动提交。
• 笔者补充：团队内共享一份“好提示 / 坏提示”对照表，比口头传授更有效。

延伸阅读#

站内笔记

• 第 2 篇：上下文工程
• 第 7 篇：Agent Skills
• 第 21 篇：Claude Code 沙箱、第 22 篇：Claude Code auto mode
• 第 19 篇：用并行 Claude 团队写 C 编译器 — 多会话并行的极端案例。

官方资源

• 当前文档
• 原博文 URL（现重定向）

本笔记依据 2026-10-17 读取的 Claude Code 官方文档版本撰写（原博文已改为持续更新的文档）。原博文链接（现重定向到文档）。