00：为什么要拆 Claude Code：从一次回答到工程系统

后面这个系列，我准备把 Claude Code 当成一个真实的 coding agent 来拆。

这里先不急着讲安装、命令和使用技巧。我真正想追的问题是：

一个能在真实代码仓库里持续工作的 AI Coding Agent，到底由哪些工程系统组成？

普通的大模型问答更像一次请求响应。用户问一个问题，模型根据当前输入给出答案。这个过程可以很强，但它主要发生在文本里。

Claude Code 面对的是另一种现场。用户给它的往往是一个工程目标：修一个报错、补一个功能、解释一段代码、重构一个模块、跑测试，最后还要说明改了什么、怎么验证。

只看模型本身，很难解释完整过程。

真正让 Claude Code 从聊天框变成工程系统的，是模型周围那套运行时机制：它要读仓库、找文件、选择上下文、调用工具、修改代码、执行命令、处理失败、维持计划，还要判断什么时候继续、什么时候停下来、什么时候问用户。

所以 00 这篇先把系列入口铺好：

我为什么要写这个系列，后面准备怎么拆，最后希望沉淀出什么。

这个系列的写法边界

我会把它写成学习笔记和拆解记录。

安装、配置、命令用法、slash command 写法这些内容，后面可能会顺手提到，但不会作为主线。它们更像使用层面的入口，能帮人上手，却还不能解释一个 coding agent 为什么能持续完成任务。

提示词也一样。Prompt System 会单独写一篇，因为它确实影响 agent 的行为。但如果只盯着提示词，很容易把 Claude Code 看成“会说话的模型”。真实的 coding agent 还要靠工具、上下文、权限、计划、观测和恢复机制一起工作。

我更想把 Claude Code 当成一个工程样本来看：

• 它如何把用户的一句话变成可推进的任务状态。
• 它如何决定什么时候读文件、什么时候搜索、什么时候修改。
• 它如何把工具结果放回下一轮判断。
• 它如何处理权限、失败、上下文过长和目标漂移。
• 它如何在长任务里保持可观察、可恢复、可收束。

换成一句更朴素的话：

我想看懂 Claude Code 背后那套让 agent 持续工作的工程机制。

我为什么要做这个系列

我一开始对 coding agent 的理解很直接：模型够强，工具接好，应该就能做事。

真正用起来以后，这个理解很快变得不够用了。

同样是“帮我修一个 bug”，普通聊天模型可能会列出几种原因；coding agent 要进入仓库现场，先看目录，再读相关文件，必要时跑命令，拿到错误输出以后继续判断，最后完成修改并验证结果。

这里面每一步都牵涉工程选择：

• 工具怎么设计，模型才更容易选对、用对。
• 上下文怎么筛，才能把关键证据放进去。
• 计划什么时候需要显式列出来。
• 文件写入和命令执行怎么控风险。
• 测试失败以后，是继续排查、换路，还是停下来问用户。
• 最后怎么证明任务确实完成了。

这些问题比某一个产品更稳定。

产品会变，模型会变，API 会变。只要 agent 要在真实环境里完成任务，它就会碰到这些工程问题。

这也是我写这个系列的原因。我想把“Claude Code 好用在哪里”“某个 agent 为什么卡住”这类感受，拆成可以复盘的工程判断。

以后再看 Cursor、Codex、Devin、OpenHands、LangGraph 或其他 agent 系统时，我希望脑子里有一套稳定的问题清单，而不是只看产品表面。

后面会按什么顺序拆

后面的文章会先拆 11 个基础模块，最后再用一篇文章把它们串成完整运行链路。

这个顺序按 coding agent 跑起来时遇到的问题来排。

1. Agent Loop / 运行时主循环

第一篇先看主循环。

用户给出目标以后，Claude Code 如何一轮一轮地观察、判断、行动、接收反馈，直到任务完成、阻塞或需要用户决策？

这一篇要回答的是：

为什么 coding agent 不能只是一次 LLM 调用？

2. Tool System / 工具系统

主循环负责推进任务，工具系统让 agent 真正能动手。

这一篇会拆最小工具集：看目录、搜索、读文件、编辑、执行命令，以及工具结果如何回到下一轮判断。

核心问题是：

模型说“我要做一件事”以后，系统如何把它变成可检查、可执行、可回收结果的工具动作？

3. Prompt System / 提示词与行为协议

