Claude Code 最佳实践¶

Claude Code 是一个自主式编程环境。它不是等你提问的聊天机器人，而是能读文件、跑命令、改代码、自主解决问题的 Agent。

这改变了你的工作方式：你描述目标，Claude 自己探索、规划、实现。但自主性带来学习曲线——Claude 有自己的约束，你需要理解它。

本指南覆盖 Anthropic 内部团队和外部工程师验证有效的模式。关于 Agent 循环的底层机制，参见 How Claude Code works（中文）。

核心约束：上下文窗口¶

所有最佳实践都围绕一个核心约束：上下文窗口会快速填满，填满后性能下降。

上下文窗口装着整个对话——你的消息、Claude 读的文件、命令输出。一次调试或代码探索就可能消耗数万 token。窗口接近满载时，Claude 会"遗忘"早期指令或犯更多错误。

上下文窗口是你最需要管理的资源。用 custom status line 持续追踪用量，参见 Reduce token usage 了解节省策略。

给 Claude 提供验证手段¶

让 Claude 自己验证工作是否完成，是"能放手不管"和"必须盯着看"的分水岭。

Claude 在工作"看起来完成"时停止。没有验证手段，"看起来完成"就是唯一信号，你变成了人工验证环。给它一个能产生通过/失败结果的检查，循环就自动闭合：Claude 做事、跑检查、读结果、迭代直到通过。

检查可以是：测试套件、构建退出码、Linter、对比输出的脚本、浏览器截图 与设计稿的比对。

验证的四个层级¶

有了检查之后，决定它在多大程度上"卡住"停止：

让 Claude 展示证据（测试输出、命令结果、截图），而不是断言"已完成"。审查证据比自己重跑验证快得多。

先探索、再规划、后编码¶

把研究规划和实现分开，避免解决错误的问题。

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

推荐的四阶段工作流¶

何时跳过规划： 范围清晰且修改小（修 typo、加 log、改变量名）时直接做。规划最有价值的场景是——你不确定方案、变更涉及多文件、或你不熟悉被修改的代码。如果能一句话描述 diff，就跳过规划。

在 Prompt 中提供精确上下文¶

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

Claude 能推理意图，但不能读你的心。引用具体文件、提及约束、指向示例模式。

模糊提示在探索阶段反而有用。比如 "what would you improve in this file?" 能发现你想不到的问题。

提供丰富内容¶

用 @ 引用文件、粘贴截图、管道输入数据——越丰富越好。

配置你的环境¶

几步配置让 Claude Code 在所有会话中都显著更高效。

完整的扩展功能概览参见 Extend Claude Code。

写好 CLAUDE.md¶

/init 生成起始文件，之后持续精简。

CLAUDE.md 是 Claude 每次对话开始时读取的特殊文件。放入 Bash 命令、代码风格、工作流规则——给 Claude 无法从代码推断的持久上下文。

# 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 反复违反规则但 CLAUDE.md 里有，文件可能太长、规则被淹没了
- 如果 Claude 问了 CLAUDE.md 已回答的问题，措辞可能有歧义
- 像代码一样对待 CLAUDE.md：出问题时审查、定期精简、观察行为变化
- 加强调（如 "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.md 可放置的位置：

配置权限¶

用 auto mode 让分类器处理审批，/permissions 白名单特定命令，/sandbox 启用 OS 级隔离。三种方式各自减少中断。

默认情况下，Claude Code 对可能修改系统的操作请求权限。安全但繁琐。三种减少中断的方式：

详见 permission modes、permission rules、sandboxing。

使用 CLI 工具¶

告诉 Claude 用 gh、aws、gcloud、sentry-cli 等 CLI 与外部服务交互——这是最省上下文的方式。

如果用 GitHub，装 gh CLI。Claude 知道怎么用它创建 issue、开 PR、读评论。没有 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、数据库等外部工具。

通过 MCP servers，你可以让 Claude 从 issue tracker 实现功能、查数据库、分析监控数据、集成 Figma 设计、自动化工作流。

设置 Hooks¶

Hooks 用于"必须每次发生、零例外"的动作。

Hooks 在 Claude 工作流的特定时点自动运行脚本。与 CLAUDE.md 的建议性指令不同，Hooks 是确定性的，保证动作发生。

