HotPursuit

【阅读笔记】Claude Code Best Practices：Agentic 编程的工程实践指南

RL Paper Reading入库于 2026/6/3|
RL论文阅读Agent系统Anthropic

【阅读笔记】Claude Code Best Practices：Agentic 编程的工程实践指南

原文：https://www.anthropic.com/engineering/claude-code-best-practices 来源：Anthropic Engineering Blog

1. 一句话总结

Context Window 是 Agentic 编程最核心的资源，用四阶段工作流和扩展机制最大化 Claude Code 的输出质量。

2. 背景知识

  • Claude Code：Anthropic 官方 CLI 工具，让 Claude 可以直接操作本地文件、执行命令、与代码库交互。
  • Context Window：模型一次能处理的 token 上限（Claude 3.5/3.7 为 200K tokens），是决定 Agent 性能的核心约束。
  • Agentic Coding：AI 不只是补全代码，而是能自主完成"理解需求→探索代码库→规划→编码→测试→提交"的完整开发循环。
  • CLAUDE.md：放置在项目根目录的说明文件，会被 Claude Code 自动加载为系统上下文。

3. 为什么会出现这篇文章

Claude Code 发布后，许多用户不清楚如何最大化其效能——要么 Context 很快耗尽，要么得到的结果质量不稳定。Anthropic 根据内部使用经验和用户反馈，总结出一套最佳实践，帮助用户系统性地使用 Claude Code 完成复杂编程任务。

4. 试图解决的问题

  • Context Window 容量有限，如何在有限空间内装入最有价值的信息？
  • 复杂编程任务如何分解成 Claude Code 能可靠执行的步骤？
  • 如何复用经验（团队规范、项目约定），避免每次重复提示？
  • 如何在保持质量的前提下扩展到更大规模的自动化编程？

5. 核心创新/洞见（最重要！含直觉理解）

关键洞见：Context Window 是有限的注意力资源，不是无限的存储空间。

模型性能随 Context 填满而下降——不是因为 token 数超限，而是因为信号被噪声稀释。当 Context 里充斥着无关代码、冗长历史和重复信息时，模型"注意力"被分散，关键指令的权重下降。

直觉理解：就像人在嘈杂环境中工作效率下降——信息量不是问题，干扰才是。好的 Claude Code 使用方式就是持续清洁 Context，只保留当前任务最需要的信息。

第二个洞见：探索先于编码。 让 Claude 先深度理解代码库结构，再开始修改，比直接开始写代码的结果质量高得多。这模拟了优秀工程师"先读代码再动手"的工作习惯。

6. 核心方法/流程

四阶段工作流

阶段1：探索（Explore）
  → 让 Claude 阅读相关文件、理解代码结构
  → 不允许做任何修改，只读取和理解

阶段2：规划（Plan）
  → 基于探索结果，让 Claude 输出详细实现计划
  → 人工审查计划，确认方向正确

阶段3：编码（Code）
  → 按计划执行，分批次完成
  → 定期 /compact 压缩 Context

阶段4：提交（Commit）
  → 运行测试、修复问题
  → 生成规范的 commit message

关键扩展机制

机制作用典型用法
CLAUDE.md持久化项目上下文代码规范、架构说明、常用命令
Hooks自动化触发特定行为保存文件后自动运行 lint
Skills（Slash Commands）封装复杂工作流为单条命令/deploy、/review
Subagents并行执行独立子任务多模块同时开发
Plugins/MCP扩展工具集接入数据库、外部 API

并行与自动化

  • 并行会话：用 Git worktree + 多个 Claude Code 实例同时处理不同功能分支。
  • Non-interactive 模式：claude -p "任务描述" 用于 CI/CD 流水线集成。
  • Headless 模式：适合批量代码审查、自动化测试生成等场景。

7. 关键概念

  • Context Rot（上下文腐化）：随任务推进，Context 中积累越来越多的无关/过时信息，导致性能下降。
  • /compact 命令：将当前 Context 历史压缩为摘要，释放 Context 空间。
  • CLAUDE.md 层级：全局（~/.claude/CLAUDE.md）→ 项目根目录 → 子目录，逐层覆盖。

8. 实际效果/数据

  • 使用四阶段工作流后，大型重构任务的成功率显著提升（文中未给出精确数字）。
  • CLAUDE.md 设置良好的项目，Claude 首次修改的准确率明显高于无说明的项目。
  • 并行 Subagents 在多模块任务上可将总耗时降低 40-60%（Anthropic 内部实验估算）。

9. 现实应用情况

  • 个人开发者：用 CLAUDE.md 固化个人偏好（测试框架、代码风格），减少重复提示。
  • 团队协作：将团队规范写入 CLAUDE.md，确保 AI 辅助编程符合团队标准。
  • CI/CD 集成：Non-interactive 模式接入流水线，自动代码审查、测试生成。
  • 大型重构：Orchestrator-Workers 模式，主 Agent 规划，Sub-agents 执行各模块修改。

10. 对 Agent 的意义

本文是构建编程 Agent 的实践手册，核心意义在于：

  • 明确了 Context 管理是 Agentic 系统的核心工程问题，而非模型能力问题。
  • CLAUDE.md 机制本质上是将隐式知识显式化——把工程师头脑中的项目知识转化为 Agent 可消费的结构化上下文。
  • 四阶段工作流提供了一个可复用的 Agent 任务执行框架，适用于任何需要"先理解再行动"的 Agent 场景。

11. 对初学者最值得学什么（Top 3）

  1. Context Window 管理意识：理解"Context 是有限注意力"这个心智模型，是使用任何 LLM Agent 工具的基础。
  2. CLAUDE.md 的写法：学会把项目知识、团队规范结构化写入 CLAUDE.md，这是提升 AI 编程质量最高性价比的投入。
  3. 探索→规划→编码的节奏：不要一上来就让 AI 写代码，先探索、先规划，质量差异巨大。

12. 局限性/待解决问题

  • Context 压缩（/compact）可能丢失重要中间状态，压缩策略需要更智能。
  • CLAUDE.md 的维护成本随项目增长而上升，缺乏自动更新机制。
  • 并行 Subagents 在需要共享状态的任务中容易出现冲突，协调机制尚不成熟。
  • Non-interactive 模式的错误恢复能力较弱，不适合需要人工判断的复杂决策点。

13. 技术演进图谱

手动提示补全（Copilot 时代）
    ↓
对话式编程（ChatGPT + 代码粘贴）
    ↓
CLI Agent（Claude Code，可操作文件系统）
    ↓
扩展机制（CLAUDE.md + Hooks + Skills）
    ↓
并行 Multi-Agent 编程（Subagents + Worktree）
    ↓
全自动 CI/CD 集成（Non-interactive + Pipeline）
    ↓
自主软件工程师（SWE-bench 全自动，进行中）

14. 阅读难度评级

★★☆☆☆（2/5）

工程实践文档，概念直观，有大量具体命令和工作流示例。需要基本的 CLI 使用经验。

15. 预估阅读时间

预计阅读时间：7分钟

← 返回文章列表