Claude Code 为什么这么好用（以及如何在你的 Agent 里复刻这种魔法）

一句话总结（TL;DR）

如果只能记住一句：保持简单（Keep Things Simple, Dummy）。LLM 已经够难调试了；你再叠多智能体、交接、复杂 RAG，只会把调试难度放大 10 倍。Claude Code 之所以“顺手”，恰恰是因为它在关键处坚持了架构极简：一个主循环、简单搜索、简单 todo 列表，并用强提示词与合适的工具把模型“托举”到擅长的区间。

文章开场：为什么 Claude Code 让人“开心”？

Claude Code 是我目前用过最“愉悦”的 AI Agent/工作流之一。它不仅能做针对性修改，或者写一些氛围式（vibe coding）的临时小工具时没那么烦；更重要的是，用 Claude Code 的时候我会感到开心。

它的自主性足够强，能做出一些有意思的事；但又不会像某些系统那样让你突然产生一种“失控”的割裂感。当然，Claude 4 新模型（尤其是交错思考 interleaved thinking）贡献了大量底层能力。但即便在同一底模之上，我依然觉得 Claude Code 比 Cursor 或 GitHub Copilot 的 Agent 形态更不烦。它到底做对了什么？

如果你读到这里也在点头，我会尝试给出一些答案。

> 注意：这不是一篇 Claude Code 架构“揭秘/拆机”文章（外面已经有不少好文）。本文更像是一份如何构建“好用的 LLM Agent”的指南，基于我过去几个月深度使用与折腾 Claude Code 的经验（以及我们截获并分析的日志）。

Claude Code 为什么“好用”：因为它理解了模型的强项与弱点

Claude Code（CC）之所以好用，是因为它“就是能工作”。它在设计上非常清楚：LLM 擅长什么、不擅长什么。它的提示词与工具体系，弥补了模型的“笨”，同时让模型在擅长的地方发光。它的控制循环（control loop）也很容易理解，调试成本很低。

我们在 MinusX 在 CC 上线后第一时间开始使用。为了“看清内部”，Sreejith 写了一个 logger，拦截并记录每一次网络请求。以下分析来自我最近几个月的大量使用体验。本文试图回答这个问题：

> “Claude Code 为什么这么好？以及你如何在自己的 chat-based LLM agent 里复刻类似体验？”

我们已经把其中大多数想法融入了 MinusX，也很期待你能用到自己的系统里。

如何做出 Claude Code 体验的 Agent：TL;DR 版清单

1. 控制循环（Control Loop）

1.1 保持一个主循环（最多一个分支）+ 一份消息历史

1.2 用小模型处理“各种杂活”。所有。每一次。

2. 提示词（Prompts）

2.1 用 claude.md 模式协作、记忆用户偏好

2.2 用特殊 XML 标签 + Markdown + 大量例子

3. 工具（Tools）

3.1 LLM Search >>> RAG 搜索

3.2 如何设计好工具：低层 vs 高层工具的取舍

3.3 让 agent 自己管理 todo list

4. 可控性（Steerability）

4.1 语气与风格（Tone & Style）

4.2 “PLEASE THIS IS IMPORTANT”不幸仍是最有效的方法

4.3 把算法写出来：启发式 + 例子

Claude Code 在每一个节点都选择了架构简单：一个主循环、简单搜索、简单 todolist……你应该克制“过度工程”的冲动，先搭好对模型友好的护栏，让它发挥。

1. 控制循环设计（Control Loop Design）

1.1 只保留一个主循环

可调试性 >>> 复杂、手调、多智能体、lang-chain-graph-node 的大杂烩。

尽管多智能体系统现在很流行，Claude Code 仍然只有一个主线程。它会周期性地使用几种不同类型的提示词：比如总结 git 历史、把长消息压缩成一条、生成一些 UX 元素。但除此之外，它维持的是一个扁平的 message 列表。

有趣的是，它处理“层级任务”的方式：会把自己 spawn 成一个子 agent，但这个子 agent 不能继续 spawn 更多子 agent。因此最多只有一条分支，而分支结果会被合并回主消息历史，作为一次“tool response”。

