2025-04-18 Anthropic Engineering

Claude Code：agentic coding 最佳实践

原文：Claude Code: Best practices for agentic coding

导读

这篇最佳实践把 Claude Code 当作一个会读文件、跑命令、改代码、持续推进问题的 agentic coding 环境，而不是普通聊天框。核心方法是控制 context、提供验证路径、配置工作环境，并在长会话中持续纠偏。

说明：本文按 Agent Learning 的中文阅读页格式，对原文结构与关键技术细节做逐节中文转述与解读；为避免整篇镜像转载，正文保留原文章节脉络、关键数字和术语，但不做逐字复刻。

核心观点

正文

Claude Code 不是聊天框

文章首先改变使用心智：Claude Code 处在代码库里，可以搜索、阅读、执行、编辑和验证。因此，用户给它的信息越接近真实工程上下文，它越能像协作者一样工作。

这也意味着 prompt 不应只是“帮我修 bug”。更好的输入包括复现步骤、报错日志、相关文件、已经尝试过的命令、期望行为、不能修改的边界，以及验收标准。

如果把 Claude Code 当成只会补全的模型，就会错过它最有价值的闭环能力：观察代码、提出计划、执行修改、运行验证、根据失败继续迭代。

管理 context：先探索，再计划，再编码

文章反复强调 context window 会快速填满。无关日志、反复纠错、过长规则和混乱历史都会让模型后续判断变差。

更稳的工作流是让 Claude 先 explore：读目录结构、定位相关文件、理解测试与约束；随后让它写 plan，把修改范围和验证方式说清；最后再让它动手 code。

这种流程看似慢一点，但能减少大幅返工。尤其在复杂仓库中，先建立 shared map 比直接生成 patch 更重要。

项目环境与 CLAUDE.md

CLAUDE.md 的作用，是把项目级知识放到模型容易读取的位置：常用测试命令、build/lint 命令、代码风格、分支策略、目录约定、禁区和审查要求。

但它不是越长越好。过度详细或互相矛盾的 CLAUDE.md 会污染 context。好的文档应该短、具体、可执行，像给新同事的 onboarding note。

工具环境也同样重要。权限、CLI、MCP servers、hooks、skills、subagents 和 plugins 都在塑造 Claude 的行动空间。

验证是完成的一部分

文章建议给 Claude 明确可运行的验证方式：测试命令、构建命令、截图检查、脚本、fixture 或手工验收步骤。

没有验证，模型容易把“代码看起来合理”当作完成。给出验证路径后，Claude 可以在失败时读取错误、定位原因并继续修复。

对于 UI、数据迁移、复杂重构等任务，验证可能不是单一测试，而是一组 evidence：截图、日志、diff、单元测试、端到端 smoke 和人工验收清单。

长会话与规模化使用

长会话最大的风险是 context 污染。用户应尽早纠偏，而不是让错误方向累计几十轮。必要时使用 /clear、compaction、checkpoint 或新 session，把已确认事实带过去。

大功能可以先让 Claude 访谈用户，产出 self-contained spec，再基于 spec 实现。这样能把需求澄清与代码执行分离，减少实现阶段反复改需求。

规模化模式包括 non-interactive mode、多个 session 并行、按文件或模块 fan-out、auto mode 和独立 review。关键不是开更多 agent，而是让每个 session 有清楚边界和验收。

深度解读

这篇最佳实践的底层逻辑，是把 coding agent 当作一个需要 onboarding、反馈和验证的工程协作者。模型能力本身很重要，但真实效果更多取决于信息是否充分、任务是否有边界、环境是否可运行、完成是否可验证。很多“Claude 没做好”的案例，本质上是给它的上下文像口头愿望，而不是工程任务包。团队如果想稳定使用 Claude Code，应建设的不只是 prompt 技巧，而是一套协作协议：项目说明、验证命令、权限边界、review 流程和 session 管理。

落地启示