AI Agent on 鬼哥的空间

Grok Bot 多 Agent 团队怎么搭：先把交接协议写清楚

Tue, 08 Sep 2026 00:00:00 +0000

很多人第一次组 Grok Bot 团队，会先创建五个名字很专业的 Bot，然后把它们拉进群聊。真正开始干活，研究员说“有几条没核实”，写作者只收到结论，检查员又不知道该和哪份来源比。五位同事都在场，工作却丢在了门缝里。

darkzodchi 最近发布的 Grok Bot 多 Agent 配置课程，抓住了这个系统最值得先解决的问题：团队通常不是坏在单个 Bot 的输出，而是坏在 Bot 之间的交接。

这篇文章把原帖的 coordinator、handoff、conflict 和 stop rules 整理成一套可粘贴的最小配置。目标很具体：先让 Researcher → Writer → Checker 三个 Bot 跑通一条可检查的链，再决定要不要增加第四个角色。

证据说明：本文依据原帖和 xAI 官方文档整理，核对日期为 2026-09-08。文中的配置模板是工程化改写，不是原帖逐字翻译，也没有在你的 Grok Bot 账号中实际运行；请按文末验收步骤测试后再用于真实工作。

先确认 Grok Bot 的协作边界

根据 xAI 的 Message and collaborate 文档，Grok Bot 群聊可以加入 2–6 个 Bots。Bots 能在群里发言，也能异步把工作交给另一个 Bot；官方建议每个阶段指定一个 owner，过多并行交接会带来重复工作和噪声。

还有两个容易漏掉的产品边界：

Bot-to-group 的交接消息目前是纯文本；如果下一个 Bot 必须检查图片，应直接把图片发给它。
所有 Bots 虽然有各自的角色和对话，但同一用户下共享一台持久云电脑、文件、浏览器会话与登录状态。官方 FAQ 明确提醒：不要把不同 Bot 当成安全边界。

这两点会直接影响架构。交接格式必须在纯文本里自洽；权限控制则不能靠“这个 Bot 名字叫 Researcher，所以它碰不到发布账号”这种美好愿望。

最小团队只需要三个专业角色

原帖建议先用三个 Bot、两次交接证明流程。这个规模刚好覆盖生产内容最基本的证据链：

Bot	唯一职责	不负责什么	可检查的输出
Researcher	搜集来源，区分已验证与未验证信息	不写最终文章	来源清单与研究 HANDOFF
Writer	只根据已验证材料形成草稿	不补猜测，不发布	草稿与写作 HANDOFF
Checker	将草稿中的关键断言逐条对照来源	不偷偷重写争议结论	PASS、修改项或 BLOCKED

协调员不算第四位专家。它是一扇门：接收目标、分派任务、跟踪状态、处理冲突，最后只返回一个结果。

第一步：把协调员写成“唯一入口”

xAI 官方建议用操作性语言定义 Bot：职责、工具和来源、工作方式、审批边界都应该写清楚；长期规则放在 Bot description，单次任务要求放在消息里。下面这份协调员描述遵循这个区分。

这是可粘贴的起点，但未经本文实测：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


You are the coordinator and the only front door to this Bot team.

Your responsibilities:
1. Restate the objective, final deliverable, and completion criteria.
2. Assign one owner to each stage.
3. Dispatch one bounded job at a time with the required input,
 expected output, source of truth, and approval boundary.
4. Do not perform specialist work yourself.
5. Accept specialist results only through the HANDOFF format.
6. Track task status as queued, working, blocked, or complete.
7. Surface conflicts and missing evidence; never resolve them silently.
8. Return one final result after the Checker reports PASS.

Never send, publish, delete, purchase, or change production systems
without explicit human approval.

先在私聊里问协调员一句：

1

Who is working on what right now? Return owner, task, status, and blocker.

如果它不能给出明确状态，先别建群。一个连工单在哪都说不清的协调员，进入群聊后通常只会获得更多可以说不清的工单。

第二步：固定 HANDOFF，不传工作过程

原帖反复强调两个字段：unverified 和 skipped。原因很实际——缺口如果没有名字，到了下游就很容易长得像事实。

我在这个原则上补齐了任务 ID、证据、产物、风险和下一步，形成下面的交接合同：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


HANDOFF
task_id: <stable identifier>
from: <current Bot>
to: <next Bot>
status: COMPLETE | BLOCKED | NEEDS_REVIEW

result:
- <the result, not the transcript of how it was produced>

verified:
- <claim or output> | source: <link or artifact>

unverified:
- <claim that could not be confirmed> | reason: <why>

skipped:
- <requested item not completed> | reason: <why>

artifacts:
- <file, link, image, or document>

risks:
- <known ambiguity, side effect, or dependency>

next_action:
- <one owner and one concrete next step>

approval_required:
- NONE | <exact human decision or action>
END HANDOFF

再把下面的接收规则加入每个专业 Bot 的 description：

1
2
3
4
5
6
7
8
9


End every task with the exact HANDOFF block.
Pass results, not a transcript of your work.

Before starting, reject an incoming handoff that is missing:
task_id, verified, unverified, skipped, artifacts, or next_action.

Use verified items as facts only when their sources are accessible.
Treat unverified items as investigation tasks, never as facts.
Do not fill a missing field by guessing.

这份格式故意有一点啰嗦。交接合同的目标不是让每条消息更漂亮，而是让接收方在十秒内判断：什么完成了，什么没有，证据在哪里，轮到谁做什么。

第三步：先跑一对一链路

不要一开始就把三个 Bot 放进群里。先让协调员按顺序完成两次可见交接：

1
2
3
4
5


Coordinator
 → Researcher
 → Writer
 → Checker
 → Coordinator

测试任务要用真实材料，但不要带发布权限。例如：根据三份指定来源，写一篇 800 字产品更新说明，不发送给任何外部人员。

每个阶段都有一个验收点：

Researcher 的 verified 条目都附有可访问来源；无法确认的内容进入 unverified。
Writer 的草稿没有把 unverified 或 skipped 内容写成事实。
Checker 能把草稿中的关键断言映射回 Researcher 的来源，并将不匹配项列为修改或阻塞。
Coordinator 只在 Checker 返回 PASS 后组装最终结果。

原帖用一个示意计算解释为什么交接次数重要：如果每次交接只能保留 85% 的有效上下文，五个 Bot 之间四次交接后，完整保留率约为 0.85^4 ≈ 52%。作者明确说明这不是 xAI 的可靠性数据，只是展示误差如何沿链路累积。

重点不是 85% 这个假设，而是每增加一次 handoff，就多一个丢失来源、忽略限制或误读状态的机会。增加 Bot 前，先确认新角色提供了独立价值，而不是把同一件事切得更碎。

第四步：链路稳定后再建群

一对一链路跑通后，再创建包含三个专业 Bot 和协调员的群聊。官方当前允许每个群选择 2–6 个 Bots，并建议在 kickoff 中写明共同结果和下一阶段 owner。

可以从这条消息开始：

1
2
3
4
5
6
7
8
9


Objective: Produce one source-checked launch brief.

@Researcher collect and verify the source material.
@Writer draft only from Researcher's verified list.
@Checker compare every consequential claim with the sources.
@Coordinator own routing, status, conflicts, and the final package.

Use the HANDOFF contract for every transfer.
Do not publish, send, or modify external systems.

群聊解决的是“让交接可见”，并不会自动修复坏的交接。成功标准应该是一条消息进入、一个完整结果出来，而且回看群聊时能找到每次移交的 owner、输入、输出和状态。

如果需要传图片，别只在群里留一句“见附件”。官方文档说明 Bot-to-group handoff 目前是纯文本；让发送方在 HANDOFF 的 artifacts 里写清图片用途，并把文件直接发给需要检查的 Bot。

第五步：提前写好冲突规则

两个 Bot 都认真工作，仍然可能得出不同结论。协调员如果悄悄挑一个看起来顺眼的答案，冲突就消失在界面上，却会留在最终产物里。

下面是一组适合研究—写作—校验链的冲突规则：

1
2
3
4
5
6
7
8
9


CONFLICT RULES
1. Current primary sources outrank memory, summaries, and prior drafts.
2. A sourced claim outranks an unsourced claim.
3. The Checker may block release but may not invent a replacement fact.
4. If two accessible primary sources conflict, preserve both positions,
 record dates and scope, and ask the human to decide when it changes
 the final conclusion.
5. The Coordinator must surface unresolved conflicts in the final result.
6. Human approval always outranks autonomous completion for external actions.

第三条尤其重要。Checker 的工作是证明“这句话站不住”，不一定负责现场写出另一句更好听的话。检查员既当裁判又替参赛者补答案，审计链很快会变成团建活动。

第六步：没有停止规则，团队会循环或假装完成

Stop rules 需要同时覆盖两类失败：系统不断把同一个任务踢来踢去，以及证据不足时提前宣布完成。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


STOP RULES
Stop the current chain and return BLOCKED when:
1. The same task_id returns to the same Bot without new evidence.
2. A required source, artifact, permission, or account is unavailable.
3. Two sources or Bots conflict on a claim that changes the deliverable.
4. The next step requires sending, publishing, deleting, purchasing,
 or changing a production system without explicit approval.
5. A tool or action fails twice with no new diagnostic evidence.
6. The Checker cannot map a consequential claim to a verified source.

When stopping, report:
- completed work
- exact blocker and evidence
- actions already attempted
- the smallest human decision needed to continue

Never replace BLOCKED with a plausible guess or a partial result labeled complete.

上线前故意制造一次阻塞：给 Researcher 一个无法访问的来源，或者让 Writer 收到缺失 unverified 字段的 HANDOFF。观察团队是否真的停下来，并准确说出缺什么。

没有见过团队正确停止，就不能说明停止规则有效。刹车测试这件事，汽车行业早就想明白了，Agent 团队也不必重新发明一次撞墙。

多个 Bot 不是多个权限边界

原帖提醒“组织架构不等于安全隔离”，官方文档给出了更明确的技术原因：同一用户的 Grok Bots 共享一台持久云电脑，也共享其中的文件、浏览器会话和登录状态。xAI 的团队与企业文档建议把电脑中的登录和文件视为该用户所有 Bots 都可能访问。

因此，权限设计至少要做到：

在每个 Bot description 中写明持久的审批边界。
发送、发布、删除、购买和生产变更保留人工批准。
只登录任务需要的账号，优先使用作用域更小的服务账号。
不再需要的账号及时退出，敏感临时文件在任务结束后清理。
真正需要独立电脑和凭据集的工作负载，使用独立用户，而不是再创建一个 Bot。

官方也说明，Bot 默认只能使用用户或团队授予的账号和插件，敏感操作可进入审批。但 description 是行为规则，不是操作系统级沙箱。把“禁止发布”写进提示词很有必要，同时仍要让发布动作经过真实审批。

常见故障，以及先改哪里

症状	常见原因	先改什么
Writer 把未核实信息写成事实	HANDOFF 没有 `unverified`，或接收方忽略它	强制字段完整性检查；Checker 逐条对源
Coordinator 自己开始写稿	职责包含“帮忙完成”，没有禁止专业工作	将协调员限制为分派、状态、冲突和汇总
群里出现两个版本，没有人决定	同一输出被并行派给多个 owner	每阶段只设一个 owner；并行只用于独立输入
Bot 反复互相转交	没有 task ID、停止条件或重试上限	同一 task 回到同一 Bot 时要求新证据，否则 BLOCKED
人直接私聊 Specialist 后，主链状态错乱	Coordinator 不知道任务被改过	中途变更统一发给 Coordinator，或明确重开任务
以为不同 Bot 看不到彼此的登录	把角色边界误当成计算隔离	按共享电脑设计账号、文件和审批策略

一次完整验收应该看到什么

在增加第四个 Bot 或把流程保存成长期 Skill 前，至少完成三次不同输入的演练，并核对下面这些结果：

Coordinator 能随时列出 owner、任务、状态和 blocker。
每次交接只有结果与证据，没有几千字工作过程。
Writer 从未把 unverified 或 skipped 内容写成已确认事实。
Checker 能把关键断言映射回来源，并阻止一次故意植入的无来源断言。
团队能在缺少来源、权限或审批时返回 BLOCKED。
群聊里可以追溯两次交接，最终只产生一个交付包。
所有外部动作仍停在人工审批之前。

原帖建议三 Bot 链干净运行三次后再增加第四个 Bot。这里“干净”的含义不该只是最后有一篇文章，而是交接字段完整、证据没有变形、阻塞能被发现、最终出口只有一个。

先把门缝补好，再招聘第五个 Bot

多 Agent 系统很容易给人一种组织已经成形的错觉：角色有名字、群聊会滚动、每个 Bot 都在输出。但真正决定结果能不能抵达终点的，是那些没那么热闹的接口。

从三个角色开始。让协调员只负责协调，让 Researcher 明确写出未验证项，让 Writer 只消费已验证材料，让 Checker 有权阻塞。固定 HANDOFF，提前写冲突规则，亲手触发一次停止条件，再把它们放进群聊。

如果三个人、两次交接都跑不稳，第五个 Bot 通常不是解决方案。它只是又增加了一道门缝。

参考资料

darkzodchi：How to Build a Team of AI Agents That Work Together in Grok Bot
xAI Docs：Message and collaborate，核对日期 2026-09-08
xAI Docs：Create and manage Bots，核对日期 2026-09-08
xAI Docs：Frequently asked questions，核对日期 2026-09-08
xAI Docs：Grok Bot for teams and enterprises，核对日期 2026-09-08

Skill 越多，Agent 为什么越容易犯选择困难？

Wed, 19 Aug 2026 00:00:00 +0000

不知道大家Vibe Coding时间久了以后会不会碰到这样的问题: 学习和使用了不少有用的skill, 自己的skill库越来越丰富, 但 Skill 库越攒越多，Agent 反而偶尔开始犯一种很熟悉的病：选择困难症。 有些问题, 这个skill能处理, 那个也能搞定, 但又都不是完美匹配当前场景的. 导致同一个问题, 多次解决路径居然不一致, 带来的结果和周边影响也不一样.

AI跟人一样, 对一些问题有多条解决路径选择时。就跟鬼哥看到“干炒牛河、辣椒炒肉、小炒黄牛肉、湖南米粉”同时出现在菜单上，脑子就直接进入一个 Infinity Loop 循环, 这顿饭都没力气吃下去了。Agent 面前如果同时摆着几十份名字相近、边界暧昧的 Skill，情况大致相同，只是它不会叹气，而是更认真地读错几份文件。

鬼哥昨天读到一篇新论文 Demystifying Agent Skills: Why They Work—Until They Don’t 恰好把这个问题拆开了。它问的不是“Skill 有没有用”，而是更麻烦也更有价值的问题：它什么时候帮忙、为什么帮忙、又从哪里开始添乱？

论文的答案很克制：Skill 确实有效，但它最主要的作用不是给 Agent 多塞一点知识，而是把过去混乱的经验压缩成一根可执行的“程序锚点”。问题也在这里：锚点一旦抛错地方，船就会稳稳地停在错误的位置。

Skill 不是“经验文档”，而是经验的蒸馏

论文把同一批历史执行轨迹做成了三种版本：

给 Agent 的东西	它保留了什么	它容易带来的问题
Raw	什么都不注入，让 Agent 从头做	每次都要重新发现环境、命令和检查步骤
Workflow Memory	清洗过的历史流程	仍夹带失败分支、偶然细节和冗长探索
Skill	从同一批流程蒸馏出的 `SKILL.md`	需要判断是否适用、如何适配

这个对照很关键。Skill 和 Workflow Memory 来自同一批成功与失败轨迹，所以它们的差异不能简单归因于“前者知道得更多”。

在匹配比较里，Skill 的成功率为 61.9%，Raw 为 59.1%，Workflow Memory 为 55.9%；Skill 相比 Workflow Memory 的增益为 6.06 个百分点，95% bootstrap 置信区间为 +0.76 到 +11.36。

更有意思的是，研究者逐条分析 Agent 轨迹后发现：Skill 有效的案例里，65.7% 是因为它提供了程序锚点——步骤顺序、工具调用、检查点、验证方案、常见坑；只有 4.5% 是因为它补充了 Agent 原本不知道的事实。

这和很多人的直觉相反。我们写 Skill 时常想“把知识写全一点”，但真正有价值的，往往是让 Agent 在关键时刻不忘记：先启动什么、再检查什么、哪种输出不算完成、踩坑后怎样退回来。

Skill 最大的作用，不是替 Agent 多记一条知识，而是在关键步骤上少忘一件事。

它最擅长修的，是“会做但总忘”的问题

论文里的细分结果很像所有做过 Agent 工程的人见过的事故单：

环境或基础设施失败：从 Raw 的 5.3% 降到 Skill 的 0.2%；
输出格式或 schema 不匹配：从 7.4% 降到 3.2%；
后台服务生命周期失败：从 2.7% 降到 0.8%。

这些不是深奥推理题。它们更多是执行纪律问题：路径没记住、服务没确认、schema 没校验、命令没按正确顺序跑。

所以一个好的 Skill，应该像一位靠谱但不啰嗦的值班同事：它不替你决定产品要不要做，却会在你准备发布前提醒“配置读了吗？”“服务起来了吗？”“返回值真符合接口吗？”

但别因此高估它。算法逻辑错误在 Skill 条件下仍有 7.4%，只做静态检查、没有真正运行验证的失败仍有 11.7%。Skill 能稳住执行，不能替人重新定义一个理解错了的问题。

Skill 的反噬：它会让错误的假设更有执行力

Skill 不是自动执行的。Agent 必须先判断它是否相关，再决定跟到什么程度，还得在当前环境里修改它。

这一步一旦偷懒，Skill 就从经验变成了惯性。论文中，skill_guidance_misapplied_or_ignored 在 Skill 组里占 10.0%，而 Raw 是 0.8%、Workflow Memory 是 0.4%。

这不是说 Skill 内容一定不好。更常见的情况是：旧任务和新任务看起来像，但一个前提已经变了；Agent 拿着一份“通常正确”的流程，顺手把它套到“不再通常”的场景上。

一个没有退出条件的 Skill，是把经验固化成偏见的最快方式。

这也是为什么我现在更在意 Skill 里有没有下面四块，而不是它写了多少页：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


## 适用前提
- 什么输入、环境和权限下使用？

## 执行路径
- 关键步骤的顺序是什么？

## 验证标准
- 跑什么检查？什么结果才算完成？

## 退出与升级
- 哪些信号说明不适用？何时停止并转人工/换方案？

前面三项让它可执行，最后一项让它不会过度自信。

Skill 库越大，难的不是保存，而是选择和适配

论文专门测了这个问题。候选 Skill 池从 5 个增加到 100 个时，Agent 在真实执行里实际使用 ground-truth Skill 的精确率，平均从 29.6% 掉到 3.3%。

但下游任务成功率却没有同步崩掉，只从 36.4% 变到 39.3%。原因并不神秘：Agent 可能看了多份相近 Skill；其中某份并非标注的“唯一正确答案”，却依然给了有用的操作线索。反过来，即使它选中了 ground-truth Skill，也仍可能在执行、适配或验证环节失败。

论文由此给出一个很重要的结论：精确调用标注上的正确 Skill，既不是任务成功的充分条件，也不是必要条件。

这对个人开发者的含义是：别只用“检索命中了没有”衡量 Skill 库。更应该问：

这份 Skill 的触发条件是否能和相邻 Skill 区分开？
它能否解释自己为什么适用于当前任务？
它的关键步骤能否被当前环境的 verifier 验证？
当它与另一份 Skill 冲突时，Agent 知不知道该降级、组合还是停下来问？

Skill 库的瓶颈从来不是存储空间，而是选择和适配能力。菜单可以很长，但“都来一份”不是一个工程策略。

失败轨迹别急着扔，它们是 Skill 的边界说明书

研究者还做了一个很实用的消融：构建 Skill 时，保留或去掉历史轨迹的“成功/失败”标记。

只有成功轨迹时，是否保留标记影响不大；一旦混入失败轨迹，结果标签就开始发挥作用。以 Gemini 在 Terminal-Bench-2 的 3 成功 + 2 失败 轨迹组合为例：构建 Skill 时保留 outcome labels，成功率为 74.62%；拿掉标签后，只有 40.00%。

这说明失败轨迹并不是应当删掉的脏东西。它告诉我们：哪一步看似合理却不通、什么条件一变流程就失效、最终验证为什么没有通过。

当然，失败记录原封不动地塞回上下文也不行——Workflow Memory 的 timeout/budget exhaustion 达 10.6%，而 Skill 为 4.4%。正确做法不是保存更多过程，而是把失败蒸馏成可判断的边界：失败模式、触发条件、检查办法、替代路径。

给个人开发者的一条 Skill 维护规则

如果你正在维护自己的 Skill 库，我建议不要从“再写一份新的”开始，而是从每次真实任务结束后的四个问题开始：

这次 Agent 反复犯的，究竟是知识缺口，还是执行步骤遗漏？
哪一步可以写成稳定的前提、动作和 verifier？
哪个失败条件必须写进这份 Skill 的退出路径？
它和已有 Skill 的边界是否足够清楚，还是只是在菜单上多加了一道相似的菜？

若答案只是“我觉得这条 Prompt 很有用”，先别急着建库。让它在几个真实任务里活下来，再把它写成 Skill。

这篇论文仍是一篇预印本，实验主要集中在终端与工具调用任务，覆盖的 Agent 框架和模型数量也有限；它不等于已经证明了所有网页 Agent 或开放式协作场景的规律。但它至少把一个常被忽略的问题说清了：Skill 的效果不是一次注入，而是一条生命周期——蒸馏、检索、调用、适配、验证。

回到开头那张菜单。鬼哥并不需要把所有菜从菜单上划掉；我需要的是知道今天为什么点这道、吃到一半发现不对时能不能换，以及不要把“菜单很丰富”误当成“晚饭已经解决”。

对 Agent 也是一样。

参考资料

Zhiyuan Jiang et al., Demystifying Agent Skills: Why They Work—Until They Don’t, arXiv:2608.14036, 2026.

天下苦旧 MCP 久矣：Anthropic新MCP协议终于开始治病了

Wed, 29 Jul 2026 00:00:00 +0000

你们在公司里落地 MCP 时，是不是也碰到过这些尴尬？

本地跑得丝滑，一上 Kubernetes、扩成两个实例，session 偶尔就找不到亲妈了；网关团队问“这次到底调用了哪个工具”，你只能指着一坨 POST 里的 JSON 说“答案在里面，请自行考古”；Agent 一遍遍调用 tools/list，工具一个没变，token 和请求倒是烧得很稳定；高风险操作想让用户确认一下，结果业务问题还没解决，先和长连接、代理超时打了一架。

鬼哥自己做 MCP 接入和应用时，这几种场面基本都见过。

开发同学觉得协议能跑，平台同学觉得它不好扩，安全同学觉得它看不懂，运维同学觉得它需要特殊照顾。最后大家围着一条本来应该很普通的工具调用链，开出了联合国大会的气势。

如果你也经历过，恭喜，我们算是对上暗号了：

天下开发者，苦旧 MCP 久矣。

它不是不能用。恰恰相反，旧 MCP 特别擅长证明一件事：模型可以调用工具。

但从“模型能调用工具”，到“公司敢让模型调用生产工具”，中间隔着负载均衡、网关、缓存、鉴权、审计、超时、扩容，以及安全团队那句永恒的灵魂拷问：

出事了算谁的？

2026 年 7 月 28 日，官方发布了新的 Model Context Protocol 规范：2026-07-28。

看完这版规范，鬼哥最大的感受只有一句：

新的 MCP，终于开始像一个基础设施协议了。

这次不是往协议里再塞几个功能，而是把那些真正妨碍 MCP 进入公司生产环境的东西，一件件拆掉：协议核心无状态、请求可路由、列表可缓存、授权更严谨、长流程不再绑死长连接、扩展也有了正式边界。

Anthropic 官方文档提到，Tier 1 SDK 每月下载量已经接近 5 亿，TypeScript 和 Python SDK 累计下载量都超过了 10 亿。生态跑到这个规模，再拿“demo 能跑”当成功标准，就多少有点不礼貌了。

下面不照着 release note 念。鬼哥直接拿公司里碰到的场景，讲讲这次到底改掉了什么。

两个实例一扩，session 先迷路了

鬼哥在公司里接远程 MCP 时，最典型的尴尬就是：单实例一切正常，一横向扩容，问题开始玄学。

旧版 MCP 在远程 HTTP 场景里，客户端先 initialize，服务端给出 Mcp-Session-Id，后续请求带着这个 session 继续走。

开发环境只有一个实例，当然岁月静好。到了生产环境，前面挂上 load balancer，后面跑多个实例，请求第一次落到 Server A，第二次被分到 Server B，B 一脸茫然：

你谁？

接下来无非几条路：

配 sticky session，让同一个客户端尽量黏住同一个实例；
搭共享 session store，让所有实例交换记忆；
在服务间同步上下文；
祈祷扩容、重启和故障转移时别出怪事。

能做，当然都能做。但为了调用一个 tool，先给负载均衡器安排一段刻骨铭心的长期关系，这个工程成本明显不太对。

2026-07-28 直接砍掉了这层协议会话：

移除 initialize / initialized 交换；
移除协议层 Mcp-Session-Id；
每个请求自己携带协议版本、客户端身份和能力；
需要提前发现服务端能力时，可以调用可选的 server/discover。

1
2
3
4
5


旧模式：
先握手 → 拿 session → 请求必须找到“熟悉你的实例”

新模式：
请求自描述 → 任意实例都能处理 → 普通 round-robin 就能跑

改完之后，MCP server 才真正像一个普通 HTTP 服务：实例随便扩，坏了随便换，请求落到谁家谁处理。Kubernetes、serverless、API Gateway、WAF、rate limiter 和 observability 这些现成基础设施，不用再围着 MCP 单独学一套脾气。

一个协议如果要求负载均衡器记住你，说明它还没学会在公司里做人。

状态可以有，但别藏在桌子底下

看到“无状态”，很多人会立刻问：那浏览器会话、代码沙箱、购物车和长任务上下文怎么办？

鬼哥在公司做这类工具时也遇到过。比如 Agent 创建了一个代码工作区，后面还要继续执行命令、读取结果。状态显然不能丢。

问题不在于“有没有状态”，而在于状态藏在哪里。

旧方式把关键状态藏进 transport session。客户端和模型知道“连接还在”，却不一定看得见自己正在操作哪个工作区。连接断了、实例换了，业务上下文也容易跟着失忆。

新方式更接近正常 API：

1
2
3


create_workspace → 返回 workspace_id
run_command(workspace_id, command)
read_result(workspace_id)

服务端返回显式 handle，模型在后续 tool call 中把它作为参数传回来。

体验上的变化很直接：

以前	现在
状态依附于连接	状态依附于明确的业务 ID
模型看不见 session 里藏了什么	模型能读取和传递 `workspace_id` / `task_id`
断线恢复依赖原会话	换实例后仍可按 handle 继续
排查时先猜“会话怎么了”	日志里直接按业务 ID 追踪

这不只是方便运维，也更适合 Agent 推理。模型看得见状态，才能引用状态、组合状态、接着做下一步。

状态不是不能有，不能装神弄鬼。

要用户点个确认，没必要拿长连接祭天

公司里的 Agent 一旦能写数据，human-in-the-loop 就绕不过去。

鬼哥碰到过的真实需求很普通：Agent 准备删除数据、修改配置、调用付费服务，执行前必须让用户确认。业务上就是一个“确定吗”，技术上却可能变成一条长时间挂着的双向流。

旧思路里，服务端执行到一半，通过打开的连接反向问客户端：

1

准备删除 3 条记录，确认吗？

听起来合理，直到它穿过公司的代理、网关和超时策略。用户去倒杯水，回来点“确认”，连接已经先替他回答了：

不确认，我没了。

MRTR，Multi Round-Trip Requests，解决的就是这个问题。它把中途交互拆成普通的多轮 request/response：

1
2
3
4
5


1. Client 调用 tool
2. Server 返回 input_required
3. Client 收集用户确认或补充参数
4. Client 带着 inputResponses 重试原调用
5. 任意 Server 实例继续处理

这样一来，删除确认、参数追问、二次授权、用户选择，都不再要求服务端死守一条连接。请求可以暂停，可以恢复，可以重试，也可以由另一个实例接着处理。

确认是业务流程，不该是连接保活挑战。

网关终于能看懂：你到底想干什么

鬼哥把 MCP 接进公司网关时，还有一个非常现实的问题：所有请求看起来都差不多。

安全团队想对删除类工具做更严格的授权，平台团队想给昂贵工具单独限流，运维想统计每个 tool 的错误率。结果网关看到的往往只是：

1
2


POST /mcp
Content-Type: application/json

至于这是 tools/call 还是 resources/read，调用的是 search 还是 delete_database，答案埋在 JSON-RPC body 里。

过去网关看 MCP，就像保安看一群都戴着口罩、穿着同款外套的人：知道有人进来了，不知道进来的是谁。

新规范要求 Streamable HTTP 请求带上 Mcp-Method 和 Mcp-Name：

1
2


Mcp-Method: tools/call
Mcp-Name: search

于是很多公司里的基础设施能力终于可以直接工作：

公司里的需求	改进后的体验
删除类 tool 单独审批	网关按 `Mcp-Name` 匹配策略
搜索和写入使用不同限流	不解析 body，header 直接分流
按方法做权限控制	安全层读取 `Mcp-Method`
统计各 tool 成本和错误率	观测系统直接按 header 分桶
对高风险调用做 WAF 规则	请求到应用前就能拦截

这两个 header 看起来只是两行字符，实际上是 MCP 对企业世界的一次低头。

而这次低头，很有必要。基础设施不怕你复杂，怕的是你什么都藏着不说。

工具一个没变，Agent 为什么还要问十遍

鬼哥在公司跑 Agent 时，经常看到一种很浪费的行为：

1
2
3


tools/list
tools/list
tools/list

Agent 每推进几步，就重新确认一次“你有哪些工具”。服务端老老实实返回同一份列表，客户端老老实实重新处理，大家都很勤奋，只有账单不太开心。

旧 MCP 对列表缓存缺少明确语义。客户端不知道这份 tool catalog 能信多久，也不知道应该按用户、租户还是全局缓存。最稳妥的办法只能是：再问一次。

