工程实践 on 鬼哥的空间

从使用者到学习者：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

Claude Code 的 hook 协议里，exit 2 = 阻止工具执行 + 把 stderr 传回 AI。sdd-cache 利用这个机制，把"缓存命中"伪装成"工具被拒"——但 stderr 里其实是有效内容。

这不是 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

Agent Skills：当 Google 工程文化遇上 AI 编程代理

Tue, 07 Apr 2026 00:00:00 +0000

“AI coding agents default to the shortest path — which often means skipping specs, tests, security reviews, and the practices that make software reliable.”

— Addy Osmani

你有没有这种体验：让 AI 写一个功能，它唰唰唰生成了 500 行代码，看起来能跑，但你心里隐约不安——没有测试、没有规范、没有安全审查，甚至你自己都不完全理解它写了什么。

你不是一个人。这正是 Addy Osmani 在 GitHub 上开源 agent-skills 的原因。这个项目在两个月内斩获 7900+ stars，核心主张简单而有力：

AI 编程代理需要纪律，而不仅仅是能力。

本文将深度拆解这个项目的设计哲学、19 个 skill 的全景图、最核心的"反合理化"创新，以及——最重要的——如何在你的日常开发中真正落地这套体系。

一、Addy Osmani 其人：从 Chrome DevTools 到 AI Agent 纪律

在聊 agent-skills 之前，有必要了解它的作者。

Addy Osmani 不是一个纯理论派。他在 Google Chrome 团队工作了近 14 年，担任过 Chrome 开发者体验负责人（Head of Chrome Developer Experience），直接负责过 Chrome DevTools、Lighthouse、Core Web Vitals 这些被数百万开发者每天使用的工具。他的工作为 Google 创造了 3.5 亿美元 的利润和成本节省。

他也是 O’Reilly 出版的《Learning JavaScript Design Patterns》和《Leading Effective Engineering Teams》的作者，早年还在 jQuery 核心团队工作过。

2025 年末，他转任 Google Cloud AI Director，专注 Gemini、Vertex AI 和 Agent Development Kit（ADK）。这个职业转型的时间点非常关键——他是在充分理解大规模工程团队如何运作之后，才开始思考 AI Agent 该如何工作的。

这就是 agent-skills 的底色：不是一个 prompt engineering 技巧集合，而是 Google 工程文化的 AI 翻译版。

他在项目中明确引用了 Software Engineering at Google 和 Google 的 engineering practices guide。换句话说，这套 skill 体系的每一条规则，都在世界上最大的代码库之一（Google 的 monorepo，20 亿行代码）中被验证过。

二、为什么 AI 编程代理需要 Skill？

2.1 AI 的默认行为：走最短路径

让我们面对现实。当你对 AI Agent 说"实现一个用户注册功能"时，它的默认行为是：

直接开始写代码（跳过规范）
一次性生成完整实现（跳过增量验证）
可能补几个测试（如果你提醒了的话）
不做安全审查
不考虑 API 契约、错误处理边界、性能影响

这不是因为 AI 不会做这些事——而是因为 没人告诉它应该做，或者更准确地说，没人用结构化的方式告诉它 必须做。

2.2 从"能写代码"到"会做工程"

Osmani 做了一个关键区分：Vibe Coding vs Agentic Engineering。

	Vibe Coding	Agentic Engineering
模式	“帮我写个 XX”	“按照 spec 实现 XX”
质量控制	人工事后审查	内置验证门
适用场景	原型、黑客松	生产代码
风险	理解债务累积	前期投入大但可控
核心哲学	AI 驱动，人类跟随	人类拥有架构，AI 执行

Vibe Coding 没有错——在原型阶段它效率惊人。但如果你的代码要上生产、要被团队维护、要承受真实用户的流量，你需要的是 Agentic Engineering。

2.3 Skill 的本质：可执行的工作流

