Claude Code

如果只研究一个编程 Agent 来理解「现代 Agent 应该怎么造」，答案就是 Claude Code。它不是功能最多的，也不是 IDE 集成最深的（那是 Cursor 的地盘），但它是把「模型能力」和「Agent 外壳（harness）」协同设计做得最彻底的产品——Anthropic 自己造模型，又自己造壳，两边的迭代可以互相喂数据。

本页基于三类公开信息写就：Anthropic 官方发布与文档、社区对 npm 包 source map 的逆向分析（Claude Code 一度随包发布了可还原源码的 source map，催生了多份高质量逆向报告）、以及大量工程实践文章。涉及内部实现的部分会明确标注「逆向分析结论」，与官方信息区分开。

一、产品形态演进：从终端玩具到全平台 harness

Claude Code 的演进路径本身就是一堂产品课——它每一步都在扩大「同一个 harness」的覆盖面，而不是重写产品。

时间	里程碑	意义
2025-02	随 Claude 3.7 Sonnet 以 research preview 发布，纯 CLI	验证了「终端里的 agentic coding」这个形态
2025-05	随 Claude 4 系列正式 GA；推出 GitHub Actions 集成	从玩具变工具，进入 CI/CD 流水线
2025-07 起	Subagent（Task 工具 + .claude/agents/）、自定义 slash command 陆续上线	从单 Agent 走向可编排的多 Agent
2025-09-29	Claude Code 2.0 + Sonnet 4.5 同天发布：原生 VS Code 扩展、checkpoints、终端 UI 刷新；Claude Code SDK 更名 Claude Agent SDK	「壳」正式成为可复用的产品化资产
2025-10-20	Claude Code on the web：claude.ai 的 Code 标签页 + iOS App，云端沙盒跑 Agent	CLI 不再是唯一入口，harness 上云
2025-11	Opus 4.5 发布，SWE-bench Verified 80.9%	模型侧继续拉开差距
2026-04	桌面版重构：侧边栏管理多个并行会话	从「一个 Agent」到「管理一群 Agent」
2026-07	桌面版内置浏览器，可边开发边预览调试	向「完整开发环境」靠拢

几个值得注意的决策：

终端是家，但不是边界。 产品经理 Cat Wu 在 TechCrunch 采访里说得很直白：CLI 会始终是 home base，但「Claude Code everywhere」是方向。Web 版不是另起一个产品，而是同一套 Agent 逻辑跑在云端沙盒里，你在手机上也能启动和监控任务。

SDK 化是把内部能力外部化。 2025 年 9 月的更名不是换个名字：Claude Agent SDK 暴露的就是 Claude Code 自己的运行时——同一套工具目录、同一套权限系统、同一个 loop。这意味着 Anthropic 认为这个 harness 本身有独立的产品价值，详见 Claude Agent SDK。

商业上它已经不是副业。 据 TechCrunch 2025 年 10 月报道，Claude Code 年化收入超过 5 亿美元，用户量自 5 月 GA 以来增长 10 倍；另有说法是 Anthropic 约 90% 的 Claude Code 代码由 Claude 自己写成——这是最激进的 dogfooding。

二、架构解剖：主 loop + 子代理 + 五层扩展面

Claude Code 不开源，但 npm 包里的 source map 让社区得以还原其 TypeScript 源码。最有分量的一份逆向分析覆盖了全部约 512,664 行代码（awesome-cc-harness 项目），加上早期 Reid Barber 和 ShareAI Lab（v1.0.33）的报告，其架构轮廓已经相当清晰：

┌────────────────────────── 用户界面层 ──────────────────────────┐
│  CLI REPL / VS Code 扩展 / Web & 桌面 / Agent SDK / GitHub App │
└──────────────────────────────┬───────────────────────────────┘
                               │
┌──────────────────────────────▼───────────────────────────────┐
│                     主 Agent Loop（Query Loop）               │
│  while(true): 模型流式输出 → 解析 tool_use → 调度工具          │
│  → 结果回注 → continue，直到模型不再调用工具                    │
│  逆向结论：核心循环只有约 30 行，但裹着约 1800 行错误恢复逻辑   │
└───────┬──────────────┬──────────────┬──────────────┬─────────┘
        │              │              │              │
