Agent-Skills on 鬼哥的空间

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.

从 agent-skills 拆解：如何开发一套 Skill + Agents 项目脚手架

Tue, 18 Aug 2026 00:00:00 +0000

很多团队做第一套 Skill 仓库时，目录通常很快就长成这样：十几个 Markdown，名字都很专业，内容也都像模像样。真正使用两周后，问题开始出现：有的规则每轮都加载，有的永远触发不了；两个“专家”互相转述，token 花了两遍，结论反而少了一层；换到另一个 Coding Agent，又得复制一套提示词。

这不是 Prompt 写得不够好，而是项目没有分层。

我最近沿着一段关于 Claude Code sub-agents 的讨论，重新拆了一遍 Addy Osmani 的 agent-skills 项目。它最值得借鉴的，并非某一份代码评审提示词，而是把一组自然语言指令做成了工程资产：能被发现、能被调用、能被组合、能被覆盖，还能被自动检查。

这篇文章就做一件事：以它为样板，搭一套自己的 Skill + Agents 项目脚手架。

我以前写过架构拆解和项目参考手册，重点是“这个项目为什么这样设计”。本文换一个方向：假设现在要从零建自己的仓库，第一批目录与验证门应该怎样落下去。

本文核对的是 agent-skills 2026 年 8 月 14 日的 0.6.7 版本：仓库包含 24 个 Skills、4 个 Agents 和 8 个 Claude lifecycle commands。项目仍在快速变化，具体字段与安装命令请以文末官方资料为准。

先分清三件事：怎么做、谁来做、何时组合

agent-skills 在 docs/agents.md 里给出了一个非常实用的三层模型：

层	回答的问题	例子	主要产物
Skill	怎么做	`code-review-and-quality`	步骤、约束、验收条件
Agent / Persona	谁来做	`code-reviewer`	专业视角、工具权限、输出格式
Command / Orchestrator	何时及如何组合	`/review`、`/ship`	确定性入口、并行编排、结果合并

这个区分看似是命名问题，实际决定了整个项目会不会失控。

Skill 不应该只是“你要认真检查安全问题”这种知识卡片。它更像一份可执行 SOP：什么时候触发，按什么顺序行动，哪些步骤不能跳过，最后拿什么证据证明任务完成。

Agent 也不该是“精通前后端、测试、安全、产品与运维的超级专家”。它需要一个稳定视角。例如 security-auditor 只负责威胁建模与漏洞审计，test-engineer 只负责测试策略与覆盖缺口。角色越单一，输出越容易预测，也越容易被别的流程复用。

编排入口则解决确定性问题。用户输入 /ship，不是让模型临场猜测该做什么，而是加载一份预先写好的编排剧本：并行启动哪些专家、分别检查什么、如何合并报告、什么条件必须判定为 NO-GO。

可以把这三层记成一句话：Skill 是工艺，Agent 是工位，Orchestrator 是流水线。 把三者写进同一个大 Prompt，就相当于把操作手册、岗位说明和生产调度贴在同一张纸上——不是不能运行，只是出问题时很难知道该改哪一段。

但别照抄三层：今天还需要“包装层”和“验证层”

如果只看概念，三层已经够清楚；如果真要做一个可发布的仓库，还差两层。

第一层是平台包装。不同 Agent Harness 的发现规则并不一致。Claude Code 能识别插件根目录的 skills/、agents/、hooks/，也继续兼容 commands/；Codex 版 agent-skills 则通过 .codex-plugin/plugin.json 指向同一份根目录 skills/。项目文档也明确说明：当前 Codex 集成复用的是 Skills，Claude 的 slash commands、personas 与 hooks 仍属于 Claude Code 侧能力。

第二层是验证。自然语言文件同样会出现“编译错误”：frontmatter 缺字段、目录名与 name 不一致、引用路径失效、多个 manifest 版本不一致、命令引用了不存在的 Skill。agent-skills 把这些检查放进 scripts/ 和 evals/，这一步把“提示词收藏夹”与“可维护项目”真正区分开来。

因此，一套更完整的结构其实是五层：

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


语义核心
├── skills/ # 可复用工作流：怎么做
├── agents/ # 专业执行者：谁来做
└── references/ # 多个工作流共享的检查表与标准

