架构设计 on 鬼哥的空间

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。

Claude Managed Agents：从聊天机器人到自主 Agent 的一步之遥

Thu, 09 Apr 2026 00:00:00 +0000

150 行代码就能造一个"数字分身"，但它只会聊天，不会做事。

如果它能帮你写代码、搜资料、跑脚本呢？

两个月前，我给博客做了一个 AI 数字分身——guige_avatar。访客点击右下角的聊天按钮，就能和"鬼哥"的 AI 分身聊技术、聊 AI、聊生活。

整个后端只有 150 行 JavaScript，部署在 Vercel 上，用的是 OpenAI 的 GPT-4.1-nano。它很轻量，也确实能用——但说实话，它只是一个穿了马甲的 Chat Completion API。

2026 年 4 月，Anthropic 推出了 Claude Managed Agents——一个托管式的 Agent 运行时平台。看完文档后我意识到：如果用 Managed Agents 重构鬼哥分身，它能从一个只会聊天的机器人，进化成一个真正能做事的自主 Agent。

本文就以这个真实案例为主线，带你理解 Managed Agents 到底是什么、能做什么、以及什么时候该用它。

一、手搓版：guige_avatar 架构剖析

先看看现在的数字分身长什么样。注意截图右下角那个小对话气泡——那就是访客与鬼哥 AI 分身聊天的入口。

1.1 整体架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


访客浏览器 Vercel Serverless
┌─────────────┐ POST ┌──────────────────┐ ┌─────────┐
│ 博客首页 │ ─────────→ │ api/chat.js │ ───→ │ OpenAI │
│ 聊天面板(JS) │ ←───────── │ (~150 行) │ ←─── │ API │
└─────────────┘ JSON │ │ └─────────┘
 │ ↓ fire-and-forget│
 │ Telegram 通知 │
 └──────────────────┘
 ↑
 data/persona.yaml
 (人设 YAML ~200行)

1.2 核心代码：就这么简单

后端的核心逻辑可以浓缩成这几步：

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


// 1. 加载人设 YAML → 构建 system prompt
const persona = yaml.load(fs.readFileSync('data/persona.yaml'));
const systemPrompt = buildSystemPrompt(persona);

// 2. 拼接历史（最多 10 轮）+ 当前消息
const messages = [
 { role: 'system', content: systemPrompt },
 ...history.slice(-10),
 { role: 'user', content: userMessage }
];

// 3. 一次 API 调用，返回结果
const response = await openai.chat.completions.create({
 model: 'gpt-4.1-nano',
 messages
});

没有 agent loop，没有工具调用，没有自主决策。每次请求就是一次单轮 LLM 推理。

1.3 人设工程：它的真正价值

guige_avatar 最精巧的部分不是代码，而是 persona.yaml——一个约 200 行的人设定义文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


personality:
 traits: ["技术极客", "偶尔幽默", "喜欢深度思考"]
 speaking_style: "口语化但有技术深度"
 
knowledge:
 expertise: ["大数据", "AI/LLM", "分布式系统"]
 current_projects: ["Claude Code 源码分析", "博客写作"]
 
boundaries:
 forbidden_topics: ["政治敏感", "个人隐私"]
 fallback: "这个话题我不太方便聊，换个有趣的话题吧？"

这种"人设工程"确实让对话体验很自然。但问题是——人设再好，它也只能聊天，不能做事。

1.4 手搓版的天花板

能力	状态
闲聊	✅ 流畅自然
回答技术问题	✅ 基于人设知识
搜索最新信息	❌ 无网络访问
查看博客文章	❌ 无文件读取
帮访客写代码	❌ 无代码执行
记住上次对话	❌ 刷新即丢失
自主完成任务	❌ 无 agent loop

这就是一个典型的聊天机器人——能对话，但不能行动。

二、Managed Agents：它到底是什么？

2.1 一句话定义

Managed Agents = Anthropic 托管的 Agent 运行时。

你不需要自己搭 agent loop、沙箱、工具执行层。Anthropic 提供一个完整的云端容器环境，Claude 在里面自主运行 bash、读写文件、搜索网页、执行代码。

如果 Messages API 是"你调用模型，模型返回文本"，那 Managed Agents 就是"你定义 Agent，Agent 自主完成任务"。

2.2 与 Messages API 的定位差异

	Messages API	Managed Agents
本质	直接模型调用	预构建的 Agent 运行时
适合	自定义 agent loop、精细控制	长时间异步任务、最小化基础设施
工具执行	你的代码负责执行	Anthropic 云端容器执行
类比	买 CPU 自己组电脑	买整机开箱即用

2.3 核心概念四件套

Managed Agents 的整个模型围绕四个概念：

