Claude Code 源码剖析：Agent 工程化实践笔记

📌 导读

Claude Code 因为 npm 打包配置失误，将 51 万行核心源码连同 source map 一起发布到 npm，引发一场「史诗级乌龙」。但懂行的人第一时间都是——下载源码。因为这是目前地表最强 Agent 的最佳工程教科书。

源码中 80% 的代码不是在让 AI 更聪明，而是在死磕「可靠性」。这就是 AI 圈最新风向——拼系统求稳。

本文基于 51 万行泄露源码（Claude Code 客户端，非 Claude 大模型本身）整理。

核心 Harness Engineering：给野马套缰绳

AI 圈新词「线束工程」的本质：与其祈求大模型变聪明、别幻觉，不如用系统约束行为、划好赛道。

⚙️ 核心启发
「模型是发动机，但一辆车能不能安全上路，靠的是刹车、方向盘、安全带。这些不起眼的东西，才是真正决定成败的。」

01 Claude Code 是什么

Claude Code 是 Anthropic 官方的编程 Agent 工具：能直接读代码、改文件、跑命令、管理 Git 的 AI 程序员。

🔹 Agent vs ChatBot vs Copilot

        ChatBot：一次性的问答。

        Copilot：补全建议，本质上也是一次性预测。

        Agent：感知-决策-行动的自主循环，大模型自己决定下一步做什么。

Claude Code 的 Agent 循环核心：大模型自我决定——读文件？执行命令？还是回复用户？直到任务完成。

02 四层分层架构

1

引擎层 — Agent 的「大脑」
不包含业务逻辑，只做协调（拼上下文发API）、分发（执行工具）、决策（结束或继续）。新增能力只需加工具，引擎层不改。

2

工具层 — Agent 的「能力」
40 多个工具，统一规范，强制三个安全属性：只读/修改、破坏性/需确认、可并行/不可并行。漏一个就编译不过，每把刀都有刀鞘。

3

服务层 — 共享「基础设施」
调大模型 API、上下文压缩、MCP 协议通信。像大楼的水电煤，谁用都走这一层。

4

安全与治理层 — 罩住所有层的安全网
权限确认、Hook 系统、Bash 安全分析（语法级检测注入，非正则匹配）。

设计要点

类型系统强制安全属性声明，用编译期约束保证合规，而不是靠代码评审。

03 Agent 工作模式：Tool-Use Loop

没有用经典的 ReAct 模式，而是用一个更简洁的 Tool-Use Loop。

❓ ReAct 的三个问题

        Token 浪费：每轮输出 Thought 文本，50 轮循环浪费数万 Token。

        应用层复杂：解析 Thought/Action 容易出错。

        为弱模型设计：强模型内部可完成推理，无需显式思考。

⭕ Tool-Use Loop 核心逻辑

        while (true) {

          压缩上下文 → 调用API

          if stopReason == 'end_turn': break

          else: 执行工具 → 更新状态 → continue

        }
      
没有 Thought 步骤。模型内部完成推理（Extended Thinking，不占上下文），直接返回 tool_use 或 end_turn。

维度	ReAct	Tool-Use Loop
推理方式	显式 Thought	内部 Extended Thinking
工具调用	解析文本提取	API 原生 tool_use
终止判断	检测「Final Answer」	API 原生 end_turn
Token 开销	每轮高开销	无额外开销
编排复杂度	高	低（if/else）
适合场景	弱模型+简单工具	强模型+复杂工具集

一句话总结：信任模型的推理能力，把应用层框架做得尽可能简单。「大道至简」反而最高效。

📋 Plan Mode：先规划再执行

通过 EnterPlanMode / ExitPlanMode 两个工具实现，并非独立框架。
流程：模型自主进入 → 只读探索（权限降为只读，只能用 Read/Grep/Glob）→ 写计划到 .claude/plans/ → 用户审批 → 恢复权限执行。

细节：每 5 轮对话，系统塞小纸条提醒「还在 Plan Mode，别改代码」，防止模型走神。

设计精髓：「工具即能力」——Plan Mode 只是调用了两个工具，引擎层无需特殊处理。

04 System Prompt 动态组装

System Prompt 不是静态文件，由十几个 Section 动态拼接而成，内含精巧的缓存优化。

「你是一个交互式代理（interactive agent），帮助用户完成软件工程任务。」

定位是 agent 而非 assistant，暗示主动行动而非被动回答。

🔒 安全红线（先肯定再约束）

✅ 允许：授权的安全测试、CTF 挑战、防御性安全研究
❌ 拒绝：DoS、供应链攻击、检测规避、大规模目标扫描

📐 行为准则（精华摘录）

1

读代码再改代码：不要对你没读过的代码提修改建议。先理解现有代码再动手。

2

少即是多：不要在用户要求之外添加功能、重构。「修 bug 不顺手清理代码」。三行相似代码胜过过早抽象。

3

先诊断再换方案：失败后先读报错、查假设、尝试针对性修复。不盲目重试，也不一次失败就放弃。

🛡️ 操作安全：可逆性 × 影响范围

自由执行：本地、可逆（编辑文件、跑测试）
需确认：删除文件/分支、force-push、reset --hard、推送代码、创建 PR、上传第三方工具。
「授权仅对指定范围有效，不能超出范围」 — 防止权限蔓延。

🔧 工具使用：专用优先

读文件用 Read 而非 cat；编辑用 Edit 而非 sed；搜索用 Grep 而非 grep。
动机：可审查性 + 权限检查。