调用与适配
├── .claude/commands/ # Claude Code 的编排入口（兼容形式）
├── .claude-plugin/ # Claude 插件元数据与市场清单
├── .codex-plugin/ # Codex 插件清单
└── .gemini/commands/ # 其他 Harness 的薄适配

工程保障
├── scripts/ # lint、链接、版本与结构校验
├── evals/ # 触发准确率与行为评测
└── .github/workflows/ # 安装、校验与发布门禁

这里最重要的设计判断是：共享的是语义核心，复制的是薄适配层。 如果你在 Claude、Codex、Gemini 目录里各维护一份完整安全规范，三个月后一定会得到三个略有不同的“唯一真相”。

第一步：从最小可运行骨架开始

不要上来就造二十个 Skill。先选择一个高频、边界清楚、结果容易验证的场景，例如“发布前评审”。最小骨架只需要这些文件：

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


my-agent-kit/
├── .claude-plugin/
│ ├── plugin.json
│ └── marketplace.json
├── skills/
│ └── code-review/
│ └── SKILL.md
├── agents/
│ └── code-reviewer.md
├── .claude/
│ └── commands/
│ └── review.md
├── scripts/
│ └── validate-skills.js
├── README.md
└── LICENSE

Claude Code 官方插件文档有一个容易踩中的规则：.claude-plugin/ 里只放 plugin.json 等元数据；skills/、agents/、hooks/ 必须位于插件根目录。把所有东西都塞进 .claude-plugin/，目录看起来很整齐，Claude Code 也会很整齐地假装没看见。

一个最小 manifest 可以这样写：

1
2
3
4
5
6
7


{
 "name": "my-agent-kit",
 "version": "0.1.0",
 "description": "Reusable engineering workflows and specialist agents",
 "author": { "name": "Your Team" },
 "license": "MIT"
}

默认目录能被自动发现时，不必急着把每条路径都写进 manifest。脚手架的第一原则不是“配置齐全”，而是“每个配置都有必要”。

第二步：把 Skill 写成有退出条件的工作流

一个 Skill 至少需要 name 和 description：

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


---
name: code-review
description: Reviews code changes for correctness, maintainability, security, and performance. Use before merging a pull request or releasing a change.
---

# Code Review

## When to use
- Before merge
- After a bug fix
- After an agent implements a feature

## Workflow
1. Read the task or spec.
2. Read tests before implementation.
3. Inspect the diff across five review axes.
4. Run the relevant verification commands.
5. Report findings by severity with file and line references.

## Verification
- [ ] Every blocker includes evidence and a concrete fix.
- [ ] Test and build status are reported.
- [ ] Uncertainty is labeled instead of guessed.

description 不是摘要，而是路由契约。Claude Code 会结合用户任务、当前上下文与 description 决定是否加载 Skill。写得太宽，Skill 会到处抢活；写得太窄，它会成为一份只有作者记得存在的文档。

agent-skills 的做法值得直接借鉴：description 同时写清“做什么”和“什么时候使用”，正文再写完整流程；把长清单移到 supporting files；尽量让 SKILL.md 保持聚焦。官方文档把这种加载方式称为按需加载：启动时主要暴露名称和描述，真正调用时再加载正文与相关资源。对于装了几十个 Skill 的环境，这不是洁癖，而是上下文预算。

我还建议给每个工作流增加两类内容：

失败时 Agent 最常找的借口，例如“改动很小，不需要测试”；
可以被外部观察的退出条件，例如测试输出、构建结果、截图或报告路径。

好的 Skill 不是让模型“更懂道理”，而是让它更难绕过流程。

第三步：让 Agent 只拥有一个视角

Agent 文件同样由 YAML frontmatter 和 Markdown 正文组成：

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


---
name: code-reviewer
description: Senior reviewer for correctness, readability, architecture, security, and performance. Use for a focused review before merge.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# Senior Code Reviewer

You review the requested change from one perspective: code quality.

## Output
- Verdict: APPROVE or REQUEST CHANGES
- Critical issues
- Required changes
- Suggestions
- Verification story

## Boundaries
- Do not implement fixes unless explicitly asked.
- Do not invoke another persona.
- State uncertainty and request evidence when needed.

这里有三个设计点。

第一，description 决定“什么时候派它上场”，正文决定“上场之后怎么工作”。不要把关键执行规则只写进 description，也不要指望正文能挽救一份含糊的 description。