概念	说明	类比
Agent	模型 + system prompt + 工具 + MCP servers	一个人的"能力定义"
Environment	云端容器模板：预装包、网络规则	这个人的"工作环境"
Session	运行中的 Agent 实例，绑定 Agent + Environment	一次具体的"工作会话"
Events	应用与 Agent 之间的消息流（SSE）	你和这个人之间的"对话"

工作流程：

1
2
3
4
5
6
7
8
9


创建 Agent（一次性） → 创建 Environment（一次性）
 ↘ ↙
 创建 Session（每次任务）
 ↓
 发送 Event（用户消息）
 ↓
 流式接收 Agent 响应（SSE）
 ↓
 可中途引导或中断

三、Case Study：数字分身 v1（手搓）vs v2（Managed Agents）

这是本文最核心的部分。我们来看，如果用 Managed Agents 重构鬼哥分身，会发生什么变化。

3.1 对话 → 能动手：工具能力

v1（手搓版）：只能基于 system prompt 中的静态知识回答。

1
2
3


访客：你最近写了什么文章？
鬼哥分身：我最近在写 Agent Skills 和 Gemma 4 的分析文章...
（这是 persona.yaml 里预写的，不是实时查的）

v2（Managed Agents 版）：有完整的工具链。

1
2
3
4
5
6
7
8


访客：你最近写了什么文章？
鬼哥分身：[使用 bash] ls content/post/ | tail -5
 [使用 read] 读取最近 5 篇文章的 frontmatter
 我最近写了这些文章：
 1. Agent Skills 深度解析（4月7日）
 2. Gemma 4 深度分析（4月5日）
 3. Karpathy 的 LLM Wiki（4月2日）
 ...每篇都有链接，要看哪篇？

Managed Agents 的内置工具：

工具	能力	数字分身的用途
Bash	执行 shell 命令	列出文章、统计数据
Read / Write / Edit	文件读写	查看博客内容、生成草稿
Glob / Grep	文件搜索	搜索特定话题的文章
Web Search / Fetch	网络搜索	查最新技术动态

3.2 内存级历史 → 持久化会话

v1：对话历史存在前端 JavaScript 内存中，刷新页面就没了。

1
2


// v1：前端维护历史，刷新即丢失
let history = []; // 🔥 页面刷新 = 失忆

v2：Session 天然持久化，Event 历史服务端保存。

1
2
3
4
5
6
7
8


# v2：Session 持久化，随时可恢复
session = client.beta.sessions.create(
 agent=avatar_agent.id,
 environment_id=env.id,
 title="访客 A 的对话"
)
# 下次访问，用同一个 session_id 继续
# 完整的对话历史都在服务端

更关键的是，Managed Agents 有 Memory（研究预览阶段）——跨会话的长期记忆。这意味着鬼哥分身可以记住：“上次这个访客问过 Spark 调优，他应该是做大数据的。”

3.3 单轮推理 → 多步 Agent Loop

这是最本质的差异。

v1：一问一答，没有中间推理步骤。

1

用户消息 → LLM 生成回复 → 返回

v2：Agent 可以自主规划多步执行。

1
2


用户消息 → Claude 思考 → 调用工具 A → 分析结果 
 → 调用工具 B → 综合判断 → 生成回复 → 返回

比如访客问"帮我分析一下你这个博客的技术栈"：

v1：只能背 persona.yaml 里预写的答案
v2：grep -r "hugo" config/ → cat themes/hugo-theme-stack/... → ls layouts/ → 基于实际代码给出准确分析

3.4 无沙盒 → 云端容器

v1：代码在 Vercel Serverless Function 里跑，只有 150ms 的冷启动预算，不能装额外的包。

v2：完整的云端容器。

1
2
3
4
5
6
7
8
9


environment = client.beta.environments.create(
 name="guige-avatar-env",
 config={
 "type": "cloud",
 "networking": {"type": "unrestricted"},
 # 可以预装任何包
 # Python, Node.js, Go, Hugo...
 },
)

容器意味着：

可以预装 Hugo 来本地构建预览
可以跑 Python 脚本分析数据
可以 git clone 仓库来读取最新代码
网络不受限，可以访问外部 API

3.5 单 Agent → 多 Agent 编排

v1：一个 function 处理所有事情。

v2：可以按职责拆分为多个专精 Agent。

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


# 主 Agent：鬼哥分身（对话协调者）
avatar = client.beta.agents.create(
 name="鬼哥分身",
 model="claude-sonnet-4-6",
 system="你是鬼哥的数字分身...",
 tools=[{"type": "agent_toolset_20260401"}],
 callable_agents=[
 {"type": "agent", "id": blog_agent.id, ...},
 {"type": "agent", "id": code_agent.id, ...},
 ]
)

# Sub-Agent 1：博客助手（搜索和推荐文章）
blog_agent = client.beta.agents.create(
 name="博客助手",
 model="claude-haiku-4-5", # 用小模型节省成本
 system="你负责搜索和推荐鬼哥的博客文章...",
 tools=[{"type": "agent_toolset_20260401"}],
)

