Claude Code 最佳实践:官方指南全文整理

Claude Code 是一个 agentic 编码环境。与「回答完问题就等着」的聊天机器人不同,它能读你的文件、跑命令、改代码、自主地把问题一路做下去——你可以盯着看、随时纠偏,也可以完全走开。

这改变了你的工作方式:不再是自己写代码、请 Claude 来评审,而是你描述想要什么,Claude 自己想清楚怎么构建——它探索、计划、然后实现。但这种自主性仍有学习曲线:Claude 在一些你需要理解的约束下工作。agentic 循环的底层原理,见 How Claude Code works。

上下文窗口装着你的整段对话:每条消息、Claude 读过的每个文件、每条命令的输出。一次调试会话或一轮代码库探索,就可能生成并消耗数万 token。这很要紧,因为 LLM 的表现随上下文填满而退化:窗口快满时,Claude 可能开始「忘记」较早的指令、犯更多错。上下文窗口是最需要管理的资源。原文附了配套工具:交互式演示(context-window)看一次会话如何被填满、自定义状态栏(statusline)持续追踪用量、以及降耗策略(Reduce token usage)。

Claude 会在工作「看起来完成了」的时候停下来。如果没有可运行的检查,「看起来完成了」就是它唯一的信号,你自己就成了验证循环——每个错误都要等你来发现。给它一个能产出通过/失败信号的东西,循环就自己闭合了:Claude 干活、跑检查、读结果、迭代,直到检查通过。

「检查」可以是任何能在对话里返回信号的东西:测试套件、构建退出码、linter、把输出与基准文件比对的脚本、或与设计稿对照的浏览器截图。

三个改写示范(原文对照表)

验证有了之后:决定它把「停止」卡多严

每一档都在用「设置成本」换「注意力」。提示版今天就能用在任何任务上;/goal 和 Stop hook 版能让无人值守的运行自己正确收尾。第四档的「第二意见」可由验证子智能体或自查发现的动态工作流承担。

让 Claude 直接跳进编码,可能产出「解决了错误问题」的代码。用 plan mode(计划模式)把探索与执行分开。推荐的工作流有四个阶段:

read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

commit with a descriptive message and open a PR

四个改写示范(原文对照表)

模糊提示也有用武之地:当你在探索、且能承受走弯路时,一句 "what would you improve in this file?" 可能挖出你根本想不到要问的问题。

喂富内容的五种方式

• 用 @ 引用文件,而不是描述代码在哪——Claude 会先读文件再回应。
• 直接粘图:复制粘贴或拖拽图片进提示。
• 给 URL:文档和 API 参考直接贴链接;常用域名用 /permissions 加白。
• 管道喂数据:cat error.log | claude 把文件内容直接送进去。
• 让 Claude 自己取:告诉它用 Bash 命令、MCP 工具或读文件的方式自行拉取上下文。

CLAUDE.md 是 Claude 每次会话开场都会读的特殊文件,放 Bash 命令、代码风格、工作流规则——这些是 Claude 无法单从代码推断出的持久上下文。/init 会分析你的代码库,识别构建系统、测试框架和代码模式,给你一个可打磨的底子。格式没有硬性要求,但要短、要人类可读。原文示例:

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

CLAUDE.md 每个会话都会加载,所以只放普遍适用的东西;只在部分场景相关的领域知识或工作流,改用 skills——Claude 按需加载,不会撑爆每次对话。

放什么、不放什么(原文对照表)

• 规则失灵的诊断:明明写了规则 Claude 还是照犯——文件可能太长,规则被淹没了;CLAUDE.md 里写了答案它还来问你——措辞可能有歧义。像对待代码一样对待 CLAUDE.md:出问题就检查、定期修剪、改完观察 Claude 行为是否真的变化。
• 强调可以调音量:加 “IMPORTANT” 或 “YOU MUST” 提升遵循度。
• 提交进 git,让团队共同贡献——这个文件的价值随时间复利。

导入与摆放位置

CLAUDE.md 可以用 @path/to/import 语法导入其他文件:

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