新规范让 tools/list、prompts/list、resources/list、resources/read 等响应可以携带：

ttlMs
cacheScope

有了明确的有效期和作用域，客户端可以放心复用结果。同时，确定性的列表顺序也能让上游上下文更稳定，减少 prompt cache 因为一点无意义的顺序抖动而失效。

前后的差别，不只是少几次网络请求：

工具发现更快；
token 消耗更低；
tool catalog 在上下文里更稳定；
多租户缓存边界更清楚；
服务端不用反复回答同一道送分题。

最贵的请求，不一定最复杂；也可能只是明知道答案没变，还要再问一遍。

安全团队终于不只剩一句“先别上”

公司里接 MCP，真正耗时间的通常不是 tool schema，而是 authorization。

鬼哥经历过类似的拉扯：开发侧已经把工具调用跑通了，接入企业身份系统时却开始连环追问：

这个 token 是谁签发的？
Agent 代表哪个用户？
credential 能不能被拿去另一个授权服务器使用？
desktop / CLI 的 localhost redirect 怎么处理？
出问题以后，能不能还原谁在什么时候调用了什么？

这些问题一个都不酷，但任何一个答不清，安全团队都可以非常合理地说：

很好，先别上。

2026-07-28 对授权做了几项关键硬化：

授权服务器应返回 iss，客户端在换 code 前必须验证，避免 authorization-server mix-up；
DCR 增加 application_type，减少 desktop / CLI 的 localhost redirect 被误拒；
client credential 与 issuer 绑定，不能跨授权服务器复用；
Dynamic Client Registration 被弃用，方向转向 Client ID Metadata Documents；
企业托管授权等能力进入正式 extensions 框架。

改进后的重点，不是 OAuth 流程看起来更漂亮，而是信任关系终于更容易说清楚：谁签发、谁使用、代表谁、能用在哪、出了事怎么查。

能调工具是 demo；知道谁以谁的名义调了什么，才是生产。

出错以后，别再让日志各说各话

鬼哥在公司排查 Agent 调用链时，还有一种熟悉的痛苦：一次 tool call 穿过客户端、SDK、MCP server，再调用下游 API，报错后每一层都有日志，但没有一层承认彼此认识。

客户端说请求失败，MCP server 说下游超时，下游系统说自己收到过一个调用。三份日志，三个 request ID，工程师只能靠时间戳和直觉玩连连看。

新规范把 W3C Trace Context 在 _meta 里的传播方式正式写清楚，固定了 traceparent、tracestate 和 baggage 的 key。这样，一条从 Agent 发起的调用，可以穿过客户端 SDK、MCP server 和下游服务，最终在兼容 OpenTelemetry 的系统里串成同一棵 span tree。

改进前，问题是“这三条日志是不是一家人”；改进后，至少可以沿着一个 trace 看到请求在哪一层慢、在哪一层错、又是谁重试了几次。

没有 trace 的 Agent 调用链，出了问题以后就不是排障，是刑侦。

长任务别再假装自己是一次 tool call

鬼哥在公司做 Agent 流程时，批量处理、生成报告、扫描代码、部署环境这类任务很常见。它们可能跑几分钟，甚至更久。

硬把这种工作塞进一次 tool call，体验通常是：

1
2
3
4
5


Client：还活着吗？
Server：在跑。
Client：跑哪了？
Server：你先别断。
网关：时间到了，我帮你们断。

新规范把 Tasks 从 experimental core 移到 io.modelcontextprotocol/tasks extension，并提供：

poll-based tasks/get
tasks/update
通过 subscriptions/listen 订阅通知

这意味着长任务可以有明确身份、状态和更新机制，不需要伪装成一条永远不结束的普通请求。

更重要的是，MCP 正式确立了 extensions 框架。新能力可以先在扩展中演进，成熟后再决定是否进入核心，core 则保持小而稳定。

同时，新规范给出至少 12 个月的弃用窗口。Roots、Sampling、Logging 和 legacy HTTP+SSE transport 被标记为 deprecated，但不会第二天突然断气。

这才是一个成熟协议该有的演进方式：能往前走，也不半夜掀生产系统的桌子。

核心协议不是收纳箱。什么都往里塞，最后就只剩下“核心”两个字比较轻。

这次升级，公司团队该检查什么

官方表示，TypeScript、Python、Go、C# 四个 Tier 1 SDK 已经支持 2026-07-28，Rust SDK 也有 beta 支持。

如果你在公司维护远程 MCP server，别只看完 release note 点个赞。建议直接拉开发、平台和安全团队过一遍下面这张表：

检查项	结合现有系统要问的问题
协议版本	是否支持 `2026-07-28`？旧客户端如何降级？
session 依赖	是否依赖 `Mcp-Session-Id`、sticky session 或共享会话存储？
状态句柄	跨调用状态能否改成显式 `task_id` / `workspace_id`？
网关路由	能否利用 `Mcp-Method` / `Mcp-Name` 做限流、鉴权和观测？
list 缓存	工具、资源和 prompt 列表能否提供稳定顺序与缓存提示？
MRTR	用户确认、补参数和二次授权能否改成 input-required / retry？
Auth	issuer 校验、credential 绑定和 DCR 迁移是否有计划？
链路追踪	`traceparent` / `tracestate` / `baggage` 能否贯穿调用链？
长任务与弃用项	是否应迁移到 Tasks extension？是否还依赖旧能力？

这一版真正拉开的，不再是谁能多暴露几个 tools，而是谁的 MCP server 能做到：

1
2
3
4
5
6


stateless
routable
cacheable
observable
governable
extensible

过去我们评价一个 MCP server，常问的是：它能不能用？

接下来公司真正会问的是：它能不能扩，能不能管，能不能查，出了事能不能解释？

最后：MCP 开始进入真正的淘汰赛

过去一年，MCP 的第一阶段是“万物皆可接”：数据库、浏览器、GitHub、Slack、Figma、云服务、公司内部系统，先把工具接进来再说。

这个阶段很热闹，也很重要。

但工具数量决定的是 demo 看起来有多丰富，基础设施能力决定的是公司敢不敢把它留在生产环境。

2026-07-28 这版规范最有价值的地方，就是它终于开始正面处理那些不适合发布会截图、却每天折磨工程团队的问题：会话、扩容、路由、缓存、授权、长任务和协议演进。

所以鬼哥的判断是：

MCP 的上半场，比的是谁接的工具多；下半场，比的是谁更像基础设施。

Agent 要真正进入公司，不缺会调用工具的 demo。

缺的是一套能被负载均衡接住、被网关看懂、被安全系统治理、被运维团队放心扩容的协议。

苦旧 MCP 久矣。

这一次，新的 MCP 总算开始治病了。

参考资料

OKF：AI Agent 缺的不是模型，是可交接的上下文

Mon, 22 Jun 2026 00:00:00 +0000

AI Agent 最怕的不是模型不够强，而是它每次开工前，都像一个刚入职的新同事：不知道表在哪，不知道指标怎么算，也不知道谁脑子里藏着关键规则。

Google Cloud 最近发布的 Open Knowledge Format（OKF），表面上看只是一个“Markdown + YAML frontmatter”的小规范。

但我觉得它真正值得关注的地方在于：它把 AI 时代最难交接的东西，重新变成了文件。

问题不是没有知识，而是知识没法交给 Agent

今天大多数公司的知识并不少。

表结构在数据目录里，指标定义在 BI 文档里，事故处理流程在 runbook 里，API 变更写在 release note 里，一些关键口径藏在老员工脑子里。

问题是：这些知识对人来说都已经够散了，对 AI Agent 来说更是灾难。

当一个 Agent 要回答：

1

怎么从事件流里计算 weekly active users？

它可能要同时知道：

哪张表是事件源；
用户 ID 用哪个字段；
bot 流量怎么排除；
时区按 UTC 还是业务地区；
老口径有没有废弃；
这个指标和看板上的 WAU 是否一致；
如果 join 用户表，应该走哪条路径。

这些信息往往分布在不同系统里：metadata catalog、Notion、Google Drive、代码注释、SQL 文件、Slack 历史消息，甚至某个资深工程师的记忆里。

所以，Agent 真正缺的不是“再聪明一点”。

它缺的是一份能被读取、能被链接、能被版本管理、能被不同工具交接的 上下文资产。

OKF 是什么：不是服务，是格式

Google Cloud 对 OKF 的定义很克制。

OKF v0.1 把知识表示成一个目录，目录里是一组 Markdown 文件，每个文件都有 YAML frontmatter。它不要求新 runtime，不要求 SDK，不绑定某个云厂商，也不要求你把知识搬进一个新平台。

最小形态大概长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


sales/
├── index.md
├── datasets/
│ ├── index.md
│ └── orders_db.md
├── tables/
│ ├── index.md
│ ├── orders.md
│ └── customers.md
└── metrics/
 ├── index.md
 └── weekly_active_users.md

一个概念就是一个文件。

文件路径就是这个概念的身份。

文件头部放少量可查询字段，正文放人和 Agent 都能读的解释：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery/...
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---

# Schema

| Column | Type | Description |
|---|---|---|
| `order_id` | STRING | Globally unique order identifier. |
| `customer_id` | STRING | FK to [customers](/tables/customers.md). |

# Joins

Joined with [customers](/tables/customers.md) on `customer_id`.

OKF 的野心不在“文件格式很复杂”，恰恰相反，它的野心在于 足够普通：

设计选择	意味着什么
Markdown	人能读，Agent 也能读
YAML frontmatter	少量结构化字段可检索、可过滤
普通目录	能进 Git，能打包，能挂载，能同步
Markdown 链接	文件之间自然形成知识图谱
最小约束	不强迫所有团队接受同一套知识模型

这就是 OKF 最有意思的地方：它不是想成为新的知识平台，而是想成为知识平台之间的交换格式。

为什么是 Markdown？因为 Agent 时代需要“知识即代码”

这几年很多团队都在重新发现一个模式：LLM wiki。

人类维护 wiki 很痛苦，因为我们会忘记更新链接，懒得补充引用，也不想每次改完一个文档还去同步另外 15 个文件。

但这些事情恰好是 LLM 擅长的。

它不会嫌整理 cross-reference 无聊，也不会因为要批量改十几个文件就开始摆烂。只要你给它一个清晰的文件结构、约束和审查机制，它可以把知识维护变成一个持续循环：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


发现新事实
 ↓
更新概念文件
 ↓
补充链接和引用
 ↓
提交 Pull Request
 ↓
人类审核
 ↓
Agent 下次直接读取更新后的上下文

这就是“知识即代码”的味道。

代码为什么能长期演进？不是因为代码天然比文档高级，而是因为它有一套成熟的协作机制：

Git 记录历史；
PR 承载讨论；
diff 暴露变化；
review 把关质量；
CI 做基础校验；
blame 能追溯责任。

OKF 想做的，是让企业知识也进入这套机制。

不是再建一个“大家都不会更新”的知识库，而是让知识文件和代码、SQL、配置、runbook 一起被管理。

OKF 和 RAG 的区别：一个是切片，一个是概念

很多人第一反应会是：这不就是 RAG 吗？

不完全是。

RAG 通常做的是：把文档切 chunk，做 embedding，查询时召回相关片段，再交给模型综合。

OKF 更像是提前把知识整理成 概念级资产。一个表、一个指标、一个 runbook、一个 API、一个 join path，都可以是独立概念。概念之间用 Markdown 链接互相指向。

可以粗暴对比一下：

维度	RAG 常见做法	OKF 的思路
基本单位	文档切片 chunk	概念 concept
组织方式	向量索引	文件目录 + 链接图
语义关系	查询时临时召回	事先显式维护
可读性	主要给系统读	人和 Agent 都能读
版本管理	往往在索引外部	天然进 Git
适合场景	大规模检索	稳定知识、指标、 schema、runbook

RAG 像是让 Agent 在图书馆里临时找资料。

OKF 像是给 Agent 一本经过整理、带目录、带交叉引用、能持续更新的工作手册。

两者不是互斥关系。OKF bundle 完全可以被索引进 RAG 系统。但它的价值在于：进入索引之前，知识已经被整理成可审查、可迁移、可复用的形态。

OKF 真正解决的是“上下文交接成本”

我觉得 OKF 的关键词不是 Markdown，也不是 YAML。

它的关键词是：handoff。

一个企业里最贵的成本，往往不是模型调用费，而是上下文交接费。

新同事入职，要问一堆人。

新 Agent 上线，要重新接一堆系统。

换一个工具，要重新导出、清洗、适配。

换一个供应商，原来的知识资产又被锁在对方的数据模型里。

OKF 试图把这些上下文从“平台内资产”变成“文件资产”。

这件事如果做成，会有几个直接变化：

过去	OKF 想推动的状态
知识绑定在工具里	知识以文件存在
Agent 依赖专用 SDK	Agent 直接读目录
数据目录和文档分离	概念文件里同时有元数据和解释
更新靠人工记忆	更新走 PR 和 review
换工具就重做集成	格式是合同，工具可替换

这也是为什么 Google Cloud 在官方文章里反复强调：OKF 是 format，不是 platform。

如果一个格式只能在某家云、某个数据库、某个 Agent 框架里跑，那它解决不了上下文迁移问题。

Databricks 和 Snowflake 都很强，但知识仍然不可复用

这里可以拿两个今天业界很强的产品来对照：Databricks Genie One 和 Snowflake Cortex Analyst。

先说清楚：这两个方向都很顶。

Databricks Genie One 的定位是面向业务团队的 AI coworker。它强调“grounded in your data”，能让业务用户提问、拿到上下文相关的答案，并进一步把洞察转成 action、agent 或 app。它背后的 Genie Ontology 被 Databricks 描述为一个持续改进、自动推断的业务术语、实体和 KPI 知识图谱，用来支撑 Genie 的回答和动作。Databricks 文档里的 Genie Spaces，也明确要求数据分析师用 Unity Catalog 数据集、示例 SQL、业务语义表达式和组织术语说明来 curate 一个 domain-specific 的问答空间。

Snowflake Cortex Analyst 也在解决同一个核心问题：业务用户用自然语言问数据问题，但数据库 schema 本身不足以告诉模型“业务到底是什么意思”。所以 Cortex Analyst 依赖 semantic model / Semantic Views，把业务实体、维度、事实、指标、表关系、verified queries 等语义信息显式建出来。Snowflake 官方文档也明确说，semantic model 是用来弥合 business users 和 database 之间的差距。

这两套东西都不是玩具。

它们代表了企业数据 AI 的一个共识：自然语言问数想要靠谱，必须有业务语义层。

但问题也在这里。

如果你的团队在 Databricks 里花了很多时间维护 Genie Space、Genie Ontology、Unity Catalog Semantics；同时另一个团队在 Snowflake 里维护 Semantic Views、Cortex Analyst semantic model、verified queries，那么这些业务知识很难天然复用。

不是因为 Databricks 或 Snowflake 做得不好。

恰恰相反，是因为它们都做得太完整了：语义层、权限、执行引擎、治理、Agent 体验，都和自家平台深度耦合。

于是用户会遇到一个很现实的问题：

业务知识	在 Databricks 里	在 Snowflake 里	跨平台复用
指标定义	Genie / Unity Catalog 语义体系	Semantic Views / semantic model	需要重新映射
表关系	Databricks 平台上下文	Snowflake semantic layer	不能直接通用
Verified queries	Genie Space 示例和验证	Cortex Analyst verified queries	格式不同
业务术语	Genie Ontology	Semantic View definitions	各自维护
Agent 行为	Genie Agents / apps	Cortex Analyst API / apps	体验绑定平台

对企业来说，选择 Databricks 或 Snowflake 当然都可以。

真正麻烦的是：一旦业务语义被写进某个平台的私有结构里，它就很难成为企业自己的可迁移资产。

今天你可能还在二选一。

明天你可能是多云、多仓、多团队并存；有的团队在 Databricks，有的团队在 Snowflake，有的知识还在 Obsidian、Notion、dbt repo、GitHub、Confluence 里。

这时候 OKF 的价值就出来了。

OKF 不试图取代 Databricks Genie，也不试图取代 Snowflake Cortex。它更像一个中间层协议：

1
2
3
4
5


Databricks Genie / Unity Catalog
 ↓ export / sync
 OKF bundle
 ↑ import / consume
Snowflake Cortex / Semantic Views

理想情况下，企业可以把最核心的业务知识沉淀成 OKF bundle：指标定义、表关系、术语、runbook、verified query、历史变更、负责人、引用来源。

然后 Databricks 可以读它，Snowflake 可以读它，内部 Agent 可以读它，未来换一个新的数据平台也能读它。

这样，平台仍然可以竞争体验、性能、治理和执行引擎。

但业务知识本身，不再被锁死在某一个平台里。

这才是 OKF 最值得期待的地方：它让企业有机会把“语义层”从平台能力，升级成自己的知识资产。

它现在还很早，但方向很对

OKF 目前是 v0.1。

Google Cloud 同时发布了几个参考实现：一个 BigQuery enrichment agent，一个静态 HTML visualizer，以及 GA4、Stack Overflow、Bitcoin public dataset 等 sample bundles。Google Cloud 的 Knowledge Catalog 也已经支持 ingest OKF 并服务给自家 Agent。

这说明它已经不只是一个 PDF 规范，而是有了可跑的 producer、consumer 和样例。

但我们也要清醒：OKF 还不是事实标准。

它接下来要面对的问题不少：

各家 catalog 和 wiki 是否愿意导出 OKF；
企业内部是否愿意把知识当代码维护；
frontmatter 字段会不会逐渐膨胀；
权限、隐私、敏感信息如何和文件分发兼容；
Agent 自动更新知识时，怎样保证审查和可信度；
不同行业的概念模型能否在“最小约束”下保持互操作。

所以，OKF 不是答案的终点。

但它至少指出了一个很重要的方向：Agent 的能力边界，不只取决于模型，也取决于知识能不能被规范地交给它。

我们可以怎么用？

如果你在团队里做 AI Agent、数据平台、知识库、内部工具，我建议不要急着问“要不要全面采用 OKF”。

更实际的做法是：先挑一个小场景试。

比如：

1
2
3
4
5
6
7
8


把一个核心指标做成 OKF bundle：

metrics/weekly_active_users.md
tables/events.md
tables/users.md
runbooks/data-quality-check.md
references/product-definition.md
log.md

然后让 Agent 基于这些文件回答问题、生成 SQL、检查口径、解释异常。

你很快就会发现：真正困难的不是写 Markdown，而是把团队脑子里的隐性知识显性化。

这也是 OKF 最有价值的地方。

它逼你回答：

我们的核心概念到底有哪些？
每个概念的权威定义在哪里？
哪些链接关系必须显式维护？
哪些知识应该进版本控制？
哪些更新必须经过人类 review？

这些问题，本来就是企业做 AI Agent 绕不开的问题。

OKF 只是给了一个足够朴素、足够可落地的容器。

Takeaway：先别急着堆 Agent，先整理上下文

如果只记住一句话，我希望是这句：

AI Agent 的下一场竞争，不只是模型能力，而是上下文工程。

模型会越来越强，工具调用会越来越顺，multi-agent 框架也会越来越多。

但真正能让 Agent 在企业里稳定工作的，往往是那些看起来不性感的东西：指标定义、表关系、runbook、决策记录、历史变更、权限边界、业务口径。

OKF 的启发是：不要把这些东西继续锁在工具里、聊天记录里、某个人脑子里。

把它们变成文件。

让人能读，让 Agent 能读，让 Git 能管理，让工具能迁移。

这可能就是 AI 时代知识管理最朴素、也最关键的一步。

参考资料

Loop Engineering：Agent 不是跑一次，而是活在循环里

Wed, 17 Jun 2026 00:00:00 +0000

最近一段时间，AI 开发讨论里有一个越来越热的词：Loop Engineering。

它把很多 AI 开发者过去两年跟 coding agent 协作沉淀下来的经验，逐渐聚集到一个共识上：你不应该再只是提示 coding agent，而应该设计会提示 agent 的循环。

鬼哥这篇引用 LangChain 团队的技术文章 The Art of Loop Engineering，来拆一下这个正在升温的工程话题。后面还有一篇来自 Google、同样围绕 Loop Engineering 的文章，更偏时间维度和落地实践，也值得期待。

过去两年，我们跟 coding agent 协作，大概是这个姿势：

1
2
3
4
5
6


我写 prompt
 -> agent 生成代码
 -> 我读结果
 -> 我补充上下文
 -> agent 再改
 -> 我再验

这当然有效。到今天为止，直接提示 agent 依然是最高性价比的日常操作。

但它有个天花板：你始终是循环里的调度器。任务从哪里来、下一步做什么、做完怎么验、失败怎么记、明天怎么接着跑，全都靠你脑子里那条线牵着。

Loop Engineering，本质上是把这条线从你的脑子里拿出来，做成外部系统：

1

发现任务 -> 分配执行 -> 隔离改动 -> 独立验证 -> 记录状态 -> 决定下一步

Prompt 还是存在，但它被放回了一个更大的机器里。你不再只是写一句话让 agent 干活，而是在设计 agent 干活的方式。

一个 Agent 最危险的幻觉，不是编错代码，而是跑完一遍就以为自己完成了任务。LangChain 这篇文章把 Agent 系统的核心能力拆成四层循环：agent loop、verification loop、event-driven loop、hill climbing loop。这个拆法很朴素，但对做过真实 Agent 工程的人来说，几乎每一层都踩过坑。

为什么我觉得这篇文章值得单独拎出来

那两篇的核心判断是：模型越强，工程师越不该把精力只花在 prompt 上，而应该设计模型工作的系统。

LangChain 这篇文章往前推了一步：它没有只说“要做系统”，而是把系统拆成了一个更可操作的结构：

层级	它解决的问题	典型失败模式
Agent loop	模型如何一步步调用工具完成任务	一次输出就收工，没计划、没状态
Verification loop	怎么知道这一步真的对了	自我感觉良好，错了也继续往下跑
Event-driven loop	Agent 怎么响应外部世界变化	只能同步问答，无法长期驻留
Hill climbing loop	系统怎么越跑越好	每次失败都是一次性事故，没有积累

这四层合起来，其实就是 Agent 从 demo 走向生产的路线图。

第一层：Agent loop，不是聊天，是“观察-行动-再观察”

最基础的一层是 agent loop。

很多人第一次做 Agent，会把它理解成“LLM + tools”：模型看一眼任务，决定调用哪个工具，拿到结果，再继续生成。这当然没错，但还不够。

真正的 agent loop 至少要包含四件事：

1

observe -> decide -> act -> update state -> observe again

也就是说，Agent 不是在“回答问题”，而是在一个不断变化的状态里行动。它每调用一次工具，世界就变了一点：文件被改了，网页打开了，数据库返回了新结果，用户可能又插了一句话。下一步动作必须基于新的状态，而不是基于最开始那段 prompt。

我自己用 Claude Code / Codex 做开发时，最明显的分水岭就是这里。弱 Agent 像一个“高级补全器”：你给它一个任务，它生成一坨代码，然后等你验尸。强一点的 Agent 会自己读文件、跑测试、看错误、再改，整个过程已经是一个小型闭环。

但只靠这一层还不够。因为 Agent loop 解决的是“会不会动”，不是“动得对不对”。

第二层：Verification loop，裁判必须独立

Agent 最容易犯的错，不是不会做，而是做错了还解释得很合理。

所以第二层是 verification loop：每一轮行动之后，系统要有一个明确的验证环节，判断结果是否满足标准。如果不满足，就把反馈送回 Agent，让它修正，而不是直接把错误带到下一步。

这跟我在本地折腾模型、写自动化脚本的体感完全一致：没有 verifier 的 Agent，越勤奋越危险。 它会非常积极地把错误扩散到更多文件、更深的状态里。

一个实用的 verification loop 可以长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


agent proposes change
 |
 v
run deterministic checks
 |
 v
LLM judge reviews ambiguous quality
 |
 v
pass -> continue
fail -> send structured feedback back to agent

这里有两个关键点。

第一，能用确定性检查的地方，别让 LLM 当裁判。测试、类型检查、lint、SQL 校验、schema validation，这些都应该是硬规则。

第二，必须用 LLM 判断的地方，也尽量让它成为独立裁判。不要让生成答案的同一个上下文顺手给自己打分。模型自评经常带着自己的思路滤镜，看不到真正的问题。

第三层：Event-driven loop，让 Agent 从“工具”变成“服务”

前两层解决的是一次任务内部的闭环。第三层 event-driven loop，解决的是更生产级的问题：Agent 怎么在真实世界里长期运行？

现实系统不是你问一句它答一句。真实系统里会发生各种事件：

用户发来新消息
GitHub 出现新 issue
CI 失败
数据库里多了一条异常记录
定时任务触发
人类审批通过或驳回

一个 event-driven Agent 不应该只是被动等待 prompt，而应该能被事件唤醒，读取上下文，恢复状态，执行下一步，然后再次挂起。

这也是 LangGraph 这类框架一直强调 state、durability、interrupt/resume 的原因。没有这些能力，Agent 只能做“同步聊天机器人”；有了这些能力，Agent 才能接近“后台工作人员”。

我觉得这一层对 AI 开发者特别重要，因为很多 Agent 项目死在这里：demo 里看起来很聪明，接到生产事件之后就不知道自己是谁、之前做过什么、现在该从哪一步继续。

一个更像生产系统的 Agent，应该长这样：

1
2
3
4
5
6


event arrives
 -> load thread / task state
 -> decide next action
 -> call tools or ask human
 -> persist state and trace
 -> wait for next event

第四层：Hill climbing loop，真正的复利在系统之外

最外层，也是最容易被忽略的一层，是 hill climbing loop。

前三层让 Agent 能跑、能验、能响应事件。第四层要回答的问题是：这个系统跑了一百次之后，有没有变得更好？

如果每次失败都只是“这次模型没发挥好”，那你永远在原地打补丁。Hill climbing loop 要做的是把失败变成可积累的工程资产：

traces：记录 Agent 每一步为什么这么做
evals：把失败案例沉淀成可重复评测
feedback：把人类纠错变成结构化信号
prompt / policy changes：把经验固化到系统行为里
regression checks：防止修好一个场景又弄坏另一个场景

这也是为什么我越来越觉得 LangSmith、OpenTelemetry、eval harness 这些东西不是“上线后再补”的配套工具，而是 Agent 工程的主干。

没有 trace，你不知道它为什么失败；没有 eval，你不知道改动是否真的变好；没有反馈闭环，你只是每天给同一个坑换名字。

Human oversight 不是“最后点一下确认”

LangChain 文章里还有一个横跨四层的点：human oversight。

很多系统把 human-in-the-loop 做成一个很浅的审批按钮：Agent 生成结果，人类点 approve 或 reject。这个当然有用，但太窄了。

更好的 human oversight 应该分布在不同层级：

位置	人类做什么	价值
Agent loop	在关键工具调用前确认	防止不可逆操作
Verification loop	对模糊质量给判断	弥补自动评测盲区
Event-driven loop	在异常分支里接管	避免系统卡死或误操作
Hill climbing loop	标注失败、调整 rubric	让系统长期进化

换句话说，人类不是 Agent 的“老板”，而是整个循环系统里的高价值传感器和调参者。

对 AI 开发者的实操建议

如果你正在做 Agent，不要一上来就问“该用哪个模型”。

先把你的系统画成四层循环，然后逐层检查：

Agent loop：它是否真的会观察状态、调用工具、更新状态、继续行动？
Verification loop：每一步有没有可执行的验收标准？能不能自动跑？
Event-driven loop：它能不能从外部事件恢复上下文，而不是每次从零开始？
Hill climbing loop：失败案例有没有沉淀成 trace、eval、规则或测试？

如果这四层里有一层是空的，你的 Agent 很可能还停留在 demo 阶段。

更直接一点：别再只调 prompt 了，把 prompt 放回循环里看。 Prompt 是 Agent 的一部分，但不是 Agent 系统本身。真正决定可靠性的，是状态、验证、事件、观测和反馈如何组成闭环。

Takeaway：下次设计 Agent，先画循环

我会把 LangChain 这篇文章的核心压缩成一句话：

Agent 工程不是让模型更聪明，而是让系统在每一次行动之后都能变得更确定。

下一次你要做一个 Agent，不妨先别打开代码编辑器。先画四个圈：

这个 Agent 怎么行动？
它怎么验证自己没有跑偏？
它怎么响应真实世界的事件？
它怎么从失败里长期爬坡？

四个圈画清楚，再选模型、写 prompt、接工具。顺序反了，你大概率会得到一个很会说话、但不能放心托付的 demo。

参考资料

别再只会提示词了：下一代程序员要会设计 Agent 循环

Wed, 17 Jun 2026 00:00:00 +0000

你以为 AI 编程的下一步是“写出更好的 prompt”？可能错了。

Addy Osmani 最近在 X 上写了一篇长文：Loop Engineering。他的判断很直接：你不应该再只是提示 coding agent，而应该设计会提示 agent 的循环。

这句话听起来像一句漂亮口号，但背后其实是 AI 编程工作流的重心迁移：从“人坐在驾驶位，一轮一轮指挥模型”，变成“人设计一个小系统，让它发现任务、分配任务、验证结果、记录状态，然后继续下一轮”。

Prompt engineering 还没死，但它不再是杠杆最大的位置

过去两年，我们跟 coding agent 协作，大概是这个姿势：

1
2
3
4
5
6


我写 prompt
 -> agent 生成代码
 -> 我读结果
 -> 我补充上下文
 -> agent 再改
 -> 我再验

这当然有效。到今天为止，直接提示 agent 依然是最高性价比的日常操作。

Addy 说的 loop engineering，本质上是把这条线从你的脑子里拿出来，做成外部系统：

1

发现任务 -> 分配执行 -> 隔离改动 -> 独立验证 -> 记录状态 -> 决定下一步

Prompt 还是存在，但它被放回了一个更大的机器里。你不再只是写一句话让 agent 干活，而是在设计 agent 干活的方式。

一个 Agent loop 至少需要五个零件

Addy 把这个循环拆成五个核心零件，再加一个外部记忆层。