# Sub-Agent 2：代码助手（分析代码、写 demo）
code_agent = client.beta.agents.create(
 name="代码助手",
 model="claude-sonnet-4-6",
 system="你负责帮访客分析代码和写 demo...",
 tools=[{"type": "agent_toolset_20260401"}],
)

当访客问文章相关的问题时，主 Agent 委托给博客助手；问代码问题时，委托给代码助手。各司其职，成本可控。

四、完整对比：手搓 vs 托管

维度	v1 手搓版	v2 Managed Agents
本质	Chat Completion 包装器	自主 Agent 平台
Agent Loop	无，单轮 request-response	有，多步推理 + 工具调用循环
工具能力	无	Bash、文件操作、Web 搜索、MCP
代码执行	不可能	云端容器沙盒
对话记忆	前端内存，刷新丢失	服务端持久化 Session
长期记忆	无	Memory（研究预览）
多 Agent	不可能	Coordinator + Sub-agents
后端代码	~150 行 JS	~50 行 Python（SDK 调用）
基础设施	Vercel function（自己维护）	Anthropic 全托管
模型	GPT-4.1-nano（OpenAI）	Claude Sonnet/Haiku（Anthropic）
成本	API 调用费 + Vercel 免费层	API 调用费 + Session 运行费
开发周期	1 天	1 天（SDK 很简洁）
适合场景	轻量级人设聊天	需要工具和自主性的场景

五、SDK 实战：5 分钟跑通 Managed Agents

5.1 安装

1
2


pip install anthropic
export ANTHROPIC_API_KEY="your-key"

5.2 创建 Agent + Environment + Session

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


from anthropic import Anthropic

client = Anthropic()

# 1. 创建 Agent
agent = client.beta.agents.create(
 name="鬼哥分身 v2",
 model="claude-sonnet-4-6",
 system="""你是鬼哥（luoli523）的数字分身。
 
性格：技术极客，偶尔幽默，喜欢深度思考。
擅长：大数据、AI/LLM、分布式系统、Claude Code。
说话风格：口语化但有技术深度，喜欢用类比解释复杂概念。

你可以使用工具来查看博客文章、搜索信息、执行代码。
当访客问到你不确定的事情时，先搜索再回答，不要编造。""",
 tools=[
 {"type": "agent_toolset_20260401"},
 ],
)

# 2. 创建 Environment
environment = client.beta.environments.create(
 name="avatar-env",
 config={
 "type": "cloud",
 "networking": {"type": "unrestricted"},
 },
)

# 3. 创建 Session
session = client.beta.sessions.create(
 agent=agent.id,
 environment_id=environment.id,
 title="访客对话",
)

print(f"Agent: {agent.id}")
print(f"Environment: {environment.id}")
print(f"Session: {session.id}")

5.3 发消息 + 流式接收

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


with client.beta.sessions.events.stream(session.id) as stream:
 # 发送用户消息
 client.beta.sessions.events.send(
 session.id,
 events=[{
 "type": "user.message",
 "content": [{
 "type": "text",
 "text": "帮我看看你博客最近写了什么文章"
 }],
 }],
 )

 # 流式处理响应
 for event in stream:
 match event.type:
 case "agent.message":
 for block in event.content:
 print(block.text, end="")
 case "agent.tool_use":
 print(f"\n[🔧 使用工具: {event.name}]")
 case "session.status_idle":
 print("\n\n✅ 完成")
 break

输出可能长这样：

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


让我看看最近的文章...
[🔧 使用工具: bash]
[🔧 使用工具: read]

最近写了这几篇：
1. **Agent Skills 深度解析**（4月7日）— 拆解 Addy Osmani 的 19 个 AI Agent skill
2. **Gemma 4 深度分析**（4月5日）— Google 开源模型的架构和应用
3. **Karpathy 的 LLM Wiki**（4月2日）— 从零理解 LLM 的百科全书

要看哪篇的详细内容？

✅ 完成

5.4 TypeScript 版本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// 创建 Agent
const agent = await client.beta.agents.create({
 name: "鬼哥分身 v2",
 model: "claude-sonnet-4-6",
 system: "你是鬼哥的数字分身...",
 tools: [{ type: "agent_toolset_20260401" }],
});

// 创建 Environment
const env = await client.beta.environments.create({
 name: "avatar-env",
 config: { type: "cloud", networking: { type: "unrestricted" } },
});

// 创建 Session
const session = await client.beta.sessions.create({
 agent: agent.id,
 environment_id: env.id,
});

// 发消息 + 流式响应
const stream = await client.beta.sessions.events.stream(session.id);

await client.beta.sessions.events.send(session.id, {
 events: [{
 type: "user.message",
 content: [{ type: "text", text: "你最近在研究什么？" }],
 }],
});

