Claude 原理与 Claude Code 代码架构详解从大模型本身，到包裹它的 Agent Harness：训练、对齐、推理、工具协议、Agent 循环、权限、上下文工程与扩展机制

01Claude 是什么

"Claude" 在不同语境下指三层东西，理解它们的边界是读懂后续内容的前提：

官方文档对 Claude Code 的定义很直接："The agentic loop is powered by two components: models that reason and tools that act. Claude Code is the layer around the model that provides the tools and manages the context the model sees." 本文 Part A 讲 model 如何"会思考"，Part B 讲 harness 如何"让它能做事"。

02底座：Transformer 与预训练

Claude 属于 decoder-only Transformer 类大语言模型。Anthropic 没有公开具体参数量、层数、MoE 与否等细节，但其基本工作方式与同类模型一致：

1. Tokenize：文本、代码、图片（视觉编码后）被切分为 token 序列。
2. Embedding + 多层 Transformer Block：每层由多头自注意力（让每个 token 读取上下文里其他 token 的信息）和前馈网络（在高维空间做非线性变换、存储"知识"）组成，残差流贯穿各层。
3. 自回归解码：模型输出下一个 token 的概率分布，采样一个 token 追加到序列末尾，重复直到结束。所有"推理""工具调用"本质上都是这样一个一个 token 生成出来的结构化文本。

训练三段式：

03对齐：RLHF 与 Constitutional AI

Claude 区别于其他模型最有代表性的训练方法是 Constitutional AI (CAI)，出自 Anthropic 2022 年论文《Constitutional AI: Harmlessness from AI Feedback》（Bai et al.）。核心思想：人类不再逐条标注"哪个回答更无害"，而是写下一份原则清单（宪法），让 AI 依据原则自我批评、自我修正、自我评判。

论文摘要中的关键结论：这样训练出的助手"harmless but non-evasive"——遇到有害请求时不是一味回避，而是解释自己为什么反对；并且"用少得多的人类标注就能更精确地控制 AI 行为"。

在此基础上，Anthropic 还发布了 Claude 的"宪法"文档与 Character Training，塑造 Claude 好奇、坦诚、愿意提出不同意见的性格；并按 Responsible Scaling Policy (RSP) 对每一代模型做 ASL 等级的安全评估后再发布。

04可解释性：模型内部在想什么

Anthropic 的 Interpretability 团队试图打造一台"AI 显微镜"：在模型激活中找到可解释的特征 (features)，再把特征连成回路 (circuits)，追踪从输入词到输出词的计算路径。在《Tracing the thoughts of a large language model》中，他们对 Claude 3.5 Haiku 做了"AI 生物学"研究，得到几条直接影响我们理解"Claude 原理"的发现：

05推理：Extended Thinking 与 Effort

Claude 支持在给出最终回答前生成 thinking 内容块，即"扩展思考"。它在 API 中是一等公民：

// 请求：开启扩展思考
{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 10000 },
  "messages": [{ "role": "user", "content": "..." }]
}
// 响应：thinking 块在前（带加密 signature），text / tool_use 在后
{ "content": [
  { "type": "thinking", "thinking": "先分析失败用例...", "signature": "EqQB..." },
  { "type": "text", "text": "问题出在 token 过期判断..." }
]}

• signature：服务端对思考内容的签名。多轮工具调用时必须把 thinking 块原样回传，模型才能在工具结果之后接着原来的思路继续（interleaved thinking）。
• Effort：独立于 thinking 的另一个旋钮，取值 low / medium / high / xhigh / max，控制每次回复投入多少推理深度与 token。Agent SDK 文档明确说明二者相互独立：可以 effort: "low" 同时开 thinking，也可以 effort: "max" 不开。
• Claude Code 中：可用 /model 和 effort 设置调整；compaction 生成摘要时也会继承会话的 thinking 配置（v2.1.198 起）。

06工具调用协议

模型本身不能执行任何东西。"调用工具"的真实含义是：模型输出一段结构化的 tool_use 块，由客户端（harness）执行，再把结果以 tool_result 塞回下一轮输入。这是 Claude Code 一切能力的协议基础。

// 工具定义：名称 + 描述 + JSON Schema。描述的质量直接决定模型会不会用、用得对不对
{ "name": "Read",
  "description": "Reads a file from the local filesystem...",
  "input_schema": { "type": "object",
    "properties": { "file_path": {"type":"string"}, "offset": {"type":"integer"} },
    "required": ["file_path"] } }

