本文档说明使用 Claude Code 时，从用户输入一条需求开始，到 Agent 调用 LLM、读取上下文、执行工具、修改文件、运行命令、再把结果返回给用户的完整交互过程。

说明：不同版本的 Claude Code、Cursor、MCP 或具体工具实现会有差异，但核心 Agent 工作流大体一致：用户提出目标，Agent 组织上下文，LLM 推理下一步，工具执行外部动作，结果回填给 LLM，循环直到任务完成。

1. 总体架构

Claude Code 可以理解为一个“带工具的 LLM Agent”。LLM 本身只负责理解、推理和生成下一步动作；真正读取文件、搜索代码、执行命令、编辑文件、调用外部系统的是 Agent Runtime 提供的工具层。

2. 核心组成部分

2.1 用户输入

用户输入是整个流程的起点，通常包含：

• 目标：例如“修复这个 bug”“解释这段代码”“帮我写测试”。

• 约束：例如“不要改接口”“用中文回复”“只改当前文件”。

• 上下文引用：例如文件路径、错误日志、PR 链接、截图、终端输出。

• 期望产物：例如代码修改、文档、提交记录、PR 描述、测试结果。

Agent 首先会判断任务类型：是只需要回答问题，还是需要读代码、改文件、运行测试、调用外部服务。

2.2 Agent Runtime

Agent Runtime 是 LLM 和外部世界之间的执行层。它负责：

• 接收用户输入。

• 组装发给 LLM 的上下文。

• 暴露可用工具列表和工具参数 schema。

• 接收 LLM 的工具调用意图。

• 真正执行工具。

• 把工具结果回填给 LLM。

• 管理多轮循环、权限、安全策略和终止条件。

可以把 Runtime 理解成“项目经理 + 执行助理”：LLM 负责判断要做什么，Runtime 负责把动作安全地执行出来。

2.3 上下文管理器

LLM 每次推理都不是只看到用户最新一句话，而是会看到一组被整理后的上下文：

• 系统级规则：例如输出格式、安全边界、工具使用规则。

• 开发者规则：例如代码风格、不能破坏用户已有改动。

• 用户偏好：例如始终用简体中文回复。

• 当前对话历史：包括用户之前的要求、Agent 的操作和工具结果。

• 工作区状态：当前目录、打开文件、诊断信息、终端状态等。

• 项目文件内容：通过读取文件、搜索代码后动态加入。

上下文窗口有限，所以 Agent 会优先保留与当前任务最相关的信息。长任务中，旧信息可能被压缩成摘要。

2.4 LLM

LLM 是推理核心，主要做这些事情：

• 理解用户意图。

• 判断需要哪些上下文。

• 选择下一步动作。

• 生成工具调用参数。

• 根据工具结果继续推理。

• 最终生成对用户可读的结果。

LLM 自己不能直接访问本地文件、运行命令或联网；它必须通过工具层完成这些动作。

2.5 工具层

工具是 Agent 的“手和眼睛”。常见工具包括：

• 文件读取工具：读取源码、配置、日志、文档。

• 搜索工具：按关键字、语义或文件名查找相关代码。

• 编辑工具：创建文件、修改文件、删除文件。

• Shell 工具：运行测试、构建、脚本、Git 命令。

• MCP 工具：连接 GitHub、Linear、Slack、数据库、浏览器等外部系统。

• 网络工具：搜索或抓取公开网页内容。

• Todo 工具：维护多步骤任务进度。

工具调用通常是一个闭环：

1. LLM 决定需要工具。

2. LLM 按工具 schema 生成参数。

3. Runtime 校验权限和参数。

4. Runtime 执行工具。

5. 工具返回结构化或文本结果。

6. 结果进入下一轮 LLM 上下文。

3. 一次交互的详细过程

下面以“用户要求修改代码”为例，描述一次典型 Agent 工作流。

4. Agent 的循环模型

Agent 的核心不是“一次性回答”，而是一个多轮循环。

这个循环通常会持续到满足以下条件之一：

• 用户目标已经完成。

• 测试或验证通过。

• 缺少必要信息，需要向用户提问。

• 权限不足或工具不可用。

• 出现风险，需要用户确认。

5. 工具调用的内部细节

一次工具调用通常包含以下信息：

{
  "tool": "ReadFile",
  "arguments": {
    "path": "/project/src/app.ts"
  },
  "reason": "需要查看入口文件以定位初始化逻辑"
}

Runtime 收到后会做几类处理：

• 参数校验：路径、类型、必填字段是否正确。

• 权限检查：是否允许读取、写入、联网、执行命令。

• 沙箱控制：限制危险操作或需要用户批准。

• 执行工具：把请求发送给具体工具实现。

• 结果标准化：把输出整理成 LLM 可以继续理解的文本或结构化数据。

