Claude Code 最佳实践全解：来自 Anthropic 工程师 Cal 的 25 分钟内训公开版

讲者Cal Rueb，Anthropic Applied AI / Member of Technical Staff，Claude Code 团队核心贡献者，负责 prompt、system prompt、tool descriptions 和评测体系。
原视频：X 转载链接约 29 分钟 ·

TL;DR：18 条 Anthropic 官方推荐 Cheatsheet

底层架构

Claude Code 是一个 pure agent——工具 + 模型 + 一个简单循环，没有 RAG / 索引 / embedding。
靠 agentic search 理解代码——glob / grep / find，像新员工探索项目。
多云部署：Anthropic API、AWS Bedrock、Google Cloud Vertex AI 三条通路。

Environment Setup

写 CLAUDE.md：放运行命令、style guide、关键上下文。
Permission management：信任的命令加白名单，少弹窗。
Integration setup：装 gh CLI 让 Claude 自己搞 PR。
Context management：/clear 重置或 /compact 总结后续传。

Effective Workflows

先让 Claude 搜索 + 制定 plan，你 review 后再放它实现。
盯 Claude 的 TODO 列表——发现歪路就按 ESC 改方向。
Smart vibe coding：用 TDD + 小步 commit 做护栏。
截图当 context：paste mock.png 让 Claude "实现成这个样子"。

Advanced Techniques

Multi-Claude：Tmux / 多 tab 同时跑 2-4 个实例。
ESC 一次停，ESC 两次跳回历史——隐藏键位。
Claude Code 既是 MCP client 也是 server。
Headless mode (-p)：进 GitHub Actions 跑自动化。

Claude 4 + Multi-Agent

think hard 触发工具调用之间思考——Claude 4 关键改进。
/model 或 /config 切换默认模型。
多 Agent 临时方案：共享 ticket.md，A 写 spec → B 读 spec 实现。

一、Cal 是谁：一个周末用到登上 Anthropic 内部排行榜的人

Cal Rueb 在 Code w/ Claude 大会现场 — Cal Rueb（Anthropic Applied AI / Member of Technical Staff），在 Code w/ Claude 大会上讲 Claude Code Best Practices。

Cal 一年半前加入 Anthropic，联合发起了 Applied AI 团队。去年年底某个周五，他在 Slack 看到同事在玩一个叫 Claude Code 的新工具——下载后丢去做一个笔记应用——「整个周末完全改写了我写代码、思考软件工程的方式」。

他不知道的是，Claude Code 团队内部装了一个使用量排行榜——那个周末他直接冲到了第 1。通过这次"被发现"，他认识了 Boris、Kat 等早期团队成员，就这样成了团队的核心贡献者——负责 prompt、system prompt、tool descriptions 和评测体系。

他既是重度用户也是核心实现者——这直接定义了他在台上讲的所有内容的可信度。

二、心智模型：「那个所有事都在终端里搞定的同事」

"Claude Code is like that coworker that does everything on the terminal."

Cal 给的类比是他做 junior 时的那位导师 Tony：

「我以前是个 junior engineer，遇到 bug 就跑去 Tony 桌前。他会甩到他的终端，一通 bash 怪招 + Vim 折腾，问题就没了。我每次走开都想：天，我也得学这套。结果我从来没学。但有了 Claude Code，等于 Tony 一直在你电脑里。」

三、底层架构：一个 Pure Agent，"Simple Thing That Works"

How Claude Code works · 四大模块 — Anthropic 官方对 Claude Code 工作机制的四模块拆解：Powerful actions & integrations / Codebase awareness / Transparency / Security。

「在 Anthropic 我们尽量做 simple thing that works。在 Claude Code 上的含义就是它是一个非常 pure agent——一些指令、几个有力的工具，让模型在一个循环里跑直到它觉得做完。」

模块	定义
Powerful actions & integrations	编辑/创建文件，使用 CLI 和 MCP 工具，做提交。窄任务到大规模重构都覆盖。
Codebase awareness	持续感知项目结构。不需要手动把文件塞进 context——Claude 按需自己搜。
Transparency	展示正在做什么，分级权限系统平衡能力和控制。
Security	请求直连模型 API，没有中间服务器；支持 Anthropic / Bedrock / Vertex。

纯 agent 架构示意（中文版） — Claude Code 纯 agent 架构：工具 + 模型 + 循环；没有 RAG / 索引 / embedding，靠 agentic search 探索代码。