agent-skills 中的每个 skill 不是文档，不是参考手册，而是一个 结构化的可执行工作流。每个 SKILL.md 文件包含：

分步工作流程：不是"你应该做 XX"，而是"第 1 步做 XX，第 2 步做 YY，做完后检查 ZZ"
验证门（Verification Gates）：每个阶段必须通过的检查点，“看起来对"不算完成
反合理化表（Anti-rationalization Tables）：AI 常用借口及预设反驳（后面详细讲）
红旗信号（Red Flags）：识别 skill 被错误应用的迹象

三、19 个 Skill 全景：DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP

整个 agent-skills 体系覆盖软件开发的完整生命周期，组织为 6 个阶段、19 个 skill：

1
2
3


DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP
/spec /plan /build /test /review /ship
 /code-simplify

3.1 Define 阶段：先想清楚再动手

Skill	核心能力
idea-refine	结构化发散/收敛思维：理解与扩展 → 评估与收敛 → 打磨输出
spec-driven-development	先写规范再写代码，四阶段门控：Specify → Plan → Tasks → Implement

spec-driven-development 是整个体系的基石。它要求每个 spec 覆盖六大核心领域：目标、命令、项目结构、代码风格、测试策略、边界。

边界定义尤其精彩，采用三级体系：

Always：永远做的事（如：每次改动必须有测试）
Ask First：需要确认才做的事（如：修改公共 API）
Never：绝不能做的事（如：直接操作生产数据库）

还有一个"假设显性化"机制：

1
2
3
4


ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
→ Correct me now or I'll proceed with these.

这比"你有什么需求？“高效一百倍——AI 先给出假设让你纠正，而不是等你把所有需求想清楚。

3.2 Plan 阶段：把大象切成薄片

Skill	核心能力
planning-and-task-breakdown	将 spec 分解为小型、可验证的任务，每个任务有明确验收标准

3.3 Build 阶段：写代码的核心战场

Skill	核心能力
incremental-implementation	薄垂直切片：实现 → 测试 → 验证 → 提交 → 下一片
test-driven-development	Red-Green-Refactor + Prove-It Pattern + 测试金字塔 80/15/5
context-engineering	五层上下文管理：Rules → Spec → 源码 → 错误 → 对话
frontend-ui-engineering	组件架构、设计系统、WCAG 2.1 AA 无障碍
api-and-interface-design	契约优先、Hyrum’s Law、错误语义

incremental-implementation 的核心理念：如果你写了 1000 行但 100 行就够，你就失败了。 它定义了三种切片策略：

垂直切片（首选）：一次实现一个完整的端到端功能切面
契约优先切片：先定义接口/类型，再填充实现
风险优先切片：先验证最不确定的部分

context-engineering 是容易被忽视但极其重要的 skill。它定义了五层上下文层级和三种打包策略：

Brain Dump：把所有相关信息一次性灌入（小任务适用）
Selective Include：精选最相关的文件和片段（中等任务）
Hierarchical Summary：先给摘要，按需展开细节（大型任务）

3.4 Verify 阶段：证明它是对的

Skill	核心能力
browser-testing-with-devtools	通过 Chrome DevTools MCP 获取 DOM、console、network、performance 实时数据
debugging-and-error-recovery	五步分诊：复现 → 定位 → 简化 → 修复 → 防护

3.5 Review 阶段：质量把关

Skill	核心能力
code-review-and-quality	五轴审查 + 评论分级（Critical/Important/Nit/Optional/FYI）
code-simplification	Chesterton’s Fence：删代码前先理解它存在的原因
security-and-hardening	OWASP Top 10 预防 + 三级边界系统
performance-optimization	度量优先 + Core Web Vitals 目标

code-review-and-quality 的审批标准直接来自 Google：”当变更确实改善了整体代码健康度时就批准，即使它不完美。“这是一种务实的工程文化——追求进步而非完美。

3.6 Ship 阶段：安全交付