┌───────▼──────┐ ┌─────▼───────┐ ┌────▼────────┐ ┌───▼─────────┐
│  工具系统     │ │ Task 子代理 │ │ 权限模型     │ │ 上下文工程   │
│ 40+ 原子工具  │ │ 独立 context│ │ 多层纵深防御 │ │ 自动压缩管道 │
│ 读并行/写串行 │ │ 只回传结论  │ │ + allowlist │ │ 180K→~45K   │
└───────┬──────┘ └─────────────┘ └───────────────┘ └─────────────┘
        │
┌───────▼──────────────── 扩展面 ──────────────────────────────┐
│ CLAUDE.md 记忆 │ Hooks（事件钩子）│ MCP 服务器 │ Skills/命令   │
└──────────────────────────────────────────────────────────────┘

主 Agent Loop：简单核心 + 重型恢复

逆向分析里最反直觉的发现是：核心 loop 极小——一个 while(true)，模型输出工具调用就执行、回填、继续，直到模型停止调用工具。这与我们在 Agent Loop 里讲的教科书结构完全一致。

真正的工程量在 loop 外面：约 1800 行的错误恢复与重试（限流、网络中断、context 溢出、流式中断续传）、多层 AbortController 级联（让用户按 Esc 能干净地打断任何一环）、以及流式执行下的读写并发控制。有分析据此给出一个尖锐的结论：代码库里只有约 1.6% 是「AI 决策逻辑」，其余全是运维性的 harness——权限、恢复、压缩、路由。这个数字的口径未必严谨（数据未核实，引用前请核对），但方向是对的：生产级 Agent 的壁垒不在 prompt，在脏活累活。

Task 子代理：上下文隔离是第一目的

主 Agent 通过 Task 工具派生子代理（subagent）。子代理拿到一个聚焦的任务描述和干净的 context window，干完活只把结论回传给主 Agent。2025 年 7 月之后，用户还可以在 .claude/agents/ 目录用 Markdown 定义自定义子代理——指定专用的 system prompt、限定可用工具、甚至指定模型。

这个设计的本质不是「多 Agent 协作」的浪漫叙事，而是上下文工程：探索代码库这种「读 50 个文件只为回答一个问题」的任务，让子代理去烧 token，主 Agent 的 context 只留答案。这与 多 Agent 架构 中讲的 orchestrator-worker 模式同源，但动机首先是省 context，其次才是分工。

三、工具集设计哲学：通用原子工具，拒绝专用宏工具

Claude Code 的工具集是「Unix 哲学」在 Agent 上的复刻：不给「重构函数」「修复 lint」这种高语义宏工具，只给一组通用的原子工具：

• 文件：Read、Write、Edit（精确的 old_string/new_string 替换）、Glob、Grep
• 执行：Bash（含后台任务）、NotebookEdit
• 信息：WebFetch、WebSearch
• 元工具：Task（派生子代理）、TodoWrite（任务清单）

为什么这样做是对的，至少有四个理由：

1. 原子工具的组合空间是无限的。 模型本来就会写代码和 shell 命令，Grep + Read + Edit 能组合出任何代码操作；而宏工具每覆盖一个新场景就要新增一个，永远追不上需求长尾。
2. 工具即接口训练。 模型厂商自己造壳，可以让模型在训练时就对齐这组工具的调用习惯（如何写 Edit 的 old_string 才不容易失配、Grep 的正则怎么给），这是第三方壳做不到的协同优势。
3. Bash 是终极逃生舱。 任何专用工具覆盖不了的操作——跑测试、git 操作、构建、起服务——都收敛到 Bash。harness 只需把 Bash 的权限管好，而不是枚举所有能力。
4. 逆向分析显示工具调度本身有讲究：只读工具（Read/Grep/Glob）可以并行执行，写操作（Edit/Write/Bash）串行执行并加锁，避免并发写冲突。这个「读并行、写串行」的分区调度是性能与安全的一个漂亮折中。