「如果一年前你要做 coding agent，你肯定会想——好我得把整个代码库索引起来、embed 起来、搞个 fancy 的 RAG 检索。Claude Code 不是这么做的。我们完全不做 indexing。Claude 像一个新人进新代码库一样去探索：用 glob、grep、find——做几次搜索，看看结果，发现还得再多查几件事，然后再搜。这就是 agentic search。」

这个选择的意义：

没有索引意味着没有索引漂移——代码改了 Claude 永远看到最新的
没有 embedding 意味着不需要预处理——cd 进去就能跑
Agentic 搜索天然 transparent——你能看到它跑了哪些 grep，比 RAG 黑盒易于审计

四、用例全景：一张表盖住整个软件生命周期

Claude Code 覆盖软件开发生命周期 · 15 用例 — Claude Code 的 5 阶段 × 15 用例全景图，外加底部 CLI 工具横栏。

阶段	用例
Discover	Explore codebase and history · Search documentation · Onboard & learn
Design	Plan project · Develop tech specs · Define architecture
Build	Implement code · Write and execute tests · Create commits and PRs
Deploy	Automate CI/CD · Configure environments · Manage deployments
Support & Scale	Debug errors · Large-scale refactor · Monitor usage & performance

Cal 反复点名几个被低估的用例：

Discovery 阶段做"思想伙伴"：开新仓库时，先说"这个 feature 我想加，请你 search 一圈，回来给我 2-3 个实现方案，不要动文件"
Build 阶段写测试——Claude Code 自己的代码库单元测试覆盖率"反常地高"，因为加测试变得无脑容易
Deploy 阶段用 SDK 做 headless——把 coding agent 撒进 CI/CD
大规模迁移——旧 Java → 新 Java、PHP → React/Angular，有 Claude Code 后变得可消化

五、Best Practices Part 1：Environment Setup & Configuration

Environment Setup & Configuration 四要点 — 环境配置四大要点：CLAUDE.md / Permission / Integration / Context。

1. `CLAUDE.md`——agent 的"项目记忆体"

「Claude Code 是 agent，它没有记忆。所以我们跨会话、跨团队成员共享状态的主要手段就是这个 CLAUDE.md 文件。启动 Claude 时如果 cwd 有这个文件，它会直接被塞进 prompt。」

放置位置：项目 cwd（check 进 git，团队共享）、~/CLAUDE.md（个人偏好，跨所有项目）、通过 @path/to/another/CLAUDE.md 引用其他位置。

值得写的内容：怎么跑 unit test、项目布局、style guide、内部工具说明。

2. Permission Management——少弹窗，多 flow

Read 操作直接放行；Write / Bash 操作弹出确认
Shift+Tab 进 auto-accept 模式——「你按下后 Claude 就只管跑」
/settings 里给特定命令开自动白名单

3. Integration Setup——装 `gh` CLI 解锁版本控制

「装上 gh CLI，Claude 就能无缝跑 GitHub 工作流——开 PR、查 issue、跑 action、留 comment。Claude 本来就擅长终端，给它工具就是给它放大器。」

4. Context Management——`/clear` vs `/compact`

/clear：清空一切（除了 CLAUDE.md），完全重启
/compact：让模型总结当前 session，总结作为新 session 的种子继续

「我们在 /compact 上投入了相当多 prompt 调优——设计目标是：你打满 context、跑 compact、然后能无缝继续。」

六、Best Practices Part 2：Effective Workflows

1. Planning and TODOs——别直接动手，先看 plan

「先让 Claude 搜一圈，告诉我它怎么 fix——别动文件。我看 plan 没问题，再让它 implement。这能省一大堆来回。」

Claude Code 大任务时会自动建一个 TODO 列表——盯着 TODO，发现哪条歪了立刻按 ESC 调方向。

2. Smart Vibe Coding——加点护栏

Vibe Coding 控制光谱 — Vibe coding 的本质是"你愿意让 Claude 跑多远"——从全人工逐条审批到 headless 完全 CI 跑。任务风险决定你站哪里。

Cal 给出的护栏组合：

TDD：让 Claude 先写测试再写实现
小步迭代：每改一小点跑一遍测试，确保过才继续
跑 type check 和 linting：让 Claude 自己解决类型和样式错误
频繁 commit：走偏了可以 reset 到上一个 good state

3. Use Screenshots to Guide & Debug

「直接 paste 一张 mock.png，说"帮我把网站建成这样"——它能看；或者截图 vs 设计稿对比，让它根据视觉差异 debug。」

七、Best Practices Part 3：Advanced Techniques

1. Multi-Claude & Parallelization

「我自己只能同时操作 2 个 Claude，但 Anthropic 里有人同时跑 4 个——Tmux、多 tab、各种姿势。用不同实例承担不同角色——一个写代码、一个做 review、一个跑测试。」

