2026 年，AI 编程 Agent 已经成了开发者的标配，但行业里有个很普遍的认知差：绝大多数人只会用 Agent，却讲不清它的工作原理。

我们习以为常地让 AI 读文件、改代码、跑测试，却很少去想：它为什么能自己决定下一步做什么？为什么对话久了会突然 “失忆”？为什么有的操作能直接执行，有的必须弹框问你？ 这些问题的答案，在今年 3 月 31 日有了最完整的参考。Anthropic 发布的 Claude Code v2.1.88 版本出现了低级发布事故 —— 遗漏了 source map 排除规则，51.2 万行 TypeScript 源码随之完整流出，大到核心架构，细到每一条安全规则、每一个工具的参数设计，全部公之于众。

这是产品级 AI 编程工具第一次被扒得如此彻底。今天这篇文章，阿宇带你从核心循环到工程细节，逐层拆解 Claude Code 的工作原理。搞懂这一套，相信你对所有 AI 编程工具的认知，都会直接跨过 “黑盒使用者” 的阶段。

一、核心本质：Agent 的底层就是一个 while 循环

很多人觉得 Agent 很神秘，好像有什么黑科技。但扒开所有包装，Claude Code 的核心骨架，就是一个再简单不过的while循环。

它的完整工作流，就是不断重复「思考→行动→观察」三个步骤，直到模型自己判断任务完成，跳出循环。用伪代码表示，核心逻辑不超过 20 行：

while (true) {
  // 1. 把对话历史+系统提示词拼好，发给大模型
  const response = await claude.chat(messages);
  
  // 2. 返回纯文本 = 任务完成，结束循环
  if (response.type === 'text') {
    display(response.text);
    break;
  }
  
  // 3. 返回工具调用 = 执行工具，结果塞回上下文
  if (response.type === 'tool_use') {
    // 先过权限检查
    if (!checkPermission(response.tool)) {
      result = askUserPermission(response.tool);
    }
    // 执行工具
    const result = executeTool(response.tool, response.params);
    // 工具结果放回对话历史，进入下一轮
    messages.push({ role: 'tool', content: result });
  }
}

这就是经典的ReAct（推理 + 行动）模式：Reasoning（模型思考下一步做什么）→ Acting（调用工具执行）→ Observation（拿到结果观察），循环往复。

和普通聊天的本质区别

普通的 ChatGPT 对话是「一问一答」：你发一次请求，AI 回一次结果，流程结束。 但编程任务天然是多步骤的 —— 你说 “帮我修这个 bug”，AI 得先读文件、搜相关代码、定位问题、修改代码、跑测试验证，中间哪一步出问题还要回头调整。这每一步，都是循环里的一次迭代。

最精妙的设计是停止条件完全由模型自主判断：不是写死 “调用 5 次工具就停”，而是模型自己评估任务有没有完成，完成了就输出纯文本结束循环。这也是为什么它能连续执行几十步操作，搞定复杂的大型任务。

很多人以为 Agent 的壁垒是架构，其实不是。架构就这么简单，真正的差距全在循环里每一个环节的工程化细节里。

二、8700 Token 系统提示词：产品理念都藏在这里

如果说循环是骨架，那系统提示词就是 Claude Code 的灵魂。它的系统提示词足足有约 8700 Token，是目前已知最详尽的 AI 编程工具提示词，而且不是一整块文本，是由多个模块拼接而成：

模块	Token 数	核心作用
系统规则	~2900	核心行为准则、安全红线
工具定义	~3000	18 + 工具的参数、用法、约束
CLAUDE.md	~1200	项目级自定义指令
通用规则	~500	代码风格、输出格式规范
Git 规则	~300	Git 操作的安全约束
技能定义	~800	可调用的预定义工作流

这里面藏着三个非常关键的设计细节，绝大多数 AI 工具都没做到位。

1. CLAUDE.md 不放进系统提示词

项目根目录的CLAUDE.md是用户自定义的项目规则，但它不是作为系统提示词注入，而是作为用户消息注入上下文。

