结论先行:Claude Code 这类 coding agent 的架构并不复杂——一个 agentic loop,加一组克制而强大的文件/终端工具,再加权限门、上下文压缩和 hook 体系。真正值得学的是它的取舍:工具数量少而粒度粗、文件系统当唯一共享状态、一切操作可审计。自己搭内部 coding agent 时,照着这几个原则走能少踩很多坑。

核心架构:一个循环加五个组件

剥掉界面,coding agent 的骨架是:

  1. Agentic loop:模型输出工具调用就执行、结果回填、再请求,循环到模型给出文本为止。没有预先编排的 DAG,走向由模型每一步决定。
  2. 核心工具集:读文件、写文件、执行命令、搜索。Claude Code 的工具集长期保持在小几十个以内,文件操作(Read/Edit/Write)、命令执行(Bash)、检索(Glob/Grep)、子 Agent(Task)。
  3. 权限层:只读操作直接放行,写操作和命令执行按规则放行或请求确认,规则可以用 allow/deny 模式声明。
  4. 上下文管理:接近窗口上限时做压缩(compaction),把历史轮次摘要后重开。
  5. 指令层:CLAUDE.md / AGENTS.md 注入项目级约定,hook 在工具调用前后插入确定性逻辑。

这五个组件的边界要分清:循环是骨架,工具是手脚,权限是刹车,上下文管理是油箱,指令层是交规。自研平台最常见的失衡是把精力全花在加功能上,而刹车和油箱还是毛坯——功能再多,跑不长也跑不安全。

工具设计:少而粗,描述为王

最容易犯的错误是造一堆细粒度工具(readFile、readLine、listDir、statFile……),让模型自己拼装。Claude Code 的做法相反:一个 Read 直接返回整个文件加行号,一个 Edit 用精确字符串替换。工具越粗,模型一次调用完成的事情越多,循环轮数越少,出错机会越少。

{
  "name": "Edit",
  "description": "Performs exact string replacement in a file. You must Read the file before editing. old_string must match exactly, including whitespace, and must be unique in the file.",
  "input_schema": {
    "type": "object",
    "properties": {
      "file_path": { "type": "string" },
      "old_string": { "type": "string" },
      "new_string": { "type": "string" }
    },
    "required": ["file_path", "old_string", "new_string"]
  }
}

注意 description 里写的是给模型看的使用契约(先读后改、必须唯一匹配)——工具描述的质量直接决定调用准确率,这比换模型划算得多。对比一下错误写法与正确写法:

{
  "name": "edit_file",
  "description": "编辑文件",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "路径" },
      "content": { "type": "string", "description": "内容" }
    }
  }
}

错误版本的问题是双重的:描述没有说清匹配规则和前置条件,模型会凭想象调用(不先 Read 就改、在多处出现相同片段时改错位置);content 全量覆盖的语义让小改动也要传整个文件,输出 token 翻倍还容易把没看到的部分覆盖掉。正确版本则把使用契约写进描述,参数按"最小改动"设计。

工具数量本身也是一个成本项:每个工具的 schema 都常驻每一轮请求的上下文底座,三十个工具和十个工具,每一轮的固定开销差着几千 token。自研平台加工具前应该过一道门槛——这个能力现有工具能不能组合出来?只有"高频 + 现有组合做不到 + 语义确实独立"才值得新增。对照 Claude Code 的工具清单可以看到,它的每个工具都满足这三条,多年演进下来数量反而收敛。

文件系统是唯一的共享状态

任务清单、代码、测试结果、中间产物,全都落在文件系统里,而不是藏在 harness 的内存结构中。这样做有三个好处:模型随时可以重读最新状态(磁盘是唯一事实源);上下文被压缩后,关键状态仍可从磁盘找回;人类可以在任何时刻介入,直接改文件再让 Agent 继续。

