为什么 Claude Code 是 Agent Loop，而不只是 RAG
研究边界
本文是基于本仓库还原源码、公开 npm 包产物和已有教程章节的架构解读，不代表 Anthropic 官方内部实现说明，也不声称覆盖未公开版本。
先把问题说清楚
把 Claude Code 理解成“给代码库做 RAG，然后回答问题”，会漏掉它最关键的部分。
RAG 的核心问题是：哪些上下文应该被检索出来喂给模型？
Agent loop 的核心问题是：模型下一步要不要动手，如果要动手，调用哪个工具、带什么参数、是否需要权限、结果如何继续进入下一轮？
Claude Code 更接近第二种。它不是一次检索加一次回答，而是一个持续运转的本地执行循环。
RAG 是检索管线，Agent Loop 是执行系统
| 维度 | 典型 RAG | Claude Code 这种 coding agent loop |
|---|---|---|
| 上下文来源 | 预先索引或向量检索 | 模型按需调用 Grep、Glob、Read 等工具 |
| 主要动作 | 找片段、回答 | 搜索、读取、编辑、执行命令、再判断 |
| 状态 | 多数是请求级上下文 | 会话历史、工具结果、权限状态、压缩摘要 |
| 风险点 | 检索不准、上下文污染 | 文件修改、命令执行、成本和循环失控 |
| 工程重点 | embedding、index、rerank | tool loop、permission、streaming、compaction |
这不是说 RAG 没用，而是说“coding agent”这个问题比 RAG 更宽。代码助手如果要真的改项目，就必须处理执行和安全。
1. Tool loop：模型不是只输出文本
在本仓库教程中，QueryEngine 被描述为核心循环。一次用户输入进入系统后，模型可能先输出一段思考方向，然后请求工具调用，例如：
- 用
Grep找某个函数或错误信息 - 用
Read打开具体文件 - 用
Edit修改代码 - 用
Bash跑测试或构建
工具执行结果再被塞回对话，模型继续判断下一步。这个“模型 -> 工具 -> 结果 -> 模型”的闭环，才是 coding agent 的主体。
2. Permission model：本地 runtime 必须有安全闸门
RAG 系统一般只读上下文，风险主要是泄露或检索错误。Local agent runtime 会碰到更硬的问题：它可能要写文件、删文件、跑 shell、访问网络或触发 git 操作。
所以权限模型不是附属功能，而是架构核心：
- 哪些工具可以自动执行
- 哪些命令必须询问用户
- 哪些路径或操作应该拦截
- 工具执行前后是否允许 hook
- 用户能否随时中断长任务
这也是为什么“会用工具”不等于“可以安全地当本地 coding agent”。
3. Grep/file context：代码上下文来自现场搜索
本仓库第 7 章已经讲过一个重要取舍：Claude Code 更强调 Grep、Glob、Read 这类本地文件工具，而不是把代码库预先变成一个向量索引。
这种方式的重点不是“没有检索”，而是检索控制权在 agent loop 里：
- 模型根据当前任务决定搜什么
- 本地工具返回精确匹配或文件内容
- 模型根据结果调整下一次搜索或修改
- 需要时再读更多文件，而不是一次塞满上下文
对 coding agent 来说，这种 file-context-on-demand 的方式更贴近开发者真实调试路径。
4. Streaming multi-turn：用户看到的是一段执行过程
Claude Code 的体验不是“等一个最终答案”。它会把模型输出、工具调用、工具结果和后续判断以流式方式推进。
这背后对应的是多轮架构：
- API 响应可以边生成边处理
- 检测到工具调用后暂停文本生成路径
- 工具结果回来后继续下一轮模型调用
- UI 层持续渲染进度，而不是只展示最终文本
这也是它看起来像“在工作”，而不只是“在回答”的原因。
5. Context compaction：长任务需要压缩记忆
Agent loop 一旦变长，工具结果、日志、文件内容和对话历史都会快速吃掉 token。单靠 RAG 不能解决这个问题，因为 agent 的历史本身也是状态。
所以 compaction 是 local agent runtime 的基础设施：
- 清理旧工具结果，保留主线
- 用摘要替代早期对话
- 在压缩前后保留关键约束
- 让长会话继续工作，而不是上下文爆掉后重开
换句话说，coding agent 的记忆不是一个静态索引，而是一条会被持续整理的执行轨迹。
市场背景：从 chat plugin 到 local agent runtime
AI coding agents 正在从“编辑器里的聊天插件”走向“本地运行时”。真正有用的 agent 需要贴近仓库、终端、权限系统和开发者工作流：
- 它要能在当前 repo 里搜索和读文件
- 它要能安全地修改代码和执行命令
- 它要能把多轮工作流展示给用户
- 它要能在上下文变长时继续保持任务主线
本仓库的独创价值不在于“复制 Claude Code”，而在于把复杂 source map 还原结果整理成一套可学习的 AI coding agent architecture 课程。读者可以从中理解 agent loop 的工程边界，再把这些思想迁移到自己的工具设计里。
结论
Claude Code 当然需要检索上下文，但它的关键不是“RAG 问答”，而是围绕本地工具、权限、安全、流式多轮和上下文压缩构建出的 agent loop。
如果只用 RAG 解释它，就像只用“文件搜索”解释 IDE。搜索很重要，但真正的产品形态来自整套 runtime。