零件	作用	没有它会怎样
Automations	定时发现任务、触发运行	每次都要人手动想起要检查什么
Worktrees	让多个 agent 并行但互不踩文件	并发一开，代码库变事故现场
Skills	固化项目知识和工作约定	每次会话都从零猜你的项目习惯
Plugins / Connectors	接入真实工具和数据源	agent 只能在文件系统里自言自语
Sub-agents	拆分执行者和验证者	写代码的人顺手给自己打满分
Memory	记录已做、待做、失败和下一步	模型每轮都忘，循环无法延续

这几个词看起来像产品功能列表，但组合起来才是重点。

单独看，automation 只是定时任务；worktree 只是 Git 技巧；skill 只是文档；connector 只是 MCP；sub-agent 只是多开一个模型。

但放在一起，它们变成了一种新的工作单元：不是一个 agent，而是一条可以重复运行的工程流水线。

Automations 是心跳：它让循环真的会“再来一次”

循环和一次性任务最大的区别，不是复杂度，而是有没有心跳。

没有 automation，你只是今天心血来潮跑了一次 agent。
有 automation，它明天还会来，后天还会来，出事时会把结果丢进你的 inbox。

Addy 举的例子很具体：

每天做 issue triage
总结 CI 失败
写 commit briefing
找出最近引入的 bug
定时运行某个 skill，而不是粘贴一大坨 prompt

这里的关键不是“自动化很酷”，而是任务发现被系统化了。

很多工程工作其实死在第一步：不是没人会修，而是没人持续看。CI 偶尔红一次、issue 堆一点、依赖慢慢旧一点、代码质量每天滑一点。人类对这种缓慢腐蚀很迟钝，循环不会。

Worktrees 是并行的刹车系统

只要你让多个 agent 同时改同一个 repo，最先坏掉的通常不是模型能力，而是文件冲突。

两个 agent 同时改同一个文件，本质上和两个工程师同时改同一段代码一样：不是不能做，而是你必须有隔离边界。

Git worktree 的价值就在这里。每个 agent 在自己的 checkout、自己的 branch 里工作，改动不会直接踩到另一个 agent 的现场。

这让并行从“看起来很爽”变成“至少机械上可控”。

但别高兴太早。worktree 解决的是文件层面的碰撞，不解决人的 review 带宽。

你可以同时开 5 个 agent，但如果你只能认真 review 1 个 PR，那么系统吞吐量的瓶颈仍然是你。并行不是免费午餐，它只是把瓶颈从执行转移到判断。

Skills 是意图的缓存

我越来越觉得，skill 最被低估的地方不是“复用提示词”，而是它把项目里的隐性规则变成了显性资产。

每个成熟项目都有一堆口头约定：

这个目录不能乱动
这个测试必须先跑
这个 API 不能破坏兼容性
这类 UI 不能做成营销页
我们上次踩过这个坑，所以现在不这么写

如果这些东西只存在于人的脑子里，agent 每次进来都会重新猜一遍。猜对了叫聪明，猜错了叫事故。

Skill 的意义是把这些判断写在外部，让 agent 每次运行都能读到。

这也是 loop engineering 里很关键的一点：循环要长期跑，就不能每次都重新理解世界。 它需要一套可积累、可维护、可版本化的项目知识。

Connectors 让循环碰到真实世界

一个只能看本地文件的 agent，能做的事很有限。

真正有用的 loop 往往要碰到真实系统：

GitHub issue 和 PR
Linear / Jira ticket
Slack / 飞书通知
CI 日志
数据库查询
线上监控
staging API

这就是 connector 的位置。MCP 这类协议的价值，不只是“让 agent 多几个工具”，而是让 loop 能把状态从真实工作流里拿进来，再把结果写回去。

差别很大：

普通 agent	Loop + connectors
“我建议你这样改”	直接开 PR
“这个 issue 可能相关”	自动链接 ticket
“CI 好像失败了”	读取日志、定位原因、发修复分支
“你可以通知团队”	CI 绿了以后发 Slack

前者是助手，后者更像一个后台工作人员。

Sub-agents：不要让写代码的人当唯一裁判

在无人值守循环里，最危险的一句话是：“看起来完成了。”

模型很擅长把自己刚刚做的事解释得很合理。它写了代码，它也知道自己想表达什么，所以它很容易忽略读者、测试、边界条件和真实需求。

所以 loop 里最值得花 token 的地方，往往是 maker / checker 分离：

1
2
3


Explorer 负责读上下文
Implementer 负责改代码
Verifier 负责按 spec 和测试挑刺

Verifier 不一定总是另一个大模型。能用确定性检查的地方，应该优先用测试、lint、type check、schema validation。

但只要涉及模糊质量，比如架构是否过度、文案是否误导、交互是否符合用户习惯，一个独立的 sub-agent 就很值钱。

循环越自动化，验证越不能省。 因为你不在现场时，错误也会自动化。

Memory 是循环的脊柱

Addy 在文里提到一个看起来很朴素、但非常重要的东西：外部记忆。

它可以是一个 Markdown 文件，也可以是 Linear board，甚至是一个很普通的状态表。关键是它必须活在单次对话之外。

原因很简单：模型会忘，repo 不会；聊天会结束，文件还在。

一个长期运行的 loop 至少要记住：

昨天发现了什么
哪些任务已经尝试过
哪些方案失败了
哪些检查通过了
哪些问题需要人类决策
下一轮应该从哪里继续

没有这个状态文件，所谓 loop 只是每天重复失忆。
有了它，agent 才能在多次运行之间接力。

这也是我觉得很多 AI 自动化项目跑不久的原因：大家拼命优化 prompt，却没有给系统一个可靠的记忆脊柱。

一个真实 loop 可以长什么样

把这些零件拼起来，一个早晨自动运行的 coding loop 大概长这样：

1
2
3
4
5
6
7
8
9


每天 9:00 automation 启动
 -> 调用 triage skill
 -> 读取昨天 CI、issues、recent commits
 -> 把发现写入 state.md 或 Linear
 -> 对值得处理的问题创建 worktree
 -> sub-agent A 起草修复
 -> sub-agent B 按项目 skill 和测试验证
 -> connector 创建 PR / 更新 ticket / 通知频道
 -> 未处理事项回到 triage inbox

你实际设计的是一条小型生产线。

最有意思的是，人类的工作没有消失，而是换了位置。你不再逐步提示每个 agent，而是在设计：

哪些任务值得自动发现
哪些检查必须硬性通过
哪些情况要中断给人
哪些状态要写下来
哪些权限不能交出去

这不是“少干活”那么简单。它更像从写脚本的人，变成设计操作系统的人。

Loop Engineering 的风险：你会更快地失控

Addy 的文章里有个很重要的提醒：这东西还早，而且 token 成本、质量下降、slop 都是真问题。

我会把风险拆成三类。

第一，验证风险。
没有可靠 verifier 的 loop，只是在自动制造自信的错误。

第二，理解债务。
loop 帮你产出越快，如果你不读、不理解、不复盘，你和代码库之间的距离就会越拉越大。

第三，认知投降。
最舒服的姿势是“让它跑吧”。但如果你只是为了逃避判断而设计 loop，它会把你的懒惰放大成系统性风险。

这就是 loop engineering 比 prompt engineering 更难的地方：prompt 错了，通常只坏一次；loop 错了，会重复坏。

Takeaway：先设计循环，再让 agent 跑

我觉得 Addy 这篇长文最值得带走的，不是某个工具功能，而是一种工作顺序：

先定义循环要解决什么问题。
再决定它如何发现任务。
给每个执行单元分配隔离环境。
把项目知识写成 skill。
用 connector 接入真实工具。
用 verifier 或 sub-agent 检查结果。
把状态写到对话之外。
最后才是：让 agent 开始跑。

换句话说，不要一上来就问“我该怎么 prompt 它”。先问：这个循环的输入、状态、验证、退出条件和人工接管点在哪里？

Loop engineering 不是把工程师拿掉。恰恰相反，它要求工程师更像工程师：少一点临场催促，多一点系统设计；少一点“帮我改一下”，多一点“这条生产线为什么可信”。

Build the loop. Stay the engineer.

参考资料

别再调教模型了：聪明人都在设计循环

Wed, 10 Jun 2026 00:00:00 +0000

Anthropic 的工程师 Boris Cherny 有一句话被反复引用：「我的工作就是写循环（My job is to write loops）。」

这句话第一次听像段子，听第二遍你会发现它在描述一个范式转移。过去我们用大模型，本能是去「调教」它——改 prompt、加 few-shot、写一长串「你必须……你不能……」的规则。但当模型本身已经足够强，真正决定产出质量的，往往不再是你怎么指挥它，而是你给它套了一个什么样的循环。

Anthropic 的 Lance Martin 最近分享了他用新一代 Claude 模型（内部代号 Fable 5，Mythos 级别）做实验的两个心得。两个都不是 prompt 技巧，而是关于怎么设计循环。下面我把它整理成中文，并加上我自己的一些体感。

为什么是「循环」，而不是「prompt」

先说清楚这个范式差在哪。

传统用法是一次性的：你写一个尽可能完美的 prompt，模型吐一个答案，好不好全看这一发。这本质上是在赌模型的「直觉」。

循环用法是迭代式的：你不再追求一发命中，而是给模型套一个「跑 → 拿反馈 → 自我纠正 → 再跑」的环，让它在一个评判标准（goal 或 rubric）上不断爬坡，直到达标才停。

	一次性 prompt	设计循环
你优化的对象	prompt 本身	环境与反馈信号
模型的角色	一次输出	反复试错、自我修正
决定质量的关键	你的措辞	评判标准设计得好不好
适合的任务	简单、确定性强	长程、可验证、能爬坡

Claude Code 里的 /goal 和 Claude Managed Agents（CMA）里的 Outcomes，就是把这套通用配方变成了你能直接用的原语。它们的本质都是：给环境注入一个反馈信号，让模型自己跟这个信号死磕。

第一招：自我纠正循环

新模型一个被反复验证的特性是——它特别擅长在循环里自我纠正。一个设计良好的 goal 或 rubric，相当于给 Claude 运行的环境加了一个反馈源：它跑一轮、通过 goal/rubric 收集反馈、修正自己，然后继续，直到标准被满足。

这里有一个最容易被忽略、却最关键的点：谁来当裁判。

直觉上你可能觉得，让模型自己检查自己的输出不就行了？但 Anthropic 的实验反复发现，模型在「自我批判」上是有系统性缺陷的——它很难客观地挑自己输出的毛病（Prithvi Rajasekaran 在 Anthropic 工程博客里专门写过这个现象）。

解法是：用一个独立的 verifier 子 agent 来打分，而不是让主 agent 自我批判。 因为打分是在一个独立的上下文窗口里完成的，不受主 agent 思路的污染，效果明显更好。CMA 的 Outcomes 就是帮你自动 spawn 一个 grader 子 agent 来做这件事。

下面这张表把两种实现方式拆得很清楚——无论是 Claude Code 的 /goal 还是 CMA 的 Outcomes，骨架都是一样的五件套：目标、裁判、循环、边界、退出条件。

注意「裁判（The judge）」这一行：/goal 用一个独立的 grader 模型（Haiku），CMA 用一个独立的 grader 子 agent——两者都刻意把评判放到了主流程之外。 这不是实现细节，这是这套方法能 work 的核心原因。

Parameter Golf：一个能跑 8 小时的玩具实验

Lance 用了一个开源的 ML 工程挑战 Parameter Golf 来测试：在 8 张 H100 上、10 分钟内，训练出一个能塞进 16MB 的最强模型。

这个挑战很像 Karpathy 的 autoresearch 项目——它考验的不是模型会不会写代码，而是一个 agent 能不能像研究员一样工作：改训练代码（一个 train_gpt.py 文件）、启动训练、轮询日志、读分数、然后决定下一个实验做什么。这是一个典型的长程、可验证、能爬坡的任务，正好是循环的主场。

他给了一个有 9 条可检查标准的 rubric（比如「跑一个 baseline」「跑 20 个实验」），让 Parameter Golf 最多跑 8 小时，由 Outcomes 的 grader 确认所有标准都满足后才允许 Claude 停手。结果：

Fable 5 把训练 pipeline 优化了约 6 倍于 Opus 4.7。 但比这个数字更有意思的是两个模型的实验风格差异：

Fable 5 敢下「结构性」的大注（比如改架构：TRAIN_SEQ_LEN=2048 带来 −0.0179、overlapped sliding-window eval 带来 −0.0207），而且有韧性——它甚至顶着一次量化回退继续推，最后拿到了最大的一次提升。
Opus 4.7 第一个实验拿了个小赢，然后几乎所有后续实验都在复制同一个模板：调一个标量、测一下、有正收益就留下。稳，但天花板低。

看图里那条蓝线（Fable 5）是怎么一个台阶一个台阶往下砸的，红线（Opus 4.7）则基本是平的——这就是「敢赌结构性改动」和「只敢调标量」的区别。循环给了模型试错的空间，而更强的模型会用这个空间去下更大的注。

第二招：记忆——跨会话的外层循环

如果说自我纠正是单次会话内的内层循环，那记忆就是跨会话的外层循环：Claude 在一次会话里把经验写进记忆，这些记忆能在未来的会话里被取回。

Lance 用 Continual Learning Bench 1.0 里的一个任务来测：给 agent 一个 SQL 数据库，让它回答一连串问题。每个问题是一个独立的 agent 会话，会话之间靠记忆来传递经验。他用 CMA 的记忆功能给每个 agent 挂载一个可跨会话共享的文件系统。

他观察到，有效使用记忆是有梯度的，从低到高是这么一条进阶链：

失败（fail）：做错了，把它记下来
调查（investigate）：在继续之前，搞清楚为什么错
验证（verify）：把诊断变成一个被核实过的事实
提炼（distill）：把验证结果升华成一条通用规则
查阅（consult）：下次直接读这条规则，而不是重新推导一遍

三个模型卡在了不同的台阶上，差距非常直观：

模型	卡在哪一步	表现
Sonnet 4.6	第 1 步（失败）	记忆只是一堆失败笔记和没验证的猜测（「也许是 prc 不是 prc_usd？」），几乎不回头查阅。得分 0.330，跟无记忆的 baseline 几乎没差
Opus 4.7	第 3 步（验证）	会建带不确定标记的 schema 参考（「可能是以分为单位？待验证」），但验证覆盖率低，只有 7–33%（中位数约 17%）。得分 0.700
Fable 5	走完全程	最强的几次运行里验证覆盖率高达 73%（30 题里验证了 22 题），并能把学到的东西提炼成通用规则，反哺未来任务。得分 0.839

看右边那张收敛曲线特别有感觉：带记忆的实线和无记忆的虚线，差距随着问题数累积越拉越大。 记忆不是「记下来」就完事了，关键在于你的 agent 能不能走完「失败 → 调查 → 验证 → 提炼 → 查阅」这条链。Sonnet 4.6 停在记笔记，Fable 5 在建知识库——这就是 0.330 和 0.839 的差距。

一个实操提醒：如果你的模型只走到第 1 步（像 Sonnet 4.6 那样），你需要给它针对具体任务的记忆指令来往上推。记忆这东西，模型越弱越需要你手把手教它怎么用。

我的体感：这其实是在重新分配「智能」

整理完这两个实验，我自己最大的感受是：Agent 工程正在从「怎么问」转向「怎么搭环境」。

过去一年我自己用 Claude Code 的体验也印证了这点。早期我花大量时间打磨 prompt，恨不得把每一步都写死。但模型一强，这套做法的边际收益就崩了——你写的规则越细，反而越限制它。真正让产出质变的，是另外两件事：

给它一个可验证的目标，然后闭嘴让它自己跑。/goal 这类原语的价值就在这——你定义「什么叫做完了」，剩下的交给循环。
让它管理自己的上下文，包括往记忆里写、从记忆里读。你不需要每次都把背景重新喂一遍。

Lance 那句话我很认同：与其直接 prompt 和 steer 模型，不如设计循环，让模型自己根据环境反馈做自我纠正（比如 /goal 或 Outcomes），并管理自己的上下文（比如记忆）。

换个角度说，你作为工程师的「智能」，正在从「写在 prompt 里」迁移到「写在循环结构里」。前者是一次性的指令，后者是可复利的系统。

Takeaway：下次构建 Agent，先问自己四个问题

如果你也想用循环的思路构建 agent，把下面四个问题贴在显示器上：

目标可验证吗？ 能不能写出一个 rubric / goal，让一个独立的裁判明确判断「做完了没有」？如果不能，先把任务拆到能验证为止。
裁判独立吗？ 千万别让主 agent 自我批判。用一个独立的 grader 模型或子 agent，在干净的上下文里打分。
循环有边界吗？ max_iterations、时间上限、退出条件——别让它无限跑。
记忆走完链路了吗？ 检查你的 agent 是停在「记笔记」，还是真的在「失败 → 调查 → 验证 → 提炼 → 查阅」。停在第一步的记忆约等于没有。

想上手的话，可以直接问最新版的 Claude Code——它能用内置的 /claude-api skill 告诉你 Fable 5 的 prompting 最佳实践、/goal、Claude Managed Agents 这些 API 特性怎么用。

说到底，写 prompt 是在赌一次直觉，设计循环是在搭一套能自我改进的系统。 模型越强，后者的回报越高。

参考资料

原推文：Lance Martin (@RLanceMartin) — Designing loops with Fable 5
Parameter Golf：开源 ML 工程挑战（16MB 模型，10 分钟，8×H100）
Continual Learning Bench 1.0：跨会话记忆基准

agent-skills 项目手册：六层架构的极致颗粒度参考

Thu, 28 May 2026 00:00:00 +0000

本手册是《从使用者到学习者：agent-skills 架构深度剖析与高手思维体系》的配套参考。文章型负责讲清楚"为什么"，本手册负责讲清楚"是什么、在哪里、如何展开"。

适用场景：回顾某一层的具体设计、查阅某个文件的角色、在自己的项目里复刻某一层时作为模板。

导读｜如何使用本手册

本手册按 agent-skills 的层级组织，每节自包含。建议查阅方式：

想了解整体结构 → 第 1 节《架构总览》
想查某一层 → 直接跳对应层级
想找设计模式 → 翻每节末尾的"经验与可复用模板"

每一节的固定结构：

定位与体量 — 该层在系统中的角色、文件数、行数
完整结构 — 目录树、文件清单
核心机制 — 关键文件逐项拆解
设计取舍 — 为什么这么设计
注意事项 — 容易踩的坑
经验与可复用模板

本手册的写法是客观第三人称。文章型《从使用者到学习者》是鬼哥的笔记体；如果你想读叙事版本，请翻文章型。

1. 架构总览

1.1 项目定位

agent-skills 是一个给 AI 编程代理使用的工程方法论文件包，由 Google 资深工程师 Addy Osmani 开源在 github.com/addyosmani/agent-skills。它不是工具、不是框架、不是 SDK——它是一组结构化的 Markdown 文件 + 少量 Bash hook 脚本，靠 Claude Code 这类 AI agent runtime 的"skill 自动加载"+“slash command”+“hook"机制生效。

1.2 完整目录树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


agent-skills/
├── CLAUDE.md 44 行
├── README.md （项目说明，本手册不展开）
│
├── skills/ 21 个 SKILL.md
│ ├── using-agent-skills/SKILL.md 180+ 行（meta-skill）
│ ├── spec-driven-development/SKILL.md 201 行
│ ├── interview-me/SKILL.md
│ ├── idea-refine/SKILL.md
│ ├── planning-and-task-breakdown/SKILL.md
│ ├── incremental-implementation/SKILL.md
│ ├── test-driven-development/SKILL.md
│ ├── context-engineering/SKILL.md
│ ├── source-driven-development/SKILL.md
│ ├── doubt-driven-development/SKILL.md
│ ├── frontend-ui-engineering/SKILL.md
│ ├── api-and-interface-design/SKILL.md
│ ├── browser-testing-with-devtools/SKILL.md
│ ├── debugging-and-error-recovery/SKILL.md
│ ├── code-review-and-quality/SKILL.md
│ ├── code-simplification/SKILL.md
│ ├── security-and-hardening/SKILL.md
│ ├── performance-optimization/SKILL.md
│ ├── git-workflow-and-versioning/SKILL.md
│ ├── ci-cd-and-automation/SKILL.md
│ ├── deprecation-and-migration/SKILL.md
│ ├── documentation-and-adrs/SKILL.md
│ └── shipping-and-launch/SKILL.md
│
├── agents/ 3 个 persona + 1 README
│ ├── README.md 120 行（编排宪法）
│ ├── code-reviewer.md 97 行
│ ├── security-auditor.md 101 行
│ └── test-engineer.md 95 行
│
├── references/ 5 个支撑文件（无 frontmatter）
│ ├── accessibility-checklist.md 160 行
│ ├── performance-checklist.md 153 行
│ ├── security-checklist.md 134 行
│ ├── testing-patterns.md 236 行
│ └── orchestration-patterns.md 370 行
│
├── hooks/ 3 个 hook + 文档 + 测试
│ ├── hooks.json 14 行（插件级注册）
│ ├── session-start.sh 24 行
│ ├── session-start-test.sh 46 行
│ ├── sdd-cache-pre.sh 106 行
│ ├── sdd-cache-post.sh 135 行
│ ├── SDD-CACHE.md 167 行（文档）
│ ├── simplify-ignore.sh 302 行
│ ├── simplify-ignore-test.sh 247 行
│ └── SIMPLIFY-IGNORE.md 90 行（文档）
│
├── .claude/commands/ 7 个 slash command
│ ├── spec.md 17 行
│ ├── plan.md 16 行
│ ├── build.md 19 行
│ ├── test.md 20 行
│ ├── review.md 17 行
│ ├── code-simplify.md 23 行
│ └── ship.md 73 行（fan-out 编排器）
│
└── docs/ （配置指南，本手册不展开）

1.3 六层架构 + 横切 hooks

层	名称	职责	加载时机	数量	约定体量
Layer 0	CLAUDE.md	仓库总入口（NAV）	always in context	1	44 行
Layer 1	using-agent-skills	路由 + 行为宪法	session start hook 注入	1	~180 行
Layer 2	.claude/commands/	用户显式入口（WHEN）	用户 `/` 触发	7	15-75 行
Layer 3	agents/	视角与输出格式（WHO）	command 派发或显式调用	3	~100 行
Layer 4	skills/	流程方法论（HOW）	描述匹配或显式调用	21	100-300 行
Layer 5	references/	清单与模式（DATA）	skill 文件指向后按需 Read	5	134-370 行
Layer X	hooks/	横切干预（AOP）	事件触发	3	24-302 行

1.4 跨层引用关系网