给自建者的直接推论

如果你在给内部工具设计 Agent 接口，先问自己「这个操作能不能用 5 个以内的原子工具组合出来」。能，就不要造新工具。工具数量膨胀是 Agent 系统最常见的自作聪明——每多一个工具，system prompt 变长、模型选错工具的概率变高、你的维护面变大。详见 工具与 MCP。

四、上下文工程实践：压缩、隔离、外部记忆三件套

Claude Code 的上下文策略可以概括为「能不进 context 的就不进，进了的想办法扔，扔之前先存盘」。这是 上下文工程 最完整的工业级样板。

自动压缩（auto-compact）

会话接近 context window 上限时，Claude Code 自动触发压缩：先发一次带「总结指令」的请求（这段历史大概率命中 prompt cache，成本可控），用生成的摘要替换消息历史；压缩前会先清掉最老的工具输出，不够再做整体摘要。逆向分析称其为一个多级管道，能把约 180K token 压到 45K 左右。用户也可以用 /compact 手动触发，并附一段「聚焦指令」告诉它重点保留什么。

关键细节：压缩后 CLAUDE.md 会从磁盘重新注入。这解释了为什么老用户都说「规则写进 CLAUDE.md，别只在对话里说」——对话里的口头规则会被压掉，磁盘上的文件不会。

子代理隔离

如前所述，Task 子代理是上下文隔离的主要手段：读代码、跑探索性任务、做调研这些「高 token 消耗、低信息产出」的活都在隔离的 context 里烧掉，主 Agent 只接收提炼后的结论。

文件引用与外部记忆

• @path/to/file 显式引用文件，把控制权交给用户而不是让模型盲目 grep。
• CLAUDE.md 分层加载：用户级（~/.claude/CLAUDE.md）、项目级（仓库根目录）、子目录级逐级生效，支持 @import 引用其他文件。它是「跨会话记忆」的载体，详见 记忆系统；写好自己的 Agent 配置文件可参考 Writing AGENTS.md。
• 2.0 引入的 checkpoints 会在每次修改前保存工作区快照，配合 /rewind 回滚——这本质上是把「可撤销性」从模型手里拿走，交给确定性的文件系统机制。

一个被低估的设计判断

Claude Code 没有内置向量检索/RAG 式的代码库索引。它赌的是「agentic search」：让模型用 Grep/Glob 像人一样找代码，配合足够强的模型和足够大的 context。这和 Cursor（重度依赖代码库 embedding 索引）是两条路线。2025-2026 年的实践表明，在强模型上 agentic search 的精度往往优于粗糙的 embedding 检索——代价是 token 消耗更高。相关讨论见 RAG。

五、权限与信任模型：把「信任」做成可配置的状态机

让一个能执行任意 shell 命令的 Agent 在你的机器上跑，核心问题是信任。Claude Code 的答案是一套分层的权限模型（更完整的讨论见 Agent 安全）。

Permission modes：按任务风险选档

经典的四档模式（会话中 Shift+Tab 循环切换）：

模式	行为	适用场景
default	读取类工具放行，编辑/Bash 逐次询问	日常开发
acceptEdits	文件编辑自动批准，Bash 仍询问	大改重构时减少打断
plan	只读模式，Agent 只能调研和出方案	动手前先对齐方案
bypassPermissions	全部放行（启动时有显著警告）	沙盒/容器/CI 环境

2026 年的版本又演进出 auto、manual、dontAsk 等更细的模式（CLI 参数 --permission-mode 可查当前支持列表），但思想没变：自主权是按模式授予的，不是模型自己争取的。

Allowlist：粒度到命令模式

.claude/settings.json 里的 permissions.allow / deny 支持到命令前缀粒度：

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(git status)",
      "Read(**/*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)"
    ]
  }
}