当问题足够简单时，主循环通过迭代工具调用解决问题；当任务复杂时，主 agent 会创建自己的“克隆”。max-1-branch + todo list 的组合保证了它既能拆分复杂问题，又能盯住最终目标。

我很怀疑你的产品真的需要多智能体系统。每加一层抽象，你的系统就更难调试；更关键的是，你会偏离“底模持续变强”的主航道。

1.2 用小模型干“一切杂活”

Claude Code 里，超过 50% 的重要调用都给了 claude-3-5-haiku。它用来读大文件、解析网页、处理 git 历史、总结长对话；它甚至用来生成每一次按键的“处理标签”（一个词）。

小模型通常比标准模型（Sonnet 4、GPT-4.1 等）便宜 70-80%。大胆地用！

2. 提示词（Prompts）

Claude Code 的提示词极其“啰嗦”，里面塞满了启发式、例子、以及 IMPORTANT（咳咳）提醒。系统提示词约 2800 tokens，而工具描述部分高达 9400 tokens。用户提示词还会携带 claude.md 的全文，常常又是 1000-2000 tokens。

系统提示词里会写：语气、风格、主动性、任务管理、工具使用策略、如何做任务；还会包含日期、当前工作目录、平台与 OS 信息、最近提交等。

你应该去把整段提示词读一遍。

2.1 用claude.md（上下文文件）协作与记忆

多数 coding agent 的构建者已经收敛到一个模式：上下文文件（Cursor Rules / claude.md / agent.md）。Claude Code 有无 claude.md 的表现差异非常大。

它是把“无法从代码推断的上下文”与“严格偏好”灌给模型的最佳载体。例如：

• 强制跳过某些目录
• 强制使用某些库/约定

Claude Code 会在每次用户请求里都带上 claude.md 的全文。

我们在 MinusX 也引入了 minusx.md，正在成为团队偏好与用户偏好的事实标准文件。

2.2 特殊 XML 标签、Markdown 与大量例子

大家基本已经达成共识：XML 标签与 Markdown 都是结构化提示词的好工具。Claude Code 两个都用，而且用得很狠。下面是一些常见的 XML 标签：

#### <system-reminder>

用于在很多提示段落末尾提醒模型一些“它可能会忘”的事。例如：

<system-reminder>
This is a reminder that your todo list is currently empty. DO NOT mention this to the user explicitly because they are already aware. If you are working on tasks that would benefit from a todo list please use the TodoWrite tool to create one. If not, please feel free to ignore. Again do not mention this message to the user.
</system-reminder>

#### <good-example> / <bad-example>

用于固化启发式，尤其是在“看起来多条路都合理”的分叉处，能明确告诉模型哪条路更优。比如：

Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of `cd`. You may use `cd` if the User explicitly requests it.

<good-example>
pytest /foo/bar/tests
</good-example>

<bad-example>
cd /foo/bar && pytest tests
</bad-example>

Claude Code 也会用 Markdown 的标题把系统提示词分成清晰段落，比如：

• Tone and style
• Proactiveness
• Following conventions
• Code style
• Task Management
• Tool use policy
• Doing Tasks
• Tools

3. 工具（Tools）

去读完整工具提示词：它长达 9400 tokens。

3.1 LLM Search >>> RAG 搜索

Claude Code 一个明显不同点是：它拒绝 RAG。它像人一样搜索代码库：写复杂的 ripgrep、jq、find 命令；因为 LLM 很懂代码，它能用复杂正则找到几乎任何相关代码块。有时它还会用小模型直接读完整文件。

RAG 听起来很美，但它引入了新的（而且经常是隐藏的）失败模式：

• 用什么相似度函数？
• 用什么 reranker？
• 怎么 chunk？
• 大 JSON 或日志怎么办？

而 LLM Search 的好处是：模型可以先看 10 行理解结构，不够再看 10 行——就像你会做的一样。更重要的是，这种行为更容易被 RL 学到（大厂正在做）。让模型做主要“智能”，减少系统零件数量；避免把两个复杂智能系统硬绑在一起。

