Claude Code 工作原理解密：从一句指令到精准修改代码
当你对 Claude Code 说”帮我修复这个 bug”时，背后并不是魔法，而是一套精密的工程系统。这篇文章将带你深入理解它的完整工作流程。
一、Claude Code 的核心机制：Agentic Loop
Claude Code 的本质是一个自主智能体，它的核心是一个被称为 “代理循环”（Agentic Loop） 的 while 循环。每一次循环包含四个阶段：
- 启动与上下文收集 —— 理解你的项目和需求
- AI 推理与工具决策 —— 规划行动步骤并选择工具
- 工具执行与安全校验 —— 实际执行命令或修改文件
- 验证与迭代 —— 检查结果并决定是否继续
整个循环会持续运行，直到 AI 认为任务已完成。
二、阶段一：启动与上下文收集
当你敲下一条指令并发送，Claude Code 会立即并行执行以下任务：
- **读取项目”说明书”**：自动查找
CLAUDE.md或AGENTS.md，获取项目结构、编码规范等信息。 - 获取当前工作区状态：读取 Git 状态、当前打开的文件、最近编辑的文件。
- 加载历史会话记忆：恢复之前的交互历史和压缩过的对话摘要。
这一切都依赖于其 20 万 token 的超大上下文窗口，使得 Claude 能”一次记住”整个项目的许多细节。
📌 误区澄清：Claude Code 不会在启动时全局扫描并生成一棵目录树文件。它是按需探索——需要看哪个目录，才用
ls、find、glob等工具实时查询。这样做更轻量、延迟更低。
三、阶段二：AI 推理与工具决策
所有收集到的信息被送入核心引擎 QueryEngine（约 46,000 行代码）。AI 在这一阶段遵循三条设计哲学：
- 最小脚手架，最大操作：框架保持极简，把复杂决策交给大模型本身。
- 工具即能力边界：Claude 的能力被严格封装在约 40 种工具中（如
Read、Write、Edit、Bash、Glob等）。新增能力 = 新增工具。 - 简单循环，工程护城河：循环核心代码仅约 200 行，但围绕它的整个系统（安全、权限、工具库）庞大而稳固。
AI 会根据你的指令和当前上下文，决定下一步调用哪个工具、以什么参数调用。
四、阶段三：工具执行与安全校验
当 AI 决策调用工具（如修改文件、运行命令）时，请求会被发送到工具调度器。这里有一个纵深防御的权限体系（共 7 种模式）：
| 模式 | 说明 |
|---|---|
| Always Allow | 只读操作（如读文件、搜索），自动放行 |
| Auto Allow (Safe Pattern) | 匹配安全模式的写操作（如 git commit），自动通过 |
| ML Classifier Gate | 机器学习模型评估命令风险 |
| Per-Session Allow | 当前会话授权过的操作，短时间内免确认 |
| Explicit Confirm | 高危操作（删除文件、网络请求）必须弹框请求用户确认 |
| Directory Scoped | 限制操作在项目目录内，越界拦截 |
| Global Deny | 硬编码禁止列表，绝不执行 |
权限通过后，具体的工具处理器（如 FileEditTool、BashTool）才会执行实际操作。
五、阶段四：验证与迭代
工具执行完毕后，输出（成功/失败、运行结果）会作为新的消息喂给 AI。AI 据此进入下一轮循环：
- ✅ 成功 → 判断是否完成目标，否则继续下一步
- ❌ 失败 → 分析错误原因，调整策略，重新尝试
这个过程形成一个强大的 “执行-反馈-调整”闭环，使得 Claude 可以自我修正，最终完成任务。
六、特殊情况：如何处理一个全新的 PRD？
如果 Git 上没有相关记录，AGENTS.md 里也没有说明，只有一个完整的 PRD（产品需求文档）链接，Claude 是如何做到的？
1. 获取并解析 PRD
Claude 会使用内置的 curl 或 fetch 工具，主动请求 PRD 链接，把全文内容下载下来。由于拥有 20 万 token 上下文，即便 PRD 长达几十页，也能一次性读入内存。
2. 在代码库中”按图索骥”
- 建立全局视野：先用
ls -R或find列出项目顶层目录。 - 模糊定位：用
glob搜索与 PRD 关键词相关的文件路径（例如 PRD 提到”支付”，就搜*payment*、*pay*）。 - 精确读取：用
Read工具打开疑似相关的文件，阅读源代码。
3. 生成计划并精准修改
- 进入 Plan Mode（计划模式），生成一份详细的修改计划，得到你的确认后再动手。
- 使用
Write和Edit工具进行精确修改。 - 自动调用
build、test等命令进行验证，形成”改 → 测 → 修”的闭环。
4. 高阶能力：MCP（模型上下文协议）
如果 PRD 存放在 Jira、Confluence、Linear、GitHub 等协作平台，Claude 可以通过 MCP 直接读取这些平台的结构化数据，而不仅仅是网页文本。这让它能够理解链接背后的业务逻辑、评论、状态等丰富信息。
七、总结：这不是魔法，是工程
从你输入一句话到 Claude 修改完代码，整个过程可以概括为：
启动并读取上下文 → AI 推理并选择工具 → 权限校验后执行 → 验证结果并迭代
Claude Code 没有全局目录树文件，没有预置的 PRD 知识，它只是像一位工程师一样：主动查阅文档、探索代码库、谨慎修改、自我验证。
而这一切的底层，是一个仅 200 行的核心循环，加上数百万行的工程代码（安全、工具、集成、模型交互）作为护城河。
希望这篇文章能帮你真正理解 AI 编程助手的工作原理。如果你正在使用 Claude Code，不妨在下次执行任务时，留意它输出的每一步——你会发现，它确实在认真地”思考”和”工作”。
💬 本文内容基于对 Claude Code 内部机制的技术讨论整理而成。如果你对 AI 编程工具感兴趣，欢迎留言交流。