deny 优先于 allow。逆向分析指出权限判定是多层纵深防御（模式 → allowlist/denylist → 交互确认 → 沙盒），每一层独立拦截，不把安全押在单点上。设置本身也是分层的：managed（企业 IT 统发）→ user（~/.claude/）→ project（.claude/settings.json，随仓库提交）→ local（settings.local.json，不进 git）。

六、Hooks 与可扩展性：模型外的确定性层

CLAUDE.md 是「劝」模型的——模型大概率遵守，但不保证。Hooks 是「管」模型的——在生命周期的固定点位执行你写的 shell 命令，确定性地运行，不受模型意志影响。这是 Claude Code 可扩展性设计里最被业界抄走的一环。

事件模型

Hooks 挂在 Agent 生命周期的事件上。生产环境最常用的五个：

SessionStart ──→ UserPromptSubmit ──→ [ Agent Loop ]
                                          │
                    ┌── PreToolUse ──→ 工具执行 ──→ PostToolUse ──┐
                    │   （可拦截/改参）              （校验/格式化）│
                    └──────────── 每个工具调用都包一层 ────────────┘
                                          │
                Stop（主 Agent 结束）/ SubagentStop / Notification / PreCompact ...

到 2026 年事件目录已扩展到 20+ 个（含子代理启停、压缩前、通知等），但掌握核心几个就覆盖了八成用途。

配置与判定协议

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/guard.py"
          }
        ]
      }
    ]
  }
}

Hook 脚本从 stdin 拿到 JSON（工具名、参数等），用退出码表达判定：exit 0 放行，exit 2 拦截并把 stderr 反馈给模型（注意：exit 1 只是报错，不拦截）。典型用法：

• PreToolUse 拦下 rm -rf、拦下对 .env 的读取、强制数据库迁移走审批
• PostToolUse 在每次 Edit 后自动跑 prettier / eslint / 类型检查，把报错喂回给模型
• Stop 检查「测试没过就不许收工」，强行让 Agent 继续修

扩展面的全貌

除了 hooks，Claude Code 的扩展点还有四个，组合起来几乎是个平台：

• MCP：接入外部工具与数据源的标准协议，见 工具与 MCP
• 自定义 slash command：.claude/commands/ 下放 Markdown 即注册新命令，本质是参数化的 prompt 模板
• Skills：按需加载的能力包，比命令更结构化
• Claude Agent SDK：把整个 harness 嵌进你自己的程序（Python claude-agent-sdk / TS @anthropic-ai/claude-agent-sdk），CI、IM 机器人、内部平台都能长出一个 Claude Code 内核

# Claude Agent SDK（Python）最小示例
import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Grep", "Bash"],
        permission_mode="acceptEdits",
        cwd="/path/to/repo",
    )
    async for message in query(
        prompt="找出这个仓库里所有未处理的 TODO 并按模块归类",
        options=options,
    ):
        print(message)

anyio.run(main)

Hooks 的信任边界

项目级 .claude/settings.json 里的 hooks 是「随仓库分发的可执行命令」——克隆一个恶意仓库并信任它，等于执行了作者写的任意脚本。这与 git hooks、direnv 是同一类 RCE 面。审阅陌生仓库的 .claude/ 目录应成为和看 package.json 的 postinstall 一样的肌肉记忆。

七、成功要素分析：为什么是它成了标杆

编程 Agent 赛道拥挤（Cursor、Copilot、Windsurf、Aider、Codex CLI……），Claude Code 能站到标杆位置，我认为是四个因素叠乘，缺一不可：

1. 模型与 harness 同厂协同。 这是最深的一条护城河。Anthropic 训练 Claude 时可以直接优化「在 Claude Code 这个壳里的表现」——工具调用习惯、长任务耐力、被打断后的恢复——而壳的迭代（改 system prompt、调工具定义、加压缩策略）又能立刻反哺跑分。第三方壳只能等模型厂发版。Sonnet 4.5 发布时 SWE-bench Verified 77.2%、Opus 4.5 到 80.9%，这些数字都是模型+harness 一起测出来的。