出方	入方	引用方式
CLAUDE.md	skills/*	列名 + schema 强制
using-agent-skills	skills/*	决策树 + 名称
commands/*	skills/*	`Invoke the agent-skills:X skill`
commands/ship.md	agents/*	`subagent_type: code-reviewer`
agents/*	skills/*	通过 README 中的 Composition 块
agents/*	references/orchestration-patterns.md	文本路径
skills/test-driven-development	references/testing-patterns.md	文本路径
skills/shipping-and-launch	references/{security,performance,accessibility}-checklist.md	文本路径
skills/frontend-ui-engineering	references/accessibility-checklist.md	文本路径
skills/code-review-and-quality	references/{security,performance}-checklist.md	文本路径
skills/security-and-hardening	references/security-checklist.md	文本路径
skills/performance-optimization	references/performance-checklist.md	文本路径
skills/doubt-driven-development	references/orchestration-patterns.md	文本路径（×2）
hooks/session-start.sh	skills/using-agent-skills	运行时 cat 注入
hooks/sdd-cache-*.sh	skills/source-driven-development	拦截 WebFetch
hooks/simplify-ignore.sh	skills/code-simplification	拦截 Read/Edit/Write

1.5 token 加载预算

加载阶段	内容	体量
Session 启动后立刻	CLAUDE.md	44 行
Session 启动 hook 注入	using-agent-skills	~180 行
用户触发 `/command`	对应命令 + 关联 skill	15-75 + 100-300 行
AI 决策时按需读取	具体 skill	100-300 行
AI 执行 skill 时按需读取	关联 reference	134-370 行

整套设计的核心：总在 context 的东西必须极短，越深的层加载得越少。

2. Layer 0｜CLAUDE.md

2.1 定位与体量

文件路径：仓库根目录 CLAUDE.md
行数：44 行
加载时机：所有 Claude Code session always in context
角色：仓库的"总入口 / 物理导航 / schema 强制者”
不做的事：不重复任何下游内容、不教学、不解释动机

2.2 完整结构（5 段）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# agent-skills

This is the agent-skills project — a collection of production-grade engineering skills for AI coding agents.

## Project Structure
[ASCII 目录树，6 行]

## Skills by Phase
[6 个阶段 + 21 个 skill 名]

## Conventions
[6 条 schema 约束]

## Commands
[2 条：npm test 不适用 + Validate 方式]

## Boundaries
[3 条：1 Always + 2 Never]

2.3 五段逐节拆解

2.3.1 Section 1: Project Structure

1
2
3
4
5
6


skills/ → Core skills (SKILL.md per directory)
agents/ → Reusable agent personas (code-reviewer, test-engineer, security-auditor)
hooks/ → Session lifecycle hooks
.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship)
references/ → Supplementary checklists (testing, performance, security, accessibility)
docs/ → Setup guides for different tools

设计细节：

每行右侧括号里直接列名：agents/ 后面列出三个 persona 名，commands/ 直接列出 7 个命令——AI 不需要再 ls 一次目录
隐式优先级：skills/ 排第一，docs/ 排最后——AI 会先把注意力放到上面
.claude/commands/ 用全路径：因为它不在仓库根目录的一级——避免 AI 找错路径

2.3.2 Section 2: Skills by Phase

1
2
3
4
5
6


Define: interview-me, idea-refine, spec-driven-development
Plan: planning-and-task-breakdown
Build: incremental-implementation, test-driven-development, ..., api-and-interface-design
Verify: browser-testing-with-devtools, debugging-and-error-recovery
Review: code-review-and-quality, code-simplification, ..., performance-optimization
Ship: git-workflow-and-versioning, ..., shipping-and-launch

对齐关系： 这一段与 using-agent-skills/SKILL.md 的路由树完全对齐——都是 6 个阶段、同样的命名、同样的归属。

已知不一致：code-simplification 出现在本节的 Review 阶段，但 using-agent-skills 决策树里没有出现。这是仓库中存在的真实不一致点。

2.3.3 Section 3: Conventions（核心 schema）

1
2
3
4
5
6


- Every skill lives in `skills/<name>/SKILL.md`
- YAML frontmatter with `name` and `description` fields
- Description starts with what the skill does (third person), followed by trigger conditions ("Use when...")
- Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification
- References are in `references/`, not inside skill directories
- Supporting files only created when content exceeds 100 lines

6 条规则可以拆为三类：

类型	规则	作用
文件位置	“Every skill lives in skills//SKILL.md”	物理约束
文件头部	“YAML frontmatter with name and description”	frontmatter 约束
文件头部	“Description starts with…”	描述写法
文件结构	“Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification”	核心 schema
跨文件	“References are in references/, not inside skill directories”	分层约束
跨文件	“Supporting files only created when content exceeds 100 lines”	拆分阈值

第 4 条是真正的核心——它定义了 SKILL.md 的 6 段式结构，整个仓库 21 个 skill 必须都长这样。

例外：using-agent-skills/SKILL.md 本身不遵守这个 schema，它有自己的特殊段（Skill Discovery、Core Operating Behaviors、Failure Modes、Lifecycle Sequence），见 Layer 1。

2.3.4 Section 4: Commands

1
2


- `npm test` — Not applicable (this is a documentation project)
- Validate: Check that all SKILL.md files have valid YAML frontmatter with name and description

只有 2 行，设计意图：

显式声明 “Not applicable”：很多模板会留空，导致 AI 浪费时间猜测；这里直接告诉 AI “别想跑 npm test”
替代验证方式：给出仓库实际的"测试"是 frontmatter 校验——这是文档型仓库的特殊做法

2.3.5 Section 5: Boundaries

1
2
3


- Always: Follow the skill-anatomy.md format for new skills
- Never: Add skills that are vague advice instead of actionable processes
- Never: Duplicate content between skills — reference other skills instead

3 条规则，其中：

规则	防止什么
Always: skill-anatomy 格式	防止贡献者发明新结构
Never: vague advice	防止 skill 变成空话
Never: duplicate content	防止跨 skill 内容漂移

第 3 条 “Never: Duplicate content” 是整个仓库的"指针架构"根源——它直接驱动了：

commands 委托给 skills（不复制方法论）
skills 委托给 references（不内嵌清单）
personas 委托给 skills（不复制流程）
hooks 委托给协议（不发明新通信机制）

2.4 设计取舍

取舍 1: CLAUDE.md 是"导航层"，不是"内容层"

最关键的设计判断：CLAUDE.md 不重复任何下游内容。

CLAUDE.md 每次对话都会自动加载到 context——每多写一行就有 N 次重复的 token 成本。所以它必须极致克制。

取舍 2: 三段式 Boundary 而非四段式

spec-driven-development 自身倡导三层 boundary（Always / Ask first / Never），但 CLAUDE.md 只用了两层（Always / Never），省掉了 Ask first。

可能的解释：CLAUDE.md 定义的是"贡献新 skill 时不可协商的约束"，没有"协商空间"；“Ask first” 适合业务边界，不适合结构约束。

2.5 注意事项

Conventions 第 4 条的 schema 不允许例外——但 using-agent-skills 自己破坏了它。这种"meta-skill 的例外"没有在 CLAUDE.md 明确声明，是隐性约定
“skill-anatomy.md” 引用没给出路径——AI 找它需要靠 grep
Skills by Phase 与决策树不一致（code-simplification 缺失）——维护时需要双地更新

2.6 经验与可复用模板

可复用的 CLAUDE.md 模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# [Project Name]

[一句话定位，不超过 30 字]

## Project Structure
[ASCII 树，每行一个目录 + 一句话描述，最多 8 行]

## [Categorical Index]
[按场景/阶段/类型给关键资产的索引，列表形式]

## Conventions
- [文件位置约束]
- [文件头部约束]
- [文件内容约束]
- [跨文件约束]

## Commands
- [跑测试的命令]（或显式声明 "Not applicable"）
- [仓库特有的验证方式]

## Boundaries
- Always: [硬规则]
- Ask first: [软规则] ← 可选
- Never: [禁止]

核心原则：

总长度 < 60 行
只放"AI 入仓必须知道"的信息
不放教程、不放示例、不放动机说明
任何超过一行的内容都应该拆到下游文件

3. Layer 1｜using-agent-skills

3.1 定位与体量

文件路径：skills/using-agent-skills/SKILL.md
行数：~180 行
加载时机：每个新会话由 hooks/session-start.sh 强制注入
角色：路由器 + 行为宪法（meta-skill）
特殊性：它是唯一一个不遵守 CLAUDE.md 6 段式 schema 的 skill

3.2 双重职责

3.2.1 职责一：Skill Router（路由器）

完整决策树（位于 SKILL.md 第 14-39 行）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


Task arrives
 │
 ├── Don't know what you want yet? ──────→ interview-me
 ├── Have a rough concept, need variants? → idea-refine
 ├── New project/feature/change? ──→ spec-driven-development
 ├── Have a spec, need tasks? ──────→ planning-and-task-breakdown
 ├── Implementing code? ────────────→ incremental-implementation
 │ ├── UI work? ─────────────────→ frontend-ui-engineering
 │ ├── API work? ────────────────→ api-and-interface-design
 │ ├── Need better context? ─────→ context-engineering
 │ ├── Need doc-verified code? ───→ source-driven-development
 │ └── Stakes high / unfamiliar code? ──→ doubt-driven-development
 ├── Writing/running tests? ────────→ test-driven-development
 │ └── Browser-based? ───────────→ browser-testing-with-devtools
 ├── Something broke? ──────────────→ debugging-and-error-recovery
 ├── Reviewing code? ───────────────→ code-review-and-quality
 │ ├── Security concerns? ───────→ security-and-hardening
 │ └── Performance concerns? ────→ performance-optimization
 ├── Committing/branching? ─────────→ git-workflow-and-versioning
 ├── CI/CD pipeline work? ──────────→ ci-cd-and-automation
 ├── Writing docs/ADRs? ───────────→ documentation-and-adrs
 └── Deploying/launching? ─────────→ shipping-and-launch

设计细节：

选择	理由
树形结构而非列表	强迫读者走唯一路径，列表会让人想选多个
父节点 → 子节点细化	`实现代码` 下嵌套 UI/API/Context，符合 AI 的层次推理习惯
问句触发而非任务描述	“Something broke?” 比 “debugging task” 更贴近真实对话

已知盲区：

code-simplification 没有出现在树里（只在 Quick Reference 表里）
deprecation-and-migration 没有出现在树里

3.2.2 职责二：Core Operating Behaviors（行为宪法）

6 条不可协商的行为约束：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


### 1. Surface Assumptions
[要求 AI 在实施前显式列假设]

### 2. Manage Confusion Actively
[遇到矛盾必须停下问，不能猜]

### 3. Push Back When Warranted
[拒绝奉承，发现问题直接说出来]

### 4. Enforce Simplicity
[主动抵抗过度工程化]

### 5. Maintain Scope Discipline
[只动被要求改的代码]

### 6. Verify, Don't Assume
[必须有可验证证据]

每一条都精确对抗一个 AI 缺陷：

行为	对抗的 AI 缺陷
1. Surface Assumptions	“静默填充"歧义
2. Manage Confusion Actively	矛盾时"就近取一”
3. Push Back	奉承倾向（sycophancy）
4. Enforce Simplicity	过度工程化倾向
5. Scope Discipline	“顺手重构"倾向
6. Verify, Don’t Assume	“看起来对就完成了"倾向

每一条都有：正例/反例对比 + 具体的判断触发词（如 “quantify when possible”、“Would a staff engineer say…"）。这是让约束真正可执行的关键。

3.3 Failure Modes（10 条失败模式）

文件末尾还有一份 10 条 Failure Modes（位于 SKILL.md 第 110-123 行），与 6 条行为形成镜像：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


1. Making wrong assumptions without checking
2. Not managing your own confusion — plowing ahead when lost
3. Not surfacing inconsistencies you notice
4. Not presenting tradeoffs on non-obvious decisions
5. Being sycophantic ("Of course!") to approaches with clear problems
6. Overcomplicating code and APIs
7. Modifying code or comments orthogonal to the task
8. Removing things you don't fully understand
9. Building without a spec because "it's obvious"
10. Skipping verification because "it looks right"

镜像关系：

行为 1（Surface Assumptions）→ 失败 1+3
行为 3（Push Back）→ 失败 5
行为 5（Scope Discipline）→ 失败 7+8+9
失败 4（不呈现 tradeoff）没有对应的正面行为 ← 这是一个缺口

分工：

Common Rationalizations → 处理"AI 的借口”（主动跳过的想法）
10 条失败模式 → 处理"AI 的症状”（已经在跳过的迹象）

3.4 Skill Rules（4 条）

1
2
3
4


1. **Check for an applicable skill before starting work.**
2. **Skills are workflows, not suggestions.**
3. **Multiple skills can apply.**
4. **When in doubt, start with a spec.**

3.5 Lifecycle Sequence

文件提供了一份"完整功能"的典型 skill 调用序列（位于 SKILL.md 第 137-153 行）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


1. interview-me → Extract what the user actually wants
2. idea-refine → Refine vague ideas
3. spec-driven-development → Define what we're building
4. planning-and-task-breakdown → Break into verifiable chunks
5. context-engineering → Load the right context
6. source-driven-development → Verify against official docs
7. incremental-implementation → Build slice by slice
8. doubt-driven-development → Cross-examine non-trivial decisions
9. test-driven-development → Prove each slice works
10. code-review-and-quality → Review before merge
11. git-workflow-and-versioning → Clean commit history
12. documentation-and-adrs → Document decisions
13. shipping-and-launch → Deploy safely

关键注释：“Not every task needs every skill. A bug fix might only need: debugging-and-error-recovery → test-driven-development → code-review-and-quality.”

这一行避免了 AI 死板地套流程。

3.6 Quick Reference 表

文件最后是一份 Quick Reference 表（位于 SKILL.md 第 159-180 行），列出全部 21 个 skill 的 phase + name + 一句话总结。这是仓库中唯一一份完整覆盖所有 skill 的速查表。

3.7 设计取舍

取舍 1: 不遵守自己倡导的 schema

using-agent-skills 本身不遵守 CLAUDE.md 第 30 行的 6 段式 schema。它有：

Overview
Skill Discovery（独有）
Core Operating Behaviors（独有）
Failure Modes to Avoid（独有）
Skill Rules（独有）
Lifecycle Sequence（独有）
Quick Reference（独有）

理由：meta-skill 是元层，不是被治理对象，可以例外。但这一例外没在 CLAUDE.md 显式声明。

取舍 2: 路由 + 治理放一起

为什么不拆成两个 skill？因为它们的服务对象重叠——都是为了让 AI 在每个任务的开始就做对决策。拆开后 AI 需要同时加载两份。

3.8 注意事项

决策树缺失 code-simplification 和 deprecation-and-migration——AI 走树时这两个 skill 可能被忽略
6 条行为是"硬约束”，但文件没有声明优先级冲突时怎么办（例如"Push Back" vs “Scope Discipline”——发现 scope 外问题该不该指出？）
Lifecycle Sequence 容易被 AI 当成必走流程，但作者明确写了"Not every task needs every skill"

3.9 经验与可复用模板

Meta-skill 应该包含的元素

1
2
3
4
5
6
7
8


✓ 路由机制（让 AI 知道"去哪里"）
✓ 全局约束（让 AI 知道"怎么做"）
✓ 失效模式（让 AI 知道"避什么"）
✓ 场景化示例（防止过度/不足应用）

✗ 不要包含具体的实现步骤（那是子 skill 的职责）
✗ 不要包含特定技术的建议（会过时）
✗ 不要包含跨越多个 skill 的冗余内容（维护负担）

4. Layer 2｜.claude/commands/

4.1 定位与体量

目录路径：.claude/commands/
文件数：7 个 .md 文件
行数范围：15-75 行（除 ship 外均极度克制）
加载时机：用户输入 /<name> 时触发
角色：用户显式入口 + skill 激活快捷键

4.2 完整命令清单

命令	行数	主调 skill	模式
`/spec`	17	spec-driven-development	单 skill 包装
`/plan`	16	planning-and-task-breakdown	单 skill 包装
`/build`	19	incremental-implementation + TDD	双 skill 并联
`/test`	20	TDD（+ browser-testing 条件）	主 skill + 兜底
`/review`	17	code-review-and-quality	单 skill 包装
`/code-simplify`	23	code-simplification	单 skill 包装
`/ship`	73	shipping-and-launch + 3 personas	Fan-out 编排器

4.3 命令文件结构

所有 7 个命令文件遵循同一模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


---
description: <动词短语 + 核心交付物，一句话不超过 80 字符>
---

Invoke the agent-skills:<skill-name> skill[, alongside agent-skills:<secondary>].

[一段说明：这个命令做什么，为什么用这个 skill]

[步骤列表，4-8 步]

[Save the output to <path>.]

Frontmatter 的极简主义： 7 个命令的 frontmatter 都只有一个字段 description。对比 Claude Code 支持的完整字段（allowed-tools、argument-hint、model、disable-model-invocation），这里全部省略。

4.4 四种命令模式

4.4.1 模式 1：单 skill 包装（5 个）

/spec、/plan、/review、/code-simplify 都是这种形态。例：spec.md 完整内容（17 行）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


---
description: Start spec-driven development — write a structured specification before writing code
---

Invoke the agent-skills:spec-driven-development skill.

Begin by understanding what the user wants to build. Ask clarifying questions about:
1. The objective and target users
2. Core features and acceptance criteria
3. Tech stack preferences and constraints
4. Known boundaries (what to always do, ask first about, and never do)

Then generate a structured spec covering all six core areas: objective, commands, project structure, code style, testing strategy, and boundaries.

Save the spec as SPEC.md in the project root and confirm with the user before proceeding.

4.4.2 模式 2：双 skill 并联（/build）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


Invoke the agent-skills:incremental-implementation skill alongside agent-skills:test-driven-development.

Pick the next pending task from the plan. For each task:

1. Read the task's acceptance criteria
2. Load relevant context (existing code, patterns, types)
3. Write a failing test for the expected behavior (RED)
4. Implement the minimum code to pass the test (GREEN)
5. Run the full test suite to check for regressions
6. Run the build to verify compilation
7. Commit with a descriptive message
8. Mark the task complete and move to the next one

If any step fails, follow the agent-skills:debugging-and-error-recovery skill.

关键设计：/build 把"实现"和"测试"绑成一个动作，强制 RED-GREEN-REFACTOR 循环。单独跑实现不写测试是常见反模式，命令层在源头阻止它。

4.4.3 模式 3：主 skill + 条件兜底（/test）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


Invoke the agent-skills:test-driven-development skill.

For new features:
1. Write tests that describe the expected behavior (they should FAIL)
2. Implement the code to make them pass
3. Refactor while keeping tests green

For bug fixes (Prove-It pattern):
1. Write a test that reproduces the bug (must FAIL)
2. Confirm the test fails
3. Implement the fix
4. Confirm the test passes
5. Run the full test suite for regressions

For browser-related issues, also invoke agent-skills:browser-testing-with-devtools to verify with Chrome DevTools MCP.

最后一句是条件式 escalation——“如果是浏览器问题，再加挂这个 skill”。

4.4.4 模式 4：Fan-out 编排器（/ship）

这是 7 个命令里唯一超过 70 行的，因为它做的事在 skill 里做不优雅：并行调度 3 个 subagent。

完整 Phase A 引文：

Spawn three subagents concurrently using the Agent tool. Issue all three Agent tool calls in a single assistant turn so they execute in parallel — sequential calls defeat the purpose of this command.

3 个 subagent：

code-reviewer — 五维 review（correctness / readability / architecture / security / performance）
security-auditor — OWASP Top 10 + secrets + auth/authz + CVEs
test-engineer — 测试覆盖分析

关键约束：

三个 Agent 调用必须在一个 assistant turn 里发出（否则失去并行性）
Subagents cannot spawn other subagents（平台约束）
三个 subagent 各自返回 report，主 agent 在 Phase B 合并

Persona 优先级： “If you’ve defined your own code-reviewer, security-auditor, or test-engineer in .claude/agents/ or ~/.claude/agents/, those take precedence over this plugin’s versions.”

Phase B 合并维度（6 项）：

Code Quality
Security
Performance
Accessibility（不由 personas 覆盖，主 agent 直接处理）
Infrastructure
Documentation

Phase C 输出模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


## Ship Decision: GO | NO-GO

### Blockers (must fix before ship)
- [Source persona: Critical finding + file:line]

### Recommended fixes (should fix before ship)
- [Source persona: Important finding + file:line]

### Acknowledged risks (shipping anyway)
- [Risk + mitigation]

### Rollback plan
- Trigger conditions: ...
- Rollback procedure: ...
- Recovery time objective: ...

### Specialist reports (full)
- [code-reviewer report]
- [security-auditor report]
- [test-engineer report]

5 条强制规则：

Phase A 三个 persona 并行运行，绝不串行
Persona 不能互相调用
Rollback plan 在 GO 决策前是必须的
任何 Critical finding 默认 NO-GO，除非用户显式接受风险
Skip fan-out 的条件（必须同时满足）：改动 ≤ 2 个文件、diff < 50 行、不涉及 auth/payments/data access/config/env

4.5 Command vs Skill 的本质区别

维度	Skill	Command
谁加载	自动/按需	用户显式触发
内容	完整方法论（100-300 行）	调用配方（15-25 行）
写给谁看	AI 模型	模型 + 人（用户要 type）
触发方式	描述匹配	`/` 前缀精确匹配
复用方向	横向通用	项目特定

4.6 命令覆盖图

有命令的 7 个 skill：

1
2
3
4
5
6
7


spec-driven-development → /spec
planning-and-task-breakdown → /plan
incremental-implementation → /build (与 TDD 联调)
test-driven-development → /test
code-review-and-quality → /review
code-simplification → /code-simplify
shipping-and-launch → /ship (并联 3 personas)

没有命令的 15 个 skill：

1
2
3
4
5
6
7
8


interview-me idea-refine
context-engineering source-driven-development
doubt-driven-development frontend-ui-engineering
api-and-interface-design browser-testing-with-devtools
debugging-and-error-recovery security-and-hardening
performance-optimization git-workflow-and-versioning
ci-cd-and-automation deprecation-and-migration
documentation-and-adrs

判定逻辑：

有命令 = 用户高频显式触发 + 是多 skill 组合的入口
无命令 = 自动激活更合适 / 是子能力 / 是兜底能力

4.7 命令命名的语义学

每个命令名都对应一个具体的可交付物：

命令	隐含承诺产物
`/spec`	SPEC.md
`/plan`	tasks/plan.md + tasks/todo.md
`/build`	代码 + 测试 + commit
`/test`	passing tests
`/review`	review report
`/code-simplify`	simplified diff
`/ship`	GO/NO-GO + rollback plan

没有 /think、/explore 这种没有产物的命令——这是一种纪律。

4.8 注意事项

/test 与 /build 内部都调用 TDD——存在重叠。连续跑 /build 时 TDD skill 会被重复激活
/ship 的 skip-fan-out 条件可能弱化纪律——任何上线都应该跑完整 checklist，但这个 “skip” 选项允许小改动跳过
没有 /debug 命令——debugging-and-error-recovery 只能在 /build 失败时被调用，用户独立遇到 bug 想触发 prove-it 流程时没有专用命令
没有 /docs 命令——documentation-and-adrs 没有显式入口，文档容易被遗忘

4.9 可复用 Command 模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


---
description: <动词短语 + 核心交付物，一句话不超过 80 字符>
---

Invoke the agent-skills:<skill-name> skill[, alongside agent-skills:<secondary>].

<一段说明：这个命令做什么，为什么用这个 skill>

[For <case-A>:]
1. <step>
2. <step>

[For <case-B>:]
1. <step>
2. <step>

[If <condition> fails, follow agent-skills:<fallback-skill> skill.]

Save the output to <path>.

5. Layer 3｜agents/

5.1 定位与体量

目录路径：agents/
文件数：3 个 persona + 1 个 README
总行数：413 行
加载时机：作为 subagent system prompt（被 command 或用户调用时）
角色：定义"WHO"——视角与输出格式

5.2 完整文件清单

文件	行数	角色
README.md	120	编排宪法 / 决策矩阵 / 反例
code-reviewer.md	97	资深 Staff Engineer 视角
security-auditor.md	101	安全工程师视角
test-engineer.md	95	QA 工程师视角

5.3 Persona 文件的 7 段固定结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


---
name: <persona-name>
description: <一句话角色描述>
---

# <Title>

You are an experienced <Role>... ← (1) 角色设定（第一人称）

## <Framework Name> ← (2) 评审维度
### 1. <Dimension 1> ...
### 2. <Dimension 2> ...

## Output Format ← (3) 输出分级
[Critical / Important / Suggestion 三级]

## <Report> Output Template ← (4) 输出模板
[Markdown 结构]

## Rules ← (5) 行为规则
[6-7 条 numbered list]

## Composition ← (6) 接线说明
- Invoke directly when: ...
- Invoke via: ...
- Do not invoke from another persona.

5.4 三个 Persona 详解

5.4.1 code-reviewer.md

五维评审框架：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


### 1. Correctness
- Does the code do what the spec/task says?
- Are edge cases handled (null, empty, boundary, error)?
- Do tests actually verify the behavior?
- Race conditions, off-by-one, state inconsistencies?

### 2. Readability
- Can another engineer understand without explanation?
- Names descriptive and consistent?
- Control flow straightforward (no deep nesting)?
- Well-organized (related code grouped)?

### 3. Architecture
- Follows existing patterns or introduces new ones?
- Module boundaries maintained?
- Abstraction level appropriate?
- Dependencies flowing in the right direction?

### 4. Security
- Input validated and sanitized at boundaries?
- Secrets kept out of code, logs, version control?
- Auth/authz checked where needed?
- Queries parameterized?

### 5. Performance
- N+1 query patterns?
- Unbounded loops or fetching?
- Sync operations that should be async?
- Missing pagination?

输出分级（三档）：

Critical — 必须 fix（安全漏洞、数据丢失、坏功能）
Important — 应该 fix（缺测试、错抽象、差错误处理）
Suggestion — 考虑改进（命名、风格、可选优化）

Review Output Template：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


## Review Summary

**Verdict:** APPROVE | REQUEST CHANGES

**Overview:** [1-2 sentences]

### Critical Issues
- [File:line] [Description and recommended fix]

### Important Issues
- [File:line] [Description and recommended fix]

### Suggestions
- [File:line] [Description]

### What's Done Well
- [Positive observation — always include at least one]

### Verification Story
- Tests reviewed: [yes/no]
- Build verified: [yes/no]
- Security checked: [yes/no]

6 条 Rules：

Review the tests first
Read the spec or task description before reviewing code
Every Critical and Important finding should include a specific fix recommendation
Don’t approve code with Critical issues
Acknowledge what’s done well
If uncertain, say so

5.4.2 security-auditor.md

职责：OWASP Top 10 + 漏洞检测 + 威胁建模。

7 条 Rules：

1
2
3
4
5
6
7


1. Focus on exploitable vulnerabilities, not theoretical risks
2. Every finding must include a specific, actionable recommendation
3. Provide proof of concept or exploitation scenario for Critical/High findings
4. Acknowledge good security practices
5. Check the OWASP Top 10 as a minimum baseline
6. Review dependencies for known CVEs
7. Never suggest disabling security controls as a "fix"

Composition：

Invoke directly when: 用户想要安全焦点的审查
Invoke via: /ship（fan-out 并联）或未来的 /audit
Do not invoke from another persona

5.4.3 test-engineer.md

职责：测试策略 + 覆盖分析 + Prove-It 模式。

典型用例： 测试漏洞分析（happy path / edge cases / error paths / concurrency）。

5.5 Composition 块——每个 Persona 的"接线说明"

每个 persona 末尾的固定段：

1
2
3
4
5


## Composition

- **Invoke directly when:** <用户什么时候直接调我>
- **Invoke via:** <哪些 command 包裹我>
- **Do not invoke from another persona.** <显式宣告"我不能被别的 persona 调">

好处：

自文档化，新人读 persona 文件就知道它在系统中的位置
防止架构腐烂——加新 persona 时必须思考接线方式
减少误用——把"不能被 persona 调"显式写出

5.6 README.md 的编排宪法

5.6.1 三层定义

1
2
3


Skill = HOW (workflow with steps and exit criteria)
Persona = WHO (role with perspective and output format)
Command = WHEN (user-facing entry point)

5.6.2 决策矩阵

1
2
3
4
5


Is the work a single perspective on a single artifact?
├── Yes → Direct persona invocation
└── No → Are the sub-tasks independent?
 ├── Yes → Slash command with parallel fan-out (e.g. /ship)
 └── No → Sequential slash commands (/spec → /plan → /build → /test → /review)

5.6.3 核心铁律

The user (or a slash command) is the orchestrator. Personas do not call other personas.

这条规则在 README 中被重复 5 次以上，背后三层原因：

平台约束：Claude Code 的 subagent 系统禁止递归（subagent 不能 spawn subagent）
信息损耗：每多一层 persona 转发就多一次"用自己语言重述"
价值密度：纯路由层无领域价值，应该让 command 来做

5.6.4 反例教学

README 专门画了一段刻意的反例：

1
2
3
4
5
6
7


/work-on-pr → meta-orchestrator
 ↓ "this needs a review"
 code-reviewer
 ↓
 meta-orchestrator (paraphrases result)
 ↓
 user

Why this fails:

Pure routing layer with no domain value
Adds two paraphrasing hops → information loss + 2× token cost
The user already knows they want a review; let them call /review directly
Replicates work that slash commands and AGENTS.md intent-mapping already do

5.6.5 Subagents vs Agent Teams

模式	触发	互相通信	用途
Subagents（默认）	`subagent_type: code-reviewer`	不能	各自跑 → 返回 report
Agent Teams（实验）	`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`	可以	competing-hypothesis 调试

关键设计：同一个 persona 文件无需修改即可工作在两种模式下。

5.6.6 Plugin 限制

Plugin agents do not support hooks, mcpServers, or permissionMode frontmatter — those fields are silently ignored.

5.7 Persona vs Skill 的本质差异

维度	Skill	Persona
Frontmatter	`name` + `description`	完全相同
语气	命令式（“Do X”）	第一人称（“You are X”）
用途	AI 执行任务的方法论	作为 subagent 的 system prompt
关注点	过程（process）	视角 + 输出格式
长度	100-300 行	90-100 行
是否有 Output Template	一般没有	必须有

5.8 为什么只有 3 个 persona？

3 个 persona 对应 /ship 的 fan-out 三个独立视角：

1
2
3


Code quality (functional) ← code-reviewer
Security (adversarial) ← security-auditor
Tests (coverage) ← test-engineer

判定标准：

必须是独立视角（不能从其他视角派生）
必须有可并行的工作内容
必须有结构化的输出便于 merge

frontend-ui、performance、accessibility 没成为 persona 的原因：

performance：和 code-reviewer 的 #5 dimension 重叠
accessibility：在 frontend-ui skill 里覆盖，更像 checklist 而不是视角
frontend-ui-engineer：是技术领域，不是"评审视角"

5.9 注意事项

Output Template 是为 fan-out 编排服务的——如果让随机的 AI prompt 生成 review，输出格式不固定，merge 就变成解析地狱
Persona 与 Skill 共用相同的 frontmatter 字段——但生效语义不同，容易混淆
Plugin 模式不支持 hooks / mcpServers / permissionMode——这些字段会被静默忽略

5.10 经验与可复用模板

新 Persona 判定标准

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


判定要不要新建 persona：
 ✓ 是一个独立视角（不能从其他视角派生）
 ✓ 有可结构化的输出（可被 merge）
 ✓ 至少被一个 command 复用（否则用户直接调 skill）
 ✓ 不是"路由器"或"meta"层

Persona 文件必须包含：
 ✓ name + description frontmatter
 ✓ 第一人称角色设定
 ✓ Framework / 评估维度
 ✓ Output Template（结构化的）
 ✓ Rules（行为规则）
 ✓ Composition 块（接线说明）

Persona 文件不应包含：
 ✗ 调用其他 persona 的逻辑
 ✗ 大段流程步骤（应该写到 skill 里）
 ✗ 大段数据/清单（应该写到 references 里）

6. Layer 4｜skills/

6.1 定位与体量

目录路径：skills/<name>/SKILL.md
文件数：21 个
总体量：每个 SKILL.md 100-300 行
加载时机：描述匹配（自动）或显式调用
角色：流程方法论（HOW）

6.2 完整 Skill 清单（按 phase 分类）

Define（定义阶段）

Skill	角色
interview-me	在写任何 plan/spec/code 前先提取用户真实意图
idea-refine	用结构化的发散/收敛思维精化想法
spec-driven-development	写结构化 spec 后再写代码

Plan（规划阶段）

Skill	角色
planning-and-task-breakdown	把 spec 拆成小而可验证的任务

Build（构建阶段）

Skill	角色
incremental-implementation	薄垂直切片，每片测试后再扩展
test-driven-development	先写失败测试，再写实现
context-engineering	在正确时机加载正确 context
source-driven-development	实现前对照官方文档验证
doubt-driven-development	对每个非平凡决策做"对抗式 fresh-context review"
frontend-ui-engineering	含 accessibility 的生产级 UI
api-and-interface-design	带清晰契约的稳定接口

Verify（验证阶段）

Skill	角色
browser-testing-with-devtools	用 Chrome DevTools MCP 做运行时验证
debugging-and-error-recovery	Reproduce → localize → fix → guard

Review（评审阶段）

Skill	角色
code-review-and-quality	五维 review + 质量门
code-simplification	不改变行为前提下降低复杂度
security-and-hardening	OWASP 防御、输入验证、最小权限
performance-optimization	先测量，只优化重要的

Ship（发布阶段）

Skill	角色
git-workflow-and-versioning	原子 commit、整洁历史
ci-cd-and-automation	每次变更上自动质量门
deprecation-and-migration	安全废弃旧接口
documentation-and-adrs	文档化"为什么"而不只是"什么"
shipping-and-launch	上线前 checklist + 监控 + rollback

6.3 SKILL.md 强制 6 段式 schema

CLAUDE.md 第 30 行强制约定：

Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification

每个 SKILL.md 必须按这 6 段组织：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


---
name: <skill-name>
description: <动词短语 + 触发条件>
---

# <Skill Name>

## Overview
<这个 skill 是干什么的、为什么存在>

## When to Use
- <列出使用场景>

**When NOT to use:**
- <列出不使用场景>

## Process
<具体步骤，可含子段>

## Common Rationalizations
| Rationalization | Reality |
|---|---|
| <借口> | <反驳> |

## Red Flags
- <反模式症状>

## Verification
- [ ] <可测试的完成条件>

每一段对应一个 AI 可能犯的错：

段	防止什么
Overview	AI 不理解 skill 的存在意义
When to Use	AI 在错误场景套用
Process	AI 跳过关键步骤
Common Rationalizations	AI 用借口跳过整个 skill
Red Flags	AI 在偏离时没察觉
Verification	AI 提前宣布完成

6.4 代表性 Skill 逐项拆解

6.4.1 spec-driven-development（教科书级 Process）

Process 段的 gated workflow：

1
2
3
4
5


SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
 │ │ │ │
 ▼ ▼ ▼ ▼
 Human Human Human Human
 reviews reviews reviews reviews

关键约束：Do not advance to the next phase until the current one is validated.

Phase 1 (Specify) 的 5 个技巧：

Surface Assumptions — 显式列假设，末尾加 → Correct me now or I'll proceed with these.
Six core areas — Objective / Commands / Project Structure / Code Style / Testing Strategy / Boundaries
三层 Boundaries — Always do / Ask first / Never do
Reframe instructions as success criteria — “Make it faster” → “LCP < 2.5s on 4G”
Spec template — 可复用 Markdown 模板

Spec template：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]

Common Rationalizations 表的设计模式：

Rationalization	Reality
“This is simple, I don’t need a spec”	Simple tasks need acceptance criteria, just shorter spec.
“I’ll write the spec after I code it”	That’s documentation, not specification.
“The spec will slow us down”	15-minute spec prevents hours of rework.
“Requirements will change anyway”	That’s why the spec is a living document.
“The user knows what they want”	Even clear requests have implicit assumptions.

这是整个仓库里 Common Rationalizations 的范本——预判 AI 会用什么理由跳过 skill，每条反驳一句话见血。

Verification checklist：

1
2
3
4
5


- [ ] The spec covers all six core areas
- [ ] The human has reviewed and approved the spec
- [ ] Success criteria are specific and testable
- [ ] Boundaries (Always/Ask First/Never) are defined
- [ ] The spec is saved to a file in the repository

关键设计：每一条都是 boolean 可判定（yes/no），没有"足够好"这种模糊词。最后一条 saved to a file 把 spec 从"对话产物"提升为"仓库产物"。

6.4.2 using-agent-skills（schema 例外）

这是唯一不遵守 6 段式 schema 的 skill，详见 Layer 1 节。

6.4.3 code-simplification（为 hook 服务的 skill）

这是少数有专门 hook 配套的 skill 之一（hooks/simplify-ignore.sh），它有特殊约束——保护代码块不能被简化。

/code-simplify 命令的步骤序列（来自 .claude/commands/code-simplify.md）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


1. Read CLAUDE.md and study project conventions
2. Identify the target code — recent changes unless a broader scope is specified
3. Understand the code's purpose, callers, edge cases, and test coverage before touching it
4. Scan for simplification opportunities:
 - Deep nesting → guard clauses or extracted helpers
 - Long functions → split by responsibility
 - Nested ternaries → if/else or switch
 - Generic names → descriptive names
 - Duplicated logic → shared functions
 - Dead code → remove after confirming
5. Apply each simplification incrementally — run tests after each change
6. Verify all tests pass, the build succeeds, and the diff is clean

6.5 Common Rationalizations 表的设计精髓

每个 skill 末尾的 Common Rationalizations 表是 agent-skills 最具识别度的设计模式。它的设计要点：

预判 AI 偷懒的理由——AI 在长 context 里会发明各种跳过 skill 的借口
每条反驳很短——一句话见血，不啰嗦
两栏对照格式——把"AI 的内心独白"和"事实"并置，制造认知摩擦

1
2
3


| Rationalization | Reality |
|---|---|
| "<AI 心里的借口>" | <一句话反驳> |

6.6 Red Flags vs Common Rationalizations 的分工

1
2


Common Rationalizations → 处理"AI 的借口"（主动跳过的想法 - 思维层）
Red Flags → 处理"AI 的症状"（已经在跳过的迹象 - 行为层）

举例：

Rationalization: “I’ll write the spec after I code it”
Red Flag: “Starting to write code without any written requirements”

两者本质相同，但作用时机不同：

Rationalization 在 AI 即将偷懒时拦截"念头"
Red Flag 在 AI 已经偷懒时识别"症状"

6.7 Verification checklist 的可判定原则

每个 skill 的 Verification 段都是 boolean 可判定的 checkbox：

✓ “The spec covers all six core areas” — yes/no
✓ “The human has reviewed and approved” — yes/no
✗ “The spec is good enough” — 不可接受（模糊）
✗ “The reviewer is satisfied” — 不可接受（模糊）

6.8 100 行拆分阈值的应用

CLAUDE.md 规定 “Supporting files only created when content exceeds 100 lines”。这一规则的应用边界：

场景	是否拆出去
spec-driven-development 的 Process 段 200 行	不拆 — 是方法论而非数据
security checklist 134 行	拆 — 是清单数据
orchestration patterns 370 行	拆 — 是模式目录
单个 skill 的几十行 Process	不拆 — 维持自包含

关键判断：100 行是 “data vs methodology” 的分界线，不是文件长度的硬上限。

6.9 注意事项

using-agent-skills 不遵守 schema 但没有显式声明例外——这是仓库的隐性约定
Skill 之间通过 description 匹配自动激活——所以 description 写法很重要（“动词短语 + 触发条件”）
Skill 不能直接调用其他 skill——必须通过 command 或用户来编排
每个 skill 是自包含的——但可以指向 reference 和其他 skill

6.10 经验与可复用模板

写 Skill 的检查清单

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


Frontmatter:
 ✓ name 字段（与目录名一致）
 ✓ description 字段（动词短语 + 触发条件 "Use when..."）
 ✓ description 第三人称

Body 6 段：
 ✓ Overview - 这个 skill 是干什么的
 ✓ When to Use - 含 "When NOT to use" 反向条件
 ✓ Process - 具体步骤（数字列表）
 ✓ Common Rationalizations - 两栏对照表，预判 AI 借口
 ✓ Red Flags - 反模式症状清单
 ✓ Verification - boolean 可判定的 checkbox

Process 段的关键技巧：
 ✓ Surface Assumptions 模板
 ✓ Reframe 模糊需求为可量化条件
 ✓ 三层 Boundaries（Always / Ask first / Never）
 ✓ 完整产物模板

不要做：
 ✗ 写成 "vague advice"（CLAUDE.md Boundary 禁止）
 ✗ 复制其他 skill 的内容（用引用代替）
 ✗ 把超过 100 行的数据/清单写在 skill 里（拆到 references）
 ✗ 模糊 Verification（必须 boolean）

7. Layer 5｜references/

7.1 定位与体量

目录路径：references/
文件数：5 个 .md 文件
行数范围：134-370 行
加载时机：被 skill 文件以"自然语言路径"指向后，由 AI 按需 Read
角色：数据层 / 清单 / 模式目录
关键特性：所有文件没有 YAML frontmatter——不被自动发现，不被自动加载

7.2 完整文件清单

文件	行数	类型	被谁引用
accessibility-checklist.md	160	Checklist	frontend-ui-engineering, shipping-and-launch
performance-checklist.md	153	Checklist	performance-optimization, code-review-and-quality, shipping-and-launch
security-checklist.md	134	Checklist	security-and-hardening, code-review-and-quality, shipping-and-launch
testing-patterns.md	236	Pattern Catalog	test-driven-development
orchestration-patterns.md	370	Pattern Catalog	doubt-driven-development（×2）, agents/README.md（×3）, commands/ship.md

7.3 两种 Reference 的功能分化

7.3.1 Checklist 类（security / performance / accessibility）

形态： 复选框任务列表，按主题分组。

例：security-checklist.md 节选：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


## Pre-Commit Checks
- [ ] No secrets in code (`git diff --cached | grep -i "password\|secret\|api_key\|token"`)
- [ ] `.gitignore` covers: `.env`, `.env.local`, `*.pem`, `*.key`
- [ ] `.env.example` uses placeholder values (not real secrets)

## Authentication
- [ ] Passwords hashed with bcrypt (≥12 rounds), scrypt, or argon2
- [ ] Session cookies: `httpOnly`, `secure`, `sameSite: 'lax'`
- [ ] Session expiration configured (reasonable max-age)
- [ ] Rate limiting on login endpoint (≤10 attempts per 15 minutes)
- [ ] Password reset tokens: time-limited (≤1 hour), single-use

## Authorization
- [ ] Every protected endpoint checks authentication
- [ ] Every resource access checks ownership/role (prevents IDOR)
- [ ] Admin endpoints require admin role verification
- [ ] API keys scoped to minimum necessary permissions

特点：

复选框 → 显式 “做过/没做” 二元状态
每条都是可验证条件（含具体参数：≥12 rounds、≤10 attempts per 15 minutes）
按主题分组（Auth / Authz / Input Validation / Headers…）
末尾常带工具命令（git diff --cached | grep -i "password..."）

触发点： 上线前、review 时。

7.3.2 Pattern Catalog 类（testing-patterns / orchestration-patterns）

形态： 正例 + 反例 + 决策表。

例：orchestration-patterns.md 节选：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


### 1. Direct invocation (no orchestration)

Single persona, single perspective, single artifact.

user → code-reviewer → report → user

Use when: one perspective on one artifact, describable in one sentence.

Examples:
- "Review this PR" → code-reviewer
- "Find security issues in auth.ts" → security-auditor
- "What tests are missing for the checkout flow?" → test-engineer

Cost: one round trip. The baseline you should always compare orchestrated patterns against.

---

### 2. Single-persona slash command

A slash command that wraps one persona with the project's skills.

/review → code-reviewer (with code-review-and-quality skill) → report

Use when: the same single-persona invocation happens repeatedly with the same setup.

Examples in this repo: /review, /test, /code-simplify.

Cost: same as direct invocation. The slash command is just a saved prompt.

Anti-signal: if the slash command's body is mostly "decide which persona to call," delete it.

---

### 3. Parallel fan-out with merge

 ┌─→ code-reviewer ─┐
/ship → fan out ───┼─→ security-auditor ─┤→ merge → go/no-go + rollback
 └─→ test-engineer ─┘

Use when:
- The sub-tasks are genuinely independent
- Each sub-agent benefits from its own context window

特点：

命名模式（A / B / C），便于交叉引用
每个模式包含：图示、用例、成本、反信号
显式列出 anti-patterns
偏架构 / 战略，而非战术

7.4 引用机制：纯文本路径

跨仓库的引用模式高度一致：

1
2
3
4


- "see `references/security-checklist.md`"
- "For detailed accessibility requirements...see `references/accessibility-checklist.md`"
- "(see references/orchestration-patterns.md)"
- "this skill orchestrates from the main session... references/orchestration-patterns.md"

没有任何自动加载机制：

不是 include 指令
不是 frontmatter 字段
不是 MCP 资源
不是 Skill 自动激活

就是一句"自然语言路径"。AI 读到这句话，自己判断是否需要 Read。

这种"软引用"的好处

AI 决定权重：context 紧张时可以不读
透明可控：用户可以看到哪些 reference 被读了
跨工具兼容：在任何能读文件的环境都能工作

7.5 orchestration-patterns.md 的特殊地位

这是 5 个 reference 里最特殊的一个：

行数最多：370 行（比其他 reference 多 2-3 倍）
被引用最多：被 commands、agents、skills 三层都引用
职责不同：其他 reference 是"任务时查"，这个是"架构演化时查"

它的核心一句话被整个仓库反复引用：

The user (or a slash command) is the orchestrator. Personas do not invoke other personas.

7.6 设计取舍

取舍 1: 为什么不把 references 写进 skill？

如果把 134-370 行的清单全塞进 skill：

坏处	说明
context 浪费	每次激活 skill 都加载几百行清单
概念混杂	方法论（process）和数据（checklist）写在一起
复用困难	security checklist 要被 3 个 skill 共用，写在 skill 里就得复制三份
更新成本	清单变了要改三个 skill

所以拆出去的真正动机是：复用 + 按需加载 + 关注点分离。

取舍 2: 100 行阈值

CLAUDE.md 规定：

Supporting files only created when content exceeds 100 lines

5 个 reference 的最小行数是 134（security-checklist），刚刚超过阈值。这说明阈值是有意控制的——不超过 100 行的内容应该直接写在 skill 里。

7.7 注意事项

没有 frontmatter：不能被 Skill 系统自动检索；只能靠 skill 里硬编码路径
没有 README/index：5 个文件没有总目录，AI 不易"发现"未引用的 reference
没有版本号：security checklist 的 bcrypt ≥12 rounds 这类参数会过时，但没有 last-updated 日期
没有交叉引用：security 和 performance 之间偶尔有重叠（如 dependency security），但没互链

7.8 经验与可复用模板

何时建一个 reference 文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


判定要不要建：
 ✓ 内容 ≥ 100 行
 ✓ 被 2+ skill 引用
 ✓ 内容偏数据/清单/模式，而非方法论
 ✓ 任务时才需要，不是总要看

判定放进哪类 reference：
 - 复选项条目 → checklist 类
 - 模式 / 反模式 → pattern catalog 类
 - 仅 1 个 skill 用 + 简短 → 留在 SKILL.md 里

Checklist 类 Reference 模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# <Topic> Checklist

Quick reference for <topic>. Use alongside the <skill-name> skill.

## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)
- ...

## <Section 1>
- [ ] <具体可验证条件 + 参数>
- [ ] <具体可验证条件 + 参数>
...

## <Section 2>
...

Pattern Catalog 类 Reference 模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


# <Domain> Patterns

<一句话描述>

The governing rule: **<铁律>**

---

## Endorsed patterns

### 1. <Pattern Name 1>
[描述 + ASCII 图示]

**Use when:** ...

**Examples:** ...

**Cost:** ...

### 2. <Pattern Name 2>
...

---

## Anti-patterns

### A. <Anti-pattern 1>
[反例图示]

**Why this fails:**
- ...
- ...

8. Layer X｜hooks/

8.1 定位与体量

目录路径：hooks/
文件数：3 个 hook 脚本 + 2 个文档 + 2 个测试 + 1 个配置
总行数：1052 行
加载时机：由 Claude Code 在特定事件触发
角色：横切关注点（AOP）——在不修改 skill 的前提下增强 skill

8.2 完整文件清单

文件	行数	角色
hooks.json	14	插件级注册（仅 session-start）
session-start.sh	24	Hook 1: 会话启动
session-start-test.sh	46	测试
sdd-cache-pre.sh	106	Hook 2: WebFetch 前
sdd-cache-post.sh	135	Hook 2: WebFetch 后
SDD-CACHE.md	167	文档
simplify-ignore.sh	302	Hook 3: 代码屏蔽
simplify-ignore-test.sh	247	测试
SIMPLIFY-IGNORE.md	90	文档

8.3 三种干预模式

Hook	触发事件	干预方式	配套 Skill
session-start	`SessionStart`	注入 context	using-agent-skills
sdd-cache	`PreToolUse:WebFetch` + `PostToolUse:WebFetch`	替换工具输出	source-driven-development
simplify-ignore	`PreToolUse:Read` + `PostToolUse:Edit\|Write` + `Stop`	遮蔽工具输入	code-simplification

8.4 Hook 1: session-start

8.4.1 注册（hooks.json）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
 "hooks": {
 "SessionStart": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
 }
 ]
 }
 ]
 }
}

8.4.2 完整脚本（session-start.sh，24 行）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


#!/bin/bash
# agent-skills session start hook
# Injects the using-agent-skills meta-skill into every new session

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SKILLS_DIR="$(dirname "$SCRIPT_DIR")/skills"
META_SKILL="$SKILLS_DIR/using-agent-skills/SKILL.md"

if ! command -v jq >/dev/null 2>&1; then
 echo '{"priority": "INFO", "message": "agent-skills: jq is required for the session-start hook but was not found on PATH. Install jq (e.g. `brew install jq` or `apt-get install jq`) to enable meta-skill injection. Skills remain available individually."}'
 exit 0
fi

if [ -f "$META_SKILL" ]; then
 CONTENT=$(cat "$META_SKILL")
 jq -cn \
 --arg message "agent-skills loaded. Use the skill discovery flowchart to find the right skill for your task.

$CONTENT" \
 '{priority: "IMPORTANT", message: $message}'
else
 echo '{"priority": "INFO", "message": "agent-skills: using-agent-skills meta-skill not found. Skills may still be available individually."}'
fi

8.4.3 作用

每个新会话启动时，把 using-agent-skills/SKILL.md 的全部 180 行注入到第一条 system message 里。

8.4.4 优雅降级

1
2
3
4


if ! command -v jq >/dev/null 2>&1; then
 echo '{"priority": "INFO", "message": "agent-skills: jq is required..."}'
 exit 0
fi

jq 缺失时输出友好提示，不报错退出。会话仍能继续，只是 meta-skill 不被注入。

8.5 Hook 2: sdd-cache

8.5.1 注册（用户级 `.claude/settings.json`）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


{
 "hooks": {
 "PreToolUse": [
 {
 "matcher": "WebFetch",
 "hooks": [
 {
 "type": "command",
 "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/sdd-cache-pre.sh",
 "timeout": 10
 }
 ]
 }
 ],
 "PostToolUse": [
 {
 "matcher": "WebFetch",
 "hooks": [
 {
 "type": "command",
 "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/sdd-cache-post.sh",
 "async": true,
 "timeout": 10
 }
 ]
 }
 ]
 }
}

8.5.2 核心矛盾

source-driven-development skill 要求每个框架决策都 fetch 官方文档
同一个项目跨会话工作意味着反复 fetch 同一个页面
简单缓存会破坏 skill 的"always verify against current docs"承诺

8.5.3 解决方案：HTTP 协议感知的缓存

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


PreToolUse:WebFetch
 ↓
有缓存？──无──→ 放行
 ↓ 有
HEAD 请求 + If-None-Match: <etag>
 ↓
返回 304？──否──→ 放行（让 WebFetch 真正跑）
 ↓ 是
exit 2 + 缓存内容输出到 stderr
 ↓
Claude Code 把 stderr 当作 WebFetch 的"错误"返回给 AI
 ↓
AI 拿到缓存内容（标记为"已通过 304 验证"）

8.5.4 关键代码片段（sdd-cache-pre.sh）

1）依赖检查 + 优雅降级（第 21-23 行）：

1
2
3


command -v jq >/dev/null 2>&1 || exit 0
command -v curl >/dev/null 2>&1 || exit 0
command -v shasum >/dev/null 2>&1 || command -v sha256sum >/dev/null 2>&1 || exit 0

2）没有验证器就不缓存（第 62-65 行）：

1
2
3
4


if [ -z "$ETAG" ] && [ -z "$LAST_MOD" ]; then
 dbg "cached entry has no etag/last-modified, cannot revalidate, bypass"
 exit 0
fi

3）HEAD 重验证（第 71-74 行）：

1
2
3
4


STATUS=$(curl -sI -o /dev/null -w "%{http_code}" \
 --max-time 5 -L \
 "${HEADERS[@]}" \
 "$URL" 2>/dev/null || echo "000")

4）exit 2 当作 in-band 信号（第 94-106 行）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{
 printf '[sdd-cache] Cache hit for %s\n\n' "$URL"
 printf 'Revalidated via HTTP 304; unchanged since %s. Use the cached\n' "$VERIFIED_AT_ISO"
 printf 'content below as if WebFetch had just returned it.\n\n'
 if [ -n "$ORIGINAL_PROMPT" ]; then
 printf 'Original WebFetch prompt: "%s". If your angle differs, judge\n' "$ORIGINAL_PROMPT"
 printf 'whether this reading still covers it.\n\n'
 fi
 printf -- '----- BEGIN CACHED CONTENT -----\n'
 printf '%s\n' "$CONTENT"
 printf -- '----- END CACHED CONTENT -----\n'
} >&2
exit 2

8.5.5 三个绝妙的设计

1）exit 2 当作 in-band 信号

Claude Code 的 hook 协议里，exit 2 = 阻止工具执行 + 把 stderr 传回 AI。sdd-cache 利用这个机制，把"缓存命中"伪装成"工具被拒"——但 stderr 里其实是有效内容。

2）没有 ETag/Last-Modified 就拒绝缓存

没有验证器的内容永不缓存。避免"缓存了但永远不知道何时该失效"的状态。

3）缓存原始 prompt

WebFetch 不返回原始 HTML，返回的是经过模型按 prompt 处理过的内容。缓存命中时把原始 prompt 也返回给 AI——让 AI 自己判断"上次的提问角度对当前任务够不够"。

8.5.6 缓存条目结构

1
2
3
4
5
6
7
8


{
 "url": "https://react.dev/reference/react/useActionState",
 "prompt": "extract the signature",
 "etag": "W/\"abc123\"",
 "last_modified": "Mon, 27 May 2026 12:00:00 GMT",
 "content": "useActionState(action, initialState) returns ...",
 "fetched_at": 1716816000
}

存放在 .claude/sdd-cache/<sha256(url)>.json。

8.5.7 已知限制

Body is prompt-shaped：缓存的不是原始 HTML，是上次 prompt 处理过的内容
Every cache write costs an extra HEAD：post hook 需要再发一次 HEAD 取 ETag
Servers without ETag or Last-Modified are never cached：没有验证器的站点永远不被缓存
A misbehaving server can serve a wrong 304：服务器 bug 会导致缓存陈旧

8.6 Hook 3: simplify-ignore

8.6.1 注册（用户级 `.claude/settings.json`）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


{
 "hooks": {
 "PreToolUse": [
 {
 "matcher": "Read",
 "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh" }]
 }
 ],
 "PostToolUse": [
 {
 "matcher": "Edit|Write",
 "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh" }]
 }
 ],
 "Stop": [
 {
 "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh" }]
 }
 ]
 }
}

8.6.2 注解语法

1
2
3
4


/* simplify-ignore-start: perf-critical */
result[0] = buf[0] ^ key[0];
result[1] = buf[1] ^ key[1];
/* simplify-ignore-end */