Skill	核心能力
git-workflow-and-versioning	基于主干开发、原子提交
ci-cd-and-automation	Shift Left、特性开关、质量门管道
deprecation-and-migration	“代码即负债”、僵尸代码清理
documentation-and-adrs	ADR 架构决策记录、文档化"为什么”
shipping-and-launch	发布前检查清单 + 分阶段发布 + 回滚方案

四、核心创新：反合理化（Anti-rationalization）

如果让我从 agent-skills 中只挑一个最重要的设计模式，毫无疑问是 反合理化表（Anti-rationalization Tables）。

4.1 问题：AI 特别擅长给自己找借口

当你要求 AI Agent 遵循某个流程时，它有一种令人印象深刻的能力——用看起来完全合理的理由解释为什么可以跳过某个步骤。

比如：

“这个改动很简单，不需要写 spec”
“这个函数逻辑很清晰，不需要测试”
“这只是内部 API，不需要安全审查”
“代码已经很清晰了，不需要文档”

每一条听起来都很合理，对吧？这正是问题所在。

4.2 解法：预设借口 + 预设反驳

agent-skills 的做法是在每个 skill 文件中内置一张 反合理化表，预先列出 AI 可能给出的所有借口，并提供反驳：

AI 可能说的借口	预设反驳
“这很简单，不需要 spec”	简单任务不需要长 spec，但仍然需要验收标准。两行 spec 也是 spec。
“重构不需要新测试”	重构必须保持行为不变，而证明行为不变的唯一方式就是测试。
“这只是内部使用”	内部 API 也会被依赖——Hyrum’s Law 不区分内外。
“加测试会拖慢进度”	不加测试会在未来拖慢进度十倍。
“错误处理可以后面再加”	“后面"是"永远不会"的委婉说法。

4.3 为什么这是最重要的创新？

因为它解决的不是能力问题，而是 意愿问题。

当前的 LLM 在技术上完全有能力写测试、写 spec、做安全审查。它们不做，是因为：

用户没有明确要求——LLM 默认满足显式需求
最短路径偏好——生成更少 token 通常被视为更高效
合理化能力太强——LLM 可以为任何跳过步骤的行为编造看似合理的理由

反合理化表本质上是一种 预编译的规则引擎：不是在运行时让 AI 判断"这个步骤重不重要”，而是在设计时就把所有可能的逃逸路径堵死。

这个思路对任何在 CLAUDE.md 或 .cursorrules 中写规则的人都有启发：不要只写"你应该做什么”，还要写"当你想跳过时，为什么不能跳过"。

五、80% 问题与理解债务（Comprehension Debt）

5.1 新瓶装新酒的技术债务

Osmani 在他的 Substack 文章中提出了一个犀利的观察：

AI 可以生成 80%+ 的代码，但问题转移到了 理解债务（comprehension debt）——开发者审查和合并他们无法独立编写的代码。

他引用的数据令人警醒：高 AI 采用团队的 PR 合并量增加了 98%，但审查时间也增加了 91%。

这意味着什么？AI 让你写代码更快了，但它同时制造了一种新的债务——你的代码库里有越来越多你不完全理解的代码。

5.2 理解债务的三个症状

“它能跑就行"综合症：代码通过了测试但没人能解释它的设计决策
脆弱修改：改一个地方崩三个地方，因为没人理解隐含的依赖关系
知识孤岛：只有 AI 的对话记录知道为什么代码长这样，而对话记录不会被版本控制

5.3 agent-skills 的解法

agent-skills 通过几个 skill 协同解决这个问题：

spec-driven-development：先有人类可读的规范，代码是规范的实现，而不是反过来
documentation-and-adrs：记录"为什么"而非"是什么”——ADR（架构决策记录）让未来的维护者理解当时的选择
incremental-implementation：每次只提交一小片，每片都有清晰的意图
code-review-and-quality：强制五轴审查，确保不是"AI 写了什么就合并什么"

核心哲学：AI 生成的代码量不是 KPI，人类理解的代码量才是。