• Client tools：由调用方执行（Claude Code 的 Read/Edit/Bash 都属于这一类）。
• Server tools：由 Anthropic 平台执行（如 web search、code execution），结果直接出现在响应中。
• 并行调用：一次响应可包含多个 tool_use 块；harness 可以并发执行只读工具。
• ACI 设计：《Building effective agents》提出要像设计 HCI 一样精心设计 Agent-Computer Interface——工具名清晰、参数防呆、描述里给示例与边界。Claude Code 内置工具的长篇描述就是这一原则的产物。

07上下文窗口与 Prompt Caching

Messages API 是无状态的：每一轮请求都要带上完整的 system prompt、工具定义和全部历史。Agent 跑 50 轮，就意味着同样的前缀被发送 50 次。两件事因此变得关键：

08Claude Code 整体架构

Claude Code 以 TypeScript 编写（GitHub anthropics/claude-code 仓库语言标注为 TypeScript，主体以原生二进制分发）。从官方文档披露的行为可以把它拆成六层：

09核心：Agentic Loop

官方文档把循环描述为三个交织的阶段：gather context → take action → verify results，重复直到任务完成，用户可随时打断。落到实现上，它就是一个围绕 Messages API 的 while 循环：

// 概念伪代码（依据 Agent SDK 文档《How the agent loop works》）
async function* agentLoop(prompt) {
  history.push(user(prompt))                          // UserPromptSubmit hook 可在此注入/拦截
  yield SystemMessage("init")
  while (true) {
    if (nearContextLimit()) await compact()          // PreCompact hook → 摘要 → compact_boundary
    const resp = await claude.messages.stream({ system, tools, messages: history })
    for (const block of resp.content) yield AssistantMessage(block)
    const calls = resp.content.filter(b => b.type === "tool_use")
    if (calls.length === 0) break                       // 无工具调用 = 本轮结束
    const results = await runTools(calls)              // 权限 → PreToolUse → 执行 → PostToolUse
    history.push(assistant(resp), user(results))
    yield UserMessage(results)
    if (++turns >= maxTurns || cost >= maxBudgetUsd) return Result("error_max_*")
  }
  runHooks("Stop")                                       // Stop hook 可要求"继续"
  yield ResultMessage({ result, usage, total_cost_usd, session_id })
}

"Turn" 的定义：一次"模型输出含工具调用 → 执行 → 结果回填"的往返。官方示例"Fix the failing tests in auth.ts"：Turn 1 Bash npm test（3 个失败）→ Turn 2 Read auth.ts / auth.test.ts → Turn 3 Edit + Bash npm test（全部通过）→ 最终纯文本回复。共 4 轮。

人在回路：按 Esc 立即取消正在运行的工具调用；直接输入并回车则作为"排队消息"，在当前工具调用结束后、同一轮内被读取，模型据此调整下一步。

10工具系统

并发策略：同一轮中多个工具调用时，只读工具（Read、Glob、Grep、标注 readOnlyHint 的 MCP 工具）可并发执行；修改状态的工具（Edit、Write、Bash）串行执行以避免冲突。

被拒绝时：工具被权限或 Hook 拒绝后，模型收到的是一条"拒绝消息"作为 tool_result，通常会换一种方式或说明无法继续——拒绝本身也是循环的一部分，而不是异常。

11权限、沙箱与检查点

Claude Code 有两类安全机制：checkpoints 让文件改动可撤销，permissions 控制什么能不经询问就执行；对 Bash 还可再叠一层 OS 级 sandbox。

11.1 权限模式（Shift+Tab 切换）

11.2 规则求值：deny 优先

1. PreToolUse Hook：exit code 2 的阻断型 hook 先于规则生效，可拦截即便被 allow 的调用。
2. deny 规则：任何层级（managed / CLI / project / user）只要命中 deny，其他层级都无法放开。
3. ask 规则：命中则必须询问，即便 hook 返回 allow。
4. allow 规则：如 Bash(npm test *)、WebFetch(domain:docs.x.com)、mcp__github__*。
5. 模式兜底：都未命中时按当前权限模式决定（询问 / 分类器 / 拒绝 / 放行）。

