1. 核心问题与总框架
2. 四个关键案例
3. 抽象原则与落地启发
4. 原文与参考

Lessons from Building Claude Code: Seeing like an Agent

一句话：agent harness 的关键不是“工具越多越强”，而是把 action space 设计成与模型真实能力形状匹配。

文章在回答什么

  • agent 的工具到底该怎么设计？
  • 只给一个通用工具够不够？
  • 给 50 个专用工具会不会更强？
  • 什么能力该做成 tool，什么该交给 search、skills、subagent？

数学题比喻

面对难题时，你想要的工具取决于自己的能力：

  • 纸：通用但效率低
  • 计算器：更强，但要会操作
  • 电脑：最强，但前提是会写代码并执行

工具必须贴合模型会不会用、愿不愿用、能不能稳定用。

核心命题

设计 agent 时，要学会 see like an agent：

  • 观察模型输出
  • 看它在哪里卡住
  • 试验不同工具形状
  • 根据模型能力升级不断重估

这不是一次性的 API 设计，而是持续的能力适配。

Lessons from Building Claude Code Seeing like an Agent
Lessons from Building Claude Code Seeing like an Agent
x.com
Open x.com in new tab

读完后的总总结

这篇文章不是在教你“发明更多工具”，而是在教你：

  1. 先观察模型的真实工作方式
  2. 只在 plain text / 通用原语不稳定时才加 tool
  3. 模型变强后，要敢于把旧脚手架撤掉
  4. 能靠 progressive disclosure、search、subagent 解决的能力，不要轻易做成常驻工具

本质上，action space 设计是模型能力观察 + 交互设计 + 工程权衡的混合体。

案例 1: AskUserQuestion

目标：降低 Claude 向用户提问的摩擦，提高 elicitation 带宽。

三次尝试

  1. 把问题塞进 ExitPlanTool

    • 实现简单
    • 但“给计划”和“问问题”语义打架

  2. 改 markdown 输出格式

    • 最通用
    • 但输出不稳定，容易漂移

  3. 单独做 AskUserQuestion tool

    • 结构受控
    • 能弹 UI、阻塞 loop
    • Claude 也更愿意调用

结论：当 plain text 无法稳定产出结构时，才值得上 tool。

案例 2: Tasks vs Todos

早期为了让模型不跑偏，Claude Code 用 TodoWrite + 每 5 turn 提醒。

但模型变强后：

  • 提醒开始像束缚
  • Claude 以为 todo 不能改
  • subagent 也很难共用一个 todo list

后来改成 Task Tool：

  • 有依赖关系
  • 能跨 subagent 共享更新
  • 可以修改和删除

结论：模型升级以后，旧工具可能会从脚手架变成枷锁。

案例 3: Search Interface

最早用 RAG / 向量库给 Claude 找上下文。

后来发现更重要的是：

  • 不只是“给它上下文”
  • 而是让它 自己建上下文

于是加入 Grep 等搜索工具，让 Claude 自己搜代码库。

再往前一步，Agent Skills 把 progressive disclosure 形式化：

  • 先暴露入口
  • 再按需读 skill 文件
  • 再递归发现更多上下文

结论：强模型更应该获得“找上下文的能力”，而不是被动喂上下文。

案例 4: Claude Code Guide Subagent

问题：Claude 不够懂“Claude Code 自己怎么用”。

直觉方案：

  • 把所有文档塞进 system prompt
  • 或者继续加一个新工具

实际方案：

  • 先给 docs 入口
  • 发现 Claude 会为了找答案把太多文档拉进上下文
  • 再做 Claude Code Guide subagent，让它专门查文档、压缩结果、只返回答案

结论：扩展 action space 不一定靠加 tool，很多时候靠 progressive disclosure + 专用 subagent 更优。

从四个案例抽象出的原则

  1. 工具要匹配模型能力，而不是匹配工程师想象中的完美接口
  2. 少量高杠杆原语通常优于很多专用工具
  3. 新工具加入门槛要高，因为每多一个工具，模型就多一个决策分支
  4. plain text、prompt、文档入口能稳定解决的问题，不要急着工具化
  5. 好工具的标准之一是：模型会主动、稳定、正确调用它
  6. 模型升级后，旧工具必须重新评估
  7. action space 设计没有固定公式，它更像实验科学

如果你自己做 agent harness

推荐默认顺序：

  • 先给最小原语：执行、搜索、读写、问用户、协作
  • 再观察真实失败模式：格式漂移？上下文找错？协作混乱？
  • 只有失败反复出现时才加新 tool
  • 能靠 skills、docs、guide subagent 解决的问题，不优先加 tool
  • 每换一个模型版本，都重测一遍 action space

目标不是“工具最多”，而是让模型以最低认知负担拿到最合适的能力。

最终方法论

See like an agent = 持续观察模型如何真正工作，再用最小但合适的 action space 去顺着它的能力形状设计。