第二，权限应当服从职责。一个只负责评审的 Agent 通常不需要 Edit 或 Write。限制工具不只是安全措施，也是在减少角色漂移：当手里只有锤子时什么都像钉子；当手里同时有读、写、部署和发消息工具时，评审员很快会产生创业冲动。

第三，插件提供的 Agent 和项目级 Agent 使用相同的基本定义格式，但能力范围与优先级并非完全相同。Claude Code 当前的优先级是：组织托管配置、--agents、项目 .claude/agents/、用户 ~/.claude/agents/、插件 agents/。项目定义可以覆盖同名插件 Agent；而出于安全原因，插件 Agent 不支持 hooks、mcpServers、permissionMode 等字段。

这反而形成了一个很好的产品机制：插件给出安全的默认角色，团队在项目中覆盖它，个人还能保留自己的通用角色。脚手架不必预见所有业务，只要设计好覆盖点。

第四步：把编排写成“显式剧本”

单一 Agent 适合直接调用。多个 Agent 只有在任务真正独立时，才值得并行 fan-out。

agent-skills 的 /ship 是一个很好的例子：主 Agent 针对同一份 diff，同时派出 code-reviewer、security-auditor 和 test-engineer。三个子 Agent 互不依赖，各自在独立上下文里生成报告；等它们返回后，主 Agent 去重、提升严重级别，并输出 GO / NO-GO 与回滚方案。

1
2
3


 ┌─ code-reviewer ────┐
/ship → parallel fan-out├─ security-auditor ├→ main agent merge → GO / NO-GO
 └─ test-engineer ────┘

这个模式成立，需要同时满足四个条件：

子任务之间没有顺序依赖；
不写同一份可变状态；
每个 Agent 提供的是不同种类的信息；
合并工作足够小，适合留在主上下文完成。

如果步骤有明确依赖，例如 /spec → /plan → /build → /test，不要为了显得“Agentic”而强行并行。agent-skills 选择让用户逐步触发生命周期命令，保留每一步之间的人类判断。流水线不是越自动越高级；错误方向跑得更快，通常只是更早抵达返工现场。

还有一个常见反模式：创建 meta-orchestrator Agent，职责只是判断该叫哪个 Agent。它没有领域价值，却多了一次上下文转述与信息损失。路由能写进入口 Skill，就不要再招聘一位“负责转接电话的 AI 经理”。

需要特别更新一个来自早期实践的认知：在当前 Claude Code 中，自定义 command 已并入 Skill 机制。.claude/commands/review.md 仍然兼容，也会生成 /review；但新项目更适合优先用 skills/<name>/SKILL.md，因为它支持 supporting files、自动触发与更完整的 frontmatter。概念上仍然需要“编排入口”，实现上未必非要保留独立 commands 层。

第五步：为不同平台写薄适配，不复制核心

如果目标只支持 Claude Code，到这里已经可以工作。如果希望项目同时服务 Codex、Gemini CLI 或其他 Harness，需要先接受一个现实：Skill 的可移植性通常高于 Agent 编排的可移植性。

agent-skills 当前版本就是很诚实的示范：同一份 skills/ 被 Claude Code 与 Codex 复用；.codex-plugin/plugin.json 只负责告诉 Codex 到哪里发现它们。Claude 专属的 agents、slash commands 和 hooks 没有假装“一次编写，到处运行”。其他平台有自己的 command 文件与安装说明。

建议把跨平台边界写成一张能力矩阵：

能力	共享语义核心	平台适配
工作流步骤与验收标准	`skills/`	通常可直接复用
共享检查表	`references/`	注意安装后的相对路径
Persona 正文	`agents/`	按 Harness 的 Agent 机制注册
并行与结果合并	编排意图可共享	工具名、并发方式需适配
安装与发现	无	manifest、marketplace、命令格式
hooks / MCP / 权限	原则可共享	配置 schema 基本各不相同

跨平台设计的目标不该是文件树完全对称，而是行为语义尽量一致。能复用 80% 的核心、允许 20% 的适配，比三套看起来相同、实际逐渐漂移的实现可靠得多。

第六步：把 Markdown 当代码测试

脚手架至少应有四类静态检查：

1
2
3
4


