---
title: "claude code core developer lessons action space design"
source_url: https://x.com/trq212/status/2027463795355095314
ingested: 2026-04-28
sha256: 2b0150eb45dda1eeaf8e504a176e14bb107022ca8b6d58ea2f241a58bfca5742
type: raw
created: 2026-05-10
updated: 2026-05-10
tags: [twitter]
---
# Lessons from Building Claude Code: Seeing like an Agent
**作者**：Thariq（Claude Code 团队）| **来源**：X (@trq212) | **时间**：2026年2月28日
---
## 一、Action Space 才是你的产品
很多人做 Agent，第一反应是堆能力：接网页、接数据库、接浏览器、接10个模型，再加一堆花哨工具。
真正上线后你会发现，最先出问题的往往是两件事：
- 模型不知道什么时候该用哪个工具，在50个入口前犹豫、乱试、误用。
- 你不知道它为什么做出这个动作，出了问题很难回放和修复。
**动作空间（Action Space）**：模型"能做什么"的全集。你给它的每个工具，都像给了一个新器官，同时也给了一个新的风险面。
**工具三档模型**：
| 工具类型 | 典型例子 | 你得到什么 | 你付出什么 |
|----------|----------|------------|------------|
| 低风险、低能力 | 只读检索、只做总结 | 失败可控 | 上限有限 |
| 中风险、可组合 | 结构化提问、任务管理 | 带宽提升、协作更稳 | 需要把契约做清楚 |
| 高风险、高上限 | bash、代码执行、网络访问 | 真正"能干活" | 权限、状态、副作用、可恢复性全要管 |
---
## 二、让模型"会问问题"——AskUserQuestion 为什么是甜蜜点
**纯文本提问的问题不在"问不出来"，而在"带宽太低"**。用户要读一长串问题，逐条回答；模型还可能追问、改问法、补充条件，回合数爆炸。
Claude Code 团队三次尝试路径：
1. **尝试1：把"问题"塞进 ExitTool** → 职责冲突：模型困惑"到底是在制定计划还是在询问计划"
2. **尝试2：强行规定 Markdown 输出格式** → 脆弱：模型多写一句解释、漏一个选项、换一个标点，解析就失败
3. **尝试3：专用 AskUserQuestion 工具** → 成功：职责单一、输出结构固定、用户从"写一段话"变成"选一个"
**落地建议：把"提问"当接口设计**
1. 问题要短：每次只问一个决策点，别把整份PRD塞进去。
2. 选项要互斥：能枚举就枚举，别让用户"同时选A又选B"。
3. 默认值要有：用户没选时怎么走，别让模型猜。
4. 保留自由输入口：当枚举覆盖不了时，允许补充，但放到单独字段。
---
## 三、模型变强后，Todo 从"拐杖"变成了"枷锁"
Claude Code 早期用 Todo 列表防跑偏：开局写todo，做完一条勾一条。模型能力较弱时很有效。
模型变强后副作用出现：
- 模型开始把todo当"不可违背的剧本"，不敢调整路线
- 系统提醒反而强化了"死守列表"的倾向
- 多Agent（subagents）并行时，共享todo变成协作瓶颈——谁改？怎么合并？怎么表达依赖？
**Todos → Tasks 的核心升级**：从"个人记事本"升级成"协作协议"
- Todos更像线性列表，适合单线程执行+防跑偏
- Tasks更像有依赖的图（DAG），适合多线程协作+状态同步
**Tasks必须具备的能力**：
- 依赖怎么表达（Task C需要Task A和B完成）
- 状态怎么同步（谁做了什么、做到哪了）
- 产物怎么归档（每个Task的输出落到哪里）
- 失败怎么回滚（某个Task失败，影响范围是什么）
**核心教训**：工具会过期。模型升级、工作方式变化后，你要敢于回头把工具重做一遍。
---
## 四、让 Agent 自己"找上下文"——渐进式披露比塞文档更稳
**RAG的问题**：
- 需要索引和维护，环境一复杂就脆弱
- 上下文是"你喂给它的"，不是"它自己找到的"
**演进路径**：RAG → Grep（让它自己搜）→ Skills（渐进式披露）
**渐进式披露（Progressive Disclosure）**：别把一切都塞进System Prompt，而是给模型一个入口，让它按需读文件，一层层展开。就像人查资料——先看目录，再看章节，再看细节，没有人先把整本书背完再开始做题。
**知识分层方案（3层）**：
- **第0层：索引（200-500字）**——只回答"有哪些能力、入口在哪、什么时候用谁"
- **第1层：模式卡片（500-1500字）**——用checklist、示例、负例写清楚"怎么做、怎么验收"（必须可执行）
- **第2层：完整手册（2000字以上）**——只在需要时加载，避免上下文长期腐化
**递归读取的克制原则**：盯着两个指标——搜索深度（翻了几层才到目标）和回报率（每多读一层答案质量提升有多大）。当"深度在增加，但答案没有更好"时就该收手了。
---
## 五、工具设计的迭代循环（7步）
1. **从真实输出里找摩擦**：别猜，拿日志看模型卡在哪、错在哪。
2. **先选最小杠杆**：能用prompt解决就别上工具；能用一个工具解决就别堆10个。
3. **把接口做窄**：一个工具只干一件事，职责清晰。
4. **把结构交给机器**：关键数据别藏在自然语言里，给schema、给枚举、给默认值。
5. **把失败做成可恢复**：允许重试、允许撤销、允许回滚，让模型错了也能爬回来。
6. **把产物落盘可验收**：别只在聊天里完成，输出要能被人审查。
7. **定期复盘工具是否过期**：模型变强后，拐杖可能变枷锁，该换就换。
**决策表：什么时候该"加工具"？**
| 你遇到的问题 | 优先解法 | 为什么 |
|-------------|---------|--------|
| 措辞不稳、格式偶尔跑偏 | 改prompt+少量示例 | 成本低，不改变Action Space |
| 需要稳定结构化输出（可解析、可渲染、可验证） | 上工具（schema+枚举+默认值） | 让结构交给机器，减少靠猜 |
| 知识量大但不常用，偶尔才需要细节 | 文件分层+渐进式披露（Skills） | 不常驻上下文，避免长期腐化 |
| 需要专门查资料、查文档、查代码，且查法有套路 | 子Agent（带搜索策略） | 扩能力但不增加主Agent工具数 |
---
## 六、反模式清单
- 让一个工具同时负责计划、提问、执行：最容易把模型绕晕，也最难debug。
- 依赖模型严格输出某种文本格式：越通用越脆弱，到生产环境最容易掉链子。
- 把todo当"剧本"而不是"状态"：模型会变得不敢调整计划，协作更难。
- 把整套文档塞进system prompt：短期有效，长期腐化，成本越跑越高。
- 只追能力上限，不管可恢复性：能做更多事，不代表你能放心让它做。
---
## 七、落地清单：做 Agent Harness 建议先补齐这12条
1. 给模型一个"结构化提问"的入口：AskUserQuestion或同类能力，优先级很高。
2. 把提问做成UI契约：问题短、选项互斥、有默认值、可自由补充。
3. 用Tasks替代静态Todos：尤其当你有subagents或并行执行时。
4. 任务必须有依赖与状态：能表达DAG，能同步更新，能关联产物。
5. 给模型能自建上下文的搜索工具：代码库内Grep往往比RAG更稳。
6. 用文件组织知识并分层：索引层、模式层、手册层，按需加载。
7. 坚持渐进式披露：不常用的信息不要常驻上下文。
8. 工具数量要克制：每多一个工具，就是多一个分叉和多一个失败点。
9. 重要动作要可回放：日志、trace、工具参数都要能复现。
10. 优先优化可恢复性：便宜的重试、明确的前置条件、可观察的状态。
11. 把交付物写成文件：让结果从聊天气泡里出来，能被review。
12. 每次模型升级都要复盘工具：旧工具可能限制新能力，别恋旧。
---
## 来源
- Thariq（@trq212）《Lessons from Building Claude Code: Seeing like an Agent》：https://x.com/trq212/status/2027463795355095314
- 微信公众号「架构师（JiaGouX）」转载版本：https://mp.weixin.qq.com/s/sATqUEgKPRB5w4kuQvqCUg