工程 · Engineering

Claude Code 最佳实践

给 Claude 一个能验证工作的办法

Claude 在「看起来做完了」的时候会停下。如果没有它能执行的检查，「看起来做完了」就是唯一可用的信号，于是你成了验证环路本身：每一个错误都要等你去发现。给它一个能产出通过或失败的东西，这个环路就自己闭合了——Claude 干活、跑检查、读结果，一直迭代到检查通过。

所谓检查，是任何能在对话里给 Claude 一个可读信号的东西：一套测试、构建的退出码、一个 linter、一个把输出与基准文件做对比的脚本，或者一张与设计稿对比的浏览器截图。在 Claude 的检查通过之后，你自己再跑一遍 /verify，对着运行中的应用确认真的是对的。

检查存在之后，再决定它多硬地卡住收尾：

• 在同一句提示里：让 Claude 跑检查并在同一条消息里迭代，就像上表那样。
• 贯穿整个会话：把检查设成 /goal 条件。一个独立的评估器在每一轮之后重新检查，Claude 会一直干活直到目标达成。如果 Claude 卡住，Claude Code 最终会带着未达成的目标结束这次运行。
• 作为确定性关卡：Stop hook 会把你的检查当脚本执行，在通过之前不允许这一轮结束。
• 交给第二双眼睛：用一个验证 subagent，或一个会自查结论的动态 workflow，让另一个模型尝试推翻结果——干活的那个 agent 不该同时是打分的那个。

每一步都是用配置换注意力。只用提示词的方式今天就能用在任何任务上；/goal 和 Stop hook 才是让无人值守的运行也能正确收尾的东西。

让 Claude 给出证据，而不是宣称成功：测试输出、它跑的命令和返回、或者结果截图。看证据比自己再跑一遍验证更快，而且对你没盯着的会话同样有效。

先探索，再计划，最后写代码

让 Claude 直接开写，很可能写出解决错问题的代码。用 plan mode 把探索和执行分开。

推荐的工作流有四个阶段：

1. 探索

按 Shift+Tab 直到状态栏显示 ⏸ plan mode on 进入 plan mode，或者用 claude --permission-mode plan 启动会话。Claude 会读文件、回答问题，但不做任何改动。

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

2. 计划

让 Claude 产出一份详细的实现计划。

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

按 Ctrl+G 把计划在编辑器里打开，直接改完再让 Claude 继续。

3. 实现

批准计划或再按 Shift+Tab 退出 plan mode，让 Claude 照着计划写代码并自行对照检查。

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

4. 提交

让 Claude 用一条描述清楚的提交信息提交，并开一个 PR。

claudecommit with a descriptive message and open a PR

plan mode 有用，但也有开销。范围清晰、改动很小的事情（改个错字、加一行日志、重命名变量），直接让 Claude 做。

计划最适合这些情况：你对接下来的做法没把握；改动会涉及多个文件；你要改的代码自己不熟。如果你能用一句话描述这次 diff，那就跳过计划。

在提示词里给出具体上下文

Claude 能推断意图，但读不了你的心。点名具体文件、说明约束、指出可以参考的现成写法。

模糊的提示也有用——尤其是在探索阶段、你付得起来回纠偏的成本时。像「这个文件你会怎么改？」这样的问题，常常能挖出你原本想不到要问的点。

提供更丰富的内容

给 Claude 提供资料有几种方式：

• 用 @ 引用文件，而不是描述代码在哪。Claude 会在回答前先读那个文件。
• 直接贴图片。复制粘贴或拖进提示词即可。
• 给 URL，指向文档和 API 参考。常用域名可以用 /permissions 加进白名单。
• 管道输入数据，例如 cat error.log | claude -p "explain this error"，把文件内容直接送进去。
• 让 Claude 自己去取。告诉它用 Bash 命令、MCP 工具或读文件来拉取上下文。

配置好你的环境

几个设置动作能让 Claude Code 在你所有会话里都明显更好用。想完整了解各种扩展能力以及各自适合什么场景，见官方文档的 Extend Claude Code。

写好 CLAUDE.md

CLAUDE.md 是一个特殊文件，Claude 在每次对话开始时都会读它。把 Bash 命令、代码风格、工作流规则写进去，就等于给了 Claude 一份它没法从代码里推断出来的长期上下文。

CLAUDE.md 没有规定格式，但要短、要好读。例如：

CLAUDE.md# 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

用 /context 确认 Claude 确实加载了它。CLAUDE.md 每个会话都会加载，所以只写普遍适用的东西。只在某些场景才相关的领域知识或流程，用 skills 更合适——Claude 按需加载，不会把每个会话都撑大。

