何时打开:你想知道 Claude Code 在 Anthropic 内部是怎么用的、有哪些"反直觉"的 best practice。本 wiki 是 Cal Rueb(Anthropic Claude Code 团队工程师)2025-Q2 在 newtype 星球的分享整理。
跟 王凯 Claude Code 终端工作流方法论(完整版) 的区别:王凯那份是"独立开发者站在产品视角的方法论 + 多 Agent 编排"。本 wiki 是"Anthropic 内部工程师视角的工具用法 + 心智模型"。建议两份对照读。
一、Claude Code 的设计哲学
Cal 一开始就强调:Claude Code 不是 IDE,也不是 Copilot,是"在终端里的 Agent"。
| 工具 | 心智模型 | 信任尺度 |
|---|---|---|
| Cursor / Copilot | IDE 内的"补全器" | 你在驾驶 |
| Devin / Manus | 自动跑任务的"机器人" | 它在驾驶 |
| Claude Code | 你的"工程师同事" | 协作 — 你做产品决策,它做实现细节 |
关键含义:
- Claude Code 跟你协作,不是替你写代码。你给方向,它给代码,你检查,你 commit
- 它"住"在终端,因为终端是工程师最熟悉的环境;不要把它当 GUI
- 它"自带 git / bash / 文件系统访问"——这是它强大也是危险的原因
二、Agentic Search vs RAG
Cal 反直觉判断:Claude Code 不用 RAG,用 Agentic Search。这是它跟其他 AI 编辑器的本质差异。
2.1 两者对比
| 维度 | RAG(向量检索) | Agentic Search(Claude Code) |
|---|---|---|
| 工作方式 | 预先 embed,查询时 top-k 检索 | 每次需要时,Agent 自己用 grep / glob / read / ls |
| 上下文 | 固定窗口,语义相似度抓 | 动态决定要看哪个文件,看到哪行 |
| 准确性 | 依赖 embedding 质量,经常抓错 | LLM 用工具直接搜,精度高 |
| 延迟 | 检索快 | 多轮 tool call 慢一点 |
| 适合场景 | 静态文档库 | 活的代码库 |
2.2 Cal 的解释
"RAG 是把书的目录扫描成向量,然后用相似度找页。但代码不是书,代码是图——文件互相 import,函数互相调用。LLM 拿着 grep / glob 就像工程师拿着 find / ag,这才是代码搜索的正确方式。"
实操含义:
- 不要给 Claude Code 加 RAG MCP——它自带的搜索能力比 RAG 强
- 让 Claude Code 自己探索代码库,不要预先喂给它"我整理好的代码摘要"
- 大代码库(>10w 行)依然 work,因为它每次只看相关的几个文件
三、CLAUDE.md:多层级配置
Cal 强调:CLAUDE.md 是 Claude Code 最重要的配置文件。3 个层级,合并生效。
3.1 三个层级
| 层级 | 路径 | 用途 |
|---|---|---|
| 全局 | ~/.claude/CLAUDE.md |
你的个人偏好(沟通风格、命名约定) |
| 项目 | <project>/CLAUDE.md(进 git) |
团队共享的项目约定(架构、风格、构建命令) |
| 私人 | <project>/CLAUDE.local.md(不进 git) |
你个人对该项目的偏好 |
合并顺序:全局 → 项目 → 私人,后者覆盖前者。
3.2 什么内容应该进 CLAUDE.md
Cal 推荐:
- 项目结构(目录树、关键模块在哪)
- 构建 / 测试命令(
pnpm dev、pytest、make build) - 代码风格(2 空格 vs 4 空格、字符串引号、命名约定)
- 架构铁律("API 调用必须走 src/api/"、"数据库 schema 改动必须迁移")
- 回避陷阱("不要碰 legacy/auth.py"、"测试不要用 mock,要用 docker 起 postgres")
- MCP 工具的使用偏好
3.3 不应该进 CLAUDE.md
- 你的密码 / API key(用环境变量)
- 大段代码片段(用 import 或链接)
- 跟工作无关的内容(私人偏好用 CLAUDE.local.md)
- "你必须 X" 这种命令式——Cal 强调用"我们倾向 X 因为 Y",带 reason 的指令 LLM 跟得更好
四、Permission 系统:三种粒度
Claude Code 的安全性来自"它能动你的 git 和 bash"。Permission 是 Cal 强调的关键。
4.1 三档 Permission
| 档位 | 描述 | 用法 |
|---|---|---|
| Ask | 每个 tool call 都问你 | 新项目 / 危险任务 |
| AcceptEdits | Read / Write / Edit 自动通过,Bash 还问 | 中等信任 |
| BypassPermissions | 完全自动 | 沙盒环境 / 你完全信任的任务 |
切换:Shift+Tab 即时切换。
4.2 Cal 的建议
- 永远不要"BypassPermissions"在生产代码库。即便你赶时间,也至少 AcceptEdits + Bash 审核
- 危险命令清单:
rm -rf、git push --force、DROP TABLE、sudo、写文件到~之外的路径 - Hooks 机制(下节)可以自动拦危险命令
4.3 Permission Modes(Cal 没提的但官方文档有)
- Plan Mode:让 Claude Code 先规划再执行(默认不进 Plan)
- Read-only Mode:只能读不能改(适合给 Claude Code 做 code review)
五、上下文管理:/clear 和 /compact
Cal 称这是 Claude Code 中"最常用但最被低估"的两个命令。
5.1 /clear
作用:清空整个对话上下文,重新开始。
何时用:
- 任务切换(刚做完 feature A,准备做 feature B)
- 对话变长但已经偏题(Claude Code 在反复 retry 同一个错误)
- 你想换思路重新来
Cal 的统计:他自己平均每天 /clear 10-20 次。每个 small task 一个 /clear。
5.2 /compact
作用:不清空,但让 Claude Code 总结当前上下文,把详细对话压缩成摘要。
何时用:
- 上下文接近 token 限制(默认 200k,Sonnet 4.6 可达 1M)
- 任务很长,中间需要"savepoint"
- 你想保留思路但减少消耗
Cal 的建议:
- 每 50% context 一次 /compact
- 但不要 /compact 后立即做新任务——先确认 compact 后的摘要包含关键信息
六、Think Hard:三档推理
Claude Code 内置了 3 个"thinking 强度"关键词(对应 extended thinking 不同等级):
| 关键词 | 强度 | Token 消耗 | 何时用 |
|---|---|---|---|
think |
低 | ~4k thinking tokens | 简单决策(改 typo 不必用) |
think hard |
中 | ~10k | 调试 / 重构 |
think harder / ultrathink |
高 | ~32k | 架构设计 / 复杂 bug |
6.1 Cal 的用法
- 95% 的对话不用 think,直接让 Claude Code 干
- 5% 的复杂任务,在 prompt 末尾加 "think hard" 或 "ultrathink"
- 不要每次都 ultrathink,会浪费 token + 拖慢响应
6.2 Cal 的反直觉建议
"如果你发现自己反复 ultrathink,说明你的任务粒度太大了。把任务切小,每个小任务用 think hard 就够。"
七、Sub-Agents:并行 + 边界
Claude Code 支持 Sub-Agents(子 Agent),Cal 强调这是"最被低估的功能"。
7.1 Sub-Agent 是什么
- 用 Task tool 启动一个新的 Claude Code 实例,有自己独立的上下文
- 主 Agent 给它 prompt,它跑完返回结果
- 多个 Sub-Agent 可以并行
7.2 Cal 推荐的 Sub-Agent 用法
| 场景 | 主 Agent 干什么 | Sub-Agent 干什么 |
|---|---|---|
| 大代码库探索 | 整合 Sub-Agent 输出 | 并行扫不同目录 |
| 多文件重构 | 协调和最终 commit | 每个文件一个 Sub-Agent 改 |
| 调研对比 | 决策选哪个方案 | 每个方案一个 Sub-Agent 跑 spike |
| Code Review | 整合反馈 | 每个 module 一个 Sub-Agent review |
7.3 Sub-Agent 的边界
- 不要让 Sub-Agent 做 commit / push(主 Agent 集中做,避免冲突)
- 不要让 Sub-Agent 启动 dev server(进程会孤立,主 Agent 不知道)
- 不要让 Sub-Agent 在 prompt 里说"找出所有 X"——它的上下文窗口限制让它漏比主 Agent 严重
- Sub-Agent 写代码时,主 Agent 要 review
7.4 多 Agent 并行的实际收益
Cal 给了一个数据:4 个 Sub-Agent 并行,总时间是 ~1.3x 单 Agent,远低于 4x。原因是 Sub-Agent 启动 + return overhead 很大,但单任务内部很快。
所以:
- 4 个 Sub-Agent 同时跑 4 个独立 module 是合算的
- 4 个 Sub-Agent 跑 4 个互相依赖的小步骤是亏的(用主 Agent 串行更快)
八、Hooks:行为触发器
Claude Code 支持 Hooks(用户 / 项目级),在特定事件触发自定义脚本。
8.1 Hook 事件
| 事件 | 何时触发 |
|---|---|
| PreToolUse | 工具调用之前 |
| PostToolUse | 工具调用之后 |
| UserPromptSubmit | 用户发消息时(可注入额外 context) |
| Stop | Agent 准备结束时 |
| SubagentStop | Sub-Agent 结束时 |
| Notification | Claude Code 等待用户输入时 |
8.2 Cal 推荐的 Hook 用法
- PreToolUse 拦截危险命令:bash 命令含
rm -rf时,弹通知或 block - PostToolUse 自动 lint:Write / Edit 之后自动跑
prettier --write或pnpm lint - UserPromptSubmit 注入 context:每次提问自动 append 项目当前 git status
- Stop 自动 commit:任务结束时自动跑
git status,提示是否 commit - Notification 弹通知:等用户输入时发 macOS notification(用
osascript)
8.3 Cal 的个人 Hooks
Cal 自己的 hooks 配置(简化版):
{
"hooks": {
"PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "~/.claude/hooks/block-dangerous.sh"}]}],
"PostToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "~/.claude/hooks/auto-lint.sh"}]}],
"Stop": [{"hooks": [{"type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff"}]}]
}
}
最后那个 Stop hook 让 Claude Code 结束时响一声——Cal 说这让他能"专心做别的事,听见声音再回头看"。
九、MCP:选型与边界
MCP(Model Context Protocol)是 Anthropic 推出的工具协议标准。Cal 给了选型建议。
9.1 什么时候用 MCP
- 你需要让 Claude Code 调用一个外部 API(GitHub、Slack、Jira、Notion)
- 该 API 不能用 curl 直接调(需要 auth、复杂分页)
- 你会反复用这个工具(一次性的不必)
9.2 什么时候不用 MCP
- 简单的 shell 命令(直接让 Claude Code 跑 bash)
- 文件系统操作(自带 Read / Write / Edit)
- Web 搜索(用 WebFetch / WebSearch)
- 一次性的脚本(写个 .sh 让 Claude Code 跑)
9.3 Cal 推荐的核心 MCP
| MCP | 用途 |
|---|---|
| github | issue / PR / review 操作 |
| playwright / chromium | 浏览器自动化 / E2E 测试 |
| postgres / sqlite | 数据库查询 |
| filesystem(项目限定) | 跨目录文件操作 |
| brave-search | 替代 WebSearch(有些场景更稳) |
9.4 MCP 反 pattern
- 不要装一堆 MCP(每个都占 context,启动慢)
- 不要让 MCP 工具描述太长(Cal 见过 5000 token 的 MCP 工具描述)
- 不要用 MCP 做"全能助手"(它只是工具,不是 Agent)
十、Cal 的个人配置模版
Cal 在演讲末尾贴了他自己的 Claude Code 配置(精简版):
10.1 ~/.claude/CLAUDE.md(全局)
# Cal's Global Preferences
- I prefer concise responses. Don't summarize what you just did unless I ask.
- When showing diffs, only show the changed lines, not full files.
- Use TypeScript over JavaScript when possible.
- Run tests before saying "done".
- If you encounter an error, fix the root cause, not the symptom.
- Never use `git push --force` without my explicit OK.
10.2 项目级 CLAUDE.md(示例)
# Project: agent-framework
## Stack
- TypeScript + Node 20
- pnpm workspace
- Vitest for tests
- Biome for lint
## Commands
- `pnpm dev` — dev server
- `pnpm test` — vitest run
- `pnpm lint` — biome check + fix
- `pnpm typecheck` — tsc --noEmit
## Architecture
- `packages/core/` — runtime engine, no external deps
- `packages/cli/` — CLI entry, depends on core
- `packages/server/` — HTTP server (Hono)
## Conventions
- Files: kebab-case (agent-runner.ts)
- Types: PascalCase, exported from index.ts
- Internal helpers: prefix with _
- Tests next to source: agent-runner.test.ts
## Tradeoffs
- We prefer composition over inheritance.
- We avoid dependency injection frameworks — passing functions is enough.
10.3 关键 Hooks
{
"hooks": {
"PostToolUse": [
{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "pnpm biome format --write $CLAUDE_FILE_PATH"}]}
],
"Stop": [
{"hooks": [{"type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff"}]}
]
}
}
十一、Cal 强调的 5 个"Gotcha"
- 不要让 Claude Code 跑
git push不询问——即使是 AcceptEdits 模式,push 默认还是要 ask - 大型重构前先 commit——Claude Code 改一半你可能不喜欢,有 checkpoint 才能 reset
- 不要在生产 repo 用 BypassPermissions——哪怕你"只是想看看"
- /clear 之前先保存关键信息——Claude Code 会忘掉所有上下文
- Sub-Agent 不会继承主 Agent 的 CLAUDE.md——Sub-Agent 启动新会话,会重新读 CLAUDE.md(所以记得把规则放进项目级)
十二、与 王凯 Claude Code 终端工作流方法论(完整版) 的对照
| 维度 | wangkai 综述 | newtype-cal 讲座(本 wiki) |
|---|---|---|
| 视角 | 独立开发者 / 产品创业者 | Anthropic 内部工程师 |
| 重点 | 多 Agent 编排 / Subagent 协作 / Plan-driven | 单 Agent 工程化 / Hooks / Permissions |
| 工具栈 | Claude Code + 多浏览器矩阵 + MCP 生态 | Claude Code + git + bash + 少量 MCP |
| 任务粒度 | 一个完整产品(几周) | 一个 feature(几小时) |
| Sub-Agent 哲学 | 主力依赖 | 谨慎使用 |
| 关键洞察 | "终端窗口即 Agent" | "Agentic Search 强过 RAG" |
最佳实践:
- 独立开发者:两份都读,先用 Cal 的"单 Agent 工程化"打底子(用熟 hooks / permissions / CLAUDE.md),再用王凯的"多 Agent 矩阵"扩规模
- Anthropic 风格的项目:主用 Cal 的方法论
- 多 Agent 矩阵项目:主用王凯的方法论,Cal 的 hooks / CLAUDE.md 作为底座
十三、引用清单
- Cal Rueb 在 newtype 星球 2025-Q2 分享(本 wiki source)
- Anthropic 官方文档:claude.com/docs/claude-code
- 相关:王凯 Claude Code 终端工作流方法论(完整版)、王凯多 Agent 浏览器矩阵架构(v1.1 实操指南)、newtype · MCP 协议与生态实战、newtype · AI Coding 实战与工具栈演化
History
- 2026-05-16:Phase 3 ingest 从
10_Claude_Code_best_practices.md创建。完整覆盖 Cal 的 12 个核心主题 + 个人配置模版 + 与王凯综述的对照。