> For the complete documentation index, see [llms.txt](https://shike.gitbook.io/ai-coding/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shike.gitbook.io/ai-coding/15-chapter.md).

# 第15章 高手改的是脚手架:skill 与子 Agent 的最佳实践

**本章导读**:用 AI 做产品,最贵的一项投入不是订阅费,而是踩坑之后才知道"原来要这样配"。本章是全书的收束,把前 14 章识别的工程模式归纳为四根可操作的杠杆——检索、上下文管理、工具设计、子 Agent 架构。读者读完本章应能做到两件事:看出自己当前配置短板在哪一根杠杆,知道按什么顺序改造。本章的核心论点是:**AI 编程的产出从来不是"模型能力"的纯函数,而是"模型 + 周围工程结构"的联合产物**。脚手架水平的差异,稳定超过模型代际的差异。

**本章关键词**:脚手架、skill、子 Agent、成本路由、四根杠杆

## 15.1 模型差距不等于产出差距

### 15.1.1 朋友的故事(经典引子)

去年冬天帮一位朋友检查他的 AI 编程配置。他刚把订阅从某海外厂商换成另一家,理由是"新模型跑分高了 3 分"。查看他的项目目录:没有总章程文件,没有规格文件,没有一条子 Agent 定义,所有对话挤在同一个会话里,上下文窗口长期处于溢出边缘。当时给出的判断是:**换模型换来的 3 分,一个缺乏工程约束的运行环境随时可以抵消掉 30 分**。

这一判断有研究支撑。2026 年 arXiv 上的一项研究(编号 2605.23950)专门分析过这个问题:基准测试的分数从来不是"模型能力"的纯函数,而是模型与其外部工程环境的联合产物\[^76^]。这层环境——提示词如何组装、上下文提供什么、工具如何定义、失败如何重试、任务是否拆给子 Agent——英文称为 harness,直译为"马具",本书统一称为"脚手架",即前十四章反复讨论的那层工程结构。

**现场还原**:朋友那次"换模型 3 分"的现场是这样的——他的项目目录里有 30 多个文件夹,每个文件夹下有 README.md,但内容早已过时;主对话里同时进行 3 个项目(主产品重构、运营工具、临时数据脚本),上下文长期处于溢出边缘;没有任何 skill 或 sub-agent 配置文件;凭据直接写在代码里(被 git push 过一次,后来删了但 git history 还在)。当时给他列了一份"脚手架健康度自检清单",勾完 20 条只勾上 5 条——其中检索 1 条、上下文 0 条、工具 2 条、子 Agent 2 条。差距最大的杠杆是上下文管理,具体表现是"每次开会前要花 10 分钟给 AI 复述项目背景",但背景信息本应写在 AGENTS.md 里供 AI 自动读取。改造顺序按 15.5.3 的方案:先补 AGENTS.md(把"项目是什么、用什么技术栈、当前进度、约束"写进文件),再拆子 Agent(把"探索"任务派给子 Agent),最后才考虑换模型。一个月后,同一份清单他勾上了 13 条,产出质量肉眼可见地稳定提升。**朋友后续没换模型,3 分的差距由 13 条脚手架补回**。

研究将同一批模型放入不同脚手架中反复测试,结论相当明确:**更换脚手架造成的分数波动,稳定超过更换一代模型**。厂商发布新模型时宣称的进步通常只有 2 到 4 分,而脚手架的更换可以带来几十个百分点的波动\[^76^]。

### 15.1.2 两组实验

第一组实验:其余条件完全相同,仅向系统中增加一个负责代码搜索的子 Agent WarpGrep,在 SWE-bench Pro(一个比 SWE-bench Verified 更难、更防污染的编程基准)上,两个模型的排名就发生了翻转——尽管后者在多数其他基准上更高\[^76^]。一个检索子 Agent 为所有模型带来 2.1 到 2.2 分的提升,论文评价其"相当于一次常规模型升级"。

第二组实验来自 Cursor 的内部研究:同一个模型,在一套脚手架下得分 46%,在另一套下得分 80%。差距来自四个变量——是将整个代码库灌入上下文还是只检索相关文件、是提交一个大任务还是拆分为带作用域的子任务、工具调用失败后是直接放弃还是纠正重试、中间结果是随手丢弃还是写入结构化工作记忆\[^77^]。

这四个变量没有一项属于模型问题。它们正是本章要收口的四根杠杆:检索、上下文管理、工具设计、子 Agent 架构。

**现场细节**:某次大型遗留系统的接入项目,工程师团队按论文里的"加一个检索子 Agent"思路试了三周。前两次试用的子 Agent 都配成了"全权限"——它们读完代码后顺手把发现的几个 bug 修了,改完直接 commit。结果是:主会话收到一份 8,000 字的"探索摘要",里面夹杂 4 个未被评审的代码改动。第三次,团队把子 Agent 改成只读权限,只准看不准动,返回内容也限定在 1,500 字以内。这次主会话的上下文保持干净,工程师的评审压力从 4 个意外 commit 降到 0,周报里的"返工工时"也直接归零。**教训**:子 Agent 不是"小型主 Agent",它是一份权限合同——不写清楚,代价由主会话和工程师一起付。

![SDD 规范层与执行习惯框架的分层](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-745b938e80a28b9e0f87e72c925e7127f25b38ea%2Fsec15_sdd_vs_superpowers.svg?alt=media)

## 15.2 规范层与执行习惯

### 15.2.1 两个常被混淆的项目

**现场还原**:某次内部技术分享会前,某 SaaS 团队的技术主管花了两个晚上把 OpenSpec 和 superpowers 都装了一遍,准备在内部分享时给出"团队该装哪个"的建议。第一晚,他跑了 OpenSpec 的 `/opsx:propose`,在某个中型模块上产出了一份 23 个 task 的清单;第二晚,他装了 superpowers,跑了一个 600 行的小型脚本改造,Agent 在第一步就被强制要求"先 brainstorm 需求"。第二天分享会上,工程师当场追问:"那我们到底装哪个?"他沉默了几秒,答:"两个都装——一个负责想清楚,一个负责把活干好。"会后,这位技术主管在团队 wiki 里加了一句话:**OpenSpec 与 superpowers 不是竞品,是时间线上的两段工序**。

OpenSpec 与 superpowers 这两个名字在 2026 年的中文技术圈经常被并排提起,"装 OpenSpec 还是 superpowers"是一个高频提问。这个问题的前提本身不成立:两者不是竞品,甚至不属于同一类工具。一个负责"动手之前先想清楚",一个负责"动手之后把活干好"。划清这条分界线,比记住任何一条命令都重要。

### 15.2.2 规范层:OpenSpec 的角色

规范驱动开发(SDD,Spec-Driven Development)的主张可以概括为一句话:规格说明取代代码成为"唯一事实来源",人与 AI 在编写任何代码之前,先就"要建什么"形成书面一致。需求只存在于聊天记录中,是 AI 编程中绝大多数返工的来源——这一判断在第 4 章、第 11 章分别强调过,SDD 是它的产业化形态。

该领域目前有三个主要项目:**Spec Kit** 是 GitHub 官方的 SDD 工具包,采用刚性阶段门的重流水线;**Kiro** 是 AWS 的 agentic IDE,把 SDD 固化为默认工作流;**OpenSpec** 出自 Fission-AI 团队,定位是"比 Spec Kit 轻、比 Kiro 开放"。

OpenSpec 的具体形态:每个变更对应一个文件夹,内含四份工件——proposal(为什么改)、specs(改成什么样)、design(怎么改)、tasks(分几步),由 `/opsx:propose`、`/opsx:apply`、`/opsx:archive` 等斜杠命令驱动,兼容 30 多种 AI 编程助手\[^68^]。

OpenSpec 对老项目的适配需要特别指出:不要求从项目第一天就订立宪法,改动哪个功能就为哪个功能补一份 spec——这正是第 11 章处理遗留系统时切身体会的方法。OpenSpec 的 README 中还有一条容易被忽略的提醒:开始实现前应先清空上下文窗口,等于把"上下文卫生"写进了使用须知。

### 15.2.3 执行习惯层:superpowers 的角色

superpowers 属于另一个物种。它的项目中有 14 个 Markdown 技能文件和一个"确保 Agent 真正使用它们"的加载器,没有一行可执行代码。装上之后的效果,相当于为 Agent 引入一位严格的工程主管:不允许直接写代码,先讨论需求(brainstorming);讨论完成后编写实现计划,细化到"没有判断力的初级工程师也能执行"的程度;随后启动子 Agent 分工开发;全程测试先行——若 Agent 先写了实现代码,技能的指令是**删除重写**,而非补写测试\[^50^]。作者称之为"方法论即代码":把资深工程师的工作习惯写成 Agent 必须遵守的强制流程。

superpowers 的自动触发机制措辞设计得相当强硬——"只要认为有哪怕 1% 的可能某个技能适用,就绝对必须调用它"。配合各技能的描述,Agent 会在该讨论时主动停下来讨论,该写测试时主动先写测试。这套机制目前已跨工具通用:Claude Code 官方插件市场收录了它,Codex、Cursor、Gemini CLI、Kimi Code 等 8 种以上工具均可安装\[^69^]。

**现场细节**:某创业团队的工程师在一个两周可交付的小项目上装了 superpowers,前三天体验良好——Agent 在每个改动前都先 brainstorm,先写测试,流程规范。第四天,他需要把一个变量名从 `user_id` 改成 `userId`(一个 3 行的 PR),Agent 仍然坚持要走"先 brainstorm→写测试→改代码→跑测试"的完整流程,首字延迟从平日的 0.8 秒涨到 3.2 秒,一轮交互耗时从 30 秒变成 4 分多钟。他当晚就在团队群里说:"这个流程对大改动是救命的,对小改动是累赘的。"一周后,团队内部约定:简单改动(单文件、< 50 行)直接走主 Agent,不进 superpowers 流程;复杂改动(跨文件、> 200 行)必须走 superpowers 流程,不许跳。**教训**:流程是给"复杂任务"配的护栏,简单任务上护栏是反向的税——把时间花在不产生价值的位置上。

![子 Agent Token 流](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-891a4e2acb56318dbc3175f78d35abc6a4a09fd8%2Fsec15_subagent_token_flow.svg?alt=media)

### 15.2.4 两者的互补关系

至此可以明确那条分界线。OpenSpec 的产出是**计划工件**:动工之前,把"要建什么"固化为文件,人与 AI 围绕文件达成一致。superpowers 的产出是**执行纪律**:动工之后,每一步按什么规范执行、如何验证、由谁评审。一个管"先想清楚",一个管"把活干好",在时间线上首尾相接,因此社区的主流用法是叠加而非二选一:由 OpenSpec 产出 proposal 和 tasks,由 superpowers 接管执行过程\[^71^]。

### 15.2.5 反对意见与剂量匹配

作为全书最后一章,反对意见必须给足篇幅,否则本章难免有带货之嫌。

Spec Kit 自己的 GitHub 讨论区挂着一条高赞批评(Discussion #1784):"SpecKit 制造了工作的幻觉(the illusion of work)"。其含义是 spec 阶段会产生大量"关于工作的工作":花两天写完宪法和规格文档,主观上感觉进展显著,实际上一行可运行的代码都没有\[^70^]。

superpowers 一侧的反噬更为具体:2026 年年中,中文社区出现一波卸载潮,用户的抱怨集中在三点——强制流程拖慢速度、Token 消耗高、14 个技能占用上下文反而使 Agent 分心、犯错增多。一位 Hacker News 用户的评论被反复引用:"装了 superpowers 之后 Claude 犯的错误比不装还多。"压力最终大到维护者亲自下场,将 14 个技能的总代码量从 3,150 行削减到 977 行,砍掉 69%,目的只有一个:少占上下文\[^72^]。

这些反对意见不是噪音,而是剂量说明书。结论只有一条:**纪律必须与场景匹配**。新项目、大团队、需严格审计的行业,适合 Spec Kit 的重流程;老项目、小团队、快速迭代,OpenSpec 加 superpowers 的轻量组合已经足够;探索性工作——验证一个想法、写一个一次性脚本、周末的个人项目——应当保持随意。流程的功能是偿还认知债;没有认知债的项目强行引入流程,付出的只是净开销。

**现场案例**:superpowers 维护者在 2026 年中的卸载潮期间,亲自下场做了一轮自检——把 14 个技能逐个审查,看哪些"真的常用",哪些"装了一年也没被调用过"。审查结果:14 个技能里 5 个是高频必用,4 个是偶发用,5 个长期闲置但占据了大量系统提示词的字数。维护者把这 5 个闲置技能直接砍掉,其余 9 个技能也精简了描述文本。最终数字:总代码量从 3,150 行降到 977 行,降幅 69%——砍掉的三分之二是"为了以防万一而存在"的复杂度。同月的中文社区反馈显示,精简后的版本在小项目上的接受度回升明显:用户反映"Agent 不再每次都问要不要 brainstorm 了"。**教训**:工具的上下文占用本身是一种税——每多占一行系统提示词,都是把用户的窗口预算从产出里挪走;工具维护者比任何用户都更清楚这一点。

![四杠杆框架](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-b5e9a967d8c5131e223d673123784c15d6d93b31%2Fsec15_four_levers.svg?alt=media)

## 15.3 子 Agent 设计模式

### 15.3.1 子 Agent 的本质

**现场还原**:某创业团队的工程师第一次为项目配子 Agent,目标很简单——把"读懂整个仓库"这件事从主会话剥离出去。他打开飞书,把 `.claude/agents/` 目录的 README 通读一遍,然后照着示例写了一份 `explorer.md`,YAML 头部配了"读取权限",正文写"你是一个代码探索 Agent,擅长快速理解陌生仓库的结构"。配完后跑了一个 600 行的中型模块做测试:子 Agent 在独立窗口里跑 3 个小时,遍历了 200 多个文件,最后返回一份 6,000 字摘要,包含完整目录树、核心模块依赖图、5 个潜在风险点。主会话收到这份摘要后,反而比之前更累——6,000 字的内容涌进来,把后续对话的窗口占用直接推到 80%。一周后,他做了两处修改:把摘要长度硬限到 1,500 字以内,把 description 从"擅长快速理解"改成"在主 Agent 询问陌生模块结构时调用,返回 1,000—1,500 字的目录树与依赖关系"。这次,主 Agent 一周内自动派了 8 次活,每次摘要都干净到位。**教训**:子 Agent 的 description 不是简介,它是主 Agent 决定"何时派活"的唯一线索——写不好,主 Agent 永远不调用;写得清晰,主 Agent 调用频率自然上来。

子 Agent(sub-agent)是由主 Agent 派生的、在独立上下文窗口中执行特定任务的二级 Agent,拥有自己的系统提示、工具权限与会话历史,任务结束后仅将结论返回主会话。

子 Agent 的核心价值是**隔离上下文**——把"探索"这种最消耗上下文的工作派给子 Agent。子 Agent 可以在独立窗口里消耗几万 token 遍历整个仓库,最后只向主会话返回 1,000 到 2,000 个 token 的蒸馏摘要\[^49^]。主会话的上下文因此保持清洁,代价是 Token 成本上升。

### 15.3.2 子 Agent 的骨架设计

以 Claude Code 为例,一个自定义子 Agent 是放在 `.claude/agents/` 目录(项目级)或 `~/.claude/agents/` 目录(用户级)下的一个 Markdown 文件:YAML 头部写元数据,正文写系统提示\[^73^]。

三个设计点需要单独说明。

**第一点:description 是委派触发器,不是简介**。主 Agent 决定"这项工作派给谁"时,读取的是各子 Agent 的 description 字段。检验标准很简单:读完这句话,能否说出它**什么时候**会被派活?说不出,就重写。

**第二点:权限最小化**。评审类子 Agent 只授予只读工具(Read、Grep、Glob),不给写权限——它发现的任何问题都只能报告,不能"顺手改掉"。这不是不信任 AI,而是故障隔离。

**第三点:上下文节俭**。并非每个子 Agent 都需要知晓项目的全部规矩,探索类的给它任务本身即可,省下的都是上下文预算。

**现场细节**:某项目负责人给团队的"代码审查"子 Agent 改了三版 description。第一版是"我是一个代码审查 Agent,擅长发现代码问题",主 Agent 在三周内一次也没派活给它——它不知道自己"什么时候该上场"。第二版改成"审查用户提交的代码改动",仍然没被调用,原因是"用户提交的代码改动"这种描述在主 Agent 视角里并不构成明确的触发场景。第三版改成"在用户提交 Pull Request 后调用,审查代码质量、风格一致性与潜在 bug,返回不超过 800 字的结构化报告",主 Agent 一周内调用了 14 次——每一次 PR 提交后,主 Agent 都能精准地找到这个子 Agent。这位负责人的总结是:**description 的好坏,有一个很简单的检验——读完这句话,能否说出它"什么时候"会被派活?说不出,就重写**。**教训**:这正是上面"第一点"里那条原则的现场版本——description 是委派触发器,不是 Agent 简介;检验标准只有一条,即"读完能否说出何时被派活",说不出的都该重写。

### 15.3.3 7 倍 Token 代价

代价必须说明,这是多数教程回避的部分:**重度使用子 Agent 的工作流,Token 消耗约为单线程会话的 7 倍**\[^360^]。原理不难理解——每个子 Agent 都要维护一份自己的上下文,三份上下文就是三份输入 Token 账单。

子 Agent 购买的不是省钱,而是主会话上下文的纯净度与并行度。三种值得使用的情形:并行探索(5 个子 Agent 同时研究 5 个主题,时间从 1 个下午压缩到 40 分钟)、隔离高噪声任务(把"会污染上下文"的工作派给子 Agent)、收敛权限(把危险操作圈进权限最小的子 Agent)。三种纯属浪费的情形:任务本身两分钟就能查完、任务依赖主会话的完整对话历史才能理解、为"显得高级"而拆分子 Agent。

**现场案例**:某中型项目(8 人技术团队)的技术主管,2026 年 9 月的某一天打开月度 API 账单——本月消耗 240 美元,是上月 35 美元的近 7 倍。他翻了一下团队配置记录,发现当月新上了 6 个子 Agent,覆盖代码审查、文档生成、依赖分析等场景。他没急着关闭子 Agent,而是当周请工程师做了一次"哪些子 Agent 的产出被实际使用"的复盘。复盘结果:6 个子 Agent 中,3 个的产出每周都用得上(代码审查、文档生成、依赖分析),2 个每周只调用 1—2 次(占比不到 5%),1 个"全权限探索 Agent"在配置后从未被主 Agent 调用过——它功能强,但 description 写得太宽,主 Agent 找不到触发场景。技术主管最终动作:关闭从未调用的 1 个,关闭调用率低于 5% 的 2 个,保留 3 个高频的。月底账单回落至 95 美元,降幅 60%——既没有全盘否定子 Agent 架构,也没有为成本牺牲质量。**教训**:子 Agent 买的不是省钱,是上下文纯净度与并行度;7 倍 token 是它的标价,不是它的价值。价签本身不该决定买不买,要看买回来后是否真的"用得上"。

## 15.4 成本路由

### 15.4.1 原则:规划用旗舰,执行向下分发

**现场还原**:某 SaaS 团队的工程师在 2026 年 8 月做了一次成本复盘。团队每月调用 AI 约 5 万次,平均 0.04 美元/次,月度账单 2,000 美元——占总运营成本的 12%,仅次于服务器费用。他没急着换模型,而是按"哪些任务必须用旗舰、哪些可以下沉"的思路把调用拆了三层:规划层(架构设计、复杂方案、跨模块重构)用旗舰;执行层(单文件改动、单元测试、文档生成)用中档;批量层(日志分析、批量改写、模板填充)用 Haiku / DeepSeek V4 Flash 之类的便宜档。改造后一个月,他把账单打印出来贴在团队墙上:平均 0.006 美元/次,月度总成本降到 300 美元,降幅 85%——而团队对"AI 写出的代码质量"的评分没变。**原则**:最贵的模型只做规划与编排,执行层的工作逐级下放给便宜模型\[^78^]。

原则可以概括为一句话:**最贵的模型只做规划与编排,执行层的工作逐级下放给便宜模型**。重度用户按此分层可节省 40% 到 85%\[^78^]。

节省的机理不是"便宜模型够用",而是任务的不对称性:一个重构任务中,真正需要旗舰判断力的可能只有 10% 的 Token(定方案、裁决争议),其余 90% 是按方案执行的工作。全程使用旗舰,相当于让架构师去搬砖。

### 15.4.2 按任务选模型速查

2026 年真正用得好的实践者,没有一个只忠于单一模型\[^368^]。按任务类型整理的路由表:

| 任务类型       | 路由到哪                                  | 选它的理由                |
| ---------- | ------------------------------------- | -------------------- |
| 规划、编排、复杂重构 | Claude 旗舰档                            | 长链路推理和复杂系统提示的遵循度最稳   |
| 日常执行、代码生成  | Claude 中档                             | 旗舰八成的能力、一半的价格,执行层默认款 |
| 超大代码库通读    | 1M 上下文模型(Gemini 系等)                   | 整个中型仓库一次性进窗口,省掉检索脚手架 |
| 结构化输出      | GPT 系                                 | JSON 等结构化输出的格式稳定性好   |
| 高频后台任务     | Haiku / DeepSeek V4 Flash / GLM-Flash | 量大单价敏感,错误代价低         |

### 15.4.3 三个成本锚点

仅掌握路由原则不够,落地需要会算账。三个锚点均注明出处。

**锚点一:每拿下一分的成本**。Haiku 每拿下一个 SWE-bench Pro 分的 output 成本约 $0.13,是全行业最便宜的路径;Opus 档约 $0.48\[^363^]。

**锚点二:订阅与按量付费的平衡点**。Claude Code 的 API 消耗平均约 $13/开发者/活跃日,90% 的用户低于 $30/活跃日\[^78^]。按此价格倒推,每月 API 用量在 370 万 Token 以内,按量付费比 Pro 订阅划算;超过这个量级,订阅制更优。

**锚点三:新一代模型的纪律是"删提示词"**。Opus 5 发布时,官方迁移指南中有一条反直觉的建议:删掉提示词中"自我验证""完成后汇报进度"类指令,因为模型已内建这些行为,保留只会导致重复验证、浪费 Token;它还会更主动地委派子 Agent,使用者要做的是显式设置上限\[^1^]\[^4^]。

**现场细节**:某公司技术主管在 Opus 5 上线两周后,按官方迁移指南做了一次"提示词瘦身"。他原来的项目级系统提示词有 1,200 字,包含"完成后请汇报进度""请自我验证输出""如不确定请主动委派子 Agent"等 7 条指令。删完之后剩下 480 字,只剩 3 条硬约束(权限边界、输出格式、禁用工具)。第一周,他和团队都紧张:Agent 还会主动汇报进度吗?会不会忘记自我验证?两周运行下来,数据显示:(1) "完成汇报"从每任务 1—2 次变成 0 次,主会话反而更安静——原来模型自身会判断何时该汇报;(2) "自我验证"行为保留率 100%,无需提示词约束;(3) 子 Agent 委派率下降 30%——旧提示词里"主动委派"的字样反而鼓励了过度委派。月底他总结了一句话:**新一代模型的纪律不是"加约束",是"删约束"**——模型越聪明,提示词越短,留出窗口给真正的任务。

## 15.5 四根杠杆:全书方法论收口

### 15.5.1 四根杠杆及其证据

回到 15.1 那篇论文给出的框架。决定 AI 编程产出的,不是模型的单点能力,而是四根杠杆的组合\[^76^]\[^77^]。

**检索**:喂给模型的信息是否恰好相关。第 14 章的三件套、第 11 章的遗留系统探索,都是在调节这根杠杆。

**上下文管理**:有限的窗口里放什么、不放什么、何时清空。这根杠杆有一条清晰的文献主线:Anthropic 官方将上下文工程定义为"找到尽可能小的高信号 Token 集合,使期望结果概率最大化"\[^74^]——要点不是塞得多,而是塞得准。

**工具设计**:给 Agent 的工具接口如何定义,失败时如何重试,权限如何收口。第 3 章的凭据管理、第 5 章的脱敏规则、第 6 章的最小权限,都属于这根杠杆。

**子 Agent 架构**:任务如何拆分、噪声如何隔离、结果如何蒸馏。15.3 节整节都在讨论它。

四根杠杆中,检索与上下文管理决定"模型看到什么",工具设计与子 Agent 架构决定"模型能做什么、怎么做"。前两根管输入质量,后两根管执行结构。

### 15.5.2 四杠杆 × 全书章节映射

| 章  | 内容         | 主杠杆        | 杠杆在章内的具体形态            |
| -- | ---------- | ---------- | --------------------- |
| 1  | 格局:选工作流宿主  | —          | 四象限选型框架               |
| 2  | 复刻网站       | 检索         | 站点侦察+证据级快照            |
| 3  | 复刻 SaaS    | 工具设计       | 凭据不落 LLM、白名单、接管节点     |
| 4  | Demo 对齐需求  | 上下文管理      | Demo 工件入库成为契约         |
| 5  | 业务数据分析     | 工具设计       | 脱敏规则隔离脏数据             |
| 6  | 该框架接飞书     | 子 Agent 架构 | 多智能体路由、常驻与隔离会话分工      |
| 7  | 行业调研       | 检索         | 三件套调用顺序;并行研究子 Agent   |
| 8  | 自我蒸馏       | 上下文管理      | 知识库/skill/prompt 三层资产 |
| 9  | 自我进化       | 子 Agent 架构 | 反馈回路与经验写回机制           |
| 10 | 7 天 MVP 收款 | 子 Agent 架构 | 时间盒内并行开发              |
| 11 | 复活屎山       | 检索         | 大代码库探索策略              |
| 12 | 竞品监控       | 四杠杆综合      | 前章资产的组合复用             |
| 13 | 四类问题与药方    | 问题线收束      | 四类病的诊断书               |
| 14 | 爬虫与数据获取    | 检索         | 检索杠杆的深化专题             |
| 15 | 本章         | 收口         | 四杠杆的证据、写法、成本与自检       |

阅读这张表的正确方式是按列读。主杠杆一列:以检索为主杠杆的有四章(2、7、11、14),以上下文管理为主的两章(4、8),以工具设计为主的两章(3、5),以子 Agent 架构为主的三章(6、9、10)。检索多出一章,是因为第 14 章整个就是它的深化专题。案例篇越往后写,越确信"喂对信息"是一切的前提。

### 15.5.3 落地路径:20 条自检清单

知道四根杠杆与真正能用,中间差一个落地动作。建议的路径分三步。

**第一步:脚手架健康度自检**。下面这份清单共 20 条,四根杠杆各 5 条,建议每月给自己的项目过一次。能勾选 15 条以上,说明脚手架状况超过我见过的九成配置;勾不到 10 条,应当先暂停研究换模型。

**【检索】**

* 新会话开工前,先告诉 Agent 去哪里找
* 项目里有机器可读的导航(总章程文件/目录说明/索引)
* 外部数据按三件套分工:常识问内置知识、时事走搜索、私有数据走爬虫
* 检索回来的内容抽查过真实性
* 大库探索派给了探索子 Agent

**【上下文管理】**

* 总章程文件在 500 行以内
* 每个任务开工前清上下文
* 长任务有检查点/进度文件
* 跨会话的经验有地方沉淀
* 窗口占用常年飘红时,知道该删什么

**【工具设计】**

* 危险操作(写库/发消息/付钱)有白名单或人工批准门
* 凭据不进对话、不进提示词
* 工具失败时有明确报错和重试策略
* 每个自动化流程先手动跑通过一遍
* 插件按需加载,不用的及时卸载

**【子 Agent 架构】**

* 每个子 Agent 职责单一,description 里写清了"什么时候用它"
* 评审/审计类子 Agent 只有读权限
* 子 Agent 返回的是蒸馏摘要(千字级)
* 并行派子 Agent 的活,事先评估过 7 倍 Token 代价值不值
* 拆子 Agent 是因为有隔离/并行/权限需求,不是因为"显得高级"

**第二步:定位短板杠杆**。自检完成后看哪一栏勾得最少——那就是当前产出质量的天花板。检索栏空得最多的人,症状是"AI 老答非所问";上下文栏空得多的,症状是"聊着聊着就忘了前面的规矩";工具栏空的,症状是"不敢让 AI 碰真实系统";子 Agent 栏空的,症状是"主会话又乱又贵"。四种症状对应第 13 章的四类问题,病根都在杠杆上。

**第三步:按顺序改造**。顺序即 15.2 至 15.4 的顺序:先补规范层与执行习惯(想清楚、干好活),再上子 Agent(拆活),最后调成本路由(省钱)。不宜倒过来——路由优化省的是钱,规范层救的是方向,方向错了,省钱没有意义。这就是"先把脚手架修好再换模型"的完整含义:它不是一句口号,而是一个带顺序的决策框架——自检定位短板、按序改造,改造后仍有差距,那时才轮到换模型。

**现场案例**:某项目工程师第一次写 AGENTS.md,目标是把"项目所有规矩都讲清楚",写完发现文档膨胀到 2,000 行——项目结构、命名规范、commit message 格式、PR 流程、测试要求、部署步骤、紧急联系、版本号规则……全部塞进一个文件。上线一周,他从 AI 行为里发现两个反常:第一,AI 提交的 3 个 PR 都违反了"commit message 必须包含 issue 编号"的规矩;第二,AI 在回复里完全没引用"项目禁止用 fetch 写后端"这条约束。他打开会话窗口,看 AI 实际加载的 AGENTS.md——主会话只读了前 600 行,后 1,400 行被截断未读。这印证了 20 条自检里那条"总章程文件在 500 行以内"——超出这个长度,后段内容就成摆设。整改方式:把 AGENTS.md 砍到 480 行,只留项目身份、技术栈、命名规范、commit/PR 流程;具体的部署步骤、紧急联系、版本号规则拆到子文档(如 `docs/deploy.md`),按需在 AGENTS.md 里加链接引用。整改后第二周,AI 在 12 个 PR 里严格遵守了 commit 格式,后段文档的"加载率"也由 0% 升到 100%(按需加载,用到时再读)。**教训**:总章程文件的字数不是越多越好——多到主会话读不完,后面的内容就自动降级为"装饰性存在",不产生任何约束力。

## 15.6 全书收束

读到这里,有一个事实需要回到读者的桌面上:人会系统性地高估 AI 提效——而这个偏差,本身就是本书要展开回答的问题。METR 找了一批资深开源维护者做随机对照试验:使用 AI 工具的一组,完成任务实际慢了 19%,但他们事前预测自己会快 24%,事后还坚持认为快了 20%——感知与实测之间有 39 个百分点的偏差\[^61^]。该实验后来经历了自我修正(2026 年初的后续研究因"开发者不愿回到无 AI 条件"而无法复现,METR 官方承认真实加速效果可能已经转正),但其方法论教训保留了下来:**人对 AI 提效的感知,系统性地偏离真实**。

整本书其实就是这句话的展开。表面上的瓶颈是模型不够聪明,于是换模型;实际的瓶颈是脚手架漏风——需求只存在于聊天记录中(第 4 章)、凭据缺乏保护(第 3 章)、上下文持续腐烂(第 7 章)、经验从不沉淀(第 8 章)、评审形同虚设(第 13 章)。表面上换脚手架是折腾,论文给出的数据是它的影响超过换一代模型\[^76^]。而子 Agent、规格文件、成本路由这些曾经属于"高级玩家的小技巧",2026 年的工具生态已经把它们做成了默认配置——superpowers 的 25 万星与 OpenSpec 进入 30 多种工具,说明整个行业都在朝这个方向收口。

模型还会换代,这个月的旗舰半年后就是旧型号;套餐还会改价,在我写这本书的三个月里,GLM 的 Coding Plan 涨了两次。会过时的东西不值得惋惜。不会过时的,是围绕四根杠杆的自检与改造能力:知道去哪里看分数的口径、知道上下文该放什么、知道什么工作该派给子 Agent、知道什么任务该用什么价位的模型。本书交付的从来不是一份可以照做的说明书——说明书六个月就会过期——而是一套判断框架。

框架至此交付完毕。它能在多大程度上转化为产出,取决于读者在自己的项目里如何使用它。

### 15.7.1 本章思考题

1. 15.1.1 的"换模型 3 分,脚手架 30 分":你团队最近一次"换模型"的决策,有没有先做"脚手架健康度自检"?如果先做自检,会改变决策吗?
2. 15.2.5 的"剂量匹配":你团队当前的项目,适合 OpenSpec 加 superpowers 的轻量组合,还是 Spec Kit 的重流程?为什么?
3. 15.3.2 的子 Agent description:你的子 Agent description 是"Agent 简介"还是"委派触发器"?读完能否说出"什么时候会被派活"?
4. 15.3.3 的 7 倍 Token 代价:你的项目子 Agent 调用率是多少?如果低于 5%,这个子 Agent 是否值得保留?
5. 15.4.1 的成本路由:你的 AI 调用是"全程旗舰"还是按"规划/执行/批量"分层?分层后月度账单降幅是多少?

### 15.7.2 本章延伸阅读

1. **\[文章] arXiv 2605.23950 harness 研究(2026-05-07 v1)** — 换 harness 波动 > 模型代际差;WarpGrep 翻转排名;四杠杆框架的一手文献 | 第 15 章
2. **\[文章] mindstudio agent harness 分析** — harness > 模型实践佐证;同一模型在两套脚手架下得分 46% vs 80% | 第 15 章
3. **\[工具文档] Fission-AI/OpenSpec GitHub README** — SDD 轻量规范层、四件套工件、/opsx 命令、30+ 助手兼容 | 第 15 章
4. **\[工具文档] obra/superpowers GitHub README** — 14 个 Markdown skill 强制 TDD/调试/评审工作流;2026-07 超 25 万 stars | 第 15 章
5. **\[文章] 掘金 Superpowers 卸载潮(2026-07-15)** — 强制流程过重反面声音;skill 代码砍 69% 的维护者亲历 | 第 15 章

## 15.7 完整提示词:脚手架四杠杆的自检与改造

以下提示词用于"诊断 AI 编程项目的脚手架短板,给出可执行的改造方案"。它把"四根杠杆(检索、上下文管理、工具设计、子 Agent 架构)"的诊断与改造落到 prompt 里,且每步改造都按"先补规范层与执行习惯 → 再上子 Agent → 最后调成本路由"的顺序。

```
你是 AI 编程脚手架顾问,擅长诊断一个 AI 编程项目的配置短板,并给出可执行的改造方案。接下来的所有工作,你必须严格按"四根杠杆(检索、上下文管理、工具设计、子 Agent 架构)"的诊断框架推进,且每步改造都按"先规范后工具、先执行后路由"的顺序。

【你的工作方式】
- 阶段一(20 条自检):让我对照清单,逐条勾选"通过/不通过/不适用",统计每根杠杆的勾选率
- 阶段二(短板定位):勾选率最低的杠杆,就是当前的"产出质量天花板"
- 阶段三(诊断报告):针对短板杠杆,给出具体症状、根因、改造方案
- 阶段四(改造顺序):严格按 15.5.3 的顺序——先规范层,再子 Agent,最后成本路由

【四根杠杆】
1. 检索(Retrieval):喂给模型的信息是否恰好相关。典型症状:AI 老答非所问。
2. 上下文管理(Context Management):有限的窗口里放什么、不放什么、何时清空。典型症状:聊着聊着就忘了前面的规矩。
3. 工具设计(Tool Design):给 Agent 的工具接口如何定义、失败如何重试、权限如何收口。典型症状:不敢让 AI 碰真实系统。
4. 子 Agent 架构(Subagent Architecture):任务如何拆分、噪声如何隔离、结果如何蒸馏。典型症状:主会话又乱又贵。

【20 条自检清单】
[检索]
- 新会话开工前,先告诉 Agent 去哪里找
- 项目里有机器可读的导航(总章程文件 / 目录说明 / 索引)
- 外部数据按三件套分工:常识问内置知识、时事走搜索、私有数据走爬虫
- 检索回来的内容抽查过真实性
- 大库探索派给了探索子 Agent

[上下文管理]
- 总章程文件在 500 行以内
- 每个任务开工前清上下文
- 长任务有检查点/进度文件
- 跨会话的经验有地方沉淀
- 窗口占用常年飘红时,知道该删什么

[工具设计]
- 危险操作(写库/发消息/付钱)有白名单或人工批准门
- 凭据不进对话、不进提示词
- 工具失败时有明确报错和重试策略
- 每个自动化流程先手动跑通过一遍
- 插件按需加载,不用的及时卸载

[子 Agent 架构]
- 每个子 Agent 职责单一,description 里写清了"什么时候用它"
- 评审/审计类子 Agent 只有读权限
- 子 Agent 返回的是蒸馏摘要(千字级)
- 并行派子 Agent 的活,事先评估过 7 倍 Token 代价值不值
- 拆子 Agent 是因为有隔离/并行/权限需求,不是因为"显得高级"

【输出格式】
# 脚手架诊断与改造报告

## 一、20 条自检结果
[4 个 5 列表格,每条标注状态]

## 二、短板定位
- [杠杆 1]:[勾选率 X/5] - 短板 / 合格
- [杠杆 2]:[勾选率 X/5] - 短板 / 合格
- [杠杆 3]:[勾选率 X/5] - 短板 / 合格
- [杠杆 4]:[勾选率 X/5] - 短板 / 合格

## 三、短板杠杆的症状与根因
[针对短板杠杆,给出 3—5 个具体症状,每个症状配 1 句话根因]

## 四、改造方案(按 ROI 排序)
### 立即可执行(本周内)
1. [步骤] - [谁做] - [预计耗时] - [验收标准]
2. ...

### 短期(本月内)
...

## 五、改造顺序(必须遵守)
1. [规范层]OpenSpec / Spec Kit → 想清楚
2. [执行层]superpowers → 把活干好
3. [子 Agent]skill + 子 Agent → 拆活
4. [成本路由]按任务选模型 → 省钱

任何一步都不能跳过或颠倒。规范层救方向,路由救钱——方向错了,省钱无意义。

【输入格式】
提供——
- 项目简介(项目类型、规模、当前痛点)
- 20 条自检结果(可由我帮你逐条勾)
- 当前使用的工具(模型名、软件名、MCP 列表)

【输出格式】
Markdown 报告,按上述结构。

【边界约束】
- 不跳过任何自检项,每条都要明确"通过/不通过/不适用"
- 不把"短板"包装成"合格"
- 不推荐"为了优化而优化"——杠杆合格就不动
- 改造方案按 ROI 排序,不按"理想"排序
- 改造顺序严格按"规范→执行→子 Agent→路由",不允许颠倒
- 不在没看实际配置的情况下,凭"理论"给诊断

【遇到这些情况,先暂停并通知我】
- 20 条自检结果存在明显矛盾(比如某条既勾"通过"又勾"不通过")
- 多个杠杆的勾选率都低于 2/5
- 改造方案涉及重大架构变更(如全面更换模型)
- 你的改造建议可能有几种合理方案
- 改造方案无法在用户接受的成本内完成

【30 天持续优化纪律】
- 每周一:跑一次 20 条自检,记录分数
- 每月 1 日:对比上月数据,看趋势
- 每季度:评估是否需要更换模型或重新选型
- 不追求"立即满分",追求"持续改善"
- 任何重大调整(更换模型、重新选型)必须有"为什么"的明确理由

【反模式警告】
- 跳过规范层直接调路由——方向错了,省钱无意义
- 全部杠杆同时优化——一次只动一根,避免混乱
- 追求脚手架完美而停下手头工作——脚手架服务于产出,不服务于完美
- 完全相信新工具宣传——新工具上线 3—6 个月再评估,先观察
- 频繁切换模型——稳定性优先,频繁切换成本极高
```

## 15.8 收束(补充)

脚手架的判断框架,核心是四个字:**自己明白**。模型换什么、套餐选什么、子 Agent 怎么拆,这些都不是"哪个最好"的问题,是"哪个最适合我"的问题。明白自己卡在哪根杠杆,明白自己的预算和时间约束,明白自己的风险承受度,明白这些之后,工具只是工具,选什么都可以,改起来也容易。框架至此收束。