经过 hook 处理后，模型 read 到的是：

1

/* BLOCK_de115a1d: perf-critical */

8.6.3 三阶段生命周期

Event	Action
`PreToolUse Read`	备份原文件 + 替换为 `BLOCK_<hash>` 占位符
`PostToolUse Edit\|Write`	展开占位符回到真实代码 + 保存模型修改
`Stop`（会话结束）	从备份恢复所有被保护的文件

8.6.4 内容哈希作为占位符 ID

1

BLOCK_de115a1d ← sha1(原始代码块) 的前 8 字符

即使模型把占位符复制、移位、删除，hash 仍能精确定位回原代码。

8.6.5 渐进式回填

Fallback expansion is progressive: full placeholder → prefix+hash+suffix → hash-only.

模型如果修改了占位符格式（比如改了 reason 文本），hook 会用越来越宽松的匹配模式尝试还原。

8.6.6 崩溃恢复

1
2


# 如果 Claude Code 崩溃没触发 Stop hook
echo '{}' | bash hooks/simplify-ignore.sh

8.6.7 已知限制

Single-line blocks hide the entire line：单行注解会隐藏整行
Comment suffix detection only covers */ and -->：模板引擎（ERB、Blade）可能不工作
Fallback is progressive, not exact：模型修改占位符格式时可能留下美容性残留
File renaming leaves placeholders：模型用 shell rename 文件，新文件会保留占位符

8.7 三个 Hook 的共性设计

共性 1: 优雅降级

1
2


command -v jq >/dev/null 2>&1 || exit 0
command -v curl >/dev/null 2>&1 || exit 0

任何 hook 都不应该让 session 卡死。依赖缺失时静默退出 0。

共性 2: 显式调试日志

1
2
3
4
5
6
7


dbg() {
 local dir="${CLAUDE_PROJECT_DIR:-$PWD}/.claude/sdd-cache"
 [ "${SDD_CACHE_DEBUG:-0}" = "1" ] || [ -f "$dir/.debug" ] || return 0
 mkdir -p "$dir"
 printf '%s [pre] %s\n' "$(date -u +%FT%TZ)" "$*" >> "$dir/.debug.log"
}
dbg "fired"

通过环境变量或 sentinel 文件触发日志——hook 是黑盒，必须留可观察性。

共性 3: 与具体 skill 一对一绑定

Hook	配套 Skill	失败影响
session-start	using-agent-skills	skill 系统不可用
sdd-cache	source-driven-development	重复 fetch（仅性能损失）
simplify-ignore	code-simplification	保护代码被改（数据损失风险）

共性 4: 文档专门解释"反直觉"行为

sdd-cache：“exit 2 不是故障，是缓存命中”
simplify-ignore：“模型看到 BLOCK 占位符是正确行为”
session-start：“jq 缺失时 skills 仍可用”

每个 hook 都假设读者会困惑，主动消除困惑。

8.8 注册的两层架构

插件层（hooks.json）

1
2
3
4
5


{
 "hooks": {
 "SessionStart": [...]
 }
}

只注册了 session-start。这是仓库默认的、所有用户都需要的 hook。

项目层（`.claude/settings.json`）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "hooks": {
 "PreToolUse": [
 { "matcher": "WebFetch", ... },
 { "matcher": "Read", ... }
 ],
 "PostToolUse": [...],
 "Stop": [...]
 }
}

sdd-cache 和 simplify-ignore 必须由用户手动注册。

设计逻辑

Hook	默认启用	理由
session-start	✓	整个 skill 系统的"启动器"——不启用整个仓库无意义
sdd-cache	✗	性能优化，有 disk I/O + 网络 HEAD 开销，opt-in
simplify-ignore	✗	改变模型可见性，有数据风险，opt-in

原则：默认开启的 hook 必须是"无副作用 + 无 opt-out 成本"的。

8.9 Hook 的核心哲学

哲学 1: 不修改 skill，增强 skill

SDD-CACHE.md 引文：

The skill itself is unchanged. It continues to follow DETECT → FETCH → IMPLEMENT → CITE. The hook only changes what happens under the hood when FETCH runs.

这是"hook 作为运行时优化器"的范式——比修改 skill 本身可维护性高得多。

哲学 2: 利用协议而非绕过

sdd-cache 没有 hack 出新的通信渠道，而是精确地用了 Claude Code hook 协议里 exit code 2 的含义。

Hook 应该作用在协议层，不应该作用在语义层。

哲学 3: 失败模式必须显式

每个 hook 都有：

依赖缺失的降级策略
调试日志
崩溃恢复路径
“看似异常但其实正常"的解释

Hook 是 invisible infrastructure——所以必须留观察接口。

8.10 注意事项

没有 hook 失败的告警机制：sdd-cache 静默 exit 0 时，用户无从知道缓存功能没生效
simplify-ignore 没覆盖 MultiEdit：matcher 只匹配 Edit|Write，但 Claude Code 还有 MultiEdit 工具
没有 hook 之间的依赖声明：如果 simplify-ignore 和某个未来 hook 同时操作 Read，行为是未定义的
session-start 强制注入 180 行：每个会话首条 message 都吃 ~2K token

8.11 经验与可复用 Hook 模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


#!/bin/bash
# <hook-name>.sh — <event> hook for <purpose>.
#
# What it does: <one paragraph>
# What it does NOT do: <one line>
# Failure mode: <how it degrades>

set -euo pipefail

# 1. 依赖检查 + 优雅降级
command -v <dep> >/dev/null 2>&1 || exit 0

# 2. 读取 hook payload
if [ -t 0 ]; then INPUT="{}"; else INPUT=$(cat); fi

# 3. 调试日志（按 env var 或 sentinel 文件触发）
dbg() {
 local dir="${CLAUDE_PROJECT_DIR:-$PWD}/.claude/<hook-name>"
 [ "${HOOK_DEBUG:-0}" = "1" ] || [ -f "$dir/.debug" ] || return 0
 mkdir -p "$dir"
 printf '%s %s\n' "$(date -u +%FT%TZ)" "$*" >> "$dir/.debug.log"
}
dbg "fired"

# 4. 业务逻辑
# ...

# 5. 通过 exit code 给 Claude Code 信号
# 0 = 放行
# 2 = 阻止 + stderr 内容传回 agent
exit 0

9. 索引与速查

9.1 跨层级关键文件速查

我想知道	看哪个文件
仓库整体定位	`CLAUDE.md`
所有 skill 的清单	`CLAUDE.md` § Skills by Phase / `skills/using-agent-skills/SKILL.md` § Quick Reference
任务路由决策树	`skills/using-agent-skills/SKILL.md` § Skill Discovery
AI 不该做什么	`skills/using-agent-skills/SKILL.md` § Failure Modes
上线前完整 checklist	`skills/shipping-and-launch/SKILL.md`
安全检查清单	`references/security-checklist.md`
性能检查清单	`references/performance-checklist.md`
多 agent 编排模式	`references/orchestration-patterns.md`
Persona 设计规则	`agents/README.md`
Hook 协议（exit code 含义）	`hooks/SDD-CACHE.md`
Spec 写作模板	`skills/spec-driven-development/SKILL.md`
Common Rationalizations 表设计	任一 skill 的对应段（参考 spec-driven-development）

9.2 设计哲学速查

哲学	来源	体现
Never Duplicate	CLAUDE.md L43	整个仓库的"指针架构”
利用协议而非绕过	hooks 设计	exit code 2、ASCII 决策树、Markdown 模板
反例教学	agents/README.md	meta-orchestrator 反例、每个 skill 的 Red Flags
100 行拆分阈值	CLAUDE.md L32	references 拆出 skill
总在 context 必须极短	CLAUDE.md 自身 44 行	按需加载架构
用约束代替能力	整个项目	用 skill 强制纪律，不期待模型自觉
User is the orchestrator	agents/README.md（重复 5+ 次）	personas 不互调

9.3 “我想做 X，该看哪里” 反向索引

想做的事	该查的层 / 文件
给我的项目写一份 CLAUDE.md	Layer 0 § 2.6 模板
给我的团队定义工程纪律的 skill	Layer 4 § 6.10 模板
加一个我的项目专用的 slash command	Layer 2 § 4.9 模板
加一个 specialist persona	Layer 3 § 5.10 模板
拆数据到 reference 文件	Layer 5 § 7.8 模板
加自定义 hook	Layer X § 8.11 模板
决定要不要新建 persona	Layer 3 § 5.10 判定标准
决定要不要新建 reference	Layer 5 § 7.8 判定标准
设计一个 fan-out 命令	`.claude/commands/ship.md` 模式
把模糊需求翻译成可验证条件	`skills/spec-driven-development/SKILL.md` § “Reframe instructions”
写 AI 看的"反合理化"表	`skills/spec-driven-development/SKILL.md` § Common Rationalizations

9.4 各层文件数量与体量对比

1
2
3
4
5
6
7
8
9


文件数： 21 (skills)
 > 7 (commands)
 > 5 (references)
 > 3 (agents) = 3 (hooks)
 > 1 (CLAUDE.md) = 1 (meta-skill)

总行数： skills > references > hooks > commands > agents > CLAUDE.md

加载频次： CLAUDE.md > meta-skill > commands > skills > agents > references > hooks

9.5 隐藏的"对齐 bug"

仓库中存在一些有意识的或可能的设计不一致：

不一致点	描述
`code-simplification` 缺失	出现在 CLAUDE.md Skills by Phase 中，但 using-agent-skills 决策树没有
`deprecation-and-migration` 缺失	类似情况
using-agent-skills 不遵守 schema	没有在 CLAUDE.md 显式声明此例外
skill-anatomy.md 路径未给	CLAUDE.md Boundary 引用了它但没说在哪里
simplify-ignore 不覆盖 MultiEdit	matcher 只配置了 `Edit\|Write`

9.6 阅读 agent-skills 的建议路径

路径 A：从外向内（推荐）

1
2
3
4
5
6
7


1. CLAUDE.md（44 行）
2. agents/README.md（120 行）
3. skills/using-agent-skills/SKILL.md（~180 行）
4. .claude/commands/ship.md（73 行）
5. skills/spec-driven-development/SKILL.md（201 行）— 教科书级 skill
6. references/orchestration-patterns.md（370 行）— 架构铁律
7. hooks/SDD-CACHE.md + sdd-cache-pre.sh — 最精彩的 hook

路径 B：从某个具体场景反向追

1
2
3
4
5
6
7
8
9


"我有一个上线决策的需求"
 ↓
.claude/commands/ship.md
 ↓
agents/code-reviewer.md + security-auditor.md + test-engineer.md
 ↓
skills/code-review-and-quality + security-and-hardening + ...
 ↓
references/security-checklist.md + performance-checklist.md

附录 A：术语表

术语	含义
Skill	一个 SKILL.md 文件，定义某个工程任务的方法论
Persona	一个 `.md` 文件，定义一个 subagent 的角色与输出格式
Command	一个 slash command 文件，定义用户显式触发的入口
Reference	不带 frontmatter 的支撑文档，通常是清单或模式目录
Hook	Bash 脚本，在 Claude Code 的特定事件触发
meta-skill	`using-agent-skills`，治理其他 skill 的元规则
fan-out	并行 spawn 多个 subagent，各自独立工作
Common Rationalizations	skill 中的"AI 借口反驳表"
Red Flags	skill 中的"AI 偏离症状清单"
Verification	skill 中的 boolean 可判定完成条件
schema	CLAUDE.md L30 强制的 SKILL.md 6 段结构
lazy loading	references 的"软引用"加载方式

附录 B：仓库地址与版本

GitHub: https://github.com/addyosmani/agent-skills
作者: Addy Osmani (Google)
本手册基于的代码状态: main branch（2026 年 5 月）

如果你想看叙事版本和鬼哥的学习思考，翻文章型《从使用者到学习者》。