结构检查：skills/<name>/SKILL.md 是否存在
Schema 检查：frontmatter、必填字段、合法字段
引用检查：相对链接、脚本与 references 是否存在
一致性检查：多个 manifest 的名称与版本是否同步

随后再加行为评测。每个 Skill 准备三组 case：

应触发：例如“帮我审查这次认证改动”；
不应触发：例如“解释一下这段代码做什么”；
边界 case：例如“只改了一行 README，需要完整发布审计吗？”

行为评测不必一开始就追求复杂分数。先记录三个结果已经很有价值：选对了哪个 Skill、有没有执行关键步骤、是否产出了要求的证据。等 case 多了，再统计触发准确率、漏执行率和不必要的 Agent 调用成本。

仓库还应提供最小安装冒烟测试：从干净环境安装插件，列出被发现的 Skills 与 Agents，调用一个最小示例，确认输出结构。很多项目的 CI 会认真检查 JSON 能否解析，却从没验证用户安装后是否真的看得到组件。这和餐厅通过了厨房验收但忘了留门，属于一种很工程化的幽默。

一套可以直接执行的开发顺序

如果现在开始搭自己的项目，我会按下面的顺序推进：

选一个高频场景，写出输入、输出与完成标准；
先实现一个 Skill，确保单独调用能稳定完成任务；
当确实需要独立视角或上下文隔离时，再增加一个 Agent；
只有多个独立视角需要合并时，才增加 fan-out 编排；
增加 manifest 与 marketplace，把本地目录变成可安装产品；
增加 lint、引用校验和安装冒烟测试；
用真实失败案例补 evals，而不是凭想象扩写 Prompt；
最后再做跨平台适配，并明确哪些能力无法等价迁移。

每新增一个组件，都应该能回答三个问题：它消除了哪段重复说明？它带来了哪种以前没有的专业判断？如果它失效，哪项测试会报警？三个问题都答不上来，先别加。

最后的检查表

发布第一版前，可以用这份清单收口：

每个 Skill 都写清 what + when，而非只写主题名称；
每个工作流都有可观察的退出条件；
每个 Agent 只有一个主要角色和一种输出格式；
只给 Agent 完成职责所需的工具；
编排只用于真正独立的并行任务；
主 Agent 负责合并，Persona 不互相转述；
共享内容只有一份源文件，平台目录保持轻薄；
项目级覆盖策略与优先级有文档说明；
frontmatter、引用、manifest 和版本经过自动校验；
至少有应触发、不应触发、边界三类评测；
在干净环境完成过一次安装与调用冒烟测试。

回头看最开始那堆 Markdown，问题从来不在数量。真正的分界线是：它们能否形成清楚的职责边界、稳定的发现机制、可控的编排关系和可重复的验证结果。

脚手架的价值，不是帮你更快地产生 Prompt，而是让团队可以像维护代码一样维护 Agent 的行为。

这也是 agent-skills 最值得借鉴的地方：它没有试图造一个无所不能的超级 Agent，而是把经验拆成工艺、工位、入口、包装和质检。所谓 Agent 工程化，大概就是从“这段提示词挺好用”，走到“这套系统出了问题，我知道该改哪一层”。

参考资料

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。

harness 不再纸上谈兵：开源 harness-project-template，附完整工作流实战

Mon, 27 Apr 2026 00:00:00 +0000

模型已经够强了。接下来卡你的不是模型，是工作流。

Codex-5.5、Claude Opus 4.7、Gemini 3、Grok 4 这一代模型出来之后，“AI 写代码"的天花板被肉眼可见地抬高了一格。一句模糊的需求扔进去，500 行能跑的代码就出来了。

但稍微跑过几个真项目你就会发现：模型再强，也只能解决"写代码"这一段；从需求到上线之间的所有事情——怎么拆需求、怎么管上下文、怎么验证、什么时候让人接管——需要一套系统化的运行规范。

这就是 harness 要解决的问题。

最近半年，Anthropic、OpenAI、Google DeepMind、Stripe 一波接一波地讲 Harness Engineering；Addy Osmani 把 Google 14 年工程文化压缩成 19 个 agent skill 开源放出来；社区里"工作流第一、模型第二"几乎成了共识。理论分析和最佳实践讨论已经够多了。

