雲里
里雾

01 AI Agent 架构原理——以 Claude Code 为例

claude code guide AI 更新于 2026/3/26

原文：How Claude Code Works

核心架构：Agentic Loop

Claude Code 的核心是一个 Agentic Loop（代理循环），由三个阶段组成：

你的指令 → [收集上下文] → [执行动作] → [验证结果] → 循环直到完成
                ↑                                    |
                └────── 你可以随时打断和调整 ─────────┘

这三个阶段不是严格分开的，而是流畅地交织在一起。一个简单的问题可能只需要收集上下文，一个 bug 修复会反复循环所有三个阶段。关键在于：每一步的结果决定下一步做什么——这就是 “agentic” 的含义。

两个核心组件

  1. 模型（Model）：负责推理——理解代码、规划步骤、做出决策
  2. 工具（Tools）：负责行动——没有工具，模型只能输出文字

Claude Code 本身是 Agentic Harness（代理框架）——它为模型提供工具、上下文管理和执行环境，把语言模型变成一个有能力的编程代理。

工具体系：五大类别

类别能力
文件操作读取、编辑、创建、重命名文件
搜索按模式找文件、用正则搜索内容、探索代码库
执行运行 shell 命令、启动服务器、跑测试、用 git
Web搜索网页、获取文档、查询错误信息
代码智能类型检查、跳转定义、查找引用（需插件）

模型根据你的指令和中间结果自主选择使用哪些工具。当你说”修复测试失败”时，Claude 可能会：运行测试 → 读错误输出 → 搜索相关源文件 → 读取文件理解代码 → 编辑修复 → 再次运行测试验证。

上下文窗口：最关键的资源

Claude 的上下文窗口容纳了：对话历史、文件内容、命令输出、CLAUDE.md、自动记忆、加载的 Skill、系统指令。

上下文满了怎么办？

管理策略：

Session（会话）管理

安全机制

  1. Checkpoint（检查点）：每次文件编辑前自动快照，Esc+Esc 可回滚
  2. Permission（权限）：Shift+Tab 切换权限模式
    • Default：编辑和命令都要确认
    • Auto-accept edits：自动接受编辑，命令仍需确认
    • Plan mode：只读模式，只做分析不做修改
    • Auto mode：后台安全分类器自动评估（研究预览）

与人协作的核心原则

知识检测

概念理解题

  1. Agentic Loop 的三个阶段是什么？它和传统的”输入→处理→输出”有什么本质区别？

  2. Claude Code 文档中提到它是一个 “Agentic Harness”。Harness（框架）和 Agent（代理）本身有什么区别？为什么这个区分很重要？

  3. 为什么上下文窗口被称为”最关键的资源”？如果不管理上下文会发生什么？

应用题

  1. 假设你要修复一个跨三个文件的 bug，但你的上下文窗口已经用了 70%。你会怎么安排工作流？

  2. Claude Code 的权限模式中，“Plan Mode” 和 “Auto Mode” 分别适用于什么场景？

迁移思考题

  1. 如果你要从零设计一个 AI Agent，Agentic Loop 的哪些部分是必须的？哪些是 Claude Code 特有的？

  2. OpenClaw 也有类似的 Agent 循环。它的 “isolated session” 和 Claude Code 的 “SubAgent” 在架构上有什么异同？

参考答案

1. Agentic Loop 的三个阶段

收集上下文（Gather Context）→ 执行动作（Take Action）→ 验证结果（Verify Results）。与传统”输入→处理→输出”的本质区别在于反馈循环：传统模式是单程的（一次输入一次输出），Agentic Loop 是迭代的——每一步的结果决定下一步做什么，模型自主决定何时停止。这意味着 Agent 可以自我纠错、自我调整策略，而传统流水线不行。

2. Agentic Harness vs Agent

Harness 是框架/脚手架——它提供工具、上下文管理、执行环境、权限控制等基础设施。Agent 是在 Harness 之上运行的推理实体（即 LLM）。区分很重要，因为同一个 Harness 可以承载不同的 Agent（比如切换模型），而同一个 Agent 在不同 Harness 上行为也不同（Claude 在 Claude Code 里能读写文件，在 Web 聊天里不能）。这也意味着你在定制 Claude Code 时，大部分定制发生在 Harness 层（Skill、Hook、MCP），而非 Agent 本身。

3. 为什么上下文窗口是最关键的资源

上下文窗口是 Agent 的”工作记忆”——所有信息（对话历史、文件内容、命令输出、系统指令）都必须塞进这个有限的空间。不管理的后果：(1) 早期指令被”遗忘”（压缩时丢失）(2) 模型性能下降（Context Rot）(3) 费用增加（token 越多越贵）(4) 响应变慢。本质上，上下文窗口的限制是 AI Agent 所有设计决策的根源约束。

4. 上下文 70% 时修复跨三文件的 bug

策略：(1) /compact 手动压缩，指定焦点为当前 bug 相关的三个文件 (2) 用 SubAgent 做文件阅读——让 SubAgent 读取三个文件的相关代码段，返回摘要（SubAgent 有独立上下文，不占主会话空间）(3) 在主会话中只保留修复所需的最小上下文，直接编辑 (4) 如果压缩后仍不够，/clear 开新会话，把 bug 描述和三个文件路径作为初始 prompt。

5. Plan Mode vs Auto Mode

Plan Mode：适合探索和规划——不确定该怎么改、需要先理解代码、想在实施前审阅计划。Claude 只做只读操作，不会修改文件。适合大型重构前的调研、复杂架构决策、代码审查。

Auto Mode：适合确定性高且信任 Claude 的场景——小的修复、格式化、明确的实现任务。后台安全分类器自动评估操作风险，低风险操作自动执行，高风险仍需确认。适合批量操作、CI 流程中的自动修复。

6. Agentic Loop 哪些必须、哪些特有

必须的：推理→工具调用→观察结果→循环（这是所有 Agent 的共性）。工具系统（某种形式的外部能力调用）也是必须的，否则只是聊天机器人不是 Agent。

Claude Code 特有的：(1) Checkpoint（文件编辑前自动快照）(2) 权限模式（Plan/Default/Auto）(3) Git 感知（worktree、commit）(4) 交互式打断（Esc）。这些都是为”在终端里编程”这个特定场景设计的。

7. OpenClaw isolated session vs Claude Code SubAgent

相同：都解决”上下文隔离”问题——在独立空间执行任务，不污染主上下文。

不同：(1) 生命周期：SubAgent 是主会话的子任务，随主会话存在；OpenClaw isolated session 是完全独立的 session 实例，有自己的 sessionId (2) 通信：SubAgent 结果直接回传到主上下文；isolated session 通过 Gateway RPC 通信 (3) 持久性：SubAgent 执行完即释放（除非有 memory）；isolated session 的记录可以独立存在 (4) 运维：SubAgent 零配置；isolated session 需要考虑 session 清理策略。

参见