原因很简单：系统提示词优先级最高，如果把用户自定义的内容和官方安全规则放在同级，就有可能被恶意用来绕过安全限制。放在用户消息层级，它的优先级低于官方安全规则，但高于普通用户对话 —— 既给了用户定制空间，又守住了安全底线。

2. 规则双重嵌套

安全规则和使用规范不是只写在系统提示词里，还完整嵌入了每一个工具的描述中。 比如 Bash 工具的描述里会反复强调：不要用cat读文件、用 Read 工具；不要用sed改文件、用 Edit 工具。 哪怕模型 “忘记” 了系统提示词里的规则，调用工具的时候还会再看一遍规则，相当于双重保险。

3. 把工程文化写进提示词

仔细看它的规则，不是泛泛的 “请写出高质量代码”，而是非常具体的编码哲学：

“不要超出任务需求加功能、重构、引入抽象” “三行重复的代码，也好过早的抽象” “默认不写注释”

这本质是把 Anthropic 自己的工程文化直接刻进了提示词里。Claude Code 输出的代码风格高度统一，不是模型天生如此，全是提示词约束出来的结果。

三、18 + 内置工具：为什么宁可做专用工具，也不全用 Bash？

模型再聪明，没有工具就只能动嘴。Claude Code 做了 18 + 内置工具，覆盖文件操作、执行、网络、Agent 调度、交互五大类，但最反直觉的设计是：明明一个 Bash 就能干所有事，它偏要做一堆专用工具。

核心工具分类

• 文件操作类：Read（读文件，支持图片 / PDF/Notebook）、Write（写文件）、Edit（精确替换）、Glob（路径搜索）、Grep（内容搜索）
• 执行类：Bash（执行 Shell 命令）、NotebookEdit（操作 Jupyter）
• 网络类：WebFetch（网页转 Markdown）、WebSearch（联网搜索）
• Agent 类：Agent（启动子 Agent）、Skill（调用预定义技能）
• 交互类：AskUserQuestion（向用户提问）、TodoWrite（任务管理）

专用工具优先的底层逻辑

系统提示词里明确写了一条规则：有专用工具就不用 Bash，Bash 只留给出 Shell 独有的操作。 这么做不是多此一举，三个核心好处：

1. 可控性更强：专用工具的参数、行为都是固定的，权限、错误处理、日志都能做精细化管控；Bash 过于灵活，风险不可控。
2. 节省 Token：最典型的是 Edit 工具，它不重写整个文件，只通过old_string和new_string做精确替换，只传 diff 内容，比整文件读写省几倍 Token。
3. 用户体验更好：用户能清晰看到 “AI 正在读取文件”“AI 正在编辑代码”，而不是面对一堆看不懂的 Shell 命令。

当然，Bash 依然是最强也最危险的工具，所以它的约束也最多：默认 2 分钟超时、不支持交互式命令、危险操作强制弹框确认，本质就是 “给能力，但牢牢套住边界”。

四、子 Agent 架构：用最便宜的模型，干最脏的活

当任务大到一个 Agent 处理不过来的时候，Claude Code 会启动子 Agent—— 相当于派出分身去并行处理子任务。它一共设计了三种子 Agent：

类型	所用模型	权限	适用场景
Explore	Haiku（最轻量最便宜）	只读，只能搜索读文件	快速探索代码库、收集信息
Plan	继承父 Agent 模型	只读	设计实现方案、梳理路径
General-purpose	继承父 Agent 模型	全工具权限	复杂多步骤任务执行

最精妙的设计：Explore Agent

这是我认为整个架构里最聪明的设计，完全是成本与效果的极致平衡：

• 用最便宜的 Haiku 模型（成本约 $0.25 / 百万输入 Token，比 Opus 便宜 60 倍），速度快成本低
• 只有只读权限，不会改代码，风险极低
• 内部可以消耗 100K+ Token，随便读几十个文件、搜整个代码库
• 最终返回给主 Agent 的，只有 1500-2000 Token 的精炼摘要