• 家目录 ~/.claude/CLAUDE.md——对你所有 Claude 会话生效。
• 项目根 ./CLAUDE.md——提交进 git 与团队共享。
• 项目根 ./CLAUDE.local.md——个人的项目笔记;加进 .gitignore 不共享。
• 父目录——monorepo 场景,root/CLAUDE.md 和 root/foo/CLAUDE.md 都会自动拉入。
• 子目录——Claude 读到该目录文件时按需拉入其中的 CLAUDE.md。

几步配置就能让 Claude Code 在你所有会话里显著更高效。扩展功能的完整总览与选型见 Extend Claude Code。

配置权限

默认情况下,Claude Code 对可能改动系统的操作(写文件、Bash 命令、MCP 工具等)逐一请求许可。这安全但繁琐——点到第十次「允许」时你已经不是在审查,只是在无脑点击。三种减少打断的方式:

更多细节见文档:permission modes、permission rules 与 sandboxing。

使用 CLI 工具

告诉 Claude Code 与外部服务交互时用 gh、aws、gcloud、sentry-cli 这类 CLI 工具——CLI 是与外部服务交互最省上下文的方式。用 GitHub 就装 gh:Claude 知道怎么用它建 issue、开 PR、读评论;没有 gh 它也能走 GitHub API,但未认证请求经常撞限流。Claude 也很擅长现学不认识的 CLI,试试这样的提示:Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.

连接 MCP 服务器

运行 claude mcp add 接入 Notion、Figma、数据库等外部工具。接上 MCP 服务器后,可以让 Claude 从工单系统实现功能、查数据库、分析监控数据、集成 Figma 设计稿、自动化工作流。

设置 Hooks

必须每次都发生、零例外的动作,用 hooks。Hooks 在 Claude 工作流的特定节点自动运行脚本。与 CLAUDE.md 的「建议性」指令不同,hooks 是确定性的,保证动作一定发生。Claude 能替你写 hook,试试:「写一个 hook,每次文件编辑后跑 eslint」或「写一个 hook,阻止对 migrations 文件夹的写入」。直接编辑 .claude/settings.json 手工配置,用 /hooks 浏览已配置项。

创建技能(Skills)

在 .claude/skills/ 下创建 SKILL.md,给 Claude 领域知识和可复用的工作流。相关时 Claude 自动应用,也可用 /skill-name 直接调用。领域知识型示例:

---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)

技能也能定义直接调用的可重复工作流(/fix-issue 1234 触发)。对有副作用、希望手动触发的工作流,加 disable-model-invocation: true:

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

创建自定义子智能体(Subagents)

在 .claude/agents/ 定义专职助手,Claude 可把隔离任务委托给它们。子智能体在自己的上下文里运行、有自己的工具集,适合要读很多文件、或需要专注视角、又不想弄乱主对话的任务。示例:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

要显式指名:「Use a subagent to review this code for security issues.」

安装插件(Plugins)

运行 /plugin 浏览市场。插件把技能、hooks、子智能体和 MCP 服务器打包成一个可安装单元,来自社区和 Anthropic。如果你写的是带类型的语言,装一个代码智能插件,给 Claude 精确的符号导航和编辑后自动报错。技能/子智能体/hooks/MCP 之间怎么选,见 Extend Claude Code。

你与 Claude Code 的沟通方式显著影响结果质量。

像问资深工程师一样问代码库问题

初上手新代码库时,把 Claude Code 当学习与探索工具,问你会问另一位工程师的那类问题:

• 日志是怎么做的?
• 怎么新建一个 API 端点?
• foo.rs 第 134 行的 async move { ... } 是干什么的?
• CustomerOnboardingFlowImpl 处理了哪些边界情况?
• 第 333 行为什么调 foo() 而不是 bar()?

这样用是一条高效的入职路径:上手更快、也减轻了其他工程师的负担。不需要特殊的提示技巧,直接问就行。

让 Claude 反过来采访你

做大功能之前,先让 Claude 采访你:从一句极简提示开始,让它用 AskUserQuestion 工具对你做访谈。它会问到你可能还没考虑的东西:技术实现、UI/UX、边界情况、取舍。原文模板:

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