反面教材是把任务状态藏在 harness 的数据库里:模型每轮要靠 harness 特殊注入才能"想起"自己该干什么,压缩后注入内容一丢,行为立刻漂移;人类想介入也找不到入口,只能整个会话重来。文件系统还是天然的集成点——测试报告是文件,hook 产物是文件,子 Agent 的交接材料也是文件,所有组件围绕同一个事实源工作,不需要发明额外的同步协议。断点续跑也顺势解决:会话中断后新起一轮,让模型先读任务清单文件和最近的改动记录,它能在一两轮内重建工作现场——重建的成本是重读几个文件,而内存方案里丢掉的状态是找不回来的。

三条可以直接抄的原则

第一,权限默认最小化。 读操作免确认,写和执行分级控制,deny 规则挡住危险路径。宁可多确认一次,不可漏挡一次。

第二,把验证闭环交给命令而不是模型。 编译过没过、测试绿不绿,用真实退出码回答,不采信模型的转述。让 harness 在循环里跑 ./gradlew test 并把真实结果喂回去:

# 错误做法:问模型"测试过了吗",采信它的文字回答
# 模型可能幻觉出"全部通过",错误一路传递到提交

# 正确做法:harness 真跑命令,用退出码说话
./gradlew test --tests "com.foo.OrderServiceTest"
echo "exit_code=$?"        # 非零就是没过,结果原文回填进上下文

第三,扩展点靠约定而非代码。 hook、AGENTS.md、MCP 三个机制覆盖了绝大多数定制需求:确定性校验用 hook,项目知识用 AGENTS.md,外部系统能力用 MCP。团队内部的 coding agent 平台,把这三个扩展点做扎实,比堆功能更重要。

常见误区对照

误区典型表现后果正确做法
细粒度工具集readFile/readLine/statFile 一大堆轮数暴涨、选错工具少而粗,按任务设计
硬编码流程把多轮步骤写成固定状态机测试挂了要先修,流水线反而脆弱相信循环,管好上下文与权限
采信模型转述“模型说测试过了”幻觉传递到提交命令真实执行,退出码回填
状态藏内存任务进度只存在 harness 里压缩后漂移,人类无法介入状态落盘,磁盘为唯一事实源
与模型强耦合工具层直接绑定某家私有参数换模型全量返工适配层隔离,沉淀层保持中立

自己造轮子时还有一点值得强调:保持 harness 对模型中立。工具 schema、上下文装配这些层与具体模型解耦,模型升级或切换供应商时,harness 侧只需要改适配层,团队沉淀的 hook、说明书、权限规则全部原样保留——这才是平台资产和模型资产的正确边界。

实战场景

一个团队从零搭内部 coding agent 的典型过程:第一版追求"全能",一口气注册了四十多个工具,上线后单任务平均轮数居高不下,模型经常在相似工具之间反复横跳(定性观察)。第二版按"少而粗"收缩到十来个工具,把文件编辑统一成一个精确替换工具并在描述里写明"先读后改",轮数立刻下来;又把验证闭环改成 harness 真跑构建命令,上线首月抓住的"模型幻觉测试通过"就不止一次。真正让团队省下最多时间的反而是最不起眼的两件事:AGENTS.md 里一行"构建命令是什么",以及 hook 里一条"mapper 目录禁改"。三个月后换了一代新模型,工具层和权限规则原封不动直接继承——当初把扩展点做在对的位置,此刻兑现成了迁移成本接近零。

检查清单

  • 工具集保持少而粗,单个工具完成一个完整动作,描述写清使用契约
  • 工具 schema、上下文装配与具体模型解耦,换模型只动适配层
  • 编译、测试等验证由 harness 真实执行,以退出码为准,不采信模型转述
  • 任务清单、中间产物、测试结果落盘,磁盘是唯一事实源
  • 权限层就位:只读放行、写与执行分级、危险路径 deny
  • hook、AGENTS.md、MCP 三个扩展点可用,定制不走硬编码
  • 没有预先编排的 DAG,流程走向交给模型在循环中决定