Claude Code架构拆解：CLI Agent极简工具链实战

过去两年，我们见证了 Agent 的尴尬童年：从最初笨拙的 Copy-Paste，到 Cursor 的 VS Code Fork 革命，再到如今 Claude Code 这种 CLI Coding Agent 的出现。

为什么以前的 Agent 总是卡在“演示很酷，实战很废”的怪圈里？而 Claude Code 究竟做对了什么，让它突然变得如此顺手？

答案可能出乎意料地“枯燥”：不是魔法，是更好的模型加上更“傻瓜”的架构。

本文基于 PromptLayer 创始人 Jared Zoneraich 的逆向工程与实战分享，尝试还原 Coding Agent 从“玩具”进化为“可用工具”的技术跃迁路径。

架构哲学：删繁就简

如果你在 2024 年开发过 Agent，你大概率画过那种复杂的 DAG（有向无环图）：

• “如果用户想退款，跳到节点 A；如果想查询，跳到节点 B……”
• 为了防止幻觉，我们堆了无数分类器（Classifiers）和路由（Routers）。

结果往往是一张维护噩梦般的蜘蛛网。

Claude Code（以及 Gemini Cli、CodeX 等新一代 CLI Coding Agent）的架构哲学可以用 Python 之禅概括：Simple is better than complex.

它们抛弃复杂 DAG，拥抱 Master While Loop。

用更细一点的伪代码解释这个 master loop：

# Claude Code 的核心逻辑伪代码
messages = [...]
while True:
    response = model.generate(messages)
if not response.tool_calls:
break
for tool in response.tool_calls:
        result = execute_tool(tool)
        messages.append(format_result(result))

就这么简单。Give it tools, and get out of the way.

这种架构的自信来源于模型能力的提升。现在的模型（如 Claude 4.5 Sonnet）已经足够聪明，能自己决定：

• 先 grep 一下代码
• 发现不对再 ls 一下目录
• 最后 edit 文件

它不需要你预设路径，它需要的是自由探索的空间。

来自 https://arcprize.org/leaderboard (2026.1)

工具箱揭秘：Bash 即正义（The Tools）

Claude Code 的工具箱极其精简，但每一个都切中要害。Jared 在逆向分析后发现，这套工具集本质上是在模拟一个人类高级工程师在终端里的行为。（注：这些工具可能随 Claude Code 版本变化而不同）

Bash：The Universal Adapter

如果只保留一个工具，那就是 Bash。

• 能跑脚本、能运行测试、能安装依赖、甚至能重启服务
• 是 Agent 与数字世界交互的通用接口
• 更关键的是：LLM 训练数据里有海量 Bash 语料，模型“天生会用”

这也是为什么很多团队在做工具设计时，会从 运维/DevOps/SRE 的既有生态中“拿来即用”，而不是重新造轮子。

Edit：Unified Diff

Claude Code 没有选择全量重写文件（Rewrite），而是选择 Diff。

• 省 Token：只输出修改的几行，上下文窗口压力骤减
• 速度快：输出更少意味着延迟更低
• 容错高：像批改作文划红线一样，基于上下文的 Diff 修改更容易命中，也更容易被人类 Review

Grep & Glob > RAG

还记得那些为了让 Agent 理解代码库而建立的复杂向量数据库（Vector DB）吗？Claude Code 的态度是：不需要。

它直接使用 grep 和 glob。这不仅是因为现在的 Context Window 更大，更因为它符合工程师的直觉：

接手一个新项目时，你不会先在脑子里建向量索引。你会先 ls 看目录结构，再 grep 关键字。

模拟人类的行为，往往就是最佳策略。

Sub-Agents（Tasks）

当任务太复杂、上下文快爆了怎么办？Claude Code 引入 Task 工具。

它可以启动一个子 Agent（Sub-agent），拥有独立上下文，去执行特定任务（例如“阅读完所有文档并总结 API 用法”），然后只把最终结果返回给主 Agent，从而有效缓解 Context 污染问题。

核心心法：相信模型，放弃微操

在传统软件工程中，我们习惯通过代码控制一切：if 条件 A 发生，就执行 B。但在构建 Coding Agent 时，这种“控制欲”往往是最大的敌人。

Jared 分享了一个很有启发的失败案例：

为了让 Agent 更好地操作 PromptLayer 的网页后台，他尝试进行“人工辅助”——给网页上的每个按钮加详细 Title 和标签，试图提前告诉 Agent “点击这里会发生什么”。

结果是：Agent 的表现反而变差了。

为什么？额外信息成了噪音，分散了模型注意力。模型原本可以通过“观察-尝试-纠错”的循环搞定任务，但人类的“硬编码微操”反而限制了模型的泛化能力。

Exploration > Hardcoding

Claude Code 的设计哲学是：当你有疑问时，相信模型（rely on the model）。

• 不要预设所有边缘情况：以前我们会写一堆正则解析输出；现在更常见做法是把错误直接丢回给模型：“你报错了，修好它。”

• 探索即纠错：模型不仅能写代码，还能读懂报错。Claude Code 之所以强，不在于一次写对，而在于它在 Master Loop 中具备 自我修复（Self-Correction） 的能力。

工程师的直觉是“把路铺好”，但 AI 时代的直觉更像是“给它地图，让它自己走”。

那些“不起眼”但很天才的细节

Constitution：CLAUDE.md

不需要复杂微调，也不需要向量库。Claude Code 依靠项目根目录下的 CLAUDE.md 来理解项目规范。

这本质上是 Prompt Engineering 的胜利：配置透明、可读，也可由用户（甚至 Agent 自己）随时修改。

System Prompt 解密：像老板一样下指令