工具结果可能类似：

ReadFile success:
1|import { createApp } from "vue";
2|import App from "./App.vue";
3|createApp(App).mount("#app");

LLM 会基于这些结果继续判断：是否还要读别的文件、是否可以编辑、是否需要运行测试。

6. 上下文如何影响结果

同样一句用户输入，在不同上下文下可能触发不同动作。

例如用户说：

“帮我修一下这个报错。”

如果上下文里有终端报错，Agent 会先分析报错栈；如果当前打开的是测试文件，Agent 可能先读相关实现；如果没有任何线索，Agent 会询问报错内容或主动搜索项目中最近失败的测试。

上下文常见来源包括：

• 用户明确贴出的错误信息。

• 当前打开文件和光标位置。

• 最近修改过的文件。

• Git diff。

• 终端输出。

• 项目规则文档。

• 已执行工具返回的结果。

7. 示例：修复一个测试失败

假设用户输入：

“运行测试发现登录页测试失败了，帮我修复。”

7.1 第一步：理解任务

Agent 会把任务拆成几个问题：

• 测试失败的具体命令是什么？

• 失败日志在哪里？

• 登录页组件和测试文件在哪里？

• 是测试写错、组件行为变了，还是依赖环境问题？

如果没有足够信息，Agent 通常会先运行测试或搜索测试文件。

7.2 第二步：收集上下文

Agent 可能调用搜索工具：

搜索关键词：login、LoginPage、登录页、auth

找到这些文件：

src/pages/LoginPage.tsx
src/pages/LoginPage.test.tsx
src/services/auth.ts

然后读取相关文件内容，理解组件行为和测试预期。

7.3 第三步：运行测试

Agent 可能调用 Shell：

npm test -- LoginPage

得到失败输出：

Expected button to be enabled
Received button is disabled

这个观察结果会被送回 LLM。LLM 看到测试预期是“输入邮箱和密码后按钮可点击”，但组件当前逻辑可能要求额外勾选协议。

7.4 第四步：定位原因

Agent 继续读取组件代码，可能发现：

const canSubmit = email && password && acceptedTerms;

而测试只填写了邮箱和密码，没有勾选协议。此时有两种可能：

• 产品行为确实要求勾选协议：应修改测试，增加勾选动作。

• 产品行为不应该要求勾选协议：应修改组件逻辑。

Agent 会根据项目上下文、需求文档或现有测试风格判断。如果无法判断，会向用户确认。

7.5 第五步：执行修改

如果判断产品行为是正确的，Agent 会编辑测试：

await user.click(screen.getByRole("checkbox", { name: /同意协议/ }));
expect(screen.getByRole("button", { name: /登录/ })).toBeEnabled();

编辑完成后，工具返回“文件已修改”。这个结果再进入下一轮 LLM。

7.6 第六步：验证

Agent 再次运行：

npm test -- LoginPage

如果测试通过，可能还会运行更大范围验证：

npm test

是否运行全量测试取决于修改范围、项目规模和用户要求。

7.7 第七步：总结给用户

最终回复通常包括：

• 修复了什么。

• 改了哪些行为或文件。

• 运行了什么验证。

• 是否还有风险或未验证内容。

例如：

已修复登录页测试失败。原因是组件当前要求用户勾选协议后才能提交，但测试只填写了邮箱和密码。我更新了测试流程，增加勾选协议步骤。

验证：npm test -- LoginPage 已通过。

8. Agent 为什么会反复读取和验证

一个可靠的 coding agent 不应该只凭猜测改代码。它通常会反复执行：

• 读代码：确认实际实现。

• 搜索调用点：确认影响范围。

• 看测试：确认期望行为。

• 小步编辑：降低破坏范围。

• 跑测试：验证修改是否有效。

• 看 Git diff：确认没有误改。

这就是为什么一次看似简单的需求，Agent 可能会进行多次工具调用。工具调用越充分，最终修改通常越稳。

9. 常见安全与权限边界

Agent 通常会避免或请求确认以下操作：

• 删除大量文件。

• 覆盖用户未提交改动。

• 执行危险 Shell 命令。

• 修改 Git 历史。

• 推送代码到远端。

• 访问需要认证的外部系统。

• 安装依赖或联网执行脚本。

这类边界由系统规则、工具权限、沙箱和用户确认共同控制。

10. 一句话总结

Claude Code 的 Agent 工作流可以概括为：

用户给目标，Agent 组织上下文，LLM 决定下一步，工具执行现实动作，执行结果回到上下文，LLM 继续推理，循环直到完成并总结。

真正关键的是：LLM 不直接“操作电脑”，它通过 Agent Runtime 暴露的工具间接完成文件读取、代码修改、命令执行和外部系统交互。