2. 克制的形态选择。 从终端起步是个被嘲笑过的决定（2025 年初大家都在卷 IDE 插件），但终端意味着：贴近真实开发环境（测试、git、构建都在这）、天然可脚本化、进 CI 零成本。等能力站稳了再长出 IDE 扩展、Web、桌面——每一步都是同一个 harness 的新壳，没有重写。

3. 把确定性机制和模型能力分层。 CLAUDE.md 管「软规则」、hooks 管「硬规则」、checkpoints 管「可撤销」、权限模式管「自主权」——每一件「不该信任模型的事」都交给了确定性机制。这让 Agent 在敢放权的同时可控，是它能进企业的关键。

4. 极致的 dogfooding。 Anthropic 声称 Claude Code 约 90% 的代码由 Claude 自己写。这个飞轮——用自己产品造自己产品，问题当天暴露、当天修——是外部竞争者复制不了的迭代速度。

也要诚实说边界：它的强项绑定了 Anthropic 模型，订阅制（Pro $20/月、Max $100–200/月）对重度用户不算便宜；在超大单体仓库里 agentic search 的 token 开销可观；「Agent 自己写的 90% 代码」带来的可维护性争议也一直存在。标杆不等于无死角。

八、对自建 Agent 的可借鉴清单

如果你正在 从零构建自己的 Agent，以下是 Claude Code 值得逐条抄走的设计，按投入产出排序：

1. loop 保持极简，工程量投给恢复。 核心 loop 三十行能写完；把力气花在限流重试、中断恢复、超时兜底上。生产中杀死 Agent 的从来不是「不够聪明」，是「挂了起不来」。
2. 原子工具 + 一个逃生舱。 读、写、执行三类原子工具足够起步；Bash（或等价物）是逃生舱，权限盯住它就盯住了八成风险。
3. 上下文当预算管理。 自动压缩兜底 + 子代理隔离省量 + 磁盘文件做持久记忆，三件套缺一不可。口头交代的规则会被压缩冲掉，落到文件里。
4. 软规则用 prompt，硬规则用代码。 「尽量写测试」进 system prompt，「测试不过不许停」进 Stop hook。凡是你不能接受「模型偶尔不听」的约束，都必须确定性执行。
5. 权限做成模式，不是弹窗。 逐次弹窗确认的尽头是用户无脑回车。按风险分档（只读/可编辑/全自动），让用户在任务开始前一次性选对档位。
6. 可撤销比可信任重要。 与其祈祷模型不删错文件，不如让每次修改前自动快照（checkpoints）。回滚能力是把「bypassPermissions」从赌博变成工程实践的前提。
7. 读写分离调度。 只读工具并行、写工具串行，一行规则换可观的延迟下降。
8. harness 和模型一起测。 评估你的 Agent 时，跑的是「模型 × 壳」的组合，任何一边的改动都要回归整套 eval，见 Agent 评估 与 可观测性。

参考资料

• Enabling Claude Code to work more autonomously — Anthropic —— 2025-09-29 官方发布：Claude Code 2.0、VS Code 扩展、checkpoints 与 Agent SDK 更名。
• Anthropic brings Claude Code to the web — TechCrunch —— Web 版上线、定价层级、收入与用户增长数据、Cat Wu 访谈。
• anthropics/claude-code Releases — GitHub —— 官方 changelog，追踪各版本功能与修复。
• awesome-cc-harness — GitHub —— 对 Claude Code 全部 512K 行 TypeScript 源码的系统性逆向分析（Agent Loop、工具系统、权限模型、压缩管道），本文多处架构结论的来源。
• Reverse engineering Claude Code — Reid Barber —— 2025 年初最早的 source map 逆向，还原 REPL 结构与工具定义。
• Inside Claude Code: A Deep-Dive Reverse Engineering Report — ShareAI Lab —— 针对 v1.0.33 的 50K+ 行反混淆分析。
• Claude Code Hooks 官方文档 —— hooks 事件、matcher 与 JSON 输出协议的权威参考。
• claude_code_docs_map.md — Simon Willison —— 从 Claude Code 自查询行为观察其 system prompt 与文档索引设计。