规格写完后,开一个全新会话来执行:新会话的上下文干净、完全聚焦实现,而你手里有一份可引用的书面规格。最有用的规格是自包含的:指名涉及的文件与接口、说明什么不在范围内、以一个端到端验证步骤收尾来证明功能可用。把规格写精确所花的时间,比盯着实现过程更值。

对话是持久的、可回退的——好好利用这一点!

尽早、频繁地纠偏

最好的结果来自紧凑的反馈循环。虽然 Claude 偶尔第一次就把问题解决得很完美,但及时纠正通常能更快得到更好的方案:

• Esc:随时打断 Claude 的动作。上下文保留,可以直接改方向。
• Esc + Esc 或 /rewind:打开回退菜单,恢复之前的对话和代码状态,或从选定消息开始做摘要。
• 「Undo that」:让 Claude 撤销自己的修改。
• /clear:不相关任务之间重置上下文。塞满无关内容的长会话会拖低表现。

激进地管理上下文

接近上下文上限时,Claude Code 会自动压缩(compact)会话历史,保留重要的代码与决策、腾出空间。长会话里,窗口会被无关对话、文件内容和命令填满,这会降低表现、有时还会让 Claude 分心:

• 任务之间勤用 /clear,整体重置上下文窗口。
• 自动压缩触发时,Claude 会摘要最重要的部分:代码模式、文件状态、关键决策。
• 要更强控制,用 /compact <指令>,比如 /compact Focus on the API changes。
• 只压缩部分对话:Esc + Esc 或 /rewind 选一个消息检查点,选「Summarize from here」(往后压缩、保留更早上下文)或「Summarize up to here」(压缩更早的、保留最近的)。见 Restore vs. summarize。
• 在 CLAUDE.md 里定制压缩行为,比如 "When compacting, always preserve the full list of modified files and any test commands",确保关键上下文能活过摘要。
• 不需要留在上下文里的快问快答,用 /btw:答案显示在可关掉的浮层里,永不进入对话历史。

用子智能体做调研

既然上下文是根本约束,子智能体就是最有力的工具之一。Claude 调研代码库要读一堆文件,全都消耗你的上下文;子智能体在独立的上下文窗口里跑,只汇报摘要回来:

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

也可以在 Claude 实现完之后用子智能体做验证:use a subagent to review this code for edge cases。

用检查点回退

你发的每条提示都会创建一个检查点。Claude 在每次修改前自动快照文件,所以检查点能恢复它们。双击 Escape 或 /rewind 打开回退菜单:只恢复对话、只恢复代码、两者都恢复、或从选定消息做摘要(细节见 Checkpointing)。有了它,你不必步步为营——直接让 Claude 试一些冒险的做法,不行就回退换路。检查点跨会话持久,关掉终端之后仍能回退。

续接对话

用 /rename 给会话命名,把会话当分支用:每条工作流有自己的持久上下文。Claude Code 在本地保存对话,跨多次坐下来的任务不用重新解释背景。claude --continue 接最近的会话,claude --resume 从列表挑。起描述性名字(如 oauth-migration)方便日后找回。完整的续接、分支与命名控制见 Manage sessions。

一个 Claude 用顺手之后,用并行会话、非交互模式和扇出(fan-out)模式放大产出。前面的一切都默认「一个人、一个 Claude、一段对话」,但 Claude Code 可以横向扩展。

非交互模式

claude -p "your prompt" 让 Claude 无会话地跑。非交互模式是把 Claude 集成进 CI 流水线、pre-commit 钩子或任何自动化工作流的方式。输出格式支持纯文本、JSON、流式 JSON,便于程序化解析:

# One-off queries
claude -p "Explain what this project does"

# Structured output for scripts
claude -p "List all API endpoints" --output-format json

# Streaming for real-time processing
claude -p "Analyze this log file" --output-format stream-json --verbose

跑多个 Claude 会话

并行跑多个 Claude 会话,可以用来加速开发、跑隔离实验、或启动复杂工作流。按你想自己协调多少来选并行方案:

• Worktrees:在隔离的 git 检出里跑独立 CLI 会话,编辑互不冲突。
• 桌面应用:可视化管理多个本地会话,每个都有自己的 worktree。
• Claude Code on the web:在 Anthropic 托管的云基础设施上、隔离 VM 里跑会话。
• Agent teams:多会话自动协同,共享任务、消息与一个队长(team lead)。

并行不只是提速,还能解锁质量导向的工作流:新鲜上下文能改善代码评审——Claude 不会偏袒自己刚写的代码。例如 Writer/Reviewer 模式:

测试也能玩类似的:一个 Claude 写测试,另一个写代码去通过它们。

跨文件扇出

大型迁移或分析,可以把工作分给许多并行的 Claude 调用:

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

也可以把 Claude 接进现有数据/处理管道:claude -p "<your prompt>" --output-format json | your_command。开发调试用 --verbose,生产环境关掉。

用 auto mode 自主运行

想要不被打断的执行 + 后台安全检查,用 auto mode:分类器模型在命令运行前审查,拦截越权扩大范围、未知基础设施和被恶意内容驱动的操作,例行工作则不弹窗直接放行。

claude --permission-mode auto -p "fix all lint errors"

带 -p 的非交互运行中,如果分类器反复拦截,auto mode 会中止——因为没有用户可以兜底。阈值见 when auto mode falls back。

加一道对抗性评审

把任务当作完成之前,让一个子智能体在全新上下文里评审 diff 并报告缺口。Claude 无人值守工作得越久,独立检查就越重要。全新子智能体上下文里的评审者只看到 diff 和你给的标准,看不到产生这次修改的推理过程,所以它按结果本身评判。要做正确性检查,直接跑自带的 /code-review 技能;要对照你的计划检查,自己写评审提示——指名要查的工作、对照的计划、什么算一条发现:

Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.

因为评审者以子智能体身份运行,实施会话直接收到缺口清单,能修完再复审,不用你在窗口间搬运结论。更长的自主运行可以用 agent team 把这个循环跨任务持续下去,你只抽查记录在案的发现。

这些是常见错误,早识别早省时间:

本指南的模式不是铁律,而是普遍好用的起点,未必对每个情境最优。有时你应该让上下文积累,因为你正深入一个复杂问题、历史很有价值;有时该跳过计划让 Claude 自己摸,因为任务本身是探索性的;有时模糊提示恰恰是对的,因为你想先看 Claude 如何理解问题、再去约束它。

留意什么有效。Claude 产出很棒时,注意你做了什么:提示的结构、你给的上下文、所处的模式;它挣扎时,问问为什么——上下文太吵?提示太模糊?任务太大、一口吃不下?随着时间推移,你会积累出任何指南都写不出来的直觉:何时具体、何时开放,何时计划、何时探索,何时清上下文、何时让它积累。

原文「相关资源」

• How Claude Code works:agentic 循环、工具与上下文管理
• Extend Claude Code:技能、hooks、MCP、子智能体与插件
• Common workflows:调试、测试、PR 等分步菜谱
• CLAUDE.md:存放项目约定与持久上下文

术语表(增补)

上下文窗口

模型单次能「看见」的全部内容:对话、读过的文件、命令输出;本文一切实践的出发点。

plan mode

计划模式:只读不写,用于探索与出计划;Ctrl+G 可在编辑器里直接改计划。

/goal

把验证条件设为会话目标,独立评估器每轮复查,不成立就继续干。

Stop hook

在 Claude 想收尾时强制跑你的检查脚本,不过不放行(连续拦 8 次后例外放行)。

auto mode

自动权限模式:独立分类器模型审查命令,只拦高风险操作,其余免弹窗。

compact / /clear

压缩(摘要保留要点)与清空(彻底重置)上下文的两种手段。

/btw

侧问:答案显示在浮层、不进对话历史,不长上下文。

checkpoint

每条提示自动创建的还原点,可恢复对话/代码/两者;只覆盖 Claude 的修改。

worktree

git 的多工作副本机制,让多个会话在隔离检出里互不踩脚。

fan-out

扇出:脚本循环调用 claude -p,把大迁移拆成许多并行小任务。