六、Conductor vs Orchestrator：两种 AI 协作范式

Osmani 提出了两种与 AI Agent 协作的模型，代表了从个人到团队的演进：

6.1 Conductor（指挥家）模式

1

人类 ←→ 单个 AI Agent（实时对话）

交互方式：紧密反馈循环，每一步都有人类参与
适用场景：复杂的架构决策、敏感的生产变更、学习新领域
典型工具：Claude Code 交互模式、Cursor 对话

就像交响乐指挥——你挥棒，乐手演奏，每个乐句你都在控制。

6.2 Orchestrator（编排者）模式

1

人类 → Spec → [Agent A] [Agent B] [Agent C] → 人类审查

交互方式：异步，前端投入规范，后端审查输出
适用场景：可并行的独立任务、批量代码迁移、标准化变更
典型工具：Claude Code Agent 模式、GitHub Copilot Workspace

就像导演——你给剧本（spec），演员们各自准备，你最后审片。

6.3 什么时候用哪个？

信号	用 Conductor	用 Orchestrator
任务间有强依赖	✓
需要实时判断	✓
任务可独立并行		✓
有清晰的验收标准		✓
涉及架构决策	✓
批量重复性工作		✓

Osmani 的关键洞察：随着 spec 质量的提高，你可以把越来越多的工作从 Conductor 模式迁移到 Orchestrator 模式。这就是 spec-driven-development 被放在第一位的原因——好的 spec 是 Orchestrator 模式的前提。

七、社区争论：Skills vs AGENTS.md

agent-skills 发布后，社区出现了一个有趣的争论：按需加载的 Skills 文件 vs 全量常驻的 AGENTS.md，哪个更好？

7.1 两种流派

Skills 流派（agent-skills 的方式）：

每个 skill 独立一个文件
通过元 skill（using-agent-skills）按需发现和加载
优点：节省 token，适合大型 skill 库
缺点：AI 需要"决定"是否加载某个 skill，这个决策本身可能出错

AGENTS.md 流派：

所有规则压缩到一个文件
每次对话都全量加载
优点：没有决策点，100% 确保规则被读取
缺点：token 消耗大，规则多了之后上下文窗口拥挤

7.2 Vercel 的实测数据

Vercel 团队做了对比测试，发现将压缩文档直接放入 AGENTS.md 的任务成功率约 100%，而 Skills 按需加载方式约 79%。

原因很直接：使用 AGENTS.md 时，Agent 不需要做"我是否应该查找这个 skill？“的决策——规则已经在上下文里了。

7.3 合理的答案：两者兼用

Osmani 自己也承认这个问题，并在项目中加入了 session hook 机制——每个新会话启动时自动注入元 skill，降低发现成本。

实际上，最佳实践是 分层使用：

层级	载体	内容
永久基线	CLAUDE.md / AGENTS.md	代码风格、架构约束、绝不能做的事
按需加载	Skills 文件	特定阶段的详细工作流（如 TDD 流程、安全审查清单）
会话级别	对话中的指令	当前任务的具体上下文

八、实战指南：如何在你的项目中落地 Agent Skills

理论讲完了，下面是 可以直接复制粘贴的落地指南。

8.1 在 Claude Code 中使用（推荐）

Claude Code 对 agent-skills 有最完整的原生支持。

方式一：通过插件安装（最简单）

1
2


# 安装 agent-skills 插件
claude plugin add addyosmani/agent-skills

安装后，你可以直接在 Claude Code 中使用斜杠命令：

1
2
3
4
5
6
7


/spec — 进入规范驱动开发流程
/plan — 将 spec 分解为任务
/build — 增量实现
/test — TDD 流程
/review — 代码审查
/ship — 发布检查
/code-simplify — 代码简化

方式二：本地目录安装（更灵活）

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


# 1. 克隆仓库
git clone https://github.com/addyosmani/agent-skills.git ~/.claude/agent-skills