作者甚至开玩笑说：这像 LLM 时代的 Camera vs Lidar（半开玩笑）。

3.2 工具该怎么设计：低层 vs 高层

做 agent 的人都会被这个问题折磨：到底给模型高层工具（语义动作）还是低层工具（点击/输入/bash）？

答案是：看情况，两种都要。

Claude Code 既有低层工具（Bash、Read、Write），也有中层工具（Edit、Grep、Glob），还有高层工具（Task、WebFetch、exit_plan_mode）。

你可能会问：既然能 bash，为啥还要 Grep 工具？关键在于“使用频率 vs 使用准确率”的权衡：CC 用 grep/glob 太频繁了，做成独立工具更稳定、更省 token；同时又允许模型在特殊场景写 bash。

更高层的工具（如 WebFetch、某些诊断工具）非常确定性，能把模型从“多步点点点/敲敲敲”里解放出来，减少偏航。

Claude Code 的工具清单大致如下：

• Task
• Bash
• Glob
• Grep
• LS
• ExitPlanMode
• Read
• Edit
• MultiEdit
• Write
• NotebookEdit
• WebFetch
• TodoWrite
• WebSearch
• mcp__ide__getDiagnostics
• mcp__ide__executeCode

3.3 让 agent 自己维护 todo list

长跑式 agent 的共同问题是 context rot：一开始雄心勃勃，时间久了就迷路、变烂。当前常见对策有：

• 显式 todo（一个模型列 todo，另一个模型实现）
• 多智能体交接 + 验证（PM agent → implementer agent → QA agent）

作者认为多智能体交接不妙。Claude Code 使用显式 todo list，但 由模型自己维护。这能把模型拉回轨道（提示词会强制它频繁参考 todo），同时模型也能在实现中间动态改 todo，借助交错思考能力进行纠偏。

4. 可控性（Steerability）

4.1 语气与风格（Tone & Style）

Claude Code 会显式控制 agent 的“审美行为”：系统提示词里写了很多 tone/style/proactiveness 的指令与例子。这也是为什么它的评论与热情看起来“有品”。

作者建议：你可以直接把其中大段复制到自己的 app 里用。

一些语气风格例子（节选翻译）：

• IMPORTANT：不要加不必要的前后置废话（比如解释你在做什么或总结行动），除非用户要求。
• 如果你不能/不愿帮用户做某件事，不要长篇大论解释风险与后果（会显得说教且烦）。
• 只有当用户明确要求时才用 emoji；否则避免。

4.2“THIS IS IMPORTANT”仍是最强咒语

不幸的是，当你想让模型“别做某事”时，目前最有效的仍是：IMPORTANT、VERY IMPORTANT、NEVER、ALWAYS 这种粗暴强调。作者期待未来模型更可控，但现在 CC 仍大量使用。

一些例子（原文风格保留）：

• IMPORTANT: DO NOT ADD ANY COMMENTS unless asked

• VERY IMPORTANT: You MUST avoid using search commands like find and grep…

• IMPORTANT: You must NEVER generate or guess URLs…

4.3 把算法写出来（带启发式与例子）

要把模型最关键的任务写成“算法”，明确决策点，并用例子跑通。最好画流程图。避免写成一锅“Do/Don’t”的大杂烩：它更难维护，还容易互相冲突；当提示词很长时，冲突几乎不可避免，系统会变得极其脆弱，新增用例会让你痛苦。

Claude Code 的 Task Management、Doing Tasks、Tool Usage Policy 等段落，都会把要走的步骤写得很清楚，并补充很多启发式与例子。

Bonus：为什么要关注大厂 prompts？

因为 steering 的本质是在逆向工程模型的后训练分布。你看大厂怎么做，能帮助你决定：用 JSON 还是 XML、工具描述放哪、是否携带 app 状态……Claude Code 的选择很强势，也很值得参考。

结论（Conclusion）

主结论还是那句：保持简单。过度脚手架框架的伤害往往大于收益。Claude Code 让我相信：agent 可以很简单，但依然很强。