Code Agent设计思考

2026/03/15

背景

本文通过对Claude Code 的agent架构进行分析，进行Code Agent架构的思考。

（由于篇幅原因，本文只针对agent架构层面进行分析，TUI、Sandbox，Context Management，Accelerate architecture，Cost Control等不包含在内）

LangGraph分析

在分析Claude Code前，先简单了解一下LangGraph，并说明为什么LangGraph不适合做Code Agent的场景，下面是一个LangGraph例程

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langchain_openai import ChatOpenAI

# 1. Define State
class State(TypedDict):
    messages: Annotated[list, add_messages]

# 2. Initialize LLM
llm = ChatOpenAI(model="gpt-4o-mini", api_key="your-api-key")

# 3. Define Node
def chatbot(state: State):
    return {"messages": [llm.invoke(state["messages"])]}

# 4. Build Graph
graph_builder = StateGraph(State)
graph_builder.add_node("chatbot", chatbot)
graph_builder.add_edge(START, "chatbot")
graph_builder.add_edge("chatbot", END)

graph = graph_builder.compile()

# 5. Run
result = graph.invoke({"messages": [("user", "Hello! How are you?")]})
print(result["messages"][-1].content)

LangGraph是基于图的设计，需要先定义好拓扑结构，简单来说就是需要将agent的固定流程给写出来。但是Code Agent使用LangGraph架构会带来以下缺点

1. 流程不可预测

用 LangGraph 做 code agent，你需要画出这样的图：开始 → 读文件？→ 改文件？→ 运行测试？→ 修 bug？→ …

但问题是：

你不知道要读哪些文件（可能 1 个，可能 50 个）
你不知道要改哪些文件
你不知道测试会不会失败
你不知道会遇到什么错误

结果： 你无法画出一个固定的图。

2：分支爆炸

假设你硬要用 LangGraph 实现”修复 bug”：

graph.add_conditional_edges(
    "read_file",
    lambda state: "edit" if needs_edit(state) else "read_more",
    {
        "edit": "edit_node",
        "read_more": "read_node",
        "run_test": "test_node",
        # ... 你需要枚举所有可能的路径
    }
)

但实际情况是：

可能需要读 A → 读 B → 改 C → 测试 → 失败 → 读 D → 改 E → 测试 → 成功
也可能是：读 A → 改 A → 测试 → 成功
还可能是：读 A → 读 B → 读 C → 发现不是 bug → 结束

你需要写无数个条件判断，而这些判断本质上就是 AI 自己能做的决策。

LangGraph 适合什么？

LangGraph 适合流程已知、步骤固定的场景：

客服机器人：意图识别 → 查询数据库 → 生成回复
数据处理管道：提取 → 转换 → 加载
多 Agent 协作：Supervisor 分配任务给 3 个固定的 Worker

这些场景的拓扑结构是确定的，可以画出图。

Claude Code Agent分析

Claude code虽然并没有开源，但在Claude Code官方文档中的How the agent loop works，已经将agent架构和tool，subAgent等讲得很清楚了。

Agent Loop

agent-loop-diagram

（Agent Loop Of Claude Code，来自Claude Code官方文档）

区别于LangGraph的静态拓扑结构，Claude Code使用Agent Loop根据场景自行动态生成拓扑结构。Agent接受需求后，会自动调用工具，将工具结果返回给agent，agent再决下一步是继续调用工具还是响应给用户，以此循环，这就解决了LangGraph中静态拓扑结构无法穷举的问题。当然Agent Loop非常依靠模型自身的的能力，要求这个模型能根据需求准确产生拓扑结构。

Tool Design

agent-loop-diagram

（Tools Of Claude Code，来自Claude Code官方文档）

对于Claude Code，tool的设计原则符合UNIX POSIX设计规范中的

“Do one thing and do it well” — Unix Philosophy

工具设计原子化，小而精，agent自行进行组合实现简单/复杂需求。复杂的工具设计，不仅带来了繁重的工具开发成本，同时也带了无法进行需求场景穷举的问题。

SubAgents

当涉及一个任务需要多个Agent完成的场景，Claude Code使用单Main Agent负责代码输出和调度 + 多个SubAgent的上下级协作方式，这种组合方式相比多个平级主agent的方式更可控，之前我们公司就做过一个实验，在多个平级主agent架构，agents之间会出现一直交流协商，但是不开始干活的情况。

总结

可以看出，Claude Code的agent架构依靠目前模型自身能力，使得不需要复杂的架构设计，就能完成Code Agent这个场景，甚至能完成比以前旧模型+复杂架构下无法完成的需求场景。目前agent开发需要做好的是，尽量不引入复杂设计，并且做好Sandbox，Context Management，Accelerate architecture，Cost Control等设计。不过也不排除未来这些能力，模型厂商也会进行内化，现在AI发展确实很快，持续学习和进步是关键。