保持精简。对每一行问一句：删掉它，Claude 会不会犯错？不会就砍掉。臃肿的 CLAUDE.md 会让 Claude 忽略你真正的指令。

如果明明写了规则，Claude 还是反复做你不想要的事，多半是文件太长、规则被淹没了。如果 Claude 问你一个 CLAUDE.md 里已经回答过的问题，多半是措辞含糊。把 CLAUDE.md 当代码对待：出问题时回看它，定期修剪，改完观察 Claude 的行为是否真的变了。对已经入库的 CLAUDE.md，跑一次 /doctor，Claude 会提议删掉那些它能从代码库推导出来的内容。

如果某一条指令总被跳过，单独给那一行加「IMPORTANT」之类的强调。强调很多行，等于一行都没强调。把 CLAUDE.md 提交进 git，让团队一起补——这个文件的价值会随时间复利增长。

CLAUDE.md 可以用 @path/to/import 语法导入其他文件。导入规则和文件可以放的位置，见官方文档。

配置权限

在 Claude Code v2.1.283 及以后，auto 模式是交互式终端与 VS Code 会话的内置起始权限模式：由一个独立的分类模型替你审掉大部分动作，只拦看起来有风险的——比如扩大影响范围、不熟悉的基础设施、或被恶意内容驱动的操作。更早的版本里，只有 Pro、Max 和 Team 套餐默认从 auto 模式起步。

Manual 模式下，会改动系统的动作都要先问你：写文件、Bash 命令、MCP 工具。这安全，但累。批准到第十次时，你其实是在点「同意」而不是在审阅。Manual 模式下有两个东西能减少打断，auto 模式下同样生效：

• 权限白名单：批准你确定安全的特定工具，比如 npm run lint 或 git commit
• 沙箱：开启操作系统级隔离，限制文件系统与网络访问，让 Claude 在划定的边界内更自由地工作

用 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 server

接上 MCP server 之后，你可以让 Claude 按 issue 跟踪器实现功能、查数据库、分析监控数据、对接 Figma 设计稿、自动化一些流程。

设置 hooks

Hooks 会在 Claude 工作流的特定时点自动跑脚本。CLAUDE.md 里的指令是建议性的，hooks 是确定性的——它保证那件事一定发生。

Hook 也可以让 Claude 来写。可以这样提示：「写一个 hook，每次改完文件都跑 eslint」，或者「写一个 hook，禁止写入 migrations 目录」。手写的话直接改 .claude/settings.json，用 /hooks 查看当前配置了哪些。

创建 skills

Skills 用你的项目、团队或领域特有的信息来扩展 Claude 的知识。相关时它会自动用上，你也可以用 /skill-name 直接调用。

在 .claude/skills/ 下建一个目录，放一个 SKILL.md 就是一个 skill：

.claude/skills/api-conventions/SKILL.md---
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/)

Skills 也能定义你直接调用的重复性流程：

.claude/skills/fix-issue/SKILL.md---
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

用 /fix-issue 1234 触发。有副作用、你想手动触发的流程，加上 disable-model-invocation: true。

创建自定义 subagent

Subagent 在自己的上下文里运行，带着自己那套允许使用的工具。适合要读很多文件、或者需要专门视角又不想弄脏主对话的任务。

.claude/agents/security-reviewer.md---
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.

要明确告诉 Claude 用 subagent：「用 subagent 审一下这段代码的安全问题」。

安装插件

插件把 skills、hooks、subagent 和 MCP server 打包成一个可安装单元，来自社区和 Anthropic。如果你用带类型的语言，装一个代码智能插件，能让 Claude 精确跳转符号，并在改动后自动发现错误。

在 skills、subagent、hooks、MCP 之间怎么选，见官方文档的 Extend Claude Code。

有效地沟通

像问另一位工程师那样问 Claude；功能比较大时，先让 Claude 反过来采访你、写出一份 spec，再开始实现。

问代码库的问题

接手新代码库时，用 Claude Code 来学习和探索。你可以问那些本来要问同事的问题：

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

这样用 Claude Code 是很有效的上手方式：缩短爬坡时间，也减轻其他工程师的负担。不需要什么特殊提示，直接问就行。

让 Claude 采访你

Claude 会问到你还没想到的地方：技术实现、界面与交互、边界情况、取舍。发送前把 [简述] 换成你的功能。

claudeI 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.

spec 写完之后，开一个全新的会话去执行它。新会话的上下文是干净的，全部用于实现；而你手上有一份写好的 spec 可以对照。