如果你想看 Addy 项目的整体定位和反合理化机制，翻《Agent Skills：当 Google 工程文化遇上 AI 编程代理》。

从使用者到学习者：agent-skills 架构深度剖析与高手思维体系

Thu, 28 May 2026 00:00:00 +0000

“AI coding agents default to the shortest path.”

— Addy Osmani

引子｜从使用者，到学习者

最近几个月，鬼哥在做 AI 项目的过程中，一直被一个问题困扰——

让 Claude / Cursor / Copilot 帮我写代码，效率确实快了。但一段时间下来，我开始隐隐不安：代码量上去了，我能真正"理解"和"掌握"的部分却在下降；功能堆得很快，但一到上线前的查 bug、做 review，处处是雷；我有十几年的工程经验，但在 AI 协作的场景下，这些经验好像没怎么用上，甚至有时候反过来被 AI 的"先把它跑起来再说"带跑偏。

直到我遇到了 agent-skills——由 Google 资深工程师 Addy Osmani 开源的一套"AI 编程纪律"系统。

这个仓库不长，核心只有 21 个 SKILL.md 文件 + 7 个 slash commands + 3 个 persona + 5 个 references + 3 个 hooks。但作为使用者用了一段时间后，我的感受是——

这不是一套"AI 提示词工程的最佳实践"，这是一套"用工程纪律驯化 AI"的完整方法论。

它让我重新意识到：

spec 不是教科书废话，它是 AI 项目的护城河
测试不是负担，它是让 AI 不胡来的物理边界
review 不是仪式，它是 AI 错位假设暴露的最后窗口

更进一步，鬼哥逐渐感受到一件事：工程经验和 AI 开发的结合点上，有一套深度的核心思维和项目纪律，对 AI 项目的质量、成败和过程的影响，远远大于 AI 模型能力本身的差异。

光当使用者已经不够。

于是我决定深入到项目里，把 agent-skills 的架构、源码、设计哲学，一层一层读透。读完后我发现：这套体系背后的设计精密程度，远超过它表面上看起来的"21 个 skill"。它是一个完整的、有层次的、自洽的工程系统——构建这样的系统，需要十几年工程经验 + 大量 AI 项目实践的双重沉淀。

这篇文章是鬼哥的剖析笔记 + 读后感。我会带你从最外层一直走到最内层，把架构拆开，讲清楚每一层在干什么、为什么这么干。但更重要的是，文章最后我想跟你聊一件事——

学这套体系，不能只学架构。要从源码里读高手的思维体系，再把思维体系落地到你自己的 AI 项目里。

如果你完全没接触过 agent-skills，推荐先看《Agent Skills：当 Google 工程文化遇上 AI 编程代理》作为前置导读。本文假设你已经对项目有基本了解，重点放在架构与工程思维的深度剖析。

一句话讲清楚 agent-skills 是什么

agent-skills 不是一个工具，也不是一个框架。

它是给 AI 编程代理使用的"工程方法论文件包"：21 个 SKILL.md 文件 + 7 个 slash commands + 3 个 persona + 5 个 references + 3 个 hooks，再加上一个 44 行的 CLAUDE.md 作为总入口。

它要解决的问题非常具体：AI 默认走捷径（skip specs、skip tests、skip reviews），怎么让它按工程纪律走完整流程。

仓库目录非常克制：

1
2
3
4
5
6
7


agent-skills/
├── CLAUDE.md 44 行，仓库总入口（always in context）
├── skills/ 21 个 SKILL.md，按开发阶段组织
├── agents/ 3 个 Persona 角色文件
├── references/ 5 个 清单与模式目录
├── hooks/ 3 个 会话生命周期脚本
└── .claude/commands/ 7 个 用户可调用的 slash command

总文件数加起来不到 50 个。但读完后你会发现：这是一个被仔细切分过、每层各司其职、互不重复的精密系统。

核心论点｜为什么 AI 项目需要"工程纪律"

在拆架构之前，鬼哥想先讲清楚 agent-skills 解决的真正问题。

AI 的"默认行为"是不可信的

大模型有一个隐藏特性：它会尽可能"快速地"给你一个看起来合理的答案。

这个特性在 ChatGPT 帮你查资料时是优点。但在它写代码时，问题就来了——

你说"做个 dashboard"，它不问"给谁用、看什么指标"，直接开始 import chart 库
你说"修这个 bug"，它不写复现测试，直接改逻辑
你说"加个登录"，它不检查权限模型，直接写 if password == request.password
你说"上线吧"，它不查 rollback 方案，直接 push

这些不是模型"能力不够"，是模型"默认走捷径"。模型本身有能力做对，但它需要外部约束告诉它"不许走捷径"。

工程纪律是 AI 输出质量的"重力场"

人类资深工程师为什么不会犯这些错？因为他经历过这些坑，养成了"先写 spec / 先写测试 / 先想 rollback"的反射。这些反射就是工程纪律。

AI 没有这种反射——除非你强行给它装一套。

agent-skills 干的就是这件事：把工程纪律以可执行的、AI 看得懂的形式编码进它的工作流。

每一个 skill 都是一段"防偷懒程序"：

spec-driven-development 强制 AI 在动代码之前写 spec
test-driven-development 强制 AI 在写实现之前写失败的测试
code-review-and-quality 强制 AI 用五维标准 review 自己的代码
shipping-and-launch 强制 AI 在上线前列 rollback 计划

读了源码我才意识到：这些 skill 文件不是"教 AI 怎么做"，是"逼 AI 不能怎么做"。 它们是反熵的力量。没有它们，AI 就会滑向"最短路径"。

“反合理化"是核心创新

整个项目里我印象最深的设计，是每个 skill 里都有的 Common Rationalizations 表：

Rationalization	Reality
“This is simple, I don’t need a spec”	A two-line spec is fine, but acceptance criteria are not optional.
“I’ll write the spec after I code it”	That’s documentation, not specification.
“The spec will slow us down”	15-minute spec prevents hours of rework.

这是 Addy 干的最聪明的一件事——预判 AI 会用什么理由跳过这个 skill，把反驳预先写好放在 skill 文件里。

AI 在长 context 里会发明各种偷懒借口（“这次比较简单”、“我可以边写边补”……）。Common Rationalizations 表的存在，等于在 AI 的内心独白旁边放了一个反驳音轨。

这一个设计，把"AI 心理学"工程化了。

整体架构｜六层 + 横切 hooks

把整个仓库读完后，鬼哥画出来的全景图是这样的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


 USER
 │
 /command
 │
 ▼
 ┌───────────────────┐
 横切 (AOP) │ .claude/commands/ │ ← Layer 2: WHEN (用户入口)
 ┌──────────┐ └─────────┬─────────┘
 │ hooks/ │ │
 │ │ ┌─────────┴─────────┐
 │ ·session │ ▼ ▼
 │ -start │ ┌─────────┐ ┌──────────┐
 │ ·sdd │ │ agents/ │ → │ skills/ │
 │ -cache │ │ (WHO) │ │ (HOW) │ ← Layer 3 / Layer 4
 │ ·simpli │ └────┬────┘ └─────┬────┘
 │ -fy-ig │ │ │
 │ -nore │ └───────┬───────┘
 └──────────┘ ▼
 ┌──────────────┐
 │ references/ │ ← Layer 5: DATA (清单/模式)
 └──────────────┘

 ┌──────────────────────┐
 │ using-agent-skills │ ← Layer 1: 路由 + 行为宪法
 │ (meta-skill) │
 └──────────────────────┘
 ▲
 ┌──────────────────────┐
 │ CLAUDE.md (44行) │ ← Layer 0: 总入口
 └──────────────────────┘

读完源码后，我把这套架构拆成了 6 个垂直层 + 1 个横切层。每一层都有非常清晰的单一职责，互不重复：

层	名字	职责	数量	加载时机
Layer 0	CLAUDE.md	仓库导航（NAV）	1 个，44 行	always in context
Layer 1	using-agent-skills	路由 + 行为宪法	1 个，180 行	session start 注入
Layer 2	commands	用户显式入口（WHEN）	7 个	用户 `/foo` 触发
Layer 3	agents	视角与输出格式（WHO）	3 个	command 派发
Layer 4	skills	流程方法论（HOW）	21 个	按需调用
Layer 5	references	清单与模式（DATA）	5 个	任务时按需读
Layer X	hooks	横切干预（AOP）	3 个	事件触发

注意每一层的信息体量是逐渐增大的——CLAUDE.md 44 行就把一切讲完；具体 skill 文件 100-300 行；reference 文件 134-370 行。这是一个精心设计的 token 预算：

总在 context 的东西必须极短（CLAUDE.md）
经常用的东西要中等长度（skills）
偶尔用的东西可以详尽（references）

这是把"context 即成本"这件事，做到极致的设计。

想看每一层的完整清单、文件路径、行数对比？翻字典型《架构总览》一节。

Layer 0｜CLAUDE.md：44 行的导航极简主义

读 agent-skills 时，鬼哥第一个被震到的就是这个 CLAUDE.md。

整个仓库的总入口、AI 每次会话都会自动加载的文件——只有 44 行。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# agent-skills

This is the agent-skills project — a collection of production-grade engineering skills for AI coding agents.

## Project Structure
[ASCII 树，6 个目录]

## Skills by Phase
**Define:** interview-me, idea-refine, spec-driven-development
**Plan:** planning-and-task-breakdown
**Build:** incremental-implementation, ...
**Verify:** browser-testing-with-devtools, debugging-and-error-recovery
**Review:** code-review-and-quality, ...
**Ship:** git-workflow-and-versioning, ..., shipping-and-launch

## Conventions
- Every skill lives in `skills/<name>/SKILL.md`
- YAML frontmatter with `name` and `description` fields
- Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification
- References are in `references/`, not inside skill directories
- Supporting files only created when content exceeds 100 lines

## Commands
- `npm test` — Not applicable (this is a documentation project)
- Validate: Check that all SKILL.md files have valid YAML frontmatter

## Boundaries
- Always: Follow the skill-anatomy.md format for new skills
- Never: Add skills that are vague advice instead of actionable processes
- Never: Duplicate content between skills — reference other skills instead

44 行做了 5 件事：

Project Structure — 一棵 ASCII 树告诉你哪里有什么
Skills by Phase — 按阶段索引 21 个 skill
Conventions — 文件 schema 约束
Commands — 怎么验证（指明 npm test 不适用）
Boundaries — 不可协商的约束（Always / Never）

它做的事 vs 它不做的事

最关键的判断：CLAUDE.md 不重复任何下游内容。

它做	它不做
列目录树	描述每个目录里有什么文件
列 skill 名字	解释每个 skill 怎么用
给 SKILL.md 模板的字段名	给字段的写法示例
说 “follow skill-anatomy.md”	重复 skill-anatomy.md 内容

它就是一组指针。

为什么必须这么克制？因为 CLAUDE.md 每次对话都会自动加载到 context——每多写一行就有 N 次重复的 token 成本。

这个判断把 CLAUDE.md 和 README.md 彻底分开。README 给人看，可以有教程、动机、示例；CLAUDE.md 给 AI 看，只给坐标。

第 30 行的 schema 强制

在 6 条 Conventions 里，最重要的是这一行：

Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification

这一行等于一份合同——整个仓库 21 个 skill 文件，结构上必须长成这样。

读到这里我突然明白：之前看的 spec-driven-development 那些教科书级别的"反合理化表”、“Red Flags 清单”、“Verification checklist”——这些不是某个 skill 的创新，是 CLAUDE.md 强制要求的格式。 21 个文件必须遵守。

一份 44 行的文档，撑起了整个仓库的形态。

字典型里有 CLAUDE.md 的完整逐行拆解。

Layer 1｜using-agent-skills：meta-skill 的双重职责

如果说 CLAUDE.md 是地图，using-agent-skills 就是这套系统的"操作系统"。

它是唯一一个会被 hook 强制注入到每个新会话的 skill。我们待会儿讲 hook 的时候你会看到，session-start.sh 干的事就一件——把 using-agent-skills 的全文塞进会话的第一条 system message。

打开这个文件，你会发现它和其他 skill 完全不一样。它做两件事：

职责一：路由器（Skill Router）

一个 ASCII 决策树：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Task arrives
 │
 ├── Don't know what you want yet? ──────→ interview-me
 ├── Have a rough concept, need variants? → idea-refine
 ├── New project/feature/change? ─────→ spec-driven-development
 ├── Implementing code? ─────────────→ incremental-implementation
 │ ├── UI work? ─────────────────→ frontend-ui-engineering
 │ ├── API work? ────────────────→ api-and-interface-design
 │ └── Stakes high? ─────────────→ doubt-driven-development
 ├── Writing/running tests? ───────→ test-driven-development
 ├── Something broke? ─────────────→ debugging-and-error-recovery
 ├── Reviewing code? ──────────────→ code-review-and-quality
 └── Deploying/launching? ────────→ shipping-and-launch

注意三个细节：

树形结构，不是列表——强迫读者走唯一路径
问句触发，不是任务描述——“Something broke?” 比 “debugging task” 更贴近真实对话
父节点 → 子节点细化——符合 AI 的层次推理习惯

职责二：行为宪法（Core Operating Behaviors）

下半部分是 6 条"不可协商的行为约束"：

1
2
3
4
5
6


1. Surface Assumptions → 显式声明假设
2. Manage Confusion Actively → 遇到矛盾不能猜
3. Push Back When Warranted → 不做 yes-machine
4. Enforce Simplicity → 主动抵抗过度工程化
5. Maintain Scope Discipline → 不顺手重构
6. Verify, Don't Assume → 验证是必经步骤

读到这里我才理解为什么 Addy 要把它叫 meta-skill——它不是一个具体技能，它是治理其他技能的元规则。每一条都精确对抗 AI 的一个典型缺陷：

行为	对抗的 AI 缺陷
Surface Assumptions	AI 倾向"静默填充"歧义
Manage Confusion Actively	AI 倾向遇到矛盾"就近取一"
Push Back	AI 的奉承倾向（sycophancy）
Enforce Simplicity	AI 的过度工程化倾向
Scope Discipline	AI 的"顺手重构"倾向
Verify, Don’t Assume	AI 的"看起来对就完成了"倾向

文件最后还有一份 10 条 Failure Modes，和 6 条行为形成"进攻 vs 防守"的双层防御：

行为约束 → 处理"AI 的借口"（主动跳过的想法）
失败模式 → 处理"AI 的症状"（已经在跳过的迹象）

一个 180 行的文件，承担了整套系统的路由 + 治理。它是 Layer 1，它的存在让 Layer 2-5 才能各司其职。

Layer 2｜commands：7 个动词的克制设计

.claude/commands/ 里只有 7 个文件：

1
2
3
4
5
6
7


/spec → 写 SPEC.md
/plan → 拆解任务
/build → 实现一个任务（TDD + incremental）
/test → 写测试
/review → 五维 review
/code-simplify → 简化代码
/ship → 上线决策

7 个 slash command，对应整个开发生命周期的 7 个关键动作。每个文件都极度克制——除了 /ship，其他都在 15-25 行之间。

Command 不是 Skill 的复刻

我刚开始读的时候有个困惑：为什么有了 21 个 skill，还要单独搞一个 commands 目录？

读完后才理解——command 是 skill 的"激活快捷键"。

维度	Skill	Command
谁加载	自动/按需	用户显式触发
内容	完整方法论（100-300 行）	调用配方（15-25 行）
写给谁看	AI 模型	模型 + 人（用户要 type）
触发方式	描述匹配	`/` 前缀精确匹配
复用方向	横向通用	项目特定

Command 文件不重复 skill 内容，而是：

显式声明要调用哪个 skill
给出最小可操作步骤（4-6 步）
指定输出位置（Save the spec as SPEC.md、Save the plan to tasks/plan.md）

举个例子，/spec 全文不到 20 行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


---
description: Start spec-driven development — write a structured specification before writing code
---

Invoke the agent-skills:spec-driven-development skill.

Begin by understanding what the user wants to build. Ask clarifying questions about:
1. The objective and target users
2. Core features and acceptance criteria
3. Tech stack preferences and constraints
4. Known boundaries

Then generate a structured spec covering all six core areas: ...

Save the spec as SPEC.md in the project root and confirm with the user before proceeding.

它把 spec-driven-development 这个 200 行的 skill，浓缩成了一个用户层的快捷指令。

命令命名的语义学

每个命令名都对应一个具体的可交付物。没有 /think 或 /explore 这种没有产物的命令——这是一种纪律：

命令	隐含承诺的产物
`/spec`	SPEC.md
`/plan`	tasks/plan.md
`/build`	代码 + 测试 + commit
`/review`	review report
`/ship`	GO/NO-GO + rollback

读到 /ship 命令时我被震到了——这是 7 个命令里唯一一个超过 70 行的，因为它是一个并行 fan-out 编排器：

1
2
3
4


/ship Phase A: 并行 spawn 3 个 subagent
 (code-reviewer + security-auditor + test-engineer)
 Phase B: 主 agent 合并三份报告
 Phase C: 输出 GO/NO-GO + Rollback Plan

注意 Phase A 的关键约束：

Issue all three Agent tool calls in a single assistant turn — sequential calls defeat the purpose of this command.

它显式约束 AI 必须在一个 turn 里发出三个 Agent 调用——否则就是串行而非并行，整个 fan-out 设计就失效了。

字典型对 7 个命令逐个拆解，并对比单 skill / 多 skill / Fan-out 三种命令模式。

Layer 3｜agents：为什么只有 3 个 persona？

agents/ 目录下只有 3 个 persona 文件 + 1 个 README：

1
2
3
4


code-reviewer.md 97 行
security-auditor.md 101 行
test-engineer.md 95 行
README.md 120 行 ← 编排宪法

只有 3 个，这是有意为之的克制。

Persona 是什么？

每个 persona 文件长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


---
name: code-reviewer
description: Senior code reviewer that evaluates changes across five dimensions...
---

# Senior Code Reviewer

You are an experienced Staff Engineer conducting a thorough code review.

## Review Framework
### 1. Correctness ...
### 2. Readability ...
### 3. Architecture ...
### 4. Security ...
### 5. Performance ...

## Output Format
[Critical / Important / Suggestion 三级]

## Review Output Template
[Markdown 模板]

## Rules
[6 条行为规则]

## Composition
- Invoke directly when: ...
- Invoke via: /review or /ship
- Do not invoke from another persona.

和 Skill 文件对比，最关键的差别是 persona 有 Output Template——一段固定的 Markdown 结构。这是因为 persona 是给"会被并行调用、需要被 merge"的 subagent 用的，输出结构必须可预测、可聚合。

三层架构：Skill × Persona × Command

读 agents/README.md 时，我看到这张表，整个系统的设计意图一下清晰了：

层	定位	例子	类比
Skill	方法论 / 步骤 / 退出条件	code-review-and-quality	HOW（怎么做）
Persona	角色 / 视角 / 输出格式	code-reviewer	WHO（谁来做）
Command	用户入口 / 编排器	`/review`, `/ship`	WHEN（何时做）

具体到 /review 一个命令上：

1
2
3
4
5
6
7
8
9


用户输入 /review
 ↓
.claude/commands/review.md (WHEN — 入口)
 ↓
agents/code-reviewer.md (WHO — 视角)
 ↓
skills/code-review-and-quality/ (HOW — 流程)
 ↓
references/security-checklist.md (DATA — 数据)

四层完整解构。每层职责单一，互不重复。

为什么只有 3 个 persona？

读到这里我才意识到——3 个 persona 不是随便选的。它们对应 /ship 命令的 fan-out 三个独立视角：

1
2
3


Code quality (functional) ← code-reviewer
Security (adversarial) ← security-auditor
Tests (coverage) ← test-engineer

判定标准：

必须是独立视角——不能从其他视角派生
必须有可并行的工作内容（同一个 diff，不同关注点）
必须有结构化的输出便于 merge

像 frontend-ui、performance、accessibility 这些为什么没成为 persona？因为它们或者和现有 persona 视角重叠，或者更像 checklist 而不是视角。

核心铁律：The user is the orchestrator

README 里反复强调一条铁律：

The user (or a slash command) is the orchestrator. Personas do not call other personas.

这条规则在 agents/README.md 里被重复了 5 次以上。背后有三层原因：

平台约束：Claude Code 的 subagent 系统禁止递归——subagent 不能再 spawn subagent
信息损耗：每多一层 persona 转发，就多一次"用自己语言重述"——信息保真度下降
价值密度：纯粹做路由的 persona 没有领域价值，应该让 command 来做

为了让这条规则更具体，README 专门画了一段反例：

1
2
3
4
5
6
7
8


错误设计：
/work-on-pr → meta-orchestrator
 ↓ "this needs a review"
 code-reviewer
 ↓
 meta-orchestrator (paraphrases result)
 ↓
 user

Pure routing layer with no domain value. Adds two paraphrasing hops → information loss + 2× token cost.

这种"先画错的样子，再讲为什么错"的反例教学法，是整套文档里最有教育意义的部分。

字典型对 3 个 persona 文件逐个拆解，并展开 README 中的所有正例/反例。

Layer 4｜skills：21 个文件，一份合同

skills/ 是这个仓库最大的目录——21 个 SKILL.md 文件，按开发阶段组织：

Define（定义）：interview-me, idea-refine, spec-driven-development
Plan（规划）：planning-and-task-breakdown
Build（构建）：incremental-implementation, test-driven-development, context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, api-and-interface-design
Verify（验证）：browser-testing-with-devtools, debugging-and-error-recovery
Review（评审）：code-review-and-quality, code-simplification, security-and-hardening, performance-optimization
Ship（发布）：git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, shipping-and-launch

但更让我震撼的是——这 21 个文件的结构高度一致。

CLAUDE.md 第 30 行的合同

CLAUDE.md 里有一句话定义了所有 skill 必须遵守的 schema：

Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification

21 个 SKILL.md 文件，逐个打开，都长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# Skill Name

## Overview
[这个 skill 是干什么的、为什么存在]

## When to Use
[何时启用 + When NOT to use]

## Process
[一步一步的方法论]

## Common Rationalizations
| Rationalization | Reality |
|---|---|

## Red Flags
[反模式症状清单]

## Verification
- [ ] [可测试的完成条件]

这是一份强制 schema。SKILL.md 写法上的约束等于：

必须告诉读者"这是干什么的"（Overview）
必须告诉读者"什么时候用 / 什么时候不用"（When to Use）
必须给出可执行步骤（Process）
必须预判用户会用什么借口跳过（Common Rationalizations）
必须列出反模式症状（Red Flags）
必须给出可验证的完成条件（Verification）

没有任何一项是装饰。每一项都对应一个 AI 可能犯的错。

spec-driven-development：教科书级 Process

读完 21 个 skill 后，我心目中最教科书的是 spec-driven-development。它的 Process 段长这样：

1
2
3
4
5


SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
 │ │ │ │
 ▼ ▼ ▼ ▼
 Human Human Human Human
 reviews reviews reviews reviews

四段 gated workflow，每段都强制 human review。Do not advance to the next phase until the current one is validated.

它的 Specify Phase 里有 5 个非常具体的技巧：

Surface Assumptions — 显式列假设，末尾加 → Correct me now or I'll proceed with these.
Six core areas — Objective / Commands / Project Structure / Code Style / Testing Strategy / Boundaries
三层 Boundaries — Always do / Ask first / Never do（关键是中间那层，把"需要人类确认"显式化）
Reframe instructions as success criteria — 把"做得快一点"翻译成"LCP < 2.5s on 4G"
Spec template — 可复用的 Markdown 模板

每一个技巧都在解决一个具体的 AI 行为偏差。

Common Rationalizations 的设计精髓

每个 skill 末尾的 Common Rationalizations 表，是整个 agent-skills 项目里我学到最重要的设计模式。它干两件事：

预判 AI 偷懒的理由——AI 在长 context 里会发明各种跳过 skill 的借口
把反驳预先写好——一句话见血，不啰嗦

这是一种反熵设计。它把"AI 心理学"工程化了，让"逼 AI 不能这么做"成为可执行的格式。

读到这里我意识到：整个 agent-skills 项目最大的创新点，可能不是"列出 21 个 skill"，而是"为 skill 文件定义了一种格式"。任何一个团队，只要愿意按这个格式写自己的 skill 文件，就能把自己的工程纪律编码给 AI。

字典型逐项拆解 spec-driven-development、test-driven-development、using-agent-skills 等代表性 skill，展示 schema 在不同语境下的应用。

Layer 5｜references：lazy loading 的数据层

references/ 目录下有 5 个文件：

1
2
3
4
5


accessibility-checklist.md 160 行
performance-checklist.md 153 行
security-checklist.md 134 行
testing-patterns.md 236 行
orchestration-patterns.md 370 行

所有文件都没有 YAML frontmatter——这是它们与 skill 最本质的区别。它们不是 skill，不被自动发现，不被自动加载。

Context-on-Demand 的设计

整套架构的分层是这样的：

1
2
3
4
5


SKILL.md (process / 方法论 / 100-200 行) ← 总在 context 里
 │
 │ 指向
 ▼
references/X.md (data / 清单 / 100-400 行) ← 按需读

skill 文件保持精简，把"长尾的检查项 / 模式目录 / 反模式表"全部下沉到 references。当 AI 真正需要时，由 skill 文件指示去读对应的 reference。

CLAUDE.md 里这条约定明确写了：

Supporting files only created when content exceeds 100 lines

100 行是阈值。超过就拆出去。

引用机制：纯文本路径

跨仓库扫了一遍引用方式，模式高度一致：

1
2
3


- "see `references/security-checklist.md`"
- "For detailed accessibility requirements...see `references/accessibility-checklist.md`"
- "(see references/orchestration-patterns.md)"

没有任何自动加载机制：

不是 include 指令
不是 frontmatter 字段
不是 MCP 资源

就是一句"自然语言路径"。AI 读到这句话，自己判断是否需要 Read。

这种"软引用"的好处：

AI 决定权重：context 紧张时可以不读
透明可控：用户可以看到哪些 reference 被读了
跨工具兼容：在任何能读文件的环境都能工作

两种 reference 的功能分化

5 个 reference 文件，本质上分两类：

类型	文件	内容形态	触发点
Checklist	security / performance / accessibility	复选框任务列表	上线前、review 时
Pattern Catalog	testing-patterns / orchestration-patterns	正例 + 反例 + 决策表	设计时、新增能力时

Checklist 类的形态：

1
2
3
4
5


## Authentication
- [ ] Passwords hashed with bcrypt (≥12 rounds)
- [ ] Session cookies: httpOnly, secure, sameSite: 'lax'
- [ ] Session expiration configured
- [ ] Rate limiting on login endpoint (≤10 attempts per 15 minutes)

复选框 → 显式"做过/没做"二元状态；每条都是可验证条件（含具体参数 ≥12 rounds、≤10 attempts）。

Pattern Catalog 类的形态：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


### 1. Direct invocation (no orchestration)
[场景描述 + 示例 + 成本]

### 2. Single-persona slash command
[...]

### 3. Parallel fan-out with merge
[ASCII 流程图 + 使用条件]

---
## Anti-patterns
[...]

命名模式（A / B / C）便于交叉引用，每个模式包含图示、用例、成本、反信号，显式列出 anti-patterns。

这一层的妙处在于：它把"数据"和"方法论"彻底分开。同一个 security-checklist 被 code-review、security-and-hardening、shipping-and-launch 三个 skill 共用——写在 reference 里就只需要维护一份。

Layer X｜hooks：无侵入的 AOP 设计

hooks/ 是整个仓库里我最佩服的一层——三个 hook，三种完全不同的干预模式：

Hook	触发事件	干预方式	配套 Skill
session-start	`SessionStart`	注入 context	using-agent-skills
sdd-cache	`PreToolUse:WebFetch` + `PostToolUse:WebFetch`	替换工具输出	source-driven-development
simplify-ignore	`PreToolUse:Read` + `PostToolUse:Edit\|Write` + `Stop`	遮蔽工具输入	code-simplification

session-start：自动加载操作系统

session-start.sh 只有 24 行，干的事就一件：

1
2
3
4
5
6


META_SKILL="$SKILLS_DIR/using-agent-skills/SKILL.md"
if [ -f "$META_SKILL" ]; then
 CONTENT=$(cat "$META_SKILL")
 jq -cn --arg message "agent-skills loaded. ...
$CONTENT" '{priority: "IMPORTANT", message: $message}'
fi

每个新会话启动时，把 using-agent-skills/SKILL.md 的全部 180 行注入到第一条 system message 里。

没有它的话：

AI 进入仓库不知道有 21 个 skill
AI 不知道决策树
AI 不知道 6 条核心行为约束

CLAUDE.md 虽然总在 context，但它只有 44 行的导航信息。真正的"操作系统"是 using-agent-skills——必须通过 hook 强制加载。

sdd-cache：HTTP 协议感知的缓存

这是整个项目里我认为最精彩的一个设计。

核心矛盾：source-driven-development skill 要求每个框架决策都 fetch 官方文档——但同一个项目跨会话工作意味着反复 fetch 同一个页面。简单缓存会破坏 skill 的"always verify against current docs"承诺。

解决方案：不靠 TTL，靠 ETag / Last-Modified 校验。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


PreToolUse:WebFetch
 ↓
有缓存？──无──→ 放行
 ↓ 有
HEAD 请求 + If-None-Match: <etag>
 ↓
返回 304？──否──→ 放行（让 WebFetch 真正跑）
 ↓ 是
exit 2 + 缓存内容输出到 stderr
 ↓
Claude Code 把 stderr 当作 WebFetch 的"结果"返回给 AI

最妙的是 exit 2 当作 in-band 信号：

1
2
3
4


if [ "$STATUS" = "304" ]; then
 # ... 输出缓存内容到 stderr ...
 exit 2
fi

这不是 hack，是对协议的精确利用。

还有一个细节：没有 ETag/Last-Modified 的内容永不缓存：

1
2
3
4


if [ -z "$ETAG" ] && [ -z "$LAST_MOD" ]; then
 dbg "cannot revalidate, bypass"
 exit 0
fi

没有验证器的内容永不缓存。这是核心安全保证——避免"缓存了但永远不知道何时该失效"的状态。

simplify-ignore：让模型物理上看不到

/code-simplify 会重写代码以提高可读性。但有些代码不能被重写：