for await (const event of stream) {
 if (event.type === "agent.message") {
 for (const block of event.content) {
 process.stdout.write(block.text);
 }
 } else if (event.type === "agent.tool_use") {
 console.log(`\n[🔧 ${event.name}]`);
 } else if (event.type === "session.status_idle") {
 console.log("\n\n✅ Done");
 break;
 }
}

六、工具配置：精细控制

默认的 agent_toolset_20260401 启用全部工具。但你也可以按需开关：

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


# 只开 bash 和文件操作，关掉网络
agent = client.beta.agents.create(
 name="安全受限的分身",
 model="claude-sonnet-4-6",
 tools=[{
 "type": "agent_toolset_20260401",
 "default_config": {"enabled": False},
 "configs": [
 {"name": "bash", "enabled": True},
 {"name": "read", "enabled": True},
 {"name": "glob", "enabled": True},
 {"name": "grep", "enabled": True},
 # web_fetch 和 web_search 保持关闭
 ]
 }],
)

还支持自定义工具——你定义接口，Claude 决定何时调用，你的代码执行后把结果返回：

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


agent = client.beta.agents.create(
 name="带自定义工具的分身",
 model="claude-sonnet-4-6",
 tools=[
 {"type": "agent_toolset_20260401"},
 {
 "type": "custom",
 "name": "get_blog_stats",
 "description": "获取博客的访问统计数据",
 "input_schema": {
 "type": "object",
 "properties": {
 "period": {
 "type": "string",
 "description": "统计周期：today, week, month"
 }
 },
 "required": ["period"]
 }
 }
 ],
)

七、手搓 vs 托管：什么时候用哪个？

这两种方案不是非此即彼的关系，而是不同复杂度和需求下的最优选择。

用手搓版（Messages API / 自建）

需求简单：纯聊天，不需要工具调用
成本敏感：Vercel 免费层 + 便宜的小模型就够了
完全控制：你需要自定义每一个细节
已有基础设施：你的团队已经有成熟的 agent 框架
离线场景：需要本地部署

用 Managed Agents

需要工具能力：Agent 需要执行代码、搜索网页、读写文件
长时间任务：任务可能运行几分钟甚至几小时
零基础设施：不想自己维护沙盒和 agent loop
多 Agent 编排：任务需要多个专精 Agent 协作
持久化会话：需要跨请求保持上下文和文件状态

混合方案：最佳实践

实际上，鬼哥分身最可能的进化路径是混合方案：

1
2
3
4
5
6
7


访客消息
 ↓
前端（博客首页）
 ↓
轻量网关（Vercel / Cloudflare Worker）
 ├── 简单闲聊 → 直接 Messages API（省钱）
 └── 复杂任务 → 转发到 Managed Agents Session

简单问答（“你是谁？““你喜欢什么？"）走便宜的 Messages API；需要搜索、执行代码、多步推理的任务走 Managed Agents。按需升级，不浪费。

八、Beta 注意事项

Managed Agents 目前是 Beta 状态（managed-agents-2026-04-01），几个关键信息：

所有 API 账户默认可用，无需单独申请
SDK 自动设置 beta header，直接用就行
Research Preview 功能（Outcomes、Multi-agent、Memory）需要单独申请
Rate Limit：创建操作 60 req/min，读取操作 600 req/min
支持 7 种 SDK：Python、TypeScript、Go、Java、C#、Ruby、PHP
还有 CLI 工具 ant（Homebrew 安装）

品牌规范提醒：如果你在产品中集成 Managed Agents，可以用 “Claude Agent” 命名，但不能用 “Claude Code” 或 “Claude Cowork” 的名称和视觉元素。

总结

从 guige_avatar 到 Managed Agents，本质上是从 “调用模型生成文本” 到 “委托 Agent 完成任务” 的范式转移。

从	到
Chat Completion	Agent Session
单轮推理	多步 Agent Loop
无工具	Bash + 文件 + Web + 自定义
前端内存	服务端持久化
单一 Agent	多 Agent 编排
自建一切	托管运行时

Managed Agents 本质上是 “Claude Code as a Service”——把 Claude Code 的核心能力（bash、文件操作、web 搜索、agent loop）包装成云端 API，让开发者在自己的产品中嵌入 Claude 级别的 Agent 能力。

对于鬼哥分身来说，150 行手搓版已经够用了。但当某天访客说"帮我写一个 Spark 调优的 demo"时，Managed Agents 版本会回答：

1
2
3
4


好的，让我帮你写一个...
[🔧 使用工具: write] 创建 spark_tuning_demo.py
[🔧 使用工具: bash] python spark_tuning_demo.py
脚本已经写好并测试通过了，关键的调优点是...

从"我告诉你"到"我帮你做”——这就是一步之遥。