相当于用极低的成本，把海量的代码信息 “压缩” 成了精华，再喂给昂贵的主模型做决策。主 Agent 的上下文不会被大量代码撑爆，成本还压得极低。

子 Agent 的约束

为了避免失控，子 Agent 也有严格限制：

• 最多 1 层嵌套，子 Agent 不能再生子 Agent，防止无限递归
• 上下文完全隔离，子 Agent 看不到父 Agent 的对话历史
• 过程对用户不可见，结果只返回给父 Agent
• 支持并行启动，多个子 Agent 同时干活

一句话总结：能用 Explore 解决的，绝不用全功能子 Agent；能用小模型干的脏活，绝不让大模型出手。

五、200K 上下文也会爆？三层压缩机制的得与失

很多人觉得 200K 上下文窗口很大，但在编程场景里，Token 消耗速度远超想象：系统提示词先占 8700，读一个 500 行文件就要 3000-5000 Token，再读几个文件、跑几次命令、几轮工具调用，轻轻松松几十万 Token 就没了。

当上下文占用达到 92%-95% 时，Claude Code 会触发三层压缩机制，按优先级逐层执行：

第一层：工具结果截断

最先被压缩的是工具返回结果。比如读了一个 1000 行的文件，压缩后只保留开头 100 行和结尾 100 行，中间内容用摘要替代。

第二层：对话历史压缩

早期的对话轮次会被整合成摘要。比如半小时前读取的文件内容，会被压缩成 “已读取 config.js，包含路由配置” 这样的一句话描述。

第三层：强制截断

如果前两层还不够，就直接删掉最早的对话内容。到这一步，模型基本就会 “失忆” 了。

压缩的副作用

压缩不是免费的，信息丢失是必然的：

• 忘记早期的修改约定，重复操作
• 忘了之前读过的文件，重复读取浪费 Token
• 丢失用户一开始提的约束要求

这也是大家常吐槽 “AI 越用越笨” 的核心原因 —— 不是模型变笨了，是上下文被压缩，信息丢了。

六、23 层安全检查：给 AI 套缰绳的艺术

AI 编程工具最大的风险是什么？是它能执行任意 Shell 命令。你让它清临时文件，它万一执行rm -rf /；你让它推代码，它万一git push --force覆盖主干，后果不堪设想。

Claude Code 用了一套 23 层的安全体系，核心设计非常值得所有 AI 应用借鉴。

权限模型：deny > ask > allow

权限评估的优先级严格遵循：拒绝 > 询问 > 允许。

• deny：匹配到就直接拒绝，不问用户，优先级最高
• ask：匹配到就弹框询问用户确认
• allow：匹配到直接执行，优先级最低

这个顺序是安全设计的核心：哪怕你手动配置了 allow 规则，只要有 deny 规则命中，操作依然会被拦截。宁可多拦一次，也绝不放行一个危险操作，和防火墙的设计逻辑完全一致。

四层规则嵌入，层层兜底

安全规则不是写在一个模块里，而是分散嵌入了整个系统的每一层：

1. 系统提示词层：全局安全要求，比如避免命令注入、XSS、SQL 注入
2. 工具描述层：每个工具自带使用约束，比如 Bash 不能跳过 Git 钩子
3. 专用规则层：比如 Git 专属规则，禁止强制推送主干、禁止修改 Git 配置
4. 用户 Hooks 层：支持用户自定义前置 / 后置钩子，在工具执行前后做拦截、回滚

双模型安全校验

还有一个很巧的设计：用两个模型做安全检查。

• Haiku（小模型）做快速初筛，判断这个操作要不要问用户，高频但简单
• Opus/Sonnet（大模型）做复杂推理，判断操作有没有潜在安全风险

毕竟权限检查是每次工具调用都要跑的高频操作，全用大模型成本太高，用小模型初筛 + 大模型复核，兼顾了安全、速度和成本。

七、CLAUDE.md 与记忆系统：让 AI “认识” 项目的正确方式