手工展开的循环（性能优化）
精心调过的算法
跨平台 workaround

如果只在注释里写"don’t simplify this"，模型不一定遵守。

simplify-ignore 的解决方案：让模型物理上看不到。

1
2
3
4


/* simplify-ignore-start: perf-critical */
result[0] = buf[0] ^ key[0];
result[1] = buf[1] ^ key[1];
/* simplify-ignore-end */

经过 hook 处理后，模型 read 文件时看到的是：

1

/* BLOCK_de115a1d: perf-critical */

只有占位符。模型根本不知道里面是什么。

三阶段生命周期：

1
2
3
4
5
6


PreToolUse:Read → 备份原文件 + 替换为 BLOCK_<hash> 占位符
 → 模型读到的是替换后的文件
PostToolUse:Edit → 模型写入新版本（仍含 BLOCK_<hash>）
 → hook 展开占位符回到原代码
 → 保存到磁盘
Stop（会话结束） → 从备份恢复所有被保护的文件

内容哈希作为占位符 ID——即使模型把占位符复制、移位、删除，hash 仍能精确定位回原代码。

三个 hook 的设计共性

虽然三个 hook 用途完全不同，但它们都遵守相同的设计原则：

优雅降级：依赖缺失（jq、curl）时静默 exit 0，让会话继续
显式调试日志：每个关键步骤打日志到 .debug.log，通过环境变量或 sentinel 文件触发
与具体 skill 一对一绑定：每个 hook 只服务一个 skill
文档专门解释反直觉行为：每个 hook 都假设读者会困惑，主动消除困惑

Hook 的核心哲学：不修改 skill，增强 skill

读完 hooks 后我意识到——这三个 hook 都没有修改任何 skill 内容，但增强了 skill 的能力。

SDD-CACHE.md: “The skill itself is unchanged. It continues to follow DETECT → FETCH → IMPLEMENT → CITE. The hook only changes what happens under the hood when FETCH runs.”

这是 AOP（面向切面编程）思想在 AI 工程里的应用：

session-start 干预 Layer 1 的加载方式
sdd-cache 干预 Layer 4 的工具调用
simplify-ignore 干预 Layer 4 的工具读写

它们都不在层级内，是横切关注点——在不修改 skill 本身的情况下增强 skill。

字典型对 hooks 三个脚本逐行拆解，展示每个 hook 的完整 shell 实现与边界情况处理。

三条贯穿全系统的设计哲学

读完整个 agent-skills 项目，鬼哥提炼出三条贯穿所有 6 层的核心哲学。它们不是 Addy 写在某一个文件里的，但渗透在每一个设计决策里。

哲学一：委托而非复制（Never Duplicate）

CLAUDE.md 第 43 行写着：

Never: Duplicate content between skills — reference other skills instead.

这一条规则贯穿了所有 6 层：

/build command 委托给 incremental-implementation + TDD，而不是复制内容
skills 委托给 references，而不是塞清单
personas 委托给 skills，而不是复制流程
hooks 委托给协议（exit code），而不是定义自己的通信机制

整个仓库的"指针架构"，根源就是 CLAUDE.md 的这一条 “Never: Duplicate content”。 任何一处违反这条规则，就会触发跨文件的内容漂移，进而瓦解整个系统的可维护性。

哲学二：利用协议而非绕过协议

sdd-cache 用 exit code 2 实现缓存命中通信——这不是 hack 出来的新通道，而是精确地用了 Claude Code hook 协议里 exit code 2 的含义。

simplify-ignore 也是——它不给模型发"特殊指令"，而是直接物理修改 Read 工具返回的文件内容。

Hook 作用在协议层，不作用在语义层。

整个项目里，凡是需要在 AI 行为上做特殊干预的地方，agent-skills 都选择"利用现有协议"的方式：

用 exit code 传信号，不发明新指令
用 ASCII 决策树触发路由，不写规则引擎
用 Markdown 模板约束输出，不接入校验工具

这种思维方式给我的启发是——好的 AI 工程，应该用 AI 已经会用的语言去约束 AI，不要发明一套 AI 看不懂的形式系统。

哲学三：用反例教学定义边界

读完 agents/README.md 后我意识到——架构铁律是"否定式"的（不要做 X），所以必须用反例教学。

agent-skills 里到处是反例：

agents/README.md 画了一段刻意的"反例代码"（meta-orchestrator）
每个 skill 的 Red Flags 段是"AI 已经在偏离时的可观察行为"
每个 skill 的 Common Rationalizations 是"AI 还没行动时的思维偏差"
spec-driven-development 列了"When NOT to use"的反向条件

正例告诉读者 “做什么”，反例告诉读者 “边界在哪里”。两者缺一不可。

很多技术文档只有正例——读者读完后知道怎么做，但不知道什么时候不该做。agent-skills 用大量反例补上了这块。

鬼哥的推荐｜从架构到思维体系

写到这里，文章其实已经把 agent-skills 的架构讲完了。但鬼哥想留点篇幅，跟你聊一件更重要的事。

不要只学架构，要读"高手的思维体系"

如果你只是把 agent-skills 当成一套"AI 提示词模板"或者"工程纪律检查表"，那你只学到了 30%。

剩下的 70% 在哪？在源码里，在每一个设计决策背后的取舍里。

举几个我读源码时被震到的地方：

1）100 行是拆分阈值，但 SKILL.md 自己可以超过 100 行。

CLAUDE.md 说 “Supporting files only created when content exceeds 100 lines”。但 spec-driven-development 的 SKILL.md 自己有 200 行——为什么不拆？

读源码我才理解：100 行规则是"data vs methodology"的分界线，不是文件长度的硬上限。方法论可以长，但清单和数据必须拆出去。这个判断只有写过大量工程文档的人才能精准把握。

2）路由树和决策矩阵交叉验证。

using-agent-skills 的决策树和 agents/README.md 的"Decision matrix"讲的是不同的事——前者是"任务路由"，后者是"协作模式选择"。两者交叉但不重叠。

读到这里我才意识到——好的文档系统会用多种结构表达同一个概念，从不同角度让读者反复确认理解。 这是教学体系而不是文档体系。

3）每个 skill 都有反例，但 Verification 没有反例。

为什么？因为 Verification 是 boolean 可判定的（yes/no），反例没有意义。Common Rationalizations 和 Red Flags 是模糊地带（AI 可能这么想/可能这么做），所以需要反例。

这种"什么需要反例、什么不需要"的精准判断，是工程经验的体现。

高手思维的核心：用约束代替能力

读完 agent-skills 后我有一个最深的感受——Addy 在用工程约束代替模型能力。

很多人做 AI 项目的第一反应是：“这个模型不够好，我要换更强的"或"我要给它更多 example”。

但 Addy 的做法是相反的：

不期待模型自己知道要写 spec → 用 skill 强制
不期待模型自己知道要写测试 → 用 TDD skill 强制
不期待模型自己知道要 review → 用 /ship 编排 review
不期待模型自己知道要 rollback → 用模板强制输出 rollback plan

他把"对模型的期待"降到最低，把"对流程的设计"提到最高。

这才是十几年工程经验在 AI 时代的真正价值——你知道"什么是会出错的"，所以你设计了流程去防止它出错，而不是寄希望于 AI 自己不出错。

落地：从一份 CLAUDE.md 开始

如果你想把这套思维体系落地到你自己的 AI 项目里，鬼哥的建议是——不要直接 fork agent-skills，先写你自己的 CLAUDE.md。

按照本文剖析的 5 段结构：

1
2
3
4
5


1. Project Structure (你的目录 + 一句话描述)
2. [Categorical Index] (按场景给资产索引)
3. Conventions (你的文件 schema 约束)
4. Commands (怎么验证 / 跑测试)
5. Boundaries (Always / Ask first / Never)

写完后，你会发现：

你自己都说不清楚的"项目惯例"——其实就是模糊的工程纪律
你写不出来的"Boundaries"——其实就是你团队里没有共识的边界
你列不齐的"Conventions"——其实就是新人最容易踩坑的地方

写一份 AI 看的 CLAUDE.md，本质上是逼自己把工程纪律显式化。 这件事的价值，远超过让 AI 写得更好。

然后你可以再写自己的 skill 文件——按照 6 段式 schema（Overview / When to Use / Process / Common Rationalizations / Red Flags / Verification）。这不仅是给 AI 看的，更是把你的工程经验沉淀成可复用资产。

结语

agent-skills 这套体系最让我震撼的，不是它的精密程度，而是它把"资深工程师的反射"编码成了 AI 可以执行的格式。

工程经验从此可以被复制、被传承、被工程化地约束 AI。

这件事的意义，在 AI 编程时代刚刚开始。

如果你和我一样，是一个想把工程经验和 AI 开发结合好的工程师——强烈建议你也深入读一遍 agent-skills 的源码。不只是学它的架构，更要学它每个决策背后的思维方式。

这是 AI 时代，老工程师的护城河。

想看每一层的极致颗粒度详细拆解？翻字典型《agent-skills 项目手册》。

想看 Addy 项目的整体定位和"反合理化"机制的来龙去脉？翻《Agent Skills：当 Google 工程文化遇上 AI 编程代理》。

本文为鬼哥的 agent-skills 学习笔记。原项目地址：https://github.com/addyosmani/agent-skills。

一张 4090 跑 Gemma4 26B：用 Ollama 搭本地 AI 开发环境实测

Mon, 04 May 2026 00:00:00 +0000

以前本地大模型像玩具：能聊天，但一进开发工作流就露怯。现在一张 4090 已经能把 Gemma4 26B 跑起来，还能接 Codex、Claude Code、Hermes Agent。问题只剩一个：它到底是生产力，还是昂贵的电子暖手宝？

这篇文章不讲玄学，直接上手：用 Ollama 部署本地模型、用 API 对话、接入开发工具，再看 RTX 4090 上的真实推理数据。

先看结论

我这台机器的实测环境：

项目	数据
GPU	NVIDIA GeForce RTX 4090
`nvidia-smi` 显存	49140 MiB
NVIDIA Driver	570.158.01
CUDA	12.8
Ollama	0.23.0
模型	`gemma4:26b`
模型文件大小	17 GB
Ollama 加载后显存	约 24.5 GB
持续输出速度	约 160-166 tokens/s
长输出功耗	约 260-265W
长输出温度	54-60C

先打补丁：我这张 4090 在 nvidia-smi 里显示约 48GB 显存，不是常见 24GB 版本。普通 24GB 4090 也可以参考这篇文章的方法，但长上下文、并发和 Agent 场景要更保守。

我的结论是：

本地 26B 模型已经能做日常开发副驾，但还不能无脑替代云端顶级模型。

它适合解释私有代码、写脚本、生成小模块、做初步 code review；但复杂重构、跨仓库规划、长链路 Agent，仍然会被模型能力、上下文和工具链沙盒卡住。

Ollama 解决了什么

Ollama 的价值不是让模型变聪明，而是把本地部署降到几条命令：

1
2


ollama pull gemma4:26b
ollama run gemma4:26b

没有 Ollama，你要处理权重格式、量化版本、CUDA、服务启动、API 适配。用 Ollama 之后，它更像一个本地模型网关：

1
2
3
4
5
6
7


开发工具 / 脚本 / Agent
 |
 v
http://localhost:11434
 |
 v
本地 Gemma4 26B

查看模型：

1

ollama list

我本机输出里有：

1
2
3
4
5
6


NAME SIZE
gemma4:26b 17 GB
gemma4:e2b 7.2 GB
gemma4:latest 9.6 GB
gpt-oss:20b 13 GB
gpt-oss:120b 65 GB

查看运行状态：

1

ollama ps

实测加载后：

1
2


NAME SIZE PROCESSOR CONTEXT
gemma4:26b 25 GB 100% GPU 262144

这行信息很关键：100% GPU 说明没有明显落到 CPU，262144 说明上下文窗口很大，但不代表每次都应该塞满。

先直接对话

命令行对话：

1

ollama run gemma4:26b

然后直接问：

1

用三句话解释 Ollama 是什么。

如果要从程序里调用，用 Ollama 原生 API：

1
2
3
4
5
6
7
8


curl http://localhost:11434/api/chat \
 -d '{
 "model": "gemma4:26b",
 "messages": [
 {"role": "user", "content": "用三句话解释 Ollama 是什么。"}
 ],
 "stream": false
 }'

Ollama 返回的 JSON 里有性能字段：

字段	含义
`load_duration`	模型加载耗时
`prompt_eval_count`	输入 token 数
`prompt_eval_duration`	输入处理耗时
`eval_count`	输出 token 数
`eval_duration`	输出生成耗时

核心公式：

1

输出速度 = eval_count / eval_duration_seconds

这比手动掐秒表靠谱。

接入 Codex：默认沙盒失败，授权后跑通

Codex CLI 版本：

1

codex-cli 0.128.0

启动方式：

1

codex --oss --local-provider ollama -m gemma4:26b

我先跑了一个只读任务：

1
2
3
4
5
6
7


codex exec \
 --oss \
 --local-provider ollama \
 -m gemma4:26b \
 -s read-only \
 --ephemeral \
 "请阅读当前目录的 benchmark.sh，简要说明它会如何测试 Ollama 本地模型性能，不要修改任何文件。"

Codex 成功识别了 Ollama provider：

1
2
3


model: gemma4:26b
provider: ollama
sandbox: read-only

但默认 read-only sandbox 下，内部执行读文件命令时失败：

1

bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted

这个结果很有价值：本地模型速度够，不代表 Agent 工具链一定顺。 这次不是模型不行，而是当前 Linux 环境下 bubblewrap sandbox 权限受限。

随后我显式授权绕过 Codex 内部 sandbox，仍然使用同一个只读任务：

1
2
3
4
5
6
7


codex exec \
 --oss \
 --local-provider ollama \
 -m gemma4:26b \
 --dangerously-bypass-approvals-and-sandbox \
 --ephemeral \
 "请阅读当前目录的 benchmark.sh，简要说明它会如何测试 Ollama 本地模型性能，不要修改任何文件。"

这次跑通了。Codex 成功执行：

1

cat benchmark.sh

并总结出脚本会调用本地 Ollama /api/chat，保存原始 JSON，再用 jq 计算 load_s、prompt_tokens_per_s、output_tokens_per_s 等指标。换句话说，Codex + Ollama + Gemma4 26B 是可用的，但在这台机器上需要绕过 Codex sandbox 才能读文件。

遇到类似问题，优先检查：

是否在受限容器、远程桌面、特殊 sandbox 里运行
系统是否允许 user namespace
Codex sandbox 模式是否过严
是否需要换普通终端或调整权限策略

接入 Claude Code：真实可用

Claude Code 版本：

1

2.1.126 (Claude Code)

Ollama 提供了 Anthropic-compatible API，所以可以这样接：

1
2
3
4
5


export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434

claude --model gemma4:26b

我用完整路径跑了一个非交互只读任务：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


env ANTHROPIC_AUTH_TOKEN=ollama \
 ANTHROPIC_BASE_URL=http://localhost:11434 \
 ANTHROPIC_API_KEY= \
 /home/luoli/.local/bin/claude \
 -p \
 --model gemma4:26b \
 --no-session-persistence \
 --permission-mode dontAsk \
 --tools Read \
 --output-format json \
 "请阅读当前目录的 benchmark.sh，简要说明它如何测试 Ollama 本地模型性能。不要修改任何文件。"

结果成功：

指标	数据
状态	success
总耗时	7889 ms
API 耗时	7824 ms
轮数	2
输入 token	16319
输出 token	713
permission denials	0

Claude Code 正确读取了 benchmark.sh，并总结出脚本会用 5 个 case 调用 Ollama /api/chat，保存原始 JSON，再用 jq 提取 total_s、load_s、prompt_tokens_per_s、output_tokens_per_s 等指标。

这就是一个正面案例：同样是 Gemma4 26B，本地模型不只会聊天，也能通过 Claude Code 的 Read 工具进入真实开发上下文。

接入 Hermes Agent

Hermes Agent 版本：

1

Hermes Agent v0.12.0 (2026.4.30)

快速启动：

1

ollama launch hermes

也可以 oneshot 测试：

1
2
3


hermes --provider ollama \
 -m gemma4:26b \
 -z "请用三句话说明你当前是否在通过 Ollama 本地模型运行，并给一个开发建议。"

我本机能跑通。再用：

1

hermes status

看到：

1
2


Model: gemma4
Provider: ollama-launch

这里有个细节：模型回答里可能说自己是 custom provider，但工具状态显示 ollama-launch。所以验证 Agent 是否真的接入本地模型，不要只看模型自述，要看工具的 status 或配置。

4090 + Gemma4 26B 实测

我写了一个 benchmark 脚本：

1

content/post/ollama-local-dev/benchmark.sh

它测试 5 类任务：

Case	目的
Short chat	短对话
Long Chinese output	长中文输出
Code generation	代码生成
Code review	代码审查
Agent planning	Agent 规划

实测结果：

Case	总耗时	输出 tokens	输出速度
短对话	4.790s	697	165.93 tokens/s
长中文输出	18.728s	2785	160.84 tokens/s
代码生成	13.337s	1985	161.66 tokens/s
代码审查	14.430s	2143	161.16 tokens/s
Agent 规划	13.631s	2028	161.48 tokens/s
长输出监控	24.020s	3554	159.79 tokens/s

结论很稳定：

1

Gemma4 26B 在这台机器上的持续输出速度约 160 tokens/s

显存、功耗和温度

模型加载后：

1
2
3
4


GPU Memory: 24527MiB / 49140MiB
Power: 72W
Temp: 51C
Process: /usr/local/bin/ollama

长输出期间用：

1

nvidia-smi dmon -s pucvmet -c 20

观察到：

指标	数据
功耗	260-265W
温度	54-60C
SM 利用率	82-87%
显存占用	约 24529MB
显存利用率	50-55%
显存频率	10501 MHz
核心频率	2670-2685 MHz

这说明推理确实主要在 GPU 上跑，而且负载不低。长时间跑 Agent 时，真正要关注的不只是 tokens/s，还有散热、风噪、电费和显存被其他任务抢占。

一个容易误判的点：thinking 也算 token

第一次烟测里，我只是问：

1

用三句话解释 Ollama 是什么。

但 API 返回里的 eval_count 到了 887，因为模型生成了不少 thinking 内容。

所以做 benchmark 时不要只看“用户看到多少字”。对推理耗时来说，模型实际生成的 token 才是成本，包括 thinking。

适合怎么用

我建议这样分工：

场景	本地 Gemma4 26B 是否适合
私有代码解释	很适合
写脚本 / 小工具	很适合
生成测试样例	适合
初步 code review	适合
大型重构	谨慎
跨仓库复杂任务	不建议只靠本地
高风险生产改动	必须人工复核

最舒服的用法不是“让本地模型全自动开发完整系统”，而是：

1
2


本地模型负责高频、低风险、隐私敏感任务；
云端强模型负责低频、高难度、强推理任务。

Takeaway

回顾一下，搭一个能用于开发的本地 AI 环境，只需要四步：

用 Ollama 拉取模型：ollama pull gemma4:26b
用 API 或 CLI 确认模型能稳定对话
把 Codex、Claude Code、Hermes 接到 localhost:11434
用 tokens/s、显存、功耗、温度和 Agent 成功率一起评估体验

这次实测最重要的结论不是“4090 很快”，而是：

本地模型的下限已经很高，但上限取决于工具链。

Claude Code 能顺利读取文件，Codex 在同一环境里被 sandbox 卡住，Hermes 能跑通但 provider 映射要核验。这才是真实的本地 AI 开发体验：模型只是发动机，方向盘、刹车和路况一样重要。

参考资料

Claude Managed Agents：从聊天机器人到自主 Agent 的一步之遥

Thu, 09 Apr 2026 00:00:00 +0000

150 行代码就能造一个"数字分身"，但它只会聊天，不会做事。

如果它能帮你写代码、搜资料、跑脚本呢？

两个月前，我给博客做了一个 AI 数字分身——guige_avatar。访客点击右下角的聊天按钮，就能和"鬼哥"的 AI 分身聊技术、聊 AI、聊生活。

整个后端只有 150 行 JavaScript，部署在 Vercel 上，用的是 OpenAI 的 GPT-4.1-nano。它很轻量，也确实能用——但说实话，它只是一个穿了马甲的 Chat Completion API。

2026 年 4 月，Anthropic 推出了 Claude Managed Agents——一个托管式的 Agent 运行时平台。看完文档后我意识到：如果用 Managed Agents 重构鬼哥分身，它能从一个只会聊天的机器人，进化成一个真正能做事的自主 Agent。

本文就以这个真实案例为主线，带你理解 Managed Agents 到底是什么、能做什么、以及什么时候该用它。

一、手搓版：guige_avatar 架构剖析

先看看现在的数字分身长什么样。注意截图右下角那个小对话气泡——那就是访客与鬼哥 AI 分身聊天的入口。

1.1 整体架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


访客浏览器 Vercel Serverless
┌─────────────┐ POST ┌──────────────────┐ ┌─────────┐
│ 博客首页 │ ─────────→ │ api/chat.js │ ───→ │ OpenAI │
│ 聊天面板(JS) │ ←───────── │ (~150 行) │ ←─── │ API │
└─────────────┘ JSON │ │ └─────────┘
 │ ↓ fire-and-forget│
 │ Telegram 通知 │
 └──────────────────┘
 ↑
 data/persona.yaml
 (人设 YAML ~200行)

1.2 核心代码：就这么简单

后端的核心逻辑可以浓缩成这几步：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// 1. 加载人设 YAML → 构建 system prompt
const persona = yaml.load(fs.readFileSync('data/persona.yaml'));
const systemPrompt = buildSystemPrompt(persona);

// 2. 拼接历史（最多 10 轮）+ 当前消息
const messages = [
 { role: 'system', content: systemPrompt },
 ...history.slice(-10),
 { role: 'user', content: userMessage }
];

// 3. 一次 API 调用，返回结果
const response = await openai.chat.completions.create({
 model: 'gpt-4.1-nano',
 messages
});

没有 agent loop，没有工具调用，没有自主决策。每次请求就是一次单轮 LLM 推理。

1.3 人设工程：它的真正价值

guige_avatar 最精巧的部分不是代码，而是 persona.yaml——一个约 200 行的人设定义文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


personality:
 traits: ["技术极客", "偶尔幽默", "喜欢深度思考"]
 speaking_style: "口语化但有技术深度"
 
knowledge:
 expertise: ["大数据", "AI/LLM", "分布式系统"]
 current_projects: ["Claude Code 源码分析", "博客写作"]
 
boundaries:
 forbidden_topics: ["政治敏感", "个人隐私"]
 fallback: "这个话题我不太方便聊，换个有趣的话题吧？"

这种"人设工程"确实让对话体验很自然。但问题是——人设再好，它也只能聊天，不能做事。

1.4 手搓版的天花板

能力	状态
闲聊	✅ 流畅自然
回答技术问题	✅ 基于人设知识
搜索最新信息	❌ 无网络访问
查看博客文章	❌ 无文件读取
帮访客写代码	❌ 无代码执行
记住上次对话	❌ 刷新即丢失
自主完成任务	❌ 无 agent loop

这就是一个典型的聊天机器人——能对话，但不能行动。

二、Managed Agents：它到底是什么？

2.1 一句话定义

Managed Agents = Anthropic 托管的 Agent 运行时。

你不需要自己搭 agent loop、沙箱、工具执行层。Anthropic 提供一个完整的云端容器环境，Claude 在里面自主运行 bash、读写文件、搜索网页、执行代码。

如果 Messages API 是"你调用模型，模型返回文本"，那 Managed Agents 就是"你定义 Agent，Agent 自主完成任务"。

2.2 与 Messages API 的定位差异

	Messages API	Managed Agents
本质	直接模型调用	预构建的 Agent 运行时
适合	自定义 agent loop、精细控制	长时间异步任务、最小化基础设施
工具执行	你的代码负责执行	Anthropic 云端容器执行
类比	买 CPU 自己组电脑	买整机开箱即用

2.3 核心概念四件套

Managed Agents 的整个模型围绕四个概念：

概念	说明	类比
Agent	模型 + system prompt + 工具 + MCP servers	一个人的"能力定义"
Environment	云端容器模板：预装包、网络规则	这个人的"工作环境"
Session	运行中的 Agent 实例，绑定 Agent + Environment	一次具体的"工作会话"
Events	应用与 Agent 之间的消息流（SSE）	你和这个人之间的"对话"

工作流程：

1
2
3
4
5
6
7
8
9


创建 Agent（一次性） → 创建 Environment（一次性）
 ↘ ↙
 创建 Session（每次任务）
 ↓
 发送 Event（用户消息）
 ↓
 流式接收 Agent 响应（SSE）
 ↓
 可中途引导或中断

三、Case Study：数字分身 v1（手搓）vs v2（Managed Agents）

这是本文最核心的部分。我们来看，如果用 Managed Agents 重构鬼哥分身，会发生什么变化。

3.1 对话 → 能动手：工具能力

v1（手搓版）：只能基于 system prompt 中的静态知识回答。

1
2
3


访客：你最近写了什么文章？
鬼哥分身：我最近在写 Agent Skills 和 Gemma 4 的分析文章...
（这是 persona.yaml 里预写的，不是实时查的）

v2（Managed Agents 版）：有完整的工具链。

1
2
3
4
5
6
7
8


访客：你最近写了什么文章？
鬼哥分身：[使用 bash] ls content/post/ | tail -5
 [使用 read] 读取最近 5 篇文章的 frontmatter
 我最近写了这些文章：
 1. Agent Skills 深度解析（4月7日）
 2. Gemma 4 深度分析（4月5日）
 3. Karpathy 的 LLM Wiki（4月2日）
 ...每篇都有链接，要看哪篇？

Managed Agents 的内置工具：

工具	能力	数字分身的用途
Bash	执行 shell 命令	列出文章、统计数据
Read / Write / Edit	文件读写	查看博客内容、生成草稿
Glob / Grep	文件搜索	搜索特定话题的文章
Web Search / Fetch	网络搜索	查最新技术动态

3.2 内存级历史 → 持久化会话

v1：对话历史存在前端 JavaScript 内存中，刷新页面就没了。

1
2


// v1：前端维护历史，刷新即丢失
let history = []; // 🔥 页面刷新 = 失忆

v2：Session 天然持久化，Event 历史服务端保存。

1
2
3
4
5
6
7
8


# v2：Session 持久化，随时可恢复
session = client.beta.sessions.create(
 agent=avatar_agent.id,
 environment_id=env.id,
 title="访客 A 的对话"
)
# 下次访问，用同一个 session_id 继续
# 完整的对话历史都在服务端

更关键的是，Managed Agents 有 Memory（研究预览阶段）——跨会话的长期记忆。这意味着鬼哥分身可以记住：“上次这个访客问过 Spark 调优，他应该是做大数据的。”

3.3 单轮推理 → 多步 Agent Loop

这是最本质的差异。

v1：一问一答，没有中间推理步骤。

1

用户消息 → LLM 生成回复 → 返回

v2：Agent 可以自主规划多步执行。

1
2


用户消息 → Claude 思考 → 调用工具 A → 分析结果 
 → 调用工具 B → 综合判断 → 生成回复 → 返回

比如访客问"帮我分析一下你这个博客的技术栈"：

v1：只能背 persona.yaml 里预写的答案
v2：grep -r "hugo" config/ → cat themes/hugo-theme-stack/... → ls layouts/ → 基于实际代码给出准确分析

3.4 无沙盒 → 云端容器

v1：代码在 Vercel Serverless Function 里跑，只有 150ms 的冷启动预算，不能装额外的包。

v2：完整的云端容器。

1
2
3
4
5
6
7
8
9


environment = client.beta.environments.create(
 name="guige-avatar-env",
 config={
 "type": "cloud",
 "networking": {"type": "unrestricted"},
 # 可以预装任何包
 # Python, Node.js, Go, Hugo...
 },
)

容器意味着：

可以预装 Hugo 来本地构建预览
可以跑 Python 脚本分析数据
可以 git clone 仓库来读取最新代码
网络不受限，可以访问外部 API

3.5 单 Agent → 多 Agent 编排

v1：一个 function 处理所有事情。

v2：可以按职责拆分为多个专精 Agent。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# 主 Agent：鬼哥分身（对话协调者）
avatar = client.beta.agents.create(
 name="鬼哥分身",
 model="claude-sonnet-4-6",
 system="你是鬼哥的数字分身...",
 tools=[{"type": "agent_toolset_20260401"}],
 callable_agents=[
 {"type": "agent", "id": blog_agent.id, ...},
 {"type": "agent", "id": code_agent.id, ...},
 ]
)

# Sub-Agent 1：博客助手（搜索和推荐文章）
blog_agent = client.beta.agents.create(
 name="博客助手",
 model="claude-haiku-4-5", # 用小模型节省成本
 system="你负责搜索和推荐鬼哥的博客文章...",
 tools=[{"type": "agent_toolset_20260401"}],
)

# Sub-Agent 2：代码助手（分析代码、写 demo）
code_agent = client.beta.agents.create(
 name="代码助手",
 model="claude-sonnet-4-6",
 system="你负责帮访客分析代码和写 demo...",
 tools=[{"type": "agent_toolset_20260401"}],
)

当访客问文章相关的问题时，主 Agent 委托给博客助手；问代码问题时，委托给代码助手。各司其职，成本可控。

四、完整对比：手搓 vs 托管

维度	v1 手搓版	v2 Managed Agents
本质	Chat Completion 包装器	自主 Agent 平台
Agent Loop	无，单轮 request-response	有，多步推理 + 工具调用循环
工具能力	无	Bash、文件操作、Web 搜索、MCP
代码执行	不可能	云端容器沙盒
对话记忆	前端内存，刷新丢失	服务端持久化 Session
长期记忆	无	Memory（研究预览）
多 Agent	不可能	Coordinator + Sub-agents
后端代码	~150 行 JS	~50 行 Python（SDK 调用）
基础设施	Vercel function（自己维护）	Anthropic 全托管
模型	GPT-4.1-nano（OpenAI）	Claude Sonnet/Haiku（Anthropic）
成本	API 调用费 + Vercel 免费层	API 调用费 + Session 运行费
开发周期	1 天	1 天（SDK 很简洁）
适合场景	轻量级人设聊天	需要工具和自主性的场景