# 2. 在你的项目 CLAUDE.md 中引用
cat >> /your/project/CLAUDE.md << 'EOF'

## Agent Skills

当执行以下任务时，加载对应的 skill 文件：
- 写规范时：读取 ~/.claude/agent-skills/skills/spec-driven-development/SKILL.md
- 写代码时：读取 ~/.claude/agent-skills/skills/incremental-implementation/SKILL.md
- 写测试时：读取 ~/.claude/agent-skills/skills/test-driven-development/SKILL.md
- 代码审查时：读取 ~/.claude/agent-skills/skills/code-review-and-quality/SKILL.md
- 安全审查时：读取 ~/.claude/agent-skills/skills/security-and-hardening/SKILL.md
EOF

方式三：配置 Session Hook（自动注入）

在项目根目录创建 .claude/hooks.json：

1
2
3
4
5
6
7
8


{
 "hooks": [
 {
 "event": "SessionStart",
 "command": "cat ~/.claude/agent-skills/skills/using-agent-skills/SKILL.md"
 }
 ]
}

这样每次开启新对话，Claude Code 会自动知道有哪些 skill 可用，并根据任务类型按需加载。

8.2 在 Cursor 中使用

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


# 1. 克隆仓库到项目根目录
git clone https://github.com/addyosmani/agent-skills.git .cursor/agent-skills

# 2. 将需要的 skill 复制为 Cursor rules
cp .cursor/agent-skills/skills/spec-driven-development/SKILL.md \
 .cursor/rules/spec-driven-development.md

cp .cursor/agent-skills/skills/test-driven-development/SKILL.md \
 .cursor/rules/test-driven-development.md

cp .cursor/agent-skills/skills/code-review-and-quality/SKILL.md \
 .cursor/rules/code-review-and-quality.md

Cursor 的限制：不支持按需加载，放入 .cursor/rules/ 的文件每次都会被加载。建议只放 3-5 个最常用的 skill，避免 token 浪费。

进阶技巧：在 .cursorrules 中添加元指令：

1
2
3
4
5
6


## 工作流程

1. 收到新需求时，先按 spec-driven-development 规则写 spec
2. Spec 确认后，按 incremental-implementation 规则分片实现
3. 每个切片完成后，按 test-driven-development 规则补测试
4. 全部完成后，按 code-review-and-quality 规则自审

8.3 在 Gemini CLI 中使用

1
2


# 原生安装命令
gemini skills install addyosmani/agent-skills

Gemini CLI 对 agent-skills 有原生支持，安装后 skill 自动可用。

8.4 在 GitHub Copilot 中使用

1
2
3
4
5
6
7
8


# 1. 将 agents/ 目录下的角色文件作为 personas
cp -r agent-skills/agents/ .github/copilot-agents/

# 2. 将核心规则写入 copilot 指令文件
cat agent-skills/skills/spec-driven-development/SKILL.md \
 agent-skills/skills/incremental-implementation/SKILL.md \
 agent-skills/skills/code-review-and-quality/SKILL.md \
 > .github/copilot-instructions.md

8.5 不用任何工具：手动提取核心规则

如果你不想安装整个项目，可以只提取最有价值的部分，写入你项目的 CLAUDE.md 或 .cursorrules：

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


## 开发流程

### 规范优先
- 任何超过 20 行的改动，先写 spec 再写代码
- Spec 必须包含：目标、验收标准、假设列表
- 不接受"这很简单不需要 spec"——两行 spec 也是 spec

### 增量实现
- 每次只实现一个薄垂直切片
- 每个切片必须：能编译、有测试、可独立提交
- 单次提交不超过 ~100 行变更

### 反合理化规则
- 当你想跳过测试时：不加测试会在未来拖慢进度十倍
- 当你想跳过安全审查时：内部 API 也会被依赖（Hyrum's Law）
- 当你想说"后面再加"时："后面"是"永远不会"的委婉说法
- 当你想一次性提交大量代码时：大 PR 隐藏 bug，小 PR 暴露 bug