🌿 Git 安全协议

绝不修改 git config；不破坏性命令（除非用户明确要求）；不跳过 hooks；
关键：用新的 commit，不用 --amend（pre-commit hook 失败时 amend 会修改不相关 commit，可能导致代码丢失）。

💰 分割线与三级缓存

      ┌──────────────────────────────────────────

      │ [角色定义][安全红线][行为准则][操作安全]

      │ [工具使用][Git安全][输出风格] ← 所有用户一样

      ├──── __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ ──

      │ [环境信息][CLAUDE.md][记忆][MCP] ← 因人而异

      └──────────────────────────────────────────

全局缓存：分割线之上所有用户共享同一份缓存。
组织缓存：同组织共享。
会话缓存：同会话只算一次。
Prompt Cache 命中可降低 90% 费用。

05 记忆系统

🗂️ 记什么：四种类型封闭集合

类型	内容
user	用户画像：角色、偏好、知识水平
feedback	该做什么/不该做什么 + Why + How to apply
project	项目动态、截止日期（相对日期转绝对日期）
reference	外部指针：去哪找什么信息

限定四种类型，逼 Agent 做分类决策，防止记忆膨胀成垃圾堆。

⛔ 不记什么：排除清单

代码模式/架构（grep/git 可得）、Git 历史（git log 权威）、调试方案（代码已包含修复）、CLAUDE.md 已有内容、当前会话上下文。
原则：能从代码推导的信息一律不存。记忆比代码「死」，存了会变成「权威的错误」。

💾 怎么存：索引 + 独立文件

      ---

      name: no-mock-database

      description: 集成测试必须用真实数据库

      type: feedback

      ---

      **Why:** 上季度 mock 测试全过但生产迁移失败

      **How to apply:** 写测试时连真实数据库

MEMORY.md 索引：≤200 行 / ≤25KB，始终加载到 System Prompt。
记忆文件：独立 .md，按需加载。
双重截断检查：行数 + 字节数。

🔍 怎么召回：Sonnet 当秘书

1

扫描头部信息：只读每个文件前 30 行 frontmatter，按修改时间排序取 200 条。

2

Sonnet 侧查询：清单+用户问题发给 Sonnet，只需返回最多 5 条相关文件名。

3

加载全文：读取选中记忆完整内容注入上下文。

陈旧度检测：超 1 天的记忆自动附加警告「请先对照当前代码验证再引用」。
并行预取：记忆选择与主模型 API 调用并行执行，Sonnet 提前完成，几乎零延迟。

        正在使用某工具时，自动过滤该工具的使用文档类记忆（噪声），但保留「已知 bug 和注意事项」（最需要知道坑）。
      

06 上下文窗口管理：压缩五步走

核心理念：能轻则轻，逐步加码。每次 API 调用前依次尝试。

层级	手段	信息损失	API 开销
第 1 层	大结果存磁盘（>50KB → 2KB 预览）	几乎为零	零
第 2 层	砍掉远古消息（Snip）	低	零
第 3 层	裁剪老工具输出（时间衰减）	中低	零
第 4 层	读时投影压缩（90% 阈值）	中	低
第 5 层	全量摘要（~93% 触发）	高	高

第 1 层：大结果存磁盘

Read 工具返回超大文件时，>50KB 写磁盘，消息中只留 2KB 预览。完整内容还在磁盘，需要时可再读特定范围。消息级上限 200KB。

第 2 层：砍掉远古消息

直接移除对话开头老消息，插入边界标记。零 API 开销，不做摘要。会传递释放 Token 数给第 5 层，避免重复压缩。

第 3 层：裁剪老工具输出

只裁剪可重新获取的工具结果（Read/Bash/Grep/Glob/Edit/Write），保留最近 5 个。
AgentTool（子 Agent 输出）、TaskTool（任务状态）永不裁剪——推理过程不可重复。
触发条件：距离上次 API 调用 ≥60 分钟（Prompt Cache 大概率已过期）。

第 4 层：读时投影

不修改原始消息，只在调用 API 时动态计算压缩视图。
触发阈值：90% 窗口开始压缩，95% 紧急压缩。运行在第 5 层之前，如果够用，就不触发全量摘要。

第 5 层：全量摘要

触发公式：有效窗口 − 13K 缓冲区。200K 模型 → 167K 触发。
三步走：生成多维摘要（用户意图、文件、错误、待办等）→ 替换旧消息 → Post-Compact Restoration（最多 5 个文件 / 50K Token 重新注入 + 25K Token Skill 恢复）。
熔断器：连续失败 3 次自动放弃，防止拖垮 Agent。

各层协调：第 2 层告诉第 5 层「已释放多少 Token」；第 4 层在第 5 层之前运行。大部分场景前三层就够，只需要「搬运」和「裁剪」，零额外 API 调用。

FIN 写在最后

「做 Agent，别老盯着模型发呆。模型是发动机，但一辆车能不能安全上路，靠的是刹车、方向盘、安全带。」

每一件事单拿出来都不是黑科技，但全串在一起，就是一套能把野马驯成耕牛的缰绳系统。

压缩分五步走、记忆分四类、System Prompt 动态组装、Tool-Use Loop 大道至简、Plan Mode 工具即能力……

Claude Code 源码泄漏缩短了国内外 AI Agent 的信息差，这些实打实的工程实践，值得每一个 Agent 开发者反复研究。