Claude Code: Best Practices for Agentic Coding（Claude Code 智能体编码最佳实践）
📄 来自 Claude 官方博客
- 原文标题
- Claude Code: Best Practices for Agentic Coding（Claude Code 智能体编码最佳实践）
- 原文链接
- https://www.anthropic.com/engineering/claude-code-best-practices （现已迁移为在线文档：https://code.claude.com/docs/en/best-practices）
- 作者
- Anthropic
⚠️ 本页是原文的中文结构化整理笔记（保留架构、数据、案例、结论），并非逐字翻译。具体参数与功能名更新很快，落地前请点击上方链接核对原文。
🎯 一句话
最有价值的几条：用 CLAUDE.md 固化项目约定、先让它探索再让它动手、给它可运行的验证手段、小步提交。⭐ 核心思想是把你脑子里的隐性知识变成它能读到的显性文件。
📑 本页目录
Claude Code 是一个智能体编码环境：你描述目标，Claude 自主探索、规划、实现。绝大多数最佳实践都源自一个约束：上下文窗口填得很快，且性能随之下降——上下文是最需要管理的资源。
一、给 Claude 一个能自己运行的验证手段
- Claude 在「看起来完成」时就会停；没有可运行的检查，你就成了人肉验证环节
- 给它一个能产生通过/失败信号的东西：测试套件、构建退出码、linter、diff 脚本、浏览器截图对比
- 验证的四个升级档位：
1. 单次提示内：要求实现后跑测试并迭代
2. 跨会话：设为
/goal条件，每轮之后由独立评估器复查 3. 确定性闸门：Stop hook 跑检查脚本，不通过就阻止回合结束 4. 第二意见：验证子 Agent 或动态工作流用全新模型试图推翻结果 - 要求 Claude 出示证据（测试输出、命令及返回、截图）而非口头宣称成功
二、先探索、再规划、后编码（Explore → Plan → Code → Commit）
- 探索： 进入 plan mode，让 Claude 读文件、回答问题、不做修改
- 规划： 让 Claude 产出详细实现计划（Ctrl+G 可在编辑器中直接改计划）
- 实现： 退出 plan mode，按计划编码并对照验证
- 提交： 描述性 commit 信息并开 PR
注意：plan mode 有开销。改错字、加日志这类一句话能描述的 diff 直接做；规划适合方案不确定、跨多文件、不熟悉代码的场景。
三、提示词提供具体上下文
| 策略 | 差的提示 | 好的提示 |
|---|---|---|
| 限定范围 | 「给 foo.py 加测试」 | 「为 foo.py 写覆盖用户已登出边界情况的测试，不要用 mock」 |
| 指向信息源 | 「为什么这个 API 这么怪」 | 「翻 ExecutionFactory 的 git 历史并总结 API 的来龙去脉」 |
| 参照现有模式 | 「加个日历组件」 | 「参考首页现有 widget 的实现模式（HotDogWidget.php 是好例子）来实现」 |
| 描述症状 | 「修登录 bug」 | 「用户反映会话超时后登录失败；查 src/auth/ 尤其 token 刷新；先写复现的失败测试再修」 |
富上下文输入：@ 引用文件、直接粘贴截图、给文档 URL、cat error.log | claude 管道输入。
四、环境配置
CLAUDE.md
- 每次会话开头自动读取；用
/init生成初稿 - 收录：Claude 猜不到的 bash 命令、异于默认的代码风格、测试指令、仓库礼仪（分支命名/PR 惯例）、项目特有架构决策、环境怪癖、常见坑
- 排除：读代码就能懂的、标准语言惯例、详细 API 文档、常变信息、「写干净代码」这类废话
- 保持精简——每一行都问「删了会不会导致 Claude 犯错？」不会就删。臃肿的 CLAUDE.md 会让真正的规则被忽略
- 可用
@path/to/import导入其他文件；可放在家目录（全局）、项目根（团队共享）、CLAUDE.local.md（个人）、父/子目录（monorepo）
权限配置
三种减少打断的方式：auto mode（分类器审查命令，只拦可疑的）、权限允许清单（npm run lint、git commit 等已知安全命令）、沙箱（OS 级隔离）
其他配置
- CLI 工具： 装
gh、aws、gcloud等——最省上下文的外部服务交互方式；Claude 也能通过--help现学不认识的 CLI - MCP servers：
claude mcp add连接 Notion、Figma、数据库等 - Hooks： 「必须每次都发生、零例外」的动作用 hooks（确定性），CLAUDE.md 指令只是建议性的
- Skills：
.claude/skills/放 SKILL.md——领域知识自动应用，或/skill-name手动触发（副作用流程加disable-model-invocation: true） - 子 Agent：
.claude/agents/定义专门助手（如 security-reviewer），隔离上下文执行 - 插件：
/plugin浏览市场；强类型语言建议装代码智能插件
五、有效沟通
- 像问资深工程师一样问代码库问题：「日志是怎么做的？」「怎么加新 API 端点？」——极佳的入职上手工作流
- 让 Claude 面试你：大功能先用 AskUserQuestion 让 Claude 深挖技术实现、UI/UX、边界情况、权衡，产出 SPEC.md，然后开新会话执行——精确的规格比盯着实现更划算
六、会话管理
- 尽早纠偏：
Esc中断、Esc+Esc//rewind回滚、「撤销刚才的改动」、/clear重置 - 同一问题纠正两次以上 → 上下文已被失败尝试污染，
/clear后用吸收了教训的更好提示词重来 - 积极管理上下文： 任务间
/clear；/compact <指令>定向压缩；/btw问不需要进入历史的小问题 - 用子 Agent 做调研： 「用子 Agent 调查 X」——在独立上下文里探索，只把摘要带回主对话
- 检查点： 每个提示词自动创建检查点，可分别恢复对话/代码/两者（不追踪 Bash 修改，不能替代 git）
- 续接会话：
claude --continue/--resume；用/rename命名会话当分支用
七、自动化与横向扩展
- 非交互模式：
claude -p "prompt"用于 CI、pre-commit、脚本；--output-format json/stream-json供程序解析 - 多会话并行： worktrees（隔离 git 检出）、桌面 App 多会话、Web 版云端 VM、Agent 团队（自动协调）
- Writer/Reviewer 模式： 一个会话实现、另一个全新上下文审查——不会偏袒自己刚写的代码
- 批量扇出： 生成任务清单 → 脚本循环调
claude -p→ 先在 2-3 个文件上试跑调好提示词再全量；--allowedTools限权 - 对抗性审查： 完工前让子 Agent 在全新上下文里对照计划审查 diff；注意被要求找茬的审查者总能找出点什么——告诉它只报影响正确性的缺口，避免过度工程
八、常见失败模式
| 失败模式 | 修复 |
|---|---|
| 大杂烩会话（多个无关任务混在一起） | 任务间 /clear |
| 反复纠正同一问题 | 两次失败后 /clear + 更好的初始提示词 |
| 过度膨胀的 CLAUDE.md | 无情修剪；已经做对的指令删掉或转成 hook |
| 信任但不验证 | 永远提供验证手段；无法验证就不要上线 |
| 无边界的调查 | 限定调查范围或交给子 Agent |
结语
这些模式是起点而非铁律。有时该让上下文积累（深挖一个复杂问题时）、有时该跳过规划（探索性任务）、有时模糊提示词正合适（想看 Claude 如何理解问题）。留意什么有效，逐渐形成指南无法传授的直觉。
✅ 检查点
- CLAUDE.md 应该写什么、不该写什么？
- 为什么「先探索再动手」很重要？
- 哪些做法能显著提升单次任务的成功率？
👀 答案
- 该写：项目特有的约定（命名、目录结构、提交规范）、常用命令（怎么跑测试、怎么构建）、容易踩的坑和「不要这样做」的历史教训。不该写：能从代码本身读出来的东西（文件列表、函数签名）、通用编程知识、会很快过时的细节。⭐ 判据：「这条信息它自己看代码能不能得到？」能，就不用写。
- 因为它对代码库的假设可能是错的。直接让它改，它会基于猜测动手；先让它读相关文件、说出计划，你能在它动手前发现误解——这时纠正的成本远低于改完之后。
- ①提供可运行的验证（测试命令、lint），让它能自己确认；②给出具体的文件路径而不是让它满仓库找；③一次一件事，别把三个不相关的需求塞进一轮；④小步提交，出问题时容易定位和回滚；⑤把重复出现的要求沉淀进 CLAUDE.md，而不是每次重复说。
🛑 可以停在这里
⚡ 走神救援
⭐核心思想：把你脑子里的隐性知识变成它能读到的显性文件。CLAUDE.md 该写：项目特有约定（命名/目录/提交规范）、常用命令、容易踩的坑和「不要这样做」的历史教训；不该写：能从代码读出来的（文件列表、函数签名）、通用编程知识、会很快过时的细节。⭐判据：「这条信息它自己看代码能不能得到？」能，就不用写。⭐⭐先探索再动手：它对代码库的假设可能是错的，先让它读相关文件、说出计划，你能在它动手前发现误解，此时纠正成本远低于改完之后。五条提升成功率：提供可运行的验证（测试/lint）让它自己确认、给具体文件路径别让它满仓库找、一次一件事、小步提交（出问题易定位回滚）、重复出现的要求沉淀进 CLAUDE.md 而不是每次重复说。