agent-skills 收官：从"能跑"到"可合并"——AI 编码的生产级标准是什么

九篇文章，从 8 月 1 号写到今天。如果只看第一篇和这一篇，你会发现一个有意思的对照：开篇我们说”AI 编码又快又烂”，今天我们要给”烂”画一条线——到底是哪里烂，烂到什么程度不可接受，以及怎么系统性地把这道线往前推。

系列到今天收官。我想用三件事把九篇串起来：先回顾全景，再讲 agent-skills 最特别的那块东西（三层评估框架），最后给三类读者一条能马上落地的采纳路线。

一、九篇文章的全景图

把九天的内容压成一句话：把一个高级工程师脑子里的工程纪律，拆成 AI 能直接执行的步骤和门控。

我们一起走过了六个阶段：DEFINE 把”要什么”想清楚，PLAN 把大象切成原子任务，BUILD 用垂直切片 + TDD 落地，VERIFY 调试分诊让 bug 修到根上，REVIEW 用五把尺子把关，最后 SHIP 把代码安全、可逆、可观察地送到生产。

每篇都聚焦在一个具体问题上，下面这张图把九篇文章按主题串起来：

flowchart LR
    A["Day1
开篇
六阶段全景"] --> B["Day2
DEFINE
需求想清楚"]
    A --> C["Day3
反合理化
堵住偷懒借口"]
    B --> D["Day4
PLAN+BUILD
切片与TDD"]
    C --> D
    D --> E["Day5
VERIFY+REVIEW
调试与评审"]
    E --> F["Day6
SHIP
CI/CD与上线"]
    F --> G["Day7
多Agent安装
实战踩坑"]
    F --> H["Day8
横评
三大技能库"]
    G --> I["Day9
收官
从能跑到可合并"]
    H --> I
    I -.反馈闭环.-> A

回到那张开篇就画过的六阶段流水线。九篇文章讲的不是六个独立的步骤，而是一个闭环——SHIP 之后收集到的反馈，会重新流回 DEFINE。这正是工程实践区别于”做完就丢”的关键。

flowchart LR
    D["DEFINE
想法打磨"] --> P["PLAN
任务拆解"]
    P --> B["BUILD
增量实现"]
    B --> V["VERIFY
调试验证"]
    V --> R["REVIEW
代码评审"]
    R --> S["SHIP
上线发布"]
    S -.反馈与监控.-> D
    V -.Tier 3 行为检查.-> B
    R -.Tier 3 行为检查.-> D

最下面那两条虚线是新加的——评估反馈。这正是我要讲的第二件事：三层评估框架。它是这套流水线能”自我修正”的机制。

二、三层评估框架：agent-skills 的独特之处

我对比过三个主流的 agent 技能库（Day8 那篇横评里有详细分析），它们解决”AI 怎么写代码”的问题方式不太一样。但 agent-skills 有一件事是另外两家都没做的：用工程化的方式评估技能本身。

仓库里 evals/ 目录藏着一个三层评估框架：

Tier	检查内容	跑在哪	成本
Tier 1：结构检查	frontmatter、命名、必填章节、命令对齐	CI（`validate-skills.js`、`validate-commands.js`）	免费
Tier 2：路由检查	正向 prompt 能否命中、负向 prompt 不会误命中、两个技能描述是否冲突	CI（`run-evals.js`）	免费
Tier 3：行为检查	智能体真跑一遍技能，是否满足 `expectations[]`	按需（`run-evals.js --behavioral`）	烧 token

它们之间的关系是递进的——Tier 1 过了不代表 Tier 2 过，Tier 2 过了不代表 Tier 3 过：

flowchart TB
    T1["Tier 1
结构检查
SKILL.md 格式正确"] -->|通过| T2["Tier 2
路由检查
描述能命中目标 prompt"]
    T2 -->|通过| T3["Tier 3
行为检查
agent 真跑符合预期"]
    T1 -->|失败| Fix1["修 SKILL.md
补 frontmatter"]
    T2 -->|失败| Fix2["修 description
加触发词 / 收敛范围"]
    T3 -->|失败| Fix3["改 skill 工作流
或补 expectations"]

    classDef tier fill:#e8f4ff,stroke:#3b82f6
    class T1,T2,T3 tier

Tier 1：结构检查

这是最朴素的一层。打开任何一个 SKILL.md，它必须满足：

YAML frontmatter 里 name 小写连字符，且和目录名一致
description 长度 ≤ 1024 字符，包含”做什么”+”何时用”
包含标准章节：Overview、When to Use、Core Process、Common Rationalizations、Red Flags、Verification
对应的 slash 命令（如果存在）也要满足对齐规则

这一层跑在 CI 上，零成本、零 token。如果 SKILL.md 写错了，CI 直接红，根本进不了主分支。

Tier 2：路由检查

这是最巧妙的一层。

问题：技能库里 24 个技能，每个都有自己的 description。当用户说”写一个失败的测试”，模型该调用 test-driven-development 还是 debugging-and-error-recovery？判定完全靠 description 里那行文字。

agent-skills 用了一种词法近似的方法：把每个 prompt 和每个 description 都做词干提取 + TF-IDF 向量化，然后对每个 prompt 跑排序，看正向 prompt 能否把对应技能排在 top-k，负向 prompt 是否不会把它误排到第一。

1
2
3

# CI 跑 Tier 2（确定性、零成本）
node scripts/run-evals.js
node scripts/run-evals.js --min-rank1 80  # 强制路由底线

README 里给了一个真实数字：**已签入的基线是 rank-1 命中率 86%**，CI 卡 80%。这两个数字之间的余量是有意留的——给”无关的描述改动”留缓冲，但不降到能掩盖回归。

冲突检查也很重要：两个技能 description 相似度 ≥ 75% 直接报错，≥ 50% 警告。我改一个技能的时候经常跑这条，避免”我以为只动了一个，结果另一个被抢走了”。

Tier 3：行为检查

这是最贵的一层，也是最关键的一层。

Tier 1 和 Tier 2 都只能检查”文档长什么样”和”描述能不能命中”。但真正的问题是：AI 真按 SKILL.md 跑下来，能不能产出符合预期的东西？

Tier 3 的做法是：给每个技能写一份 evals.json，里面是真实的 prompt + 一份 expectations[]（可验证的预期）。然后用无头 claude 跑，把整个 trace（包含工具调用）丢给 grader 评分。

1 2	# 烧 token 的 Tier 3 node scripts/run-evals.js --behavioral test-driven-development

跑出来什么样子？比如 test-driven-development 的 eval：

{
  "id": 1,
  "kind": "execution",
  "prompt": "修一下发票总额里的舍入 bug，先写测试。",
  "expectations": [
    "修复前先写一个会失败的测试并展示它失败",
    "实现只写到刚好让测试通过",
    "修复后跑一遍完整测试集，确保没有回归"
  ]
}

这三个 expectation 都是可验证的行为，不是文风。grader 看的是 trace：有没有先写测试？实现的 diff 有没有超过必要范围？跑测试的命令有没有执行、退出码是不是 0？

更狠的是 Tier 3 还包含压力测试——专门给纪律类技能加的：时间压力（”赶时间，先跳过 SPEC”）、沉没成本（”已经写了 200 行，懒得回滚”）、权威压力（”老板说要直接上线”）。看技能流程在压力下还撑不撑得住。

三层的意义

把三层叠加起来，我们其实在解决一个根本问题：**技能库的”质量保证”**。

Tier 1 保证”格式对”——技能不是随便抄来的模板。
Tier 2 保证”用得上”——描述里有用户实际会说的词，不会被另一个技能抢走。
Tier 3 保证”真管用”——按 skill 跑出来的产物，确实是它承诺的产物。

没有这三层的技能库，是”我写了一个 SKILL.md，你信我”。有三层的技能库，是”我写了一个 SKILL.md，CI 验过 24 个 prompt 路由，5 个真跑过的 trace 评分”。这两件事的差距，就是”个人经验沉淀”和”团队可信赖基础设施”的差距。

三、AI 时代的”生产级”标准

九篇写到这里，我心里一个越来越清晰的图景浮现出来：**AI 时代真正稀缺的不是”能写出代码”，而是”能交付生产级代码”**。

什么是生产级？我们拆开看。

不只是能跑

能跑是底线。但生产级代码还要满足：

维度	含义	对应实践
可合并	评审者看完敢点 merge	原子任务、垂直切片、五维度评审
可回滚	出问题时能 5 分钟内撤回	Feature Flag、安全默认值、git stash
可观察	出问题时能 5 分钟内定位	埋点、trace、日志、告警阈值
可验证	改完知道有没有破坏	测试金字塔、TDD、回归测试
可解释	半年后看代码知道为什么这么写	ADR、文档、commit message

每一行都不是新概念。但在 AI 协作场景下，它们被同时推到了一个新的量级——模型产出太快，错误也被放大了同样的倍数。

三套经典理论的拼图

我一直在想，这套体系对应到软件工程的经典理论里是什么。答案是三个东西的拼图：

测试金字塔（Mike Cohn 提出）：80% 单元测试 + 少量集成 + 极少数 E2E。这是 Day4 反复强调的——test-driven-development 的核心。

DORA 指标（DORA 团队多年研究）：部署频率、变更前置时间、变更失败率、事故恢复时间。这四个指标越高，团队越高效。SHIFT LEFT + FASTER IS SAFER + 可观察性 + 可回滚，对应的就是这四个指标。Day6 那篇讲 SHIP 的文章本质上就是 DORA 四个指标的具体落地。

安全左移（Shift Left Security）：把安全检查从”上线前”挪到”写代码时”。security-and-hardening 技能把这条原则拆成了 dependency audit、secret scan、输入校验、auth/authz、错误信息泄露五条线。

把这三套理论拼起来，AI 编码时代的”生产级”标准可以总结成一句话：

能跑 + 能验 + 能回 + 能看 + 能护——五项都过，才算生产级。

能跑对应能跑通的最小代码；能验对应测试金字塔；能回对应 DORA 的 MTTR 和 Feature Flag；能看对应可观测性；能护对应安全左移。

工程纪律比模型能力更重要

这九篇写下来，我越来越确信一件事：决定 AI 编码质量的，不是模型能力，是工程纪律。

模型的能力每年都在涨，但跳步骤的习惯也在跟着涨。Sonnet 4 比 Sonnet 3.5 更聪明，但它”觉得这个改动太小，跳过 SPEC”的概率没有降低。模型越强，跳步骤越难被发现——因为跳完之后的结果看起来还很像样。

工程纪律做的事，是把流程变成强制。Tier 1 的 CI 检查强制 SKILL.md 不能乱写；Tier 2 的路由评估强制 description 不能漂移；Tier 3 的行为评估强制跑出来的产物必须满足预期；SKILL.md 里的反合理化表强制”我跳过 SPEC”的借口过不去。

这些”强制”才是真正的护栏。模型能力是油门，工程纪律是刹车和方向盘——只踩油门不握方向盘，开得越快越危险。

四、三条采纳路线图

理论讲完了，讲点更实际的。下面是给三类读者的具体路径。每条都假设你已经会用 Claude Code、Cursor 或者类似的 AI 工具——agent-skills 不是给完全不会写代码的人准备的。

个人开发者

如果你是一个人写项目，时间精力都有限，建议从三个技能开始：

**1. interview-me**（DEFINE）。在你拿不准需求的时候用。一个小时问清楚，比三天返工划算。

**2. test-driven-development**（BUILD）。这条最难坚持，但回报最大。学会之后你会发现 AI 写代码不再是”赌一把”，而是”一步一步有证据”。

**3. debugging-and-error-recovery**（VERIFY）。调试分诊六步法，Stop-the-Line + 分诊清单 + 防回归测试。模型最容易在调试时翻车，这条直接堵死。

三个技能配齐，日常开发的”质量下限”就有了。剩下的慢慢加，不要一次上 24 个。

小团队（2-10 人）

小团队的关键不是”每个人都会全套”，而是”团队里有共同的纪律”。建议引入三个技能：

**1. spec-driven-development**（DEFINE）。让 PR description 不再是”实现了 XX”，而是”实现了 SPEC-123 的第 4 项”。

**2. planning-and-task-breakdown**（PLAN）。任务拆成原子任务，验收标准写到 checklist。这一步解决了”代码 review 才发现需求理解不一致”的经典扯皮。

**3. code-review-and-quality**（REVIEW）。五维度评审作为 review checklist 的基础。code-reviewer、test-engineer、security-auditor 三个 persona 在 review 时直接 fan out。

三个技能跑三个月，团队的 PR 通过率、bug 率、事故恢复时间都会有可观测的变化。

开源维护者

维护开源项目最大的挑战是外部贡献者的质量参差。建议这样引入：

第一步：全量引入。 把 24 个技能作为仓库的 AGENTS.md + CLAUDE.md 的参考骨架。AGENTS.md 是仓库内已经写好的范例，可以直接参考。

第二步：改造 AGENTS.md。 把仓库已有的 AGENTS.md 改写成”项目专版”——比如把 spec-driven-development 里的 SPEC 模板换成你项目的 issue 模板，把 TDD 的”测试命令”换成你项目的测试命令。

第三步：加 CI 校验。 把 Tier 1 的 validate-skills.js 移植到你的 CI 里，跑一次结构检查。如果你的项目引入了多技能编排，把 Tier 2 的路由评估也接进来。

这三步做完，外部贡献者的 PR 会从”看运气”变成”至少结构上过得去”。

五、本博客的下一步

九篇系列文章到这里就结束了，但 agent-skills 的实践在这个博客才刚刚开始。

我自己已经在做的几件事，先汇报一下进度。

1. 在本博客（Hexo）部署流程中实测 agent-skills。 这个博客的 deploy.sh 脚本就是天然的试验田——它是一个 shell 脚本，逻辑清晰但缺乏单元测试，正好适合用 TDD 改造。下个月的文章里我会专门讲这次改造的过程。

2. 把 deploy.sh 等脚本用 skill 改造。 计划是用 test-driven-development 给 deploy.sh 写一套单元测试，用 debugging-and-error-recovery 重构错误处理，用 observability-and-instrumentation 加埋点。改造完以后 deploy 流程会变成”可合并、可回滚、可观察”——对应今天讲的”生产级”五项里的三项。

3. 后续文章预告。 我在计划两个新系列：

agent-skills 实战系列：拿真实的项目（包括这个博客）做改造，把”怎么用”讲透。预计 9 月开始。
AI 编码的工程纪律系列：跳出 agent-skills 的范畴，把测试金字塔、DORA、安全左移这些经典理论在 AI 时代重新解构一遍。

如果你也在用 agent-skills，或者有想看的具体话题，欢迎在评论区或者 GitHub 提。

写在最后

写到这里，九篇文章画上了句号。但我心里清楚，句号只是给这一段阅读一个停顿。

回到开篇那张图——DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP → 反馈 → DEFINE。它没有真正的终点。SHIP 之后的反馈，会重新流回 DEFINE。

AI 编码这件事也一样。我们今天写的所有纪律、所有门控、所有评估，都会随着模型能力的演进而调整。但**”工程纪律让产出从能用变成生产级”**这件事不会变。

把这九篇当作起点，不是终点。

祝我们都能写出”能跑、可合并、可回滚、可观察、可解释”的代码。

参考资料

本文采用署名-非商业性使用-相同方式共享 4.0 国际许可协议，转载请注明出处。