Claude 能帮你写 Hook。试试："Write a hook that runs eslint after every file edit" 或 "Write a hook that blocks writes to the migrations folder."

编辑 .claude/settings.json 手动配置，运行 /hooks 浏览已配置的 Hook。

创建 Skills¶

在 .claude/skills/ 创建 SKILL.md 文件，给 Claude 领域知识和可复用工作流。

Skills 用项目/团队/领域特定信息扩展 Claude 的知识。Claude 在相关时自动应用，或用 /skill-name 直接调用。

# .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 用于有副作用、需要手动触发的工作流。

创建自定义子 Agent¶

在 .claude/agents/ 定义专用助手，Claude 可将隔离任务委托给它们。

子 Agent 在自己的上下文中运行，有自己的工具集。适用于读很多文件或需要专注而不污染主对话的任务。

# .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 使用子 Agent："Use a subagent to review this code for security issues."

安装插件¶

/plugin 浏览市场。插件将 skills、tools、集成打包为一键安装单元。

Plugins 将 skills、hooks、subagents 和 MCP servers 打包为来自社区和 Anthropic 的可安装单元。如果用类型化语言，安装 code intelligence plugin 给 Claude 精确的符号导航和编辑后自动错误检测。

如何在 skills、subagents、hooks 和 MCP 之间选择，参见 Extend Claude Code。

有效沟通¶

沟通方式显著影响输出质量。

问代码库相关问题¶

像问高级工程师一样问 Claude 问题。

入职新代码库时，用 Claude Code 学习和探索。问你会问其他工程师的问题：

• 日志系统是怎么工作的？
• 如何新建一个 API endpoint？
• foo.rs 第 134 行的 async move { ... } 做了什么？
• CustomerOnboardingFlowImpl 处理了哪些边界情况？
• 第 333 行为什么调 foo() 而不是 bar()？

这种用法有效缩短入职时间、减少其他工程师的负担。无需特殊提示技巧，直接问。

让 Claude 面试你¶

对于较大功能，先让 Claude 面试你。用最少的 prompt 开始，让 Claude 通过 AskUserQuestion 工具追问。

Claude 会问你可能没考虑到的事——技术实现、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.

Spec 完成后，开一个新会话执行。新会话的上下文干净，完全聚焦于实现；你有书面 Spec 可随时参考。

最有用的 Spec 是自包含的：列出涉及的文件和接口、说明范围外的内容、以端到端验证步骤结尾来证明功能可用。花在精确 Spec 上的时间比花在看实现过程上的时间回报更高。

管理你的会话¶

对话是持久化和可逆的。利用这一点。

尽早纠偏¶

发现 Claude 偏离方向时立即纠正。

最好的结果来自紧密的反馈循环。虽然 Claude 偶尔一次完美解决问题，但快速纠正通常更快产出更好的方案。

如果同一会话中纠正了 Claude 两次以上同一问题，上下文已被失败方案塞满。运行 /clear，用更精确的 prompt 重新开始——融入你学到的东西。干净会话 + 更好 prompt 几乎总是优于长会话 + 累积修正。

积极管理上下文¶

不相关任务之间用 /clear 重置上下文。

Claude Code 在接近上下文限制时自动压缩对话历史，保留重要代码和决策并释放空间。

长会话中，上下文窗口可能充满无关对话、文件内容和命令，降低性能甚至让 Claude 分心。

用子 Agent 做调查¶

用 "use subagents to investigate X" 委托研究。子 Agent 在独立上下文中探索，主对话保持干净。

上下文是根本约束，子 Agent 是最强大的工具之一。Claude 研究代码库时会读大量文件，全部消耗上下文。子 Agent 在独立上下文窗口中运行，只返回摘要：

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

子 Agent 探索代码库、读相关文件、返回发现——不污染主对话。

也可在 Claude 实现完成后用子 Agent 验证：

use a subagent to review this code for edge cases

用检查点回退¶

每次发送 prompt 都创建检查点。你可以将对话、代码或两者恢复到任何之前的检查点。

Claude 在每次修改前自动快照文件。双击 Escape 或运行 /rewind 打开回退菜单。可以只恢复对话、只恢复代码、两者都恢复，或从选定消息总结。参见 Checkpointing。