"Yes, and don't ask again" 对 Bash 和 WebFetch 会把规则永久写入仓库根的 .claude/settings.local.json；文件修改授权只在本会话有效。

11.3 Sandbox

开启后 Bash 工具运行在 OS 级隔离中：macOS 用 Seatbelt，Linux / WSL2 用 bubblewrap。文件系统写入限制在工作目录，网络经代理按域名白名单放行。沙箱与权限互补：权限决定"要不要执行"，沙箱限制"执行了能碰到什么"。对应开源实现 @anthropic-ai/sandbox-runtime。

11.4 Checkpoints

• 每个开启新一轮的用户 prompt 都创建一个检查点；编辑前对受影响文件做快照，保留最近 100 个检查点。
• Esc Esc 或 /rewind 回退代码和/或对话；检查点随会话保存，resume 后仍可用。
• 局限：Bash 命令造成的改动、子代理编辑、外部改动、远程副作用（数据库、部署）都不在快照覆盖范围内——这类风险靠权限控制。

12上下文工程与压缩

Anthropic 工程博客把这一层称为 context engineering：上下文是有限的"注意力预算"，token 越多，模型对每条信息的召回越弱（context rot）。Claude Code 的策略是"让模型看到最小但足够的高信号 token 集合"：

压缩后什么会保留（官方《What survives compaction》）

如果单个文件或工具输出过大，导致每次摘要后上下文立即被重新撑满，Claude Code 会在几次尝试后停止自动压缩并报 thrashing 错误，而不是无限循环。

13记忆：CLAUDE.md 与 Auto Memory

每个会话都从全新的上下文窗口开始。跨会话的"记忆"只靠两种落盘文件：

