Claude Code 架构
把 Claude Code 理解为 agentic harness：中央循环、上下文系统、工具、扩展、并行工作与可观测性。
一句话理解
Claude Code 不只是一个调用模型的终端工具。它更像一个 agentic harness：组装上下文，让模型推理，执行工具调用，记录结果，再把结果送回循环。
模型很重要，但它只是循环中的一个节点。真正的工程能力来自周围几层：上下文加载、权限、工具、skills、MCP servers、hooks、subagents、worktrees 和会话状态。
这是心智模型，不是私有实现契约
本页用六层模型解释 Claude Code。这个分层适合用来理解产品能力，但不代表 Anthropic 内部一定按这些模块名或边界实现 CLI。
中央 Agent Loop
Claude Code 的每一轮大致是这样：
- 组装 prompt：系统指令、项目上下文、对话历史、已加载 skills、可见工具和你的新消息。
- 模型基于上下文推理，返回文本或工具请求。
- Claude Code 检查权限并分发工具。
- 工具结果回到对话。
- 循环继续，直到 Claude 回复或任务结束。
这个循环本身故意保持简单。智能主要来自模型，以及控制“模型能看到什么、能做什么、哪些状态能跨时间保留”的外围 harness。
Loop 周围的六层
| 层 | 负责什么 | 用户可见能力 |
|---|---|---|
| 输入层 | 会话启动、信任、权限、命令解析 | claude、/resume、权限模式、workspace trust |
| 知识层 | 项目指令、记忆、上下文加载、压缩 | CLAUDE.md、AGENTS.md、.claude/rules/、auto memory、/context、/compact |
| 执行层 | 内置工具和工具分发 | Read/Edit/Write、Bash、搜索、web、checkpoints、代码智能 |
| 集成层 | 外部系统和扩展边界 | MCP servers、plugins、channels、hooks |
| 并行层 | 隔离 workers、脚本化编排和独立会话 | Subagents、dynamic workflows、worktrees、agent view、agent teams |
| 自动化层 | 不需要持续提示也能继续工作 | /goal、/loop、scheduled tasks、routines、channels |
| 云端输出层 | 云端 planning、深度 review 和可分享页面 | Ultraplan、ultrareview、artifacts |
| 可观测层 | 审计和生命周期控制 | JSONL transcripts、hooks、/cost、/doctor、监控集成 |
输入层
请求到达模型之前，Claude Code 会先判断当前会话、项目是否可信，以及哪些操作可以无需询问直接执行。
最重要的控制点：
- 会话身份：新会话、恢复会话、fork 会话或命名会话。
- 权限模式：
default、acceptEdits、plan、auto、dontAsk、bypassPermissions。 - 设置作用域：managed、命令行、本地、项目、用户配置。
- Workspace trust：Claude Code 是否能在当前目录工作。
这就是为什么同一个 prompt 在 plan mode、CI、可信本地仓库或沙箱中会有不同行为。
知识层
Claude Code 需要的不只是你最新一句话。它会从多处构建工作上下文：
- 来自
CLAUDE.md、.claude/CLAUDE.md、嵌套 CLAUDE.md 和 AGENTS.md 的项目指令。 - 来自
.claude/rules/的规则，包括读取匹配文件时才加载的路径规则。 - 仓库级 Claude memory store 中的 auto memory。
- 启动时加载 skill descriptions，真正触发时才加载完整 skill。
- 启动时加载 MCP tool names，更大的 tool definitions 延迟到需要时。
- 对话历史、文件读取、工具输出和 compact summary。
当上下文窗口接近满时，Claude Code 会自动压缩。不要把某个精确百分比或内部抽取顺序当成 API 契约。更可靠的实践是：持久规则放文件里，高噪声探索交给 subagents，长会话主动 /compact 或 /clear。
执行层
执行层就是工具运行时。工具把推理变成行动：
- 文件工具读取、编辑、创建和重组代码。
- 搜索工具查找文件、符号和文本。
- Bash 跑测试、构建、git 命令和本地脚本。
- Checkpoints 给文件编辑做快照，方便 rewind。
- 代码智能插件补充语言服务器导航和诊断。
每次工具调用的结果都会回到 loop。好的 Claude Code 会话通常不是“一次性大答案”，而是很多小的 observe-act-verify 循环。
集成层
Claude Code 连接仓库外部系统后会更强：
- MCP servers 暴露外部工具和资源，比如数据库、issue tracker、文档、浏览器、内部 API。
- Hooks 在生命周期事件上运行确定性自动化。
- Plugins 把 skills、agents、hooks 和 MCP servers 打包，供项目或团队复用。
- Channels 和远程集成可以把外部事件推入正在运行的会话。
Claude 需要外部数据或动作时用 MCP；某件事必须每次发生时用 hooks；一套配置变成可复用资产时用 plugins。
并行层
Claude Code 现在有几种并行模型，解决的问题不同：
| 模型 | 隔离方式 | 通信方式 | 适合场景 |
|---|---|---|---|
| Subagent | 同一会话内的独立上下文 | 结果摘要返回 parent | 高噪声研究、测试运行、专门 worker |
| Dynamic workflow | Script runtime 协调大量 agents | Script 聚合结果 | 大规模审计、研究、迁移、交叉验证 |
| Agent view | 独立后台 sessions | 人来监督 sessions | 管理多个独立任务 |
| Worktree session | 独立目录和分支 | 人来协调 | 独立分支或实验 |
| Agent team | 独立 Claude Code 实例 | 共享任务列表和直接消息 | 需要互相沟通的复杂工作 |
Subagents 默认解决上下文隔离。Worktrees 默认解决文件隔离。Agent teams 更重，而且仍是实验能力，但适合多个 agent 需要互相交流的任务。
可观测层
Claude Code 会记录和暴露运行过程，方便你调试行为：
- 会话 transcript 本地以 JSONL 保存。
/cost、/context、/doctor、/hooks、/mcp展示运行状态。- Hooks 可以审计或阻止生命周期事件。
- 监控集成可以导出 usage、trace 和运维信号。
Agent 不能只看最后有没有 diff。你还需要知道它看了什么、尝试了什么、改了什么、哪里需要人类审批。
实践含义
- 持久事实放 CLAUDE.md 或 rules，不放聊天里。
- 重复流程放 skills，不塞进巨大的 CLAUDE.md。
- 高噪声探索交给 subagents，不污染主上下文。
- 广泛、可重复的 fan-out 交给 dynamic workflows 或 ultracode。
- 并行编辑放 worktrees。
- 只有 worker 需要互相沟通时才用 agent teams。
- 监督多个独立 sessions 时用 agent view。
- 确定性强制用 hooks。
- 外部系统连接用 MCP。
- 需要 Claude 持续工作时，用
/goal、/loop、routines 和 channels。 - 可复用配置用 plugins。
官方参考
- How Claude Code works
- Extend Claude Code
- Explore the context window
- Run agents in parallel
- Dynamic workflows
- Orchestrate teams of Claude Code sessions
继续实践
Claude Code 架构 的核心概念已经读完
如果你想把理解变成可复用的能力，可以到 AgentWay 继续练习