最佳实践

Claude Code 是一个智能体编程环境。它不像聊天机器人那样回答完就等待，而是能读你的文件、运行命令、做修改，并在你旁观、纠偏甚至走开时自主解决问题。这会改变你的工作方式：你不再自己写代码再让 Claude 评审，而是描述想要什么，由 Claude 去探索、规划和实现。

本页的大多数建议都基于同一个约束：Claude 的上下文窗口会很快被填满，而且填得越满，表现越差。 上下文窗口里装着整段对话：每条消息、Claude 读过的每个文件、每次命令输出。一次调试或代码库探索就可能消耗几万个 token。上下文变满后，Claude 可能开始「忘记」早先的指令或犯更多错误，所以上下文窗口是最需要管理的资源。

让 Claude 能验证自己的工作

给 Claude 一个它可以运行的检查：测试、构建、可对比的截图。这是「你得盯着的会话」和「可以走开的会话」的区别。

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

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

检查建立后，决定它对停止的约束有多强：

• 在一条提示里：让 Claude 在同一条消息里运行检查并迭代
• 贯穿整个会话：把检查设为 /goal 条件，由独立的评估器在每个回合后重新检查，Claude 持续工作直到目标达成
• 作为确定性关卡：用 Stop Hook 把你的检查作为脚本运行，在它通过前阻止回合结束
• 由第二意见把关：用验证子智能体或动态工作流，让一个全新的模型来尝试反驳结果，这样干活的智能体就不是给自己打分的那个

让 Claude 展示证据，而不是断言成功：测试输出、运行的命令及其返回，或结果截图。审阅证据比自己重跑验证更快，对你没盯着的会话也适用。

先探索，再计划，再编码

把研究和规划与实现分开，避免解决错了的问题。推荐的四个阶段：

1. 探索：进入计划模式（按 Shift+Tab 直到状态栏显示 ⏸ plan mode on，或用 claude --permission-mode plan 启动），Claude 读文件、回答问题但不做改动

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

2. 计划：让 Claude 写详细的实现计划。按 Ctrl+G 可以在文本编辑器里直接修改计划

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

3. 实现：批准计划或按 Shift+Tab 退出计划模式，让 Claude 编码并对照计划验证
4. 提交：让它写描述性的提交信息并创建 PR

计划模式有用，但也有额外开销。范围清晰、改动很小的任务（改错别字、加一行日志、重命名变量）直接让 Claude 做。规划在你对方案不确定、改动涉及多个文件、或对要改的代码不熟时最有价值。如果你能用一句话描述 diff，就跳过计划。

在提示里给出具体上下文

指令越精确，需要的纠正就越少。

探索阶段可以用模糊提示（比如「这个文件你会改进什么？」），它可能带出你没想到的问题。

提供丰富内容：用 @ 引用文件而不是描述代码在哪；直接粘贴或拖放图片；给出文档和 API 参考的 URL（用 /permissions 把常用域名加入白名单）；用 cat error.log | claude 通过管道传入数据；让 Claude 自己用 Bash、MCP 工具或读文件去获取所需上下文。

配置你的环境

写好 CLAUDE.md：运行 /init 生成起始版本，再逐步改进。它是 Claude 每次对话开头都会读的特殊文件，放 Bash 命令、代码风格和工作流规则，这些是 Claude 无法从代码里推出的持久上下文。保持简短，对每一行问自己：「删掉它会让 Claude 犯错吗？」如果不会就删掉，臃肿的 CLAUDE.md 会让 Claude 忽略你真正的指令。

如果 Claude 总是跳过某条指令，可以只给那一行加上「IMPORTANT」之类的强调；强调的行太多，就没有一行突出了。把 CLAUDE.md 提交进 git，让团队一起完善。

配置权限：用 /permissions 预先批准你信任的工具，用 /sandbox 让沙箱内的命令不用询问就运行。想自己批准编辑和命令时切到 Manual 模式。两种减少打扰的工具：权限白名单（如 npm run lint、git commit）和沙箱（OS 级别的文件系统和网络隔离）。

使用 CLI 工具：告诉 Claude 用 gh、aws、gcloud、sentry-cli 等 CLI 与外部服务交互，这是最省上下文的方式。没有 gh 时 Claude 仍可调用 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 或你的数据库等，例如：

claude mcp add --transport http notion https://mcp.notion.com/mcp

设置 Hooks：对必须每次都发生、零例外的动作使用 Hook。CLAUDE.md 的指令是建议性的，Hook 是确定性的。Claude 可以替你写 Hook，如「Write a hook that runs eslint after every file edit」；也可以直接编辑 .claude/settings.json，运行 /hooks 浏览已配置的内容。

创建 Skill：在 .claude/skills/ 下建带 SKILL.md 的目录，给 Claude 领域知识和可复用工作流：

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

Skill 也可以定义你直接调用的工作流，有副作用、想手动触发的用 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

之后运行 /fix-issue 1234 调用。

创建自定义子智能体：在 .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,
authentication flaws, secrets in code, and insecure data handling.
Provide specific line references and suggested fixes.

明确告诉 Claude 使用它们：「Use a subagent to review this code for security issues.」

安装插件：运行 /plugin 浏览市场。插件把 Skill、Hooks、子智能体和 MCP 服务器打包成一个可安装单元；用类型化语言的话，装一个代码智能插件能让 Claude 精确导航符号并在编辑后自动发现错误。

有效沟通

问代码库问题：像问资深工程师那样问 Claude，比如「How does logging work?」「How do I make a new API endpoint?」「Why does this code call foo() instead of bar() on line 333?」这是有效的上手方式，不需要特殊提示词。