• 加载顺序：从文件系统根目录到当前目录逐级拼接（不是覆盖），离启动目录越近越后读；子目录中的 CLAUDE.md 在 Claude 读写该目录文件时才按需加载。
• 体积：CLAUDE.md 4 MiB 以内全量加载（越短遵循度越好）；MEMORY.md 只加载前 200 行或 25KB，主题文件按需用 Read 读取。
• 辅助：@path 导入其他文件；.claude/rules/*.md 可用 paths: 限定生效范围；块级 HTML 注释会在注入前被剥离。

14扩展层：Skills / MCP / Hooks / Subagents

14.1 Skills

一个目录 + SKILL.md（YAML frontmatter + Markdown 指令）+ 可选脚本/资源。模型在会话开始只看到 name 与 description，判断相关时调用 Skill 工具才加载正文——这是"渐进式披露"。可设 disable-model-invocation: true 只允许用户 /name 手动触发，context: fork 让技能在子代理中运行，allowed-tools 预批准工具。

---
name: release-notes
description: Generate release notes from merged PRs. Use when the user asks for a changelog.
allowed-tools: Bash(gh pr list *), Read
---
# 正文：步骤、模板、注意事项……（被调用时才进入上下文）

14.2 MCP (Model Context Protocol)

开放协议，让 Claude Code 作为 MCP client 连接外部服务（GitHub、数据库、浏览器、Jira…）。传输支持 stdio（本地进程）、HTTP、SSE、WebSocket；作用域分 local / project（.mcp.json）/ user；支持 OAuth。工具以 mcp__<server>__<tool> 命名，可直接写进权限规则。Claude Code 自身也能 claude mcp serve 作为 MCP server 被别的客户端调用。

14.3 Hooks

在生命周期固定点运行的确定性逻辑，不依赖模型"记得"去做。三种节奏：每会话（SessionStart / SessionEnd）、每轮（UserPromptSubmit / Stop）、每次工具调用（PreToolUse / PostToolUse）；另有 PermissionRequest、SubagentStart/Stop、PreCompact/PostCompact、Notification、FileChanged 等。处理器类型五种：

// .claude/settings.json：每次 Edit/Write 后自动格式化
{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write",
    "hooks": [ { "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" } ] } ] } }

14.4 Subagents

通过 Agent 工具派生的独立工作者：自己的上下文窗口、自己的 system prompt（Markdown 正文）、可限定工具集与模型、可 isolation: worktree 在独立 git worktree 里改代码、可前台或后台运行。内置有 Explore（只读、快速搜索，quick / medium / very thorough 三档）、Plan（plan mode 下调研）、general-purpose 等。定义放在 .claude/agents/*.md 或 ~/.claude/agents/：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Fork 是特殊的子代理：它复制当前对话与 system prompt 作为起点，适合"带着全部背景去做一件旁支任务"，结果同样以摘要形式回到主线。这对应《Building effective agents》中的 orchestrator-workers 模式：主代理动态拆分任务、派给工人、汇总结果。

15Agent SDK 与控制协议

Claude Agent SDK（Python / TypeScript）不是重新实现一遍 Agent，而是捆绑原生 Claude Code 二进制，以子进程方式驱动它。从开源的 claude-agent-sdk-python 源码可以看到其结构：

claude_agent_sdk/
├── query.py / client.py          # 对外 API：一次性 query() 与长连接 ClaudeSDKClient
├── types.py                      # ClaudeAgentOptions、消息与内容块类型
└── _internal/
    ├── transport/subprocess_cli.py   # 启动 claude 进程，stdin/stdout 走 stream-json
    ├── query.py                      # 双向控制协议：control_request / control_response
    ├── message_parser.py             # JSON 行 → AssistantMessage / ResultMessage …
    ├── sdk_mcp_bridge.py             # 进程内自定义工具以 SDK MCP server 暴露给 CLI
    └── session_store.py / sessions.py # 会话转录镜像、resume / fork

SDK 与 CLI 之间除了普通消息流，还有一条控制通道，在 _internal/query.py 中可见的请求子类型包括：

这说明 Claude Code 的核心循环只有一份实现，终端 TUI、IDE、SDK、CI 都是同一个循环的不同"前端"——这也是官方反复强调"the underlying agentic loop is identical"的原因。

16一次请求的完整时序

场景：在仓库里运行 claude，输入"修复 auth 模块失败的测试"，权限模式 default，开启 sandbox。

1. 启动：加载 settings 各层（managed › CLI › local › project › user），合并权限规则；运行 SessionStart hooks；连接 MCP servers（只取工具名）；扫描 skills / agents 描述；新建会话 JSONL。
2. 组装上下文：system prompt + 核心工具 schema + CLAUDE.md 链 + MEMORY.md 前 200 行 + git status 快照 + skill 描述 → 打上缓存断点。
3. 提交 prompt：UserPromptSubmit hook 可注入额外上下文；创建 checkpoint。
4. Turn 1 · 收集：模型（可能带 thinking）输出 Bash: npm test -- auth；Bash 不在 allow 列表 → 弹出审批 → 用户选"Yes, and don't ask again"写入 settings.local.json；在 Seatbelt/bubblewrap 内执行；PostToolUse；结果作为 tool_result 回填。
5. Turn 2 · 定位：模型并行发出 Grep "validateToken" 与 Read auth.ts、Read auth.test.ts；只读工具在工作目录内免审批，并发执行。
6. Turn 3 · 行动：Edit auth.ts（old_string → new_string）；编辑前快照文件；审批通过；PostToolUse hook 自动 prettier；LSP 返回诊断（如有）。
7. Turn 4 · 验证：再次 Bash npm test -- auth，命中刚保存的 allow 规则，直接执行，全部通过。
8. 结束：模型输出不含工具调用的文本总结；Stop hook 运行（可要求继续）；ResultMessage 记录 usage 与成本；对话与快照落盘，可 --continue 恢复或 /rewind 回退。

17设计取舍与最佳实践

使用建议

• 给模型可验证的目标（测试、截图、预期输出），它会自己闭环验证。
• 复杂任务先用 plan mode 对齐方案，再执行。
• 大范围搜索交给 Explore 子代理，保持主上下文干净；用 /context 看谁在占空间。
• 必须每次都发生的事用 Hooks（格式化、拦截危险命令），而不是写在提示里祈祷模型记得。
• CLAUDE.md 保持简短、具体、可执行；可复用流程沉淀为 Skills。

参考资料

• How Claude Code works · How the agent loop works (Agent SDK)
• Permissions · Permission modes · Sandboxing · Checkpointing
• Explore the context window · Memory · Extend Claude Code
• Hooks reference · Subagents · Skills · MCP
• Tool use · Extended thinking · Prompt caching
• Building effective agents · Effective context engineering for AI agents
• Constitutional AI: Harmlessness from AI Feedback (Bai et al., 2022) · Tracing the thoughts of a large language model
• github.com/anthropics/claude-code · github.com/anthropics/claude-agent-sdk-python