# Claude Code Best Practices

> 原文链接：https://code.claude.com/docs
> 作者/来源：Anthropic
> 阅读日期：2026-04-02

## 一句话总结
Claude Code 最佳实践的核心约束是 **context window 会快速填满且性能随之下降**；围绕这一约束，官方从验证机制、探索-规划-实现工作流、context 管理、环境配置和并行扩展五个维度给出了系统性指导。

## 核心论点

整篇文档围绕一个核心约束展开：**Claude 的 context window 填满得很快，性能随填充而退化**。当 context window 接近上限时，Claude 会开始"忘记"早期指令或犯更多错误。因此，context window 是最需要管理的稀缺资源。

文档提出了几个关键的高杠杆实践：

**给 Claude 自我验证的方法**——这被标记为"你能做的杠杆效应最高的一件事"。提供测试、截图或预期输出让 Claude 能检查自己的工作。没有明确的成功标准，Claude 可能产出看起来正确但实际不工作的代码，你就成了唯一的反馈循环。

**先探索、再规划、再编码**——使用 Plan Mode 分离研究和执行。四阶段工作流：Explore（用 Plan Mode 读文件、回答问题）→ Plan（创建详细实现计划）→ Implement（切回 Normal Mode 编码并验证）→ Commit（提交并创建 PR）。但对范围清晰的小任务可以跳过规划。

**积极管理 context**——在不相关任务之间频繁使用 `/clear` 重置；使用 subagent 做调研以保持主会话干净；如果纠正 Claude 两次以上仍然出错，清除 context 用更好的 prompt 重新开始。

**编写有效的 CLAUDE.md**——只包含 Claude 无法从代码本身推断出的信息；保持简洁，对每一行问"删除它会导致 Claude 犯错吗？"；像代码一样维护它，定期修剪和测试。使用 `@path/to/import` 语法引用其他文件。

**自动化和扩展**——使用 `claude -p` 进行非交互式运行，支持 CI/CD 集成；Writer/Reviewer 模式用两个 session 实现自我审查；fan-out 模式处理大规模迁移。

## 关键概念
- **Context Window 退化**：LLM 性能随 context 填充而显著下降——这是所有最佳实践的底层约束
- **自我验证（Self-verification）**：给 agent 验证手段（测试、截图、linter）是杠杆效应最高的实践
- **Plan Mode**：分离探索/规划和实现，避免解决错误的问题
- **Subagent**：在独立 context 中运行的子 agent，用于调研和审查，保持主会话干净
- **Skills**：`.claude/skills/` 中的 `SKILL.md` 文件，按需加载的领域知识和可复用工作流
- **Hooks**：在 Claude 工作流特定点自动运行的脚本，与 CLAUDE.md 指令不同，hooks 是确定性的
- **Auto Mode**：自动审批模式，由 classifier 模型审查命令，阻止有风险的操作
- **Checkpointing**：Claude 的每个操作都创建检查点，可以回滚对话和代码到任何先前状态

## 实践建议
1. **验证优先**：每个任务都要提供明确的验证标准——测试用例、预期输出、参考截图
2. **大任务先规划**：对涉及多文件修改或不确定方案的任务，使用 Plan Mode 先探索后实现
3. **积极清理 context**：不相关任务之间用 `/clear`；纠正两次失败后清除重来
4. **用 subagent 做调研**：`"use subagents to investigate X"` 让调研在独立 context 中进行
5. **CLAUDE.md 保持精简**：只包含 Claude 无法自行推断的信息；定期修剪；提交到 git 让团队共同维护
6. **用 hooks 替代规则**：对"必须每次发生、没有例外"的操作用 hooks 而非 CLAUDE.md 指令
7. **并行运行**：用 Writer/Reviewer 模式提高代码质量；用 fan-out 模式处理大规模任务
8. **使用 CLI 工具**：安装 `gh`、`aws` 等 CLI 工具——这是与外部服务交互最节省 context 的方式
9. **避免"厨房水槽"会话**：不要在一个 session 中混合不相关任务

## 独到观点
作为官方文档，其最独到的贡献是将 **context window 管理** 提升为第一性原则，所有其他实践都是这一约束的推论。subagent 的使用建议特别有洞察力——不是用 subagent 做并行工作，而是用它做"context 隔离的调研"，这是一种优雅的 context 管理策略。另外，"纠正两次以上就清除重来"的经验法则非常实用，说明积累的错误纠正本身就是 context 污染源。Skills 和 hooks 的区分（advisory vs deterministic）也是重要的设计哲学。

## 与其他文章的关联
- 与 **Writing a Good CLAUDE.md**（#15）直接互补：本文给出了 CLAUDE.md 的基本框架和原则，#15 提供了更深入的策略思考（如指令容量上限、progressive disclosure）
- 与 **HumanLayer Backpressure**（#13）高度相关：backpressure wrapper 应该通过 hooks 或 CLAUDE.md 配置来管理工具输出
- 与 **OpenHands Context Condensation**（#14）对应：Claude Code 内置的 auto compaction 就是一种 context condensation，两者解决同一问题
- 与 **Claude Code Sandboxing**（#16）关联：sandboxing 和 auto mode 共同解决权限管理问题
- 与 **Code Execution with MCP**（#17）相关：MCP 集成是环境配置的重要部分
- 与 **Fowler Humans and Agents**（#22）理念一致：CLAUDE.md 和 hooks 就是 harness 的具体实现，体现"on the loop"思想
- 与 **Fowler Quality with Agents**（#20）互补：自我验证机制是保证 agent 代码质量的关键实践