让 Claude 采访你：较大的功能先让 Claude 采访你。用最简提示开始，让它用 AskUserQuestion 工具提问：

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.

规格写完后，开一个新会话来执行，新会话的上下文干净、只聚焦实现。最有用的规格是自包含的：列出涉及的文件和接口，说明范围之外的内容，并以一个能证明功能可用的端到端验证步骤结尾。

管理你的会话

尽早、经常纠偏：反馈环越紧，结果越好。

• Esc：中途停下 Claude，上下文保留，可以重定向
• Esc + Esc 或 /rewind：打开回退菜单，恢复之前的对话和代码状态，或从选中的消息开始总结
• 「Undo that」：让 Claude 还原它的改动
• /clear：在不相关的任务之间重置上下文

如果同一个问题在一个会话里纠正了超过两次，上下文里就塞满了失败的做法。运行 /clear，把学到的东西融入更具体的提示，重新开始。干净的会话加更好的提示，几乎总是胜过累积了很多纠正的长会话。

积极管理上下文：

• 在任务之间频繁用 /clear
• 自动压缩触发时，Claude 会总结最重要的内容；想要更多控制，运行 /compact Focus on the API changes
• 只压缩一部分对话：Esc + Esc 或 /rewind，选中消息检查点，选 Summarize from here 或 Summarize up to here
• 在 CLAUDE.md 里定制压缩行为，例如「压缩时始终保留已修改文件的完整列表和所有测试命令」
• 不需要留在上下文里的问题用 /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 大胆尝试，不行就回退换一种做法。注意检查点只追踪通过 Claude 文件编辑工具做的改动，Bash 命令或外部进程的改动不会被捕获，它不能替代 git。

恢复对话：用 /rename 给会话命名并当作分支对待，每条工作线有自己的持久上下文。claude --continue 接着上次继续，claude --resume 从列表里选。

自动化与扩展

非交互模式：在 CI、pre-commit Hook 或脚本里用 claude -p "prompt"。

# 一次性查询
claude -p "Explain what this project does"
# 给脚本用的结构化输出
claude -p "List all API endpoints" --output-format json
# 实时处理用的流式输出
claude -p "Analyze this log file" --output-format stream-json --verbose

json 格式返回带 result 字段的单个 JSON 对象；stream-json 每行一个 JSON 对象，以 init 事件开头。

运行多个会话：按你想自己协调的程度选择并行方式：worktree（在隔离的 git 检出里运行独立 CLI 会话）、跨会话消息、桌面应用、云端会话、智能体视图（研究预览，claude agents）、智能体团队（实验性，默认关闭）。

多会话还能带来质量收益：全新的上下文改善代码评审，因为 Claude 不会偏向它刚写的代码。例如作者/评审者模式：会话 A 实现限流器，会话 B 在新上下文里评审它，再把反馈带回会话 A。也可以让一个 Claude 写测试，另一个写代码让测试通过。

跨文件扇出：大规模迁移或分析时，运行 /batch <instruction> 让 Claude 把改动拆给 5 到 30 个子智能体，每个在自己的 worktree 里工作；或者用自己的脚本循环调用 claude -p：

for 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 *)"
done

先根据前 2-3 个文件出的问题改进提示，再跑全集。--allowedTools 限制 Claude 能做什么，无人值守运行时尤其重要。

用 auto 模式自主运行：分类器模型在命令运行前审查，拦截范围升级、未知基础设施和受恶意内容驱动的动作，让常规工作不经提示通过：

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

加一道对抗式评审：把任务视为完成前，让子智能体在全新上下文里评审 diff 并报告缺口。评审者只看到 diff 和你给的标准，看不到产生改动的推理过程。可以运行内置的 /code-review Skill，或自己写评审提示，指明要检查的工作、对照的计划和什么算发现：

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.

被要求找缺口的评审者通常总会报告一些，即使工作没问题。追着每条发现跑会导致过度工程。告诉评审者只标出影响正确性或既定需求的缺口，其余视为可选。

避免常见的失败模式

• 「厨房水槽」会话：从一个任务开始，又问了无关的事，再回到第一个任务，上下文里全是无关信息。修复：在无关任务之间 /clear
• 反复纠正：Claude 做错了，你纠正，还是错，再纠正，上下文被失败的做法污染。修复：两次纠正失败后，/clear 并把学到的东西写进更好的初始提示
• CLAUDE.md 写得过长：太长的话，重要规则会淹没在噪音里，Claude 会无视其中一半。修复：毫不留情地精简；如果 Claude 没有这条指令也能做对，就删掉它或改成 Hook
• 信任后不验证：Claude 给出一个看起来合理、但没处理边界情况的实现。修复：始终提供验证（测试、脚本、截图）；无法验证的就不要发布
• 无休止的探索：让 Claude「调查」某事却不限定范围，它会读上百个文件把上下文填满。修复：把调查范围限定得窄一些，或用子智能体，让探索不消耗主上下文

培养你自己的直觉

本页的模式不是教条，而是一般情况下效果不错的起点，不一定适合每种情况。有时你应该让上下文累积，因为你正深陷一个复杂问题、历史很有价值；有时该跳过规划让 Claude 自己摸索，因为任务本来就是探索性的；有时模糊的提示恰恰合适，因为你想看看 Claude 会怎么理解。留意什么有效：Claude 产出很好时，注意你做了什么（提示结构、提供的上下文、所处模式）；Claude 吃力时，问问为什么——上下文太嘈杂？提示太模糊？任务对一次完成来说太大？