但你打开 GitHub 想找一个能 clone 就用的脚手架，会发现极少。要么是 SaaS 公司的工作流截图（看不到代码），要么是某个 README 里散落的 CLAUDE.md（缺工具链衔接），要么是单个 skill 文件（没串成完整流水线）。理论已经足够，缺的是开箱即用的脚手架。

于是鬼哥我做了两件事：

整理出一个 GitHub Template：luoli523/harness-project-template —— Python + FastAPI 起步，clone 即用，30 秒装好。
用它从 0 跑了一个真实 v1 示例项目（多币种财务账本），39 个 atomic commit、253 个测试、93.79% 覆盖，从 SPEC 到 SHIP 一步没跳。

下面分两部分：先看模板长什么样、怎么用；再看那个 v1 项目是怎么从一句需求一步一步落到 39 个 commit 的，全程截图。

一、template：长什么样、怎么用

目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


harness-project-template/
├── .agent/prompts/ # 工具无关的 prompt 模板
├── .agents/skills/ # 6 个核心 skill（Claude Code + Codex 自动发现）
├── .claude/ # Claude Code 专属：slash commands + permissions
├── .github/workflows/ # CI 跑同一组门禁（ruff + mypy + pytest）
├── AGENTS.md # 项目规约（所有 agent 必读）
├── CLAUDE.md # 指向 AGENTS.md
├── src/<your_pkg>/ # FastAPI 脚手架（一个 /health 端点 + async 测试）
├── tests/
└── scripts/init-template.sh # 一键改名 + sync + 装 hooks

事实来源在 AGENTS.md + .agents/skills/，工具特定入口（slash command）只是包装。换 IDE 不用重新教 agent，这是设计上的关键。

6 个核心 skill

这 6 个 skill 不是我自己造的——它们摘选自 Google 资深工程师 Addy Osmani 开源的 addyosmani/agent-skills 项目（详细解读见 Agent Skills：当 Google 工程文化遇上 AI 编程代理）。Addy 把 Google 14 年工程文化压缩成 19 个 agent-executable skill，每个都是一份带"反合理化表"的 markdown 工作流。我没把 19 个全塞进模板，只放每个项目里最小化能把项目跑起来的 6 个：

Skill	何时调用	核心约束
`spec-driven-development`	新功能起步	先列假设清单 → 用户确认 → 写 spec
`planning-and-task-breakdown`	spec 通过后	拆成 ≤100 LOC 任务，每任务 2-5 条二元验收
`incremental-implementation`	单任务实现	RED → GREEN → REFACTOR → atomic commit
`test-driven-development`	任何业务逻辑	先写失败测试，看红，再写实现
`code-review-and-quality`	自审时	五轴顺序：correctness → readability → architecture → security → performance
`git-workflow-and-versioning`	提交时	一任务一 commit，message 引用 spec

剩下 13 个（staged rollout、deprecation migration、incident response 等）按需加，不在最小集合里。

三步起步

1
2
3
4
5
6
7
8
9


# 1. 拉模板（GitHub UI 用 "Use this template" 也行）
gh repo create my-service --template luoli523/harness-project-template --private --clone
cd my-service

# 2. 一键改名 + sync + 装 hooks + 跑门禁
./scripts/init-template.sh my_service

# 3. 启动开发服务器，验证脚手架已绿
uv run uvicorn my_service.main:app --reload

标准使用顺序

之后任何新功能都走这个流程：

1
2
3
4
5
6


/spec <feature> # → 假设清单 → 你确认 → spec/<feature>.md
/plan spec/<feature>.md # → 拆成 ≤100 LOC 任务清单
/build spec/<feature>.md T1 # 一次一个任务，TDD + atomic commit
/build spec/<feature>.md T2
... (重复直到 T_n)
/review # 五轴自审，找 bug 修 bug

每个 slash command 包装一个 skill，跨工具一致。换到 Codex CLI 用 $spec-driven-development、换到 Cursor 直接打开 .agents/skills/<name>/SKILL.md 让 agent 跟着读。

二、实战：从一句需求到 39 个 commit

光看模板不够说服力。下面是我用它跑一个真实 v1（多币种财务账本）的完整过程，截图为证。

Step 1: `/spec` —— 一句话需求 → 假设清单

我扔进去的需求是这样：

我想做一个财务记账系统，自动按月生成资产负债表、利润表、现金流量表。日常货币是 SGD，CNY 消费、USD 投资、HKD 资产。