每次开新对话，AI 都是一张白纸，不知道你的项目架构、编码规范、技术栈。Claude Code 用两套体系解决这个问题。

CLAUDE.md：项目级说明书

放在项目根目录的CLAUDE.md，每次开新对话都会自动加载。你可以在里面写项目架构、常用命令、编码规范、注意事项，相当于给 AI 留了一份项目说明书。

它还支持三级优先级：

1. 目录级 CLAUDE.md（优先级最高，仅作用于当前目录）
2. 项目级 CLAUDE.md（作用于整个项目）
3. 用户级 CLAUDE.md（全局所有项目生效）

记忆系统：跨对话的持久化

跨对话的用户偏好、项目背景这类信息，则存在本地的记忆文件里，分为用户、反馈、项目、参考四类。

但记忆系统最核心的设计原则是：记忆是可疑索引，不是可信真相。 系统明确要求：不能只靠记忆就做操作，必须先读文件确认当前状态。比如记忆里写了 “配置在第 50 行”，AI 也必须先打开文件确认，不能直接去改第 50 行 —— 因为代码随时可能变化。

这个设计非常务实。很多 AI 工具的记忆功能踩坑，就是把记忆当成了事实；而 Claude Code 里，记忆只是帮你快速定位的线索，最终决策永远以真实代码为准。

八、双模型策略：成本砍几十倍的秘密

Claude Code 不是全程用一个大模型，而是大小模型配合，这是它能把日均成本控制在几美元的核心秘诀。

模型	定位	负责工作	成本
Haiku	直觉系统	权限判断、分类、元数据提取、快速检索	~$0.25 / 百万输入 Token
Opus/Sonnet	大脑系统	代码理解、方案设计、复杂推理、代码生成	~$15 / 百万输入 Token

两者价格差了整整 60 倍。如果所有操作都用 Opus，仅权限检查这一项就会吃掉 30%-40% 的成本；换成 Haiku 之后，这部分成本直接降到不到 1%。

一次典型的编程任务，可能有 20-30 次权限检查、格式校验这类简单操作，但真正需要深度推理的只有 5-10 次。把简单的事交给小模型，把贵的算力花在核心推理上，这就是 AI 应用商业化的必修课。

九、写在最后：给开发者的 5 点启示

拆解完整个架构，最大的感受是：Claude Code 根本不是什么魔法，就是极致的工程化。每一个让你觉得 “AI 好聪明” 的瞬间，背后都是精心设计的规则和约束。

不管你是用 AI 工具写代码，还是自己做 AI 应用开发，这几点都非常值得借鉴：

1. Agent 没有银弹，先跑通最小循环再做加法 不要上来就搞复杂的状态机、花里胡哨的架构。先把最基础的 “思考 - 行动 - 观察” 循环跑通，再逐步加工具、加规则、加安全。简单架构 + 丰富规则，永远比复杂架构 + 稀疏规则更可靠。

2. 提示词工程是真正的产品壁垒 代码逻辑很容易抄，但几千 Token 提示词里的细节、分寸、产品理念，是抄不走的。AI 产品的核心竞争力，很多时候就藏在这些 “软规则” 里。

3. 安全是架构，不是事后补的功能 安全不能做成一个独立模块，必须渗透到系统的每一层。一个没有权限控制的 Agent，就像有 root 权限的实习生 —— 能力越强，闯祸的潜力越大。

4. 上下文管理，决定了用户感知的 “智商上限” 用户觉得 AI 笨，很多时候不是模型不行，是上下文管理没做好。重要信息要放在不会被压缩的地方，复杂任务要拆分，善用子 Agent 分担上下文压力。

5. 多模型混合是 AI 应用的标配 没有任何场景值得全程用最贵的模型。大模型做决策，小模型做执行；核心环节用重模型，边缘环节用轻模型。这是成本和体验的最优解。

---

互动话题：如果让你自研编程 Agent，你会模仿它的子 Agent 分层架构，还是自己重新设计任务调度逻辑？我是阿宇，欢迎大家留言交流！