Jared 分享了基于泄露信息的 Claude Code System Prompt 核心原则，很多都值得借鉴：

• Concise Output（极简输出）：除非用户要求细节，否则输出不要超过 4 行
• No "Here is..."（拒绝废话）：不要说“好的，这是您的代码...”，直接给代码
• Action over Text（行动至上）：能用 Tool 解决的，别用文字解释
• Style Match（风格一致）：严格匹配项目现有代码风格
• No Comments（拒绝注释）：除非用户要求，否则不要画蛇添足加注释
• Parallelism（并行执行）：鼓励并行运行命令、大规模搜索，并用 TodoWrite 跟踪进度

这些指令的目的只有一个：让 Agent 更像一个干练的 Senior Engineer，而不是一个啰嗦的 Chatbot。

Skills：可扩展的 “System Prompt”

随着任务变复杂，System Prompt 会越来越长，甚至超过 Context 限制。Claude Code 引入 Skills 机制。

可以把它理解为按需加载的“技能包”：Agent 会根据当前任务决定是否加载额外上下文或能力。

典型场景包括：

• Documentation Updates：加载特定文档写作风格指南
• Design Style Guide：写前端时加载 UI 设计规范
• Deep Research：加载深度搜索与总结能力
• DOCX/Excel Processing：加载办公文档处理技能（很多人没想到的用法）

To-Do Lists：提示词驱动的结构化

当你让 Claude Code 干活时，它往往会先列一个 To-Do List（是不是又很像人类工作方式？）。

有趣的是，这不是代码里写死的逻辑，而是 System Prompt 诱导出来的行为：

• 给用户一种“确定性”的心理安全感
• 支持断点续传：程序 Crash 了，把 To-Do List 重新喂给模型，它也能知道下一步要干嘛

Thinking Knobs

Think、Think Hard、Ultra Think。

这不是噱头，而是把 Inference-Time Compute（推理时计算） 变成可调参数：复杂重构就“多想一会儿”，简单 Bug fix 就直接干。

市场格局：没有全局最优解

在 Coding Agent 的战场上，没有唯一王者，只有不同流派（The "AI Therapist" Problem）：

• Claude Code：CLI 极简主义。简单直观，适合不想离开终端的开发者。
• Cursor：UI 速度流，强调极致响应。利用用户数据飞轮让体验更丝滑。
• OpenAI CodeX：内核硬核派（rust 实现），更关注底层沙箱安全（Kernel-level Sandboxing），适合企业级高安全场景。
• Sourcegraph Amp：Web 协作流，主打 Handoff（接力） 机制：一个 Agent 搞不定时，无缝切换到另一个 Context 或模型（无需用户选择），像接力赛一样把问题解决掉。

核心启示：Claude Code 教给我们的 5 条构建法则

Jared 总结了 Claude Code 成功的 5 个核心要素。对任何想构建 Agent 或 AI 驱动应用的开发者而言，这些更像当下的“硬规则”。

1）Trust in the model（相信模型）

不要试图用传统代码逻辑去“微操”模型。

• 反直觉：工程师总想把所有路铺好（比如给网页按钮加详细标签）。
• 新常识：模型的泛化与纠错能力往往强过硬编码规则。遇到不确定性时，给目标，让它自己探索，而不是给僵化步骤。

2）Simple design wins（简单致胜）

架构越简单越好。

• 拒绝复杂：不要搞几百节点 DAG，不要搞复杂路由网络。
• 拥抱简单：一个 while loop 加上强模型，很多时候能击败精心设计的复杂架构。

这类取舍，本质上就是 后端架构 里“可维护性优先”的延伸：复杂系统最大的成本，往往不是写出来，而是长期演进与排障。

3）Bash is all you need（Bash 足矣）

工具选择上，不要重新发明轮子。

• 通用接口：Bash 是这个星球上运行代码最通用的接口之一，也是 LLM 训练数据里最丰富的语料之一。
• 少即是多：与其开发 50 个专用 Tool（create_file、delete_file、git_commit ...），不如只给它一个 bash 工具。模型知道怎么用 touch、rm、git。

4）Context management matters（上下文管理是关键）

这是目前 Agent 最大的隐形杀手（The Boogeyman）。

• 瓶颈：上下文窗口被垃圾信息填满，模型表现会显著下降。
• 策略：把“上下文清洗”当一等公民。利用 Summarization（摘要）、Handoff（接力）或 Sub-agents（子智能体）机制，保持主线程清爽。

5）Different perspectives for different problems（不同问题，不同视角）

没有“万能药”。Coding Agent 领域不存在全局最优解（Global Maxima）。

• Claude Code：强在 CLI 交互与复杂 Git/环境管理，适合“不想离开终端”的场景。
• Cursor：强在 UI 速度与代码补全，适合“快速编写”的场景。
• CodeX：强在底层沙箱安全。
• 结论：别试图找一个能打败所有人的 Agent，而要构建最适合特定场景（User Persona）的 Agent。

小结

Claude Code 的出现，标志着 Coding Agent 进入 “实用主义” 时代：它不再是炫技玩具，而是通过做减法（Less RAG、Less DAG、Less Guardrails）回归软件工程本质。

未来，我们或许不再直接调用 LLM API，而是直接调用一个 Headless 的 run_agent() SDK，让它在后台默默修 Bug、写文档、提 PR。

最好的工具，就是当你感觉不到它存在的时候。

资料来源：Jared Zoneraich "How Claude Code Works" - https://www.youtube.com/watch?v=RFKCzGlAU6Q

如需继续交流 Coding Agent 的架构与落地经验，可到 云栈社区 相关板块参与讨论。