注意 AI 没有立即开始写 spec。skill 强制它先列出所有它正打算做的隐含假设，让我逐条确认：

四大类：A. 范围切分（最关键，先确认）、B. 业务模型假设、C. 技术假设、D. 验收边界。每条都是一个具体决定（“v1 不做权责发生制”、“HKD 折算并入而不单独成列”、“持久层用 SQLite”），等你 ✓。

这一步的真实价值：它把需求里所有模糊的地方拽到表面。你看到"v1 不做权责发生制"才会反应过来"等下，那利息预提怎么算？"——这才是真正要决定的事。

我逐条回 OK 之后，AI 才动手写 spec/<feature>.md。spec 写完，AI 主动停下：

“按规则停在这里，不进入 plan 阶段。请做以下两件事之一：1. 签字通过——回 approved 或 /plan，或 2. 打回修改…”

这就是 gated workflow 的实物体现：闸门写在 skill 里，AI 自己执行。它不会越权，也不会替你决定 spec 通过没。

Step 2: `/plan` —— 切成 27 个任务卡

spec 签字之后，/plan 命令把它拆成任务清单：

每个任务：≤100 LOC 估算、2-5 条二元验收清单、列出 blocker、依赖图无环。底部 AI 还会标注它自己拿不准的拆分点，建议我"扫一眼”——这种"主动暴露不确定性"也是 skill 引导出来的。

最终这个项目切成 27 个任务，覆盖基础设施 → 数据模型 → 纯函数业务逻辑 → 仓储 → 报表引擎 → HTTP 路由 → 横切错误处理 → E2E + 收尾。

Step 3: `/build T1, T2, ... T27` —— 每任务一个 TDD 红绿循环

/build T1 开始第一个任务。RED 阶段——先写失败测试，跑红：

GREEN 阶段——装依赖、写实现、跑测试转绿、跑全门禁：

ruff check ✅、ruff format --check ✅、mypy --strict ✅、pytest ✅ —— 四道门禁全过才算 GREEN。

最后 atomic commit，pre-commit hooks 再过一遍，commit message 引用 spec + task ID：

关键：单任务做完，AI 自动停下，等下一个 /build T2 或 approved：

“T1 完成，停在这里。等你说 /build 或 approved 我再开 T2…”

不会顺手做下一个任务，不会"图省事一次写完几个"。每个任务一个独立 commit、独立的 RED→GREEN→commit 循环。这种粒度对未来 git bisect 找 bug、git revert 回滚都是无可替代的。

T1 → T27 重复 27 次。

Step 4: `/review` —— 五轴自审

27 个任务全做完后，/review 走五轴自审（correctness → readability → architecture → security → performance），找出了 5 个真 bug + 2 个 spec 漂移。每个发现拆成独立 fix commit + 测试，又是 7 个 commit。

最终交付

39 个 atomic commit、253 个测试、93.79% 覆盖。ruff + ruff format + mypy --strict + pytest 四道门禁全程绿。

从一句需求到能跑的 v1，全程留痕、可审计、可回滚。每个设计抉择有 spec 锚点；每个 commit 可独立 revert；每个 bug 修复有测试。短期看慢一点，长期少欠一笔技术债。

三、Takeaway：现在去 clone

理论文章已经读够多了。这一周我把工作流物化成模板 + 用它跑通一个真实项目，证明这套不是镜中水月。

仓库地址：luoli523/harness-project-template —— Python + FastAPI 起步，30 秒装好，欢迎试用。

这套模板我会持续维护：

你用它跑了项目、发现 skill 该改进、想加新 skill —— 提 issue 或 PR
你跑出来的项目踩了模板没覆盖的坑 —— 提 issue，我把教训沉淀回模板
你想要不同技术栈的类似脚手架（Go、Rust、TypeScript）—— 留言说明诉求，我考虑分仓维护

模型还会变强、context window 还会变大，但让模型按工作流出活这个能力不会自动到来。希望这个仓库帮你省掉前两天的摸索成本。

参考链接

上篇 1：Harness Engineering：当模型够强，系统设计成为胜负手
上篇 2：Agent Skills：当 Google 工程文化遇上 AI 编程代理
模板仓库：luoli523/harness-project-template
原始 skills 项目：addyosmani/agent-skills