提示词更像 agent 的行为协议。

这一篇会拆 system prompt、工具描述、项目规则、协作风格分别约束什么，以及哪些规则适合写进 prompt，哪些更适合交给工具和权限系统。

核心问题是：

Prompt 规则和工程规则的边界在哪里？

4. Memory System / 记忆系统

记忆解决长期适配问题。

这一篇会看 CLAUDE.md、项目规则、用户偏好、历史经验分别适合保存什么，也会看错误记忆如何污染后续任务。

核心问题是：

什么信息值得长期保存，什么信息只应该留在当前会话？

5. Context Management / 上下文管理

真实仓库太大，模型一次读不完。

这一篇会拆 agent 如何决定读什么、跳过什么，保留什么、压缩什么，什么时候搜索，什么时候打开文件，什么时候总结历史。

核心问题是：

Prompt engineering 和 context engineering 到底有什么不同？

6. Planning & Task State / 计划与任务状态

复杂任务需要一套外显的状态。

这一篇会看 todo、task state、阶段性验证、完成条件这些机制如何让长任务保持方向。

核心问题是：

什么样的任务需要显式计划？计划太粗或太细分别会带来什么问题？

7. Permission & Safety / 权限与安全

只要 agent 能写文件、跑命令，权限系统就会进入核心链路。

这一篇会拆文件写入、shell 命令、网络访问、敏感信息读取的风险差异，以及 allow、deny、ask 这类策略如何影响效率和信任。

核心问题是：

哪些行为绝不能只靠 prompt 约束？

8. Observability / 可观测系统

执行过程看得见，agent 才更容易调试，也更容易被信任。

这一篇会拆工具调用日志、命令输出、错误信息、上下文变化、token 使用、成本追踪这些信息为什么重要。

核心问题是：

如何从执行轨迹里看懂 agent 为什么做出某个决策？

9. Fallback & Recovery / 兜底与失败恢复

Agent 一定会失败，恢复能力决定它能走多远。

这一篇会看工具失败、命令失败、测试失败、上下文不足、权限拒绝、模型误判时，系统应该如何重试、换路、降级或请求用户介入。

核心问题是：

Agent 如何避免在失败后反复执行无效动作？

10. Hooks & Extension / Hook 与扩展机制

Claude Code 可以接入真实工作流。

这一篇会拆 hook、skill、slash command、MCP 分别解决什么问题，哪些规则适合自动化，哪些流程适合沉淀为可复用能力。

核心问题是：

Prompt、hook、skill、MCP 的边界分别在哪里？

11. Multi-Agent / Subagent / 多 Agent 协作

多 agent 解决的是任务隔离、角色分工和上下文边界问题。

这一篇会拆 subagent 解决什么问题，多个 agent 如何隔离上下文、任务和权限，以及 planner、coder、reviewer、tester 这类角色什么时候真的有必要。

核心问题是：

什么时候应该引入 subagent，什么时候单 agent 反而更合适？

12. 完整运行链路

前面 11 篇按模块拆。最后一篇换一个角度，把它们重新串起来。

这时问题变成：

用户输入一个目标以后，一个 coding agent 内部到底经历了什么？

这一篇会把目标理解、记忆加载、提示词拼装、上下文选择、工具调用、权限判断、失败恢复、验证结果放到同一条链路里看。

如果前面是在拆零件，最后这一篇就是看机器如何跑起来。

最后想得到什么

这个系列写完以后，我希望得到一套理解 coding agent 的工程框架。

以后再看任何一个 agent 系统，都可以先问同一组问题：

• 它的主循环是什么？
• 它有哪些基础工具？
• 它如何组织提示词和项目规则？
• 它如何管理记忆和上下文？
• 它如何规划任务并维护状态？
• 它如何处理权限和安全？
• 它如何记录执行轨迹？
• 它如何从失败中恢复？
• 它如何扩展到外部工作流？
• 它什么时候需要多 agent？

这些问题能帮助我把一个产品拆回工程系统。

更进一步，如果以后自己做一个 coding agent，这个系列也应该能沉淀出一张设计清单：最小工具集是什么，主循环怎么跑，状态怎么维护，权限怎么拦，失败怎么处理，最后怎么验证。

所以我拆 Claude Code，不是为了证明它完美。

我更想借它回答一个更大的问题：

AI Agent 如何从一次聪明的回答，变成一个可维护、可调试、可协作的工程系统？