最有用的 spec 是自包含的：点名涉及的文件和接口，写明什么不在范围内，最后给一个端到端的验证步骤，证明这个功能确实能用。花在把 spec 写精确上的时间，回报高于花在盯着实现上的时间。

管理你的会话

对话是持久的，也是可回退的。把这两点用起来。

尽早、频繁地纠偏

最好的结果来自紧凑的反馈环路。Claude 偶尔一次就做对，但多数时候，快速纠正能更快得到更好的方案。

• Esc：中断 Claude 正在做的事。上下文会保留，你可以就地改方向。
• Esc + Esc 或 /rewind：打开回退菜单，恢复之前的对话与代码状态，或者从某条消息开始做总结。
• 「撤销这个」：让 Claude 撤掉它自己的改动。
• /clear：在互不相关的任务之间重置上下文。带着无关内容的长会话会降低表现。

如果同一个问题在一个会话里纠正了两次以上，上下文里已经堆满了失败的尝试。跑 /clear，带着你学到的东西写一条更具体的提示重新开始。干净的会话加更好的提示，几乎总是胜过带着一堆纠正的长会话。

激进地管理上下文

接近上限时 Claude Code 会自动压缩对话历史：保留重要的代码和决策，腾出空间。

长会话里，上下文窗口会塞满无关的对话、文件内容和命令，既降低表现，有时还会让 Claude 分心。

• 任务之间常用 /clear，彻底重置上下文窗口
• 自动压缩触发时，Claude 会总结最关键的部分：代码模式、文件状态、关键决策
• 想更可控，用 /compact <指令>，比如 /compact Focus on the API changes
• 只想压缩一段对话，用 Esc + Esc 或 /rewind 选一个消息检查点，然后选择「从这里开始总结」或「总结到这里」：前者压缩该点之后的若干消息、保留早先的上下文；后者压缩早先的消息、完整保留近期内容
• 把压缩行为写进 CLAUDE.md，例如「压缩时始终保留完整的改动文件列表和所有测试命令」，保证关键上下文熬过总结
• 不需要留在上下文里的问题，用 /btw：答案不会进入对话历史，查个细节而不撑大上下文

用 subagent 做调研

既然上下文是根本约束，就把研究挪出主上下文。Claude 调研一个代码库要读大量文件，全都消耗你的上下文。Subagent 在独立的上下文窗口里跑，只把摘要报回来：

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

Claude 实现完之后，也可以用 subagent 来做验证。

用 checkpoint 回退

Claude 在每次改动前会自动给文件做快照，checkpoint 就是靠它恢复。双击 Escape 或跑 /rewind 打开回退菜单：可以只恢复对话、只恢复代码、两者都恢复，或者从选中的消息开始总结。

于是你不必每一步都精心规划：可以让 Claude 试一个冒险的做法，不行就退回来换一条路。Checkpoint 跟对话一起保存，关掉终端、之后恢复会话，仍然能回退。

恢复会话

Claude Code 把对话保存在本地，所以一个任务跨几天也不用重新解释背景。跑 claude --continue 接着上一次，或者 claude --resume 从列表里挑。给会话起描述性名字，比如 oauth-migration，之后好找。

自动化与规模化

把单个 Claude 用顺之后，用并行会话、非交互模式和扇出模式把产出放大。

非交互模式

claude -p "your prompt" 让 Claude 非交互地跑，不需要人应答。除非你传 --no-session-persistence，这次运行仍会创建一个可恢复的会话。非交互模式是把 Claude 接进 CI 流水线、pre-commit hook 或任何自动化流程的方式。输出格式让结果可以程序化解析：纯文本、JSON 或流式 JSON。

bash# 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

第一条打印纯文本。json 格式返回一个带 result 字段的 JSON 对象。stream-json 每行打印一个 JSON 对象，以一个 init 事件开头。

并行跑多个会话

按你愿意投入多少协调成本来选并行方式；需要在会话之间传递发现时，再加上消息机制：

• Worktree：在互相隔离的 git 检出里跑各自的 CLI 会话，改动不会互相踩
• 跨会话消息：让你自己开的几个会话互相传递发现
• 桌面应用：可视化地管理多个本地会话，可以各自一个 worktree
• 云端 Claude Code：默认在 Anthropic 托管的基础设施上跑会话
• Agent view：研究预览。跑 claude agents 派发在后台持续运行的会话，在一个界面里看
• Agent teams：实验性，默认关闭。多会话自动协同，共享任务、消息，有 team lead

除了并行干活，多会话还能支撑偏向质量的工作流。全新的上下文能让代码审查更有效，因为 Claude 不会偏袒自己刚写的代码。