五、SDK 实战：5 分钟跑通 Managed Agents

5.1 安装

1
2


pip install anthropic
export ANTHROPIC_API_KEY="your-key"

5.2 创建 Agent + Environment + Session

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


from anthropic import Anthropic

client = Anthropic()

# 1. 创建 Agent
agent = client.beta.agents.create(
 name="鬼哥分身 v2",
 model="claude-sonnet-4-6",
 system="""你是鬼哥（luoli523）的数字分身。
 
性格：技术极客，偶尔幽默，喜欢深度思考。
擅长：大数据、AI/LLM、分布式系统、Claude Code。
说话风格：口语化但有技术深度，喜欢用类比解释复杂概念。

你可以使用工具来查看博客文章、搜索信息、执行代码。
当访客问到你不确定的事情时，先搜索再回答，不要编造。""",
 tools=[
 {"type": "agent_toolset_20260401"},
 ],
)

# 2. 创建 Environment
environment = client.beta.environments.create(
 name="avatar-env",
 config={
 "type": "cloud",
 "networking": {"type": "unrestricted"},
 },
)

# 3. 创建 Session
session = client.beta.sessions.create(
 agent=agent.id,
 environment_id=environment.id,
 title="访客对话",
)

print(f"Agent: {agent.id}")
print(f"Environment: {environment.id}")
print(f"Session: {session.id}")

5.3 发消息 + 流式接收

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


with client.beta.sessions.events.stream(session.id) as stream:
 # 发送用户消息
 client.beta.sessions.events.send(
 session.id,
 events=[{
 "type": "user.message",
 "content": [{
 "type": "text",
 "text": "帮我看看你博客最近写了什么文章"
 }],
 }],
 )

 # 流式处理响应
 for event in stream:
 match event.type:
 case "agent.message":
 for block in event.content:
 print(block.text, end="")
 case "agent.tool_use":
 print(f"\n[🔧 使用工具: {event.name}]")
 case "session.status_idle":
 print("\n\n✅ 完成")
 break

输出可能长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


让我看看最近的文章...
[🔧 使用工具: bash]
[🔧 使用工具: read]

最近写了这几篇：
1. **Agent Skills 深度解析**（4月7日）— 拆解 Addy Osmani 的 19 个 AI Agent skill
2. **Gemma 4 深度分析**（4月5日）— Google 开源模型的架构和应用
3. **Karpathy 的 LLM Wiki**（4月2日）— 从零理解 LLM 的百科全书

要看哪篇的详细内容？

✅ 完成

5.4 TypeScript 版本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// 创建 Agent
const agent = await client.beta.agents.create({
 name: "鬼哥分身 v2",
 model: "claude-sonnet-4-6",
 system: "你是鬼哥的数字分身...",
 tools: [{ type: "agent_toolset_20260401" }],
});

// 创建 Environment
const env = await client.beta.environments.create({
 name: "avatar-env",
 config: { type: "cloud", networking: { type: "unrestricted" } },
});

// 创建 Session
const session = await client.beta.sessions.create({
 agent: agent.id,
 environment_id: env.id,
});

// 发消息 + 流式响应
const stream = await client.beta.sessions.events.stream(session.id);

await client.beta.sessions.events.send(session.id, {
 events: [{
 type: "user.message",
 content: [{ type: "text", text: "你最近在研究什么？" }],
 }],
});

for await (const event of stream) {
 if (event.type === "agent.message") {
 for (const block of event.content) {
 process.stdout.write(block.text);
 }
 } else if (event.type === "agent.tool_use") {
 console.log(`\n[🔧 ${event.name}]`);
 } else if (event.type === "session.status_idle") {
 console.log("\n\n✅ Done");
 break;
 }
}

六、工具配置：精细控制

默认的 agent_toolset_20260401 启用全部工具。但你也可以按需开关：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# 只开 bash 和文件操作，关掉网络
agent = client.beta.agents.create(
 name="安全受限的分身",
 model="claude-sonnet-4-6",
 tools=[{
 "type": "agent_toolset_20260401",
 "default_config": {"enabled": False},
 "configs": [
 {"name": "bash", "enabled": True},
 {"name": "read", "enabled": True},
 {"name": "glob", "enabled": True},
 {"name": "grep", "enabled": True},
 # web_fetch 和 web_search 保持关闭
 ]
 }],
)

还支持自定义工具——你定义接口，Claude 决定何时调用，你的代码执行后把结果返回：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


agent = client.beta.agents.create(
 name="带自定义工具的分身",
 model="claude-sonnet-4-6",
 tools=[
 {"type": "agent_toolset_20260401"},
 {
 "type": "custom",
 "name": "get_blog_stats",
 "description": "获取博客的访问统计数据",
 "input_schema": {
 "type": "object",
 "properties": {
 "period": {
 "type": "string",
 "description": "统计周期：today, week, month"
 }
 },
 "required": ["period"]
 }
 }
 ],
)

七、手搓 vs 托管：什么时候用哪个？

这两种方案不是非此即彼的关系，而是不同复杂度和需求下的最优选择。

用手搓版（Messages API / 自建）

需求简单：纯聊天，不需要工具调用
成本敏感：Vercel 免费层 + 便宜的小模型就够了
完全控制：你需要自定义每一个细节
已有基础设施：你的团队已经有成熟的 agent 框架
离线场景：需要本地部署

用 Managed Agents

需要工具能力：Agent 需要执行代码、搜索网页、读写文件
长时间任务：任务可能运行几分钟甚至几小时
零基础设施：不想自己维护沙盒和 agent loop
多 Agent 编排：任务需要多个专精 Agent 协作
持久化会话：需要跨请求保持上下文和文件状态

混合方案：最佳实践

实际上，鬼哥分身最可能的进化路径是混合方案：

1
2
3
4
5
6
7


访客消息
 ↓
前端（博客首页）
 ↓
轻量网关（Vercel / Cloudflare Worker）
 ├── 简单闲聊 → 直接 Messages API（省钱）
 └── 复杂任务 → 转发到 Managed Agents Session

简单问答（“你是谁？““你喜欢什么？"）走便宜的 Messages API；需要搜索、执行代码、多步推理的任务走 Managed Agents。按需升级，不浪费。

八、Beta 注意事项

Managed Agents 目前是 Beta 状态（managed-agents-2026-04-01），几个关键信息：

所有 API 账户默认可用，无需单独申请
SDK 自动设置 beta header，直接用就行
Research Preview 功能（Outcomes、Multi-agent、Memory）需要单独申请
Rate Limit：创建操作 60 req/min，读取操作 600 req/min
支持 7 种 SDK：Python、TypeScript、Go、Java、C#、Ruby、PHP
还有 CLI 工具 ant（Homebrew 安装）

品牌规范提醒：如果你在产品中集成 Managed Agents，可以用 “Claude Agent” 命名，但不能用 “Claude Code” 或 “Claude Cowork” 的名称和视觉元素。

总结

从 guige_avatar 到 Managed Agents，本质上是从 “调用模型生成文本” 到 “委托 Agent 完成任务” 的范式转移。

从	到
Chat Completion	Agent Session
单轮推理	多步 Agent Loop
无工具	Bash + 文件 + Web + 自定义
前端内存	服务端持久化
单一 Agent	多 Agent 编排
自建一切	托管运行时

Managed Agents 本质上是 “Claude Code as a Service”——把 Claude Code 的核心能力（bash、文件操作、web 搜索、agent loop）包装成云端 API，让开发者在自己的产品中嵌入 Claude 级别的 Agent 能力。

对于鬼哥分身来说，150 行手搓版已经够用了。但当某天访客说"帮我写一个 Spark 调优的 demo"时，Managed Agents 版本会回答：

1
2
3
4


好的，让我帮你写一个...
[🔧 使用工具: write] 创建 spark_tuning_demo.py
[🔧 使用工具: bash] python spark_tuning_demo.py
脚本已经写好并测试通过了，关键的调优点是...

从"我告诉你"到"我帮你做”——这就是一步之遥。

参考资料

Agent Skills：当 Google 工程文化遇上 AI 编程代理

Tue, 07 Apr 2026 00:00:00 +0000

“AI coding agents default to the shortest path — which often means skipping specs, tests, security reviews, and the practices that make software reliable.”

— Addy Osmani

你有没有这种体验：让 AI 写一个功能，它唰唰唰生成了 500 行代码，看起来能跑，但你心里隐约不安——没有测试、没有规范、没有安全审查，甚至你自己都不完全理解它写了什么。

你不是一个人。这正是 Addy Osmani 在 GitHub 上开源 agent-skills 的原因。这个项目在两个月内斩获 7900+ stars，核心主张简单而有力：

AI 编程代理需要纪律，而不仅仅是能力。

本文将深度拆解这个项目的设计哲学、19 个 skill 的全景图、最核心的"反合理化"创新，以及——最重要的——如何在你的日常开发中真正落地这套体系。

一、Addy Osmani 其人：从 Chrome DevTools 到 AI Agent 纪律

在聊 agent-skills 之前，有必要了解它的作者。

Addy Osmani 不是一个纯理论派。他在 Google Chrome 团队工作了近 14 年，担任过 Chrome 开发者体验负责人（Head of Chrome Developer Experience），直接负责过 Chrome DevTools、Lighthouse、Core Web Vitals 这些被数百万开发者每天使用的工具。他的工作为 Google 创造了 3.5 亿美元 的利润和成本节省。

他也是 O’Reilly 出版的《Learning JavaScript Design Patterns》和《Leading Effective Engineering Teams》的作者，早年还在 jQuery 核心团队工作过。

2025 年末，他转任 Google Cloud AI Director，专注 Gemini、Vertex AI 和 Agent Development Kit（ADK）。这个职业转型的时间点非常关键——他是在充分理解大规模工程团队如何运作之后，才开始思考 AI Agent 该如何工作的。

这就是 agent-skills 的底色：不是一个 prompt engineering 技巧集合，而是 Google 工程文化的 AI 翻译版。

他在项目中明确引用了 Software Engineering at Google 和 Google 的 engineering practices guide。换句话说，这套 skill 体系的每一条规则，都在世界上最大的代码库之一（Google 的 monorepo，20 亿行代码）中被验证过。

二、为什么 AI 编程代理需要 Skill？

2.1 AI 的默认行为：走最短路径

让我们面对现实。当你对 AI Agent 说"实现一个用户注册功能"时，它的默认行为是：

直接开始写代码（跳过规范）
一次性生成完整实现（跳过增量验证）
可能补几个测试（如果你提醒了的话）
不做安全审查
不考虑 API 契约、错误处理边界、性能影响

这不是因为 AI 不会做这些事——而是因为 没人告诉它应该做，或者更准确地说，没人用结构化的方式告诉它 必须做。

2.2 从"能写代码"到"会做工程"

Osmani 做了一个关键区分：Vibe Coding vs Agentic Engineering。

	Vibe Coding	Agentic Engineering
模式	“帮我写个 XX”	“按照 spec 实现 XX”
质量控制	人工事后审查	内置验证门
适用场景	原型、黑客松	生产代码
风险	理解债务累积	前期投入大但可控
核心哲学	AI 驱动，人类跟随	人类拥有架构，AI 执行

Vibe Coding 没有错——在原型阶段它效率惊人。但如果你的代码要上生产、要被团队维护、要承受真实用户的流量，你需要的是 Agentic Engineering。

2.3 Skill 的本质：可执行的工作流

agent-skills 中的每个 skill 不是文档，不是参考手册，而是一个 结构化的可执行工作流。每个 SKILL.md 文件包含：

分步工作流程：不是"你应该做 XX"，而是"第 1 步做 XX，第 2 步做 YY，做完后检查 ZZ"
验证门（Verification Gates）：每个阶段必须通过的检查点，“看起来对"不算完成
反合理化表（Anti-rationalization Tables）：AI 常用借口及预设反驳（后面详细讲）
红旗信号（Red Flags）：识别 skill 被错误应用的迹象

三、19 个 Skill 全景：DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP

整个 agent-skills 体系覆盖软件开发的完整生命周期，组织为 6 个阶段、19 个 skill：

1
2
3


DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP
/spec /plan /build /test /review /ship
 /code-simplify

3.1 Define 阶段：先想清楚再动手

Skill	核心能力
idea-refine	结构化发散/收敛思维：理解与扩展 → 评估与收敛 → 打磨输出
spec-driven-development	先写规范再写代码，四阶段门控：Specify → Plan → Tasks → Implement

spec-driven-development 是整个体系的基石。它要求每个 spec 覆盖六大核心领域：目标、命令、项目结构、代码风格、测试策略、边界。

边界定义尤其精彩，采用三级体系：

Always：永远做的事（如：每次改动必须有测试）
Ask First：需要确认才做的事（如：修改公共 API）
Never：绝不能做的事（如：直接操作生产数据库）

还有一个"假设显性化"机制：

1
2
3
4


ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
→ Correct me now or I'll proceed with these.

这比"你有什么需求？“高效一百倍——AI 先给出假设让你纠正，而不是等你把所有需求想清楚。

3.2 Plan 阶段：把大象切成薄片

Skill	核心能力
planning-and-task-breakdown	将 spec 分解为小型、可验证的任务，每个任务有明确验收标准

3.3 Build 阶段：写代码的核心战场

Skill	核心能力
incremental-implementation	薄垂直切片：实现 → 测试 → 验证 → 提交 → 下一片
test-driven-development	Red-Green-Refactor + Prove-It Pattern + 测试金字塔 80/15/5
context-engineering	五层上下文管理：Rules → Spec → 源码 → 错误 → 对话
frontend-ui-engineering	组件架构、设计系统、WCAG 2.1 AA 无障碍
api-and-interface-design	契约优先、Hyrum’s Law、错误语义

incremental-implementation 的核心理念：如果你写了 1000 行但 100 行就够，你就失败了。 它定义了三种切片策略：

垂直切片（首选）：一次实现一个完整的端到端功能切面
契约优先切片：先定义接口/类型，再填充实现
风险优先切片：先验证最不确定的部分

context-engineering 是容易被忽视但极其重要的 skill。它定义了五层上下文层级和三种打包策略：

Brain Dump：把所有相关信息一次性灌入（小任务适用）
Selective Include：精选最相关的文件和片段（中等任务）
Hierarchical Summary：先给摘要，按需展开细节（大型任务）

3.4 Verify 阶段：证明它是对的

Skill	核心能力
browser-testing-with-devtools	通过 Chrome DevTools MCP 获取 DOM、console、network、performance 实时数据
debugging-and-error-recovery	五步分诊：复现 → 定位 → 简化 → 修复 → 防护

3.5 Review 阶段：质量把关

Skill	核心能力
code-review-and-quality	五轴审查 + 评论分级（Critical/Important/Nit/Optional/FYI）
code-simplification	Chesterton’s Fence：删代码前先理解它存在的原因
security-and-hardening	OWASP Top 10 预防 + 三级边界系统
performance-optimization	度量优先 + Core Web Vitals 目标

code-review-and-quality 的审批标准直接来自 Google：”当变更确实改善了整体代码健康度时就批准，即使它不完美。“这是一种务实的工程文化——追求进步而非完美。

3.6 Ship 阶段：安全交付

Skill	核心能力
git-workflow-and-versioning	基于主干开发、原子提交
ci-cd-and-automation	Shift Left、特性开关、质量门管道
deprecation-and-migration	“代码即负债”、僵尸代码清理
documentation-and-adrs	ADR 架构决策记录、文档化"为什么”
shipping-and-launch	发布前检查清单 + 分阶段发布 + 回滚方案

四、核心创新：反合理化（Anti-rationalization）

如果让我从 agent-skills 中只挑一个最重要的设计模式，毫无疑问是 反合理化表（Anti-rationalization Tables）。

4.1 问题：AI 特别擅长给自己找借口

当你要求 AI Agent 遵循某个流程时，它有一种令人印象深刻的能力——用看起来完全合理的理由解释为什么可以跳过某个步骤。

比如：

“这个改动很简单，不需要写 spec”
“这个函数逻辑很清晰，不需要测试”
“这只是内部 API，不需要安全审查”
“代码已经很清晰了，不需要文档”

每一条听起来都很合理，对吧？这正是问题所在。

4.2 解法：预设借口 + 预设反驳

agent-skills 的做法是在每个 skill 文件中内置一张 反合理化表，预先列出 AI 可能给出的所有借口，并提供反驳：

AI 可能说的借口	预设反驳
“这很简单，不需要 spec”	简单任务不需要长 spec，但仍然需要验收标准。两行 spec 也是 spec。
“重构不需要新测试”	重构必须保持行为不变，而证明行为不变的唯一方式就是测试。
“这只是内部使用”	内部 API 也会被依赖——Hyrum’s Law 不区分内外。
“加测试会拖慢进度”	不加测试会在未来拖慢进度十倍。
“错误处理可以后面再加”	“后面"是"永远不会"的委婉说法。

4.3 为什么这是最重要的创新？

因为它解决的不是能力问题，而是 意愿问题。

当前的 LLM 在技术上完全有能力写测试、写 spec、做安全审查。它们不做，是因为：

用户没有明确要求——LLM 默认满足显式需求
最短路径偏好——生成更少 token 通常被视为更高效
合理化能力太强——LLM 可以为任何跳过步骤的行为编造看似合理的理由

反合理化表本质上是一种 预编译的规则引擎：不是在运行时让 AI 判断"这个步骤重不重要”，而是在设计时就把所有可能的逃逸路径堵死。

这个思路对任何在 CLAUDE.md 或 .cursorrules 中写规则的人都有启发：不要只写"你应该做什么”，还要写"当你想跳过时，为什么不能跳过"。

五、80% 问题与理解债务（Comprehension Debt）

5.1 新瓶装新酒的技术债务

Osmani 在他的 Substack 文章中提出了一个犀利的观察：

AI 可以生成 80%+ 的代码，但问题转移到了 理解债务（comprehension debt）——开发者审查和合并他们无法独立编写的代码。

他引用的数据令人警醒：高 AI 采用团队的 PR 合并量增加了 98%，但审查时间也增加了 91%。

这意味着什么？AI 让你写代码更快了，但它同时制造了一种新的债务——你的代码库里有越来越多你不完全理解的代码。

5.2 理解债务的三个症状

“它能跑就行"综合症：代码通过了测试但没人能解释它的设计决策
脆弱修改：改一个地方崩三个地方，因为没人理解隐含的依赖关系
知识孤岛：只有 AI 的对话记录知道为什么代码长这样，而对话记录不会被版本控制

5.3 agent-skills 的解法

agent-skills 通过几个 skill 协同解决这个问题：

spec-driven-development：先有人类可读的规范，代码是规范的实现，而不是反过来
documentation-and-adrs：记录"为什么"而非"是什么”——ADR（架构决策记录）让未来的维护者理解当时的选择
incremental-implementation：每次只提交一小片，每片都有清晰的意图
code-review-and-quality：强制五轴审查，确保不是"AI 写了什么就合并什么"

核心哲学：AI 生成的代码量不是 KPI，人类理解的代码量才是。

六、Conductor vs Orchestrator：两种 AI 协作范式

Osmani 提出了两种与 AI Agent 协作的模型，代表了从个人到团队的演进：

6.1 Conductor（指挥家）模式

1

人类 ←→ 单个 AI Agent（实时对话）

交互方式：紧密反馈循环，每一步都有人类参与
适用场景：复杂的架构决策、敏感的生产变更、学习新领域
典型工具：Claude Code 交互模式、Cursor 对话

就像交响乐指挥——你挥棒，乐手演奏，每个乐句你都在控制。

6.2 Orchestrator（编排者）模式

1

人类 → Spec → [Agent A] [Agent B] [Agent C] → 人类审查

交互方式：异步，前端投入规范，后端审查输出
适用场景：可并行的独立任务、批量代码迁移、标准化变更
典型工具：Claude Code Agent 模式、GitHub Copilot Workspace

就像导演——你给剧本（spec），演员们各自准备，你最后审片。

6.3 什么时候用哪个？

信号	用 Conductor	用 Orchestrator
任务间有强依赖	✓
需要实时判断	✓
任务可独立并行		✓
有清晰的验收标准		✓
涉及架构决策	✓
批量重复性工作		✓

Osmani 的关键洞察：随着 spec 质量的提高，你可以把越来越多的工作从 Conductor 模式迁移到 Orchestrator 模式。这就是 spec-driven-development 被放在第一位的原因——好的 spec 是 Orchestrator 模式的前提。

七、社区争论：Skills vs AGENTS.md

agent-skills 发布后，社区出现了一个有趣的争论：按需加载的 Skills 文件 vs 全量常驻的 AGENTS.md，哪个更好？

7.1 两种流派

Skills 流派（agent-skills 的方式）：

每个 skill 独立一个文件
通过元 skill（using-agent-skills）按需发现和加载
优点：节省 token，适合大型 skill 库
缺点：AI 需要"决定"是否加载某个 skill，这个决策本身可能出错

AGENTS.md 流派：

所有规则压缩到一个文件
每次对话都全量加载
优点：没有决策点，100% 确保规则被读取
缺点：token 消耗大，规则多了之后上下文窗口拥挤

7.2 Vercel 的实测数据

Vercel 团队做了对比测试，发现将压缩文档直接放入 AGENTS.md 的任务成功率约 100%，而 Skills 按需加载方式约 79%。

原因很直接：使用 AGENTS.md 时，Agent 不需要做"我是否应该查找这个 skill？“的决策——规则已经在上下文里了。

7.3 合理的答案：两者兼用

Osmani 自己也承认这个问题，并在项目中加入了 session hook 机制——每个新会话启动时自动注入元 skill，降低发现成本。

实际上，最佳实践是 分层使用：

层级	载体	内容
永久基线	CLAUDE.md / AGENTS.md	代码风格、架构约束、绝不能做的事
按需加载	Skills 文件	特定阶段的详细工作流（如 TDD 流程、安全审查清单）
会话级别	对话中的指令	当前任务的具体上下文

八、实战指南：如何在你的项目中落地 Agent Skills

理论讲完了，下面是 可以直接复制粘贴的落地指南。

8.1 在 Claude Code 中使用（推荐）

Claude Code 对 agent-skills 有最完整的原生支持。

方式一：通过插件安装（最简单）

1
2


# 安装 agent-skills 插件
claude plugin add addyosmani/agent-skills

安装后，你可以直接在 Claude Code 中使用斜杠命令：

1
2
3
4
5
6
7


/spec — 进入规范驱动开发流程
/plan — 将 spec 分解为任务
/build — 增量实现
/test — TDD 流程
/review — 代码审查
/ship — 发布检查
/code-simplify — 代码简化

方式二：本地目录安装（更灵活）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 1. 克隆仓库
git clone https://github.com/addyosmani/agent-skills.git ~/.claude/agent-skills

# 2. 在你的项目 CLAUDE.md 中引用
cat >> /your/project/CLAUDE.md << 'EOF'

## Agent Skills

当执行以下任务时，加载对应的 skill 文件：
- 写规范时：读取 ~/.claude/agent-skills/skills/spec-driven-development/SKILL.md
- 写代码时：读取 ~/.claude/agent-skills/skills/incremental-implementation/SKILL.md
- 写测试时：读取 ~/.claude/agent-skills/skills/test-driven-development/SKILL.md
- 代码审查时：读取 ~/.claude/agent-skills/skills/code-review-and-quality/SKILL.md
- 安全审查时：读取 ~/.claude/agent-skills/skills/security-and-hardening/SKILL.md
EOF

方式三：配置 Session Hook（自动注入）

在项目根目录创建 .claude/hooks.json：

1
2
3
4
5
6
7
8


{
 "hooks": [
 {
 "event": "SessionStart",
 "command": "cat ~/.claude/agent-skills/skills/using-agent-skills/SKILL.md"
 }
 ]
}

这样每次开启新对话，Claude Code 会自动知道有哪些 skill 可用，并根据任务类型按需加载。

8.2 在 Cursor 中使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 1. 克隆仓库到项目根目录
git clone https://github.com/addyosmani/agent-skills.git .cursor/agent-skills

# 2. 将需要的 skill 复制为 Cursor rules
cp .cursor/agent-skills/skills/spec-driven-development/SKILL.md \
 .cursor/rules/spec-driven-development.md

cp .cursor/agent-skills/skills/test-driven-development/SKILL.md \
 .cursor/rules/test-driven-development.md

cp .cursor/agent-skills/skills/code-review-and-quality/SKILL.md \
 .cursor/rules/code-review-and-quality.md

Cursor 的限制：不支持按需加载，放入 .cursor/rules/ 的文件每次都会被加载。建议只放 3-5 个最常用的 skill，避免 token 浪费。

进阶技巧：在 .cursorrules 中添加元指令：

1
2
3
4
5
6


## 工作流程

1. 收到新需求时，先按 spec-driven-development 规则写 spec
2. Spec 确认后，按 incremental-implementation 规则分片实现
3. 每个切片完成后，按 test-driven-development 规则补测试
4. 全部完成后，按 code-review-and-quality 规则自审

8.3 在 Gemini CLI 中使用

1
2


# 原生安装命令
gemini skills install addyosmani/agent-skills

Gemini CLI 对 agent-skills 有原生支持，安装后 skill 自动可用。

8.4 在 GitHub Copilot 中使用

1
2
3
4
5
6
7
8


# 1. 将 agents/ 目录下的角色文件作为 personas
cp -r agent-skills/agents/ .github/copilot-agents/

# 2. 将核心规则写入 copilot 指令文件
cat agent-skills/skills/spec-driven-development/SKILL.md \
 agent-skills/skills/incremental-implementation/SKILL.md \
 agent-skills/skills/code-review-and-quality/SKILL.md \
 > .github/copilot-instructions.md

8.5 不用任何工具：手动提取核心规则

如果你不想安装整个项目，可以只提取最有价值的部分，写入你项目的 CLAUDE.md 或 .cursorrules：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


## 开发流程

### 规范优先
- 任何超过 20 行的改动，先写 spec 再写代码
- Spec 必须包含：目标、验收标准、假设列表
- 不接受"这很简单不需要 spec"——两行 spec 也是 spec

### 增量实现
- 每次只实现一个薄垂直切片
- 每个切片必须：能编译、有测试、可独立提交
- 单次提交不超过 ~100 行变更

### 反合理化规则
- 当你想跳过测试时：不加测试会在未来拖慢进度十倍
- 当你想跳过安全审查时：内部 API 也会被依赖（Hyrum's Law）
- 当你想说"后面再加"时："后面"是"永远不会"的委婉说法
- 当你想一次性提交大量代码时：大 PR 隐藏 bug，小 PR 暴露 bug

### 验证门
- "它能跑"不等于"它是对的"
- 每个阶段必须有可验证的证据，不接受"我确认过了"
- 修 bug 必须先写复现测试（Prove-It Pattern）

8.6 团队落地建议：渐进式采用路径

不要试图一次性采用全部 19 个 skill。推荐的渐进路径：

第一周：只用 3 个核心 skill

1

spec-driven-development → incremental-implementation → code-review-and-quality

这三个 skill 覆盖了最关键的问题：先想后做、小步快跑、质量把关。

第二周：加入测试和安全

1
2


+ test-driven-development
+ security-and-hardening

第三周：加入上下文和文档

1
2


+ context-engineering
+ documentation-and-adrs

第四周以后：按需加入其他 skill

1
2
3
4


+ performance-optimization（性能敏感项目）
+ frontend-ui-engineering（前端项目）
+ api-and-interface-design（API 项目）
+ shipping-and-launch（频繁发布的项目）

8.7 自定义你自己的反合理化表

agent-skills 最大的价值不是直接用它的 19 个 skill，而是学会它的 设计模式，然后写你自己的。

以下是一个模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


## [你的 Skill 名称]

### 工作流程
1. 第一步...
2. 第二步...
3. 第三步...

### 验证门
- [ ] 检查项 1
- [ ] 检查项 2

### 反合理化表
| 你可能想说的借口 | 为什么不能接受 |
|----------------|--------------|
| "这种情况不会发生" | 如果不会发生，加个断言不会有任何成本 |
| "文档以后再写" | 以后的你不会记得现在的上下文 |
| "这只是临时方案" | 没有比临时方案更永久的东西了 |

### 红旗信号
- 如果你发现自己在 [某种情况]，说明这个 skill 被错误应用了

九、“你的 AI 编程代理需要一个经理”

最后分享 Osmani 的一个深刻洞察：

AI 协作本质上是 管理问题，而非 prompting 问题。

他发现，与 AI Agent 高效协作所需的能力，和管理人类团队的能力惊人地相似：

管理能力	在 AI Agent 中的对应
清晰的任务界定	写好 spec，而非模糊指令
审慎委托	判断哪些任务可以完全交给 AI，哪些需要检查点
验证循环	不是"做完了吗？“而是"给我看证据”
异步检查	Orchestrator 模式下的批量审查

委托的三个层次：

完全委托：明确的、低风险的任务（如格式化、简单重构）
带检查点委托：中等复杂度，关键节点需要人工确认
保留人工：架构决策、安全关键路径、性能关键路径

如果你曾经是一个好的技术负责人，你已经具备了与 AI Agent 高效协作的核心能力。 不同的是，你的"下属"现在每秒能输出 100 行代码——这让你的管理质量变得前所未有地重要。

总结

agent-skills 不仅是一个工具集——它是对 AI 编程时代工程文化的一次系统性思考。

几个关键 takeaway：

AI 编程代理的问题不是能力不够，而是纪律不够。agent-skills 通过结构化的工作流和反合理化机制解决这个问题。
反合理化表是最值得学习的设计模式。不要只告诉 AI “应该做什么”，还要预设它"想跳过时的借口"并提供反驳。
理解债务是新的技术债务。AI 让代码增长更快，但如果人类理解跟不上，代码库会变成黑箱。
从 Conductor 到 Orchestrator 的演进是必然的，而好的 spec 是这个演进的前提。
渐进式采用：先用 3 个核心 skill（spec + incremental + review），再逐步扩展。

最后用 Osmani 自己的话收尾：

“Agentic Engineering is not about AI writing all the code. It’s about humans owning the architecture, quality, and correctness — while AI executes under human guidance.”

人类拥有架构、质量和正确性，AI 在人类的指导下执行。

这大概是 2026 年最值得内化的一句话。