你可以让 Claude 放手尝试有风险的事。不行就回退，换个方案。检查点跨会话持久化——关掉终端之后仍可回退。

注意：检查点只追踪 Claude 做的更改，不追踪外部进程。这不是 git 的替代品。

恢复对话¶

用 /rename 命名会话，把它们当作分支：每个工作流有自己的持久上下文。

Claude Code 在本地保存对话。跨多次坐下工作时不需要重新解释上下文。claude --continue 继续最近会话，claude --resume 从列表中选择。给会话起描述性名称如 oauth-migration 以便之后找到。参见 Manage sessions。

自动化与扩展¶

一个 Claude 用好了，用并行会话、非交互模式、扇出模式倍增产出。

以上内容假设一人一 Claude 一对话。但 Claude Code 能水平扩展。本节展示如何做更多。

运行非交互模式¶

claude -p "prompt" 用于 CI、pre-commit hooks 或脚本。加 --output-format stream-json --verbose 获取流式 JSON 输出。

claude -p "your prompt" 以非交互方式运行 Claude，没有会话。非交互模式 是将 Claude 集成到 CI 流水线、pre-commit hooks 或任何自动化工作流的方式。

# 一次性查询
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

运行多个 Claude 会话¶

并行运行多个 Claude 会话：加速开发、运行隔离实验、启动复杂工作流。

根据你想做多少协调，选择并行方式：

并行之外，多会话也能提升质量。新上下文改善代码审查——Claude 不会对自己刚写的代码有偏见。

Writer/Reviewer 模式示例：

类似地：一个 Claude 写测试，另一个写代码让测试通过。

跨文件扇出¶

循环调用 claude -p 处理每个任务。用 --allowedTools 限定批量操作的权限。

对大规模迁移或分析，将工作分发到多个并行 Claude 调用：

1. 生成任务列表：让 Claude 列出需要迁移的所有文件
2. 写脚本循环处理：

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

3. 先在几个文件上测试，再大规模运行：根据前 2-3 个文件的问题优化 prompt，然后跑全集。--allowedTools 限制 Claude 可做的事——无人值守时很重要。

也可将 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。

添加对抗性审查步骤¶

在视为完成之前，让子 Agent 在新上下文中审查 diff 并报告遗漏。

Claude 无人值守工作越久，独立检查在结束前就越重要。在新 子 Agent 上下文中运行的审查者只看到 diff 和你给的标准，而不是产生变更的推理过程——它用自己的判断评估结果。

正确性检查可运行内置 /code-review skill，在新子 Agent 中审查当前 diff 并返回发现。要对照计划检查，自己写审查 prompt：

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 运行，实现会话直接收到遗漏并可修复和重新审查，无需你在窗口间复制。对更长的自主运行，agent team 可在多任务间持续此循环，你只需抽查记录的发现。

注意：被 prompt 要求"找遗漏"的审查者通常会报告一些，即使工作完善——因为那是它被要求做的。追逐每个发现导致过度工程：多余的抽象层、防御性代码、为不可能发生的情况写测试。告诉审查者只标记影响正确性或明确需求的遗漏，其余视为可选。

避免常见失败模式¶

识别这些模式可节省大量时间。

培养你的直觉¶

本指南的模式不是铁律。它们是通用有效的起点，但未必对每种情况都最优。

有时你应该让上下文累积——因为你深陷一个复杂问题、历史记录有价值。有时应该跳过规划——因为任务是探索性的。有时模糊 prompt 恰恰正确——因为你想看 Claude 如何解读问题再加以约束。

注意什么有效。当 Claude 产出优秀输出时，留意你做了什么：prompt 结构、提供的上下文、所在的模式。当 Claude 挣扎时，问为什么。上下文太嘈杂？prompt 太模糊？任务对一次通过来说太大？

随着时间推移，你会培养出任何指南都无法捕捉的直觉。你会知道何时精确、何时开放，何时规划、何时探索，何时清上下文、何时让它累积。

相关资源¶

• How Claude Code works（中文） — Agent 循环、工具和上下文管理
• Extend Claude Code — skills、hooks、MCP、subagents 和 plugins
• Common workflows — 调试、测试、PR 等逐步指南
• CLAUDE.md — 存储项目约定和持久上下文