比如 Writer / Reviewer 模式：

测试也能这么玩：让一个 Claude 写测试，另一个写代码去通过它们。

跨文件扇出

大迁移或大分析，可以把工作分摊到许多并行的 Claude 调用上。跑 /batch <指令>，Claude 会把改动拆给 5 到 30 个 subagent，每个在自己的 worktree 里干活。想用自己的脚本驱动扇出，就循环调用 claude -p：

1. 生成任务清单

让 Claude 把需要迁移的文件列表写成文件，下一步的循环就能读它。提示例如：list all 2,000 Python files that need migrating and save the list to files.txt

2. 写个脚本遍历这个清单

bashfor file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

3. 先在几个文件上试，再全量跑

根据前两三个文件出的问题改进提示词，然后跑全量。--allowedTools 预批准了迁移需要的工具；--permission-mode dontAsk 会拒绝其他任何需要批准的调用——无人值守时这一点很重要，不过你安装的 mod 仍可能批准其中一些调用。

也可以把 Claude 接进已有的数据处理流水线：

bashclaude -p "<your prompt>" --output-format json | your_command

用 auto 模式自主运行

想要不被打断、同时后台还有安全检查，用 auto 模式。一个分类模型在命令执行前审查，拦下扩大影响范围、不熟悉的基础设施、被恶意内容驱动的操作，其余常规工作直接放行。

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

在带 -p 的非交互运行里，如果分类器反复拦截某些操作，Claude Code 不会因此终止这次运行。

加一步对抗式审查

Claude 无人值守跑得越久，独立检查就越重要。审查者跑在全新的 subagent 上下文里，只看到 diff 和你给的判据，看不到产生这次改动的推理过程，因此它会按自己的理解评估结果。

想查正确性，跑内置的 /code-review skill：它在全新的 subagent 里审查当前 diff 找 bug，把发现送回会话。想对照计划检查，就自己写审查提示——点名要检查的东西、对照的计划，以及什么算一条发现：

claudeUse 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.

因为审查者以 subagent 运行，实现它的那个会话能直接收到这些缺口，自己修完再重审，不需要你在窗口之间复制粘贴。

被要求「找缺口」的审查者，通常总能报告出一些，即使实现本身是好的——它被要求做的就是这个。追着每一条发现改，会滑向过度设计：多余抽象层、防御性代码、为不可能发生的情况写测试。告诉审查者只报影响正确性或明确需求的缺口，其余当作可选项。

避开常见的失败模式

这些都是常见的坑，早点认出来能省很多时间：

• 一锅烩会话。从一件事开始，中途问了个不相关的，又回第一件事。上下文里全是无关信息。
  对策：不相关的任务之间跑 /clear。
• 反复纠正。Claude 做错、你纠正、还是不对、再纠正。上下文被失败的尝试污染。
  对策：纠正两次还不行，就跑 /clear，把学到的东西写进一条更好的初始提示。
• 过度膨胀的 CLAUDE.md。文件太长，Claude 会忽略其中一半，因为重要规则被噪声淹没了。
  对策：狠心删。Claude 不用这条指令也能做对的，删掉，或者改成 hook。
• 信了但没验。Claude 给出一个看起来像样、其实没处理边界情况的实现。
  对策：永远提供验证手段（测试、脚本、截图）。验不了，就别发。
• 无限探索。你让 Claude「调研一下」，没圈范围。它读了几百个文件，把上下文填满。
  对策：把调研范围收窄，或者交给 subagent，别让它吃掉主上下文。

培养你的直觉

这份指南里的做法不是铁律。它们是普遍好用的起点，但不一定适合每种情况。

有时你就该让上下文累积——你正深陷一个复杂问题，历史很有价值。有时你该跳过计划，让 Claude 自己摸——因为任务是探索性的。有时模糊的提示恰好最合适——因为在约束它之前，你想先看看它怎么理解这个问题。

留意什么管用。当 Claude 产出很好，回想你做了什么：提示词的结构、你给的上下文、你当时在哪个模式。当它卡住，问一句为什么：上下文太吵？提示太模糊？任务太大，一次做不完？

慢慢地，你会养出任何指南都写不下来的直觉：什么时候该具体，什么时候该开放；什么时候该计划，什么时候该探索；什么时候该清空上下文，什么时候该让它累积。

相关资源

• How Claude Code works：agentic 环路、工具与上下文管理
• Extend Claude Code：skills、hooks、MCP、subagent 与插件
• Common workflows：调试、测试、PR 等场景的分步做法
• CLAUDE.md：存放项目约定与长期上下文