### 验证门
- "它能跑"不等于"它是对的"
- 每个阶段必须有可验证的证据，不接受"我确认过了"
- 修 bug 必须先写复现测试（Prove-It Pattern）

8.6 团队落地建议：渐进式采用路径

不要试图一次性采用全部 19 个 skill。推荐的渐进路径：

第一周：只用 3 个核心 skill

1

spec-driven-development → incremental-implementation → code-review-and-quality

这三个 skill 覆盖了最关键的问题：先想后做、小步快跑、质量把关。

第二周：加入测试和安全

1
2


+ test-driven-development
+ security-and-hardening

第三周：加入上下文和文档

1
2


+ context-engineering
+ documentation-and-adrs

第四周以后：按需加入其他 skill

1
2
3
4


+ performance-optimization（性能敏感项目）
+ frontend-ui-engineering（前端项目）
+ api-and-interface-design（API 项目）
+ shipping-and-launch（频繁发布的项目）

8.7 自定义你自己的反合理化表

agent-skills 最大的价值不是直接用它的 19 个 skill，而是学会它的 设计模式，然后写你自己的。

以下是一个模板：

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


## [你的 Skill 名称]

### 工作流程
1. 第一步...
2. 第二步...
3. 第三步...

### 验证门
- [ ] 检查项 1
- [ ] 检查项 2

### 反合理化表
| 你可能想说的借口 | 为什么不能接受 |
|----------------|--------------|
| "这种情况不会发生" | 如果不会发生，加个断言不会有任何成本 |
| "文档以后再写" | 以后的你不会记得现在的上下文 |
| "这只是临时方案" | 没有比临时方案更永久的东西了 |

### 红旗信号
- 如果你发现自己在 [某种情况]，说明这个 skill 被错误应用了

九、“你的 AI 编程代理需要一个经理”

最后分享 Osmani 的一个深刻洞察：

AI 协作本质上是 管理问题，而非 prompting 问题。

他发现，与 AI Agent 高效协作所需的能力，和管理人类团队的能力惊人地相似：

管理能力	在 AI Agent 中的对应
清晰的任务界定	写好 spec，而非模糊指令
审慎委托	判断哪些任务可以完全交给 AI，哪些需要检查点
验证循环	不是"做完了吗？“而是"给我看证据”
异步检查	Orchestrator 模式下的批量审查

委托的三个层次：

完全委托：明确的、低风险的任务（如格式化、简单重构）
带检查点委托：中等复杂度，关键节点需要人工确认
保留人工：架构决策、安全关键路径、性能关键路径

如果你曾经是一个好的技术负责人，你已经具备了与 AI Agent 高效协作的核心能力。 不同的是，你的"下属"现在每秒能输出 100 行代码——这让你的管理质量变得前所未有地重要。

总结

agent-skills 不仅是一个工具集——它是对 AI 编程时代工程文化的一次系统性思考。

几个关键 takeaway：

AI 编程代理的问题不是能力不够，而是纪律不够。agent-skills 通过结构化的工作流和反合理化机制解决这个问题。
反合理化表是最值得学习的设计模式。不要只告诉 AI “应该做什么”，还要预设它"想跳过时的借口"并提供反驳。
理解债务是新的技术债务。AI 让代码增长更快，但如果人类理解跟不上，代码库会变成黑箱。
从 Conductor 到 Orchestrator 的演进是必然的，而好的 spec 是这个演进的前提。
渐进式采用：先用 3 个核心 skill（spec + incremental + review），再逐步扩展。

最后用 Osmani 自己的话收尾：

“Agentic Engineering is not about AI writing all the code. It’s about humans owning the architecture, quality, and correctness — while AI executes under human guidance.”

人类拥有架构、质量和正确性，AI 在人类的指导下执行。

这大概是 2026 年最值得内化的一句话。