Claude Code 全景架构与手写演进导览

市面上的大多数 AI 辅助编码工具，要么停留在编辑器侧边栏的“聊天窗口”，要么过度包装成庞大而黑盒的框架。每当模型陷入幻觉、重复执行错误命令或陷入死循环时，开发者很难穿透厚重的抽象层去排查问题。

Claude Code 作为业界公认工程完成度极高的终端 Coding Agent，其核心理念却出奇地纯粹：“One loop & Bash is all you need”。

它没有依赖任何外部的 Agent 框架，整个系统的核心能力均由一个清晰的异步循环衍生而来。为了彻底搞懂一个能处理真实工程任务的 Coding Agent 是如何炼成的，本专栏采用从零手写、逐步叠加机制的演进路径：从不到 30 行的极简 Python 循环出发，逐层增加工具分发、任务规划、上下文隔离、按需技能、三层压缩、磁盘 DAG 任务图、非阻塞异步与 Git 工作树隔离，最终拼装出工业级的多智能体协作网络。

演进路线图：从 30 行到工业级 Harness

整个系列分为基础 Harness 与高级工程系统两个阶段，共计 12 个循序渐进的进阶节点：

专栏架构全景导航

第一阶段：基础 Harness（s01 ~ s06）

构建轻量但具备自主闭环能力的 Agent 运行底座：

篇号 文章标题与核心内容 关键机制与生产源码映射
01 Agent Loop：一个循环就是一个 Agent 30 行极简循环、stop_reason 判定；对齐 Claude Code src/query.ts 1729 行状态机与六大状态转移
02 Tool Use：扩展模型能触达的边界 Dispatch Map 字典查找模式，原子操作与沙箱校验；对齐 src/tools.ts 中 40+ 核心工具清单
03 TodoWrite：让 Agent 不再迷路 规划层与状态机；为什么强制“同时仅有一个进行中任务”；解析从 V1 内存 Todo 到 V2 磁盘 Task 的演进
04 Subagent：上下文隔离的正确姿势 避免大段源码中间日志污染主对话；子 Agent 独立上下文、最小工具授权与纯文本摘要返回机制
05 Skill Loading：按需加载领域知识 解决 System Prompt 动辄超 20k Token 痛点；两层渐进披露机制与 SKILL.md 规范剖析
06 Context Compact：三层压缩换无限会话 轻量 Context Collapse、LLM 激进摘要与 Auto-flush；严格保留代码路径与精确行号锚点

第二阶段：高级工程与协同（s07 ~ s12）

让系统迈入真实团队研发，解决多文件冲突与后台长时间运行：

篇号 文章标题与核心内容 关键机制与生产源码映射
07 Task System：持久化任务图 磁盘持久化 JSON 存储；DAG 依赖关系定义、前置阻塞 blockedBy 与进程崩溃断点续跑
08 Background Tasks：非阻塞工具执行 后台子进程执行编译/单测，Agent 主循环不挂起等待；主动通知唤醒与输出日志滚动检索
09 Agent Teams：多 Agent 协作 去除中心化消息中间件依赖；基于文件系统的 Mailbox 架构，Team 目录划分与多智能体分工
10 Team Protocols：结构化通信协议 请求-响应结构化握手；Schema 强制校验、协议超时熔断与通信死锁预防
11 Autonomous Agents：自组织团队 去中心化协同；成员自主监听任务池并执行原子文件抢单（Task Claiming）；动态负载均衡
12 Worktree 隔离：多 Agent 并行不踩踏 Git Worktree 物理目录沙箱；彻底解决并发 Agent 对同一文件写踩踏问题；分支合并门禁

核心设计哲学

在阅读或编写 Agent 系统时，时刻牢记一条法则：

Agent 的系统复杂度应当伴随真实工程需求逐步生长，而不是从第一天就过度设计。

从 while True 的 30 行极简原型出发，每增加一个特性，都是为了解决上一阶段暴露出的一处确凿痛点：

  • 只有 Bash 不安全 $\rightarrow$ 增加专用工具与 Dispatch Map；
  • 任务步数一多就跑偏 $\rightarrow$ 引入 TodoWrite / Task 规划层；
  • 文件读取把上下文撑爆 $\rightarrow$ 派生独立上下文的 Subagent；
  • 专业领域规则塞不下 $\rightarrow$ 设计按需唤醒的 Skill Loading；
  • 超长任务遭遇 Token 上限 $\rightarrow$ 搭建三层 Context Compact；
  • 多 Agent 协同冲突 $\rightarrow$ 引入 文件消息总线 与 Git Worktree 隔离。

所有的主流框架本质上都是这些基础机制的不同排列组合。掌握了底层的齿轮咬合逻辑，无论面对任何新框架，你都能一眼看透其本质。

下一篇，我们将从最精简的骨架开始：搭出不到 30 行代码的最小可运行 Agent Loop。