Multi-Claude 协作模式 — Multi-Claude 工作流：Agent A 写 spec → ticket.md 持久化共享状态 → Agent B 读 spec 实现 → Agent C 做 review。

2. Use Escape——一次停，两次跳回历史

ESC 一次：停下当前工具调用，让你 interject
ESC 两次：跳回对话历史——隐藏功能，「让你能从某个旧节点重新分支」

3. Tool Expansion & MCP

关键信息："Claude Code is both an MCP client & server!"——可以把 Claude Code 自己当成 MCP server 暴露给别的 agent 用。

「如果你纠结某个工具是装本地 CLI 还是装 MCP server——选 CLI。CLI 通常文档好、Claude 用得更顺。MCP 留给 CLI 真的搞不定的能力。」

4. Headless Automation——用 `-p` 进 CI

claude -p "..." # programmatic / headless 模式

把 Claude Code 撒进 GitHub Actions、大规模批量改动——Anthropic 自己最兴奋也还在摸索的方向。

八、Claude 4 新特性：`think hard` 在 tool calls 之间思考

Claude 4 think hard 中间态思考输出 — Claude 4 触发 think hard 后的中间态推理：在工具调用之间继续 think。

「过去的模型只在 tool call 之前 thinking——但 thinking 在 tool call 之间才最有用。从 Claude 4 开始，我们的模型在 tool call 之间也会 think。」

触发方法：prompt 里加 "think hard"（也支持 think harder / ultrathink）。Cal 强调：做任务、debug 时随手扔个 "think hard"，效果差距很大。

九、Q&A 三连

Q1. 多个 `CLAUDE.md` 怎么处理？

IDE 集成 + @subdir/CLAUDE.md 引用语法 — Cal 现场演示 VS Code 集成和 @subdir/CLAUDE.md 引用语法。

同一目录只能有一个
子目录里的 CLAUDE.md 默认不被读（Anthropic 自己是 monorepo，全部读会炸 context）
Agent 在 agentic search 中发现相关子目录的 CLAUDE.md 会按需读取
确定要某些子 CLAUDE.md 总是被读——在主文件里用 @subdir/CLAUDE.md 显式引用

Q2. `CLAUDE.md` 写了 Claude 还是不听话？

「这其实是模型问题，不是 prompt 问题。我们在 3.7 的 prompts 里写了一大堆 'don't leave comments'，模型就是爱留。」

「Claude 4 大幅改善了这个——instruction following 强了很多。升级后是重新看 CLAUDE.md 的好时机——可能有些条目可以删掉，也可能要补几条。」

启示：Prompt 工程的天花板是模型本身，老模型上死磕 prompt 不如等下一代。

Q3. 多 Agent 之间能不能共享 context？

「我们暂时还是在做 simple thing that works——一个超强 coding agent 干所有事。如果你现在就要多 agent 通信，让所有 agent 都读写一个 shared markdown file 是最实用的招。」

「我自己常做：让 Claude A 把开发说明写到 ticket.md，然后我开一个新 Claude 说'hey 同事留了一个 ticket，你来做'——agent B 就从 ticket.md 接上。」

它把"agent 间通信"从工程难题降级成"文件 I/O + agentic 阅读理解"。

写在最后

Claude Code 在 Anthropic 内部的设计哲学非常一致——simple thing that works：

不做 RAG、不做 indexing、不做 fancy retrieval
不做原生 multi-agent，先把单 agent 做到顶
不做 GUI flow，all-in 终端
不做封闭 backend，多云 / MCP 都开放
CLAUDE.md 是核心 affordance，但它就是一个 plain markdown

模型能力快速进步的时候，最好的产品形态是给模型最少的脚手架，让它自己长出能力。Cal 的整集分享，本质就是这个判断的 25 分钟使用手册。

附录：本文是怎么自动做出来的？

本文 12 张配图、~8000 字正文，全部基于 25 分钟原始视频自动产出：

A. 视频处理（8 张 slide 原图）——豆包 Doubao-Seed 多模态 + ffmpeg：ASR 转录 → 关键帧提取 → 手挑高密度 slide → ffmpeg 截图。

B. 中文化技术示意图（4 张）——gpt-image-gen skill + gpt-image-2-vip 模型。

总成本约 30 万 token + 4 张 1024×1024 出图，全过程从视频 URL 到博客成稿不到 15 分钟。

原视频（X 转载）：eng_khairallah1/status/2059725747930239264
本文英文原话尽量贴近转录，意译和延伸部分由作者承担。