agent-skills：用生产级工程纪律武装 AI Agent

<blockquote><p>&quot;Process over prose — workflows over reference.&quot;<br>流程重于文字，工作流重于参考。</p><p>——addyosmani&#x2F;agent-skills README</p></blockquote><p>第 15 章讲 Compound Engineering 让每一轮工作沉淀知识，下一轮起点更高。第 14 章讲 improve 让强模型做审计、弱模型做执行。两章都在回答&quot;怎么让 Agent 做正确的事&quot;。</p><p>本章要回答一个更前置的问题：Agent 知道什么是正确的事吗？</p><p>回答这个问题的人叫 Addy Osmani。</p><p><img src="/images/image-20260620105908917.png"></p><p>如果你写过前端，大概率读过他的书。他在 Google Chrome 领导开发者体验工程团队近 14 年，主导了 Chrome DevTools、Lighthouse、PageSpeed Insights、Core Web Vitals 等工具和标准的建设。2026 年转任 Google Cloud AI 总监，负责 Gemini、Vertex AI 和 Agent Development Kit。著有《Learning JavaScript Design Patterns》《Leading Effective Engineering Teams》，博客名篇《The Cost of JavaScript》从 2017 年到 2023 年持续更新了七年，几乎定义了 web 性能优化的讨论框架。他在前端工程和 web 性能领域的影响力，塑造了一整代前端开发者的工程实践。</p><p>2026 年初，他的注意力从&quot;人怎么写更好的代码&quot;转向了&quot;AI 怎么写更好的代码&quot;。2 月 15 日，他开源了 agent-skills，定位一句话：<strong>&quot;Production-grade engineering skills for AI coding agents&quot;——把资深工程师的工作流、质量门禁和最佳实践，编码为 Agent 不可绕过的结构化约束。</strong> 到 6 月，近 60K star。</p><p>但这不只是又一个爆款开源项目。Osmani 在这个项目里做的事，和他过去十年做的事一模一样：把隐性的工程知识显式化。《Learning JavaScript Design Patterns》是把资深工程师脑子里的设计模式写成可学习的目录。Chrome DevTools 的文档是把调试技巧写成可操作的步骤。agent-skills 是把工程纪律写成 Agent 无法自我说服跳过的约束。</p><p>用 AI 写代码的人都会碰到一种熟悉的挫败感。Agent 接到任务，跳过规格直接敲代码。你说&quot;先写测试&quot;，它说&quot;好的&quot;，然后继续敲代码。你说&quot;这里需要安全检查&quot;，它说&quot;明白&quot;，然后加了一行 <code>// TODO: add auth</code>。你说&quot;代码能简化一下吗&quot;，它说&quot;当然&quot;，然后把三个函数合并成一个更长的函数。</p><p>Agent 不是不听话。它是真的不知道什么叫&quot;先写测试&quot;&quot;安全检查&quot;&quot;简化代码&quot;。这些是资深工程师花了好多年才内化的纪律，而 Agent 的默认行为是用最短路径把代码写出来，能跑就行。其他的都不在它的输出分布里。</p><p>agent-skills 要反转的就是这件事。它所有的设计决策，从七阶段生命周期到反合理化表到验证门禁，都指向同一个目标：让 Agent 像资深工程师一样工作。不是写代码更快，是不跳过那些让代码值得写的东西。</p><span id="more"></span><h2 id="16-1-agent-skills-是什么"><a href="#16-1-agent-skills-是什么" class="headerlink" title="16.1 agent-skills 是什么"></a>16.1 agent-skills 是什么</h2><p>agent-skills 是一套结构化 Markdown 工作流的集合。24 个 skill，7 个斜杠命令，覆盖从想法到上线的完整生命周期。</p><p>安装简单。Claude Code 插件市场直接装：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br></pre></td><td class="code"><pre><span class="line">/plugin marketplace add addyosmani/agent-skills</span><br><span class="line">/plugin install agent-skills@addy-agent-skills</span><br></pre></td></tr></table></figure><p>MIT 开源，纯 Markdown 格式，兼容 Claude Code、Cursor、Gemini CLI、Codex、Windsurf、OpenCode、GitHub Copilot 等几乎所有主流工具。</p><p>但它和前面章节讲的所有技能有一个根本区别。Mattpocock 的 skills 帮你做具体的事，调试、写 PRD、审查代码。improve 帮你审计代码库。Compound Engineering 帮你沉淀知识。agent-skills 不帮你做事。它规定你怎么做事。</p><p>不是&quot;帮我写测试&quot;。是&quot;你写任何代码之前必须先写测试，这是流程，不能跳过&quot;。不是&quot;帮我审查这段代码&quot;。是&quot;你提交的每段代码都必须经过五轴审查，没有例外&quot;。它不是工具箱。是纪律手册。</p><p>Osmani 自己给这个区别下了一个定义：&quot;Process over prose — workflows over reference.&quot;每个 skill 不是一个供阅读的参考文档，是一个有步骤、有检查点、有退出标准的可执行流程。Agent 读了它，不是学到了知识，是被强制遵守一个流程。</p><h2 id="16-2-核心问题：Agent-跳过工程纪律"><a href="#16-2-核心问题：Agent-跳过工程纪律" class="headerlink" title="16.2 核心问题：Agent 跳过工程纪律"></a>16.2 核心问题：Agent 跳过工程纪律</h2><p>Agent 最擅长的事也是它最危险的事：写代码。它能在几秒钟内生成几百行看起来正确的代码。问题就在&quot;看起来正确&quot;。</p><p>写代码之前想清楚需求？Agent 倾向于跳过。&quot;这个很简单，不需要规格&quot;。写完代码补测试？Agent 倾向于跳过。&quot;测试后面再补&quot;。合并前做安全审查？Agent 倾向于跳过。&quot;这个改动不涉及安全&quot;。代码能简化吗？Agent 倾向于不。它写的代码就是它认为最优的样子。</p><p>Osmani 把这些叫做合理化借口（rationalization）。Agent 不是在偷懒。它是在用统计学上最可能的路径完成任务。写代码是它的强项，写规格不是。跳过不擅长的步骤、直奔擅长的步骤，这不是恶意，是概率。</p><p>但软件工程的百年教训是：跳过的步骤会回来。没写的规格变成理解偏差。没写的测试变成生产 bug。没做的审查变成技术债。没简化的代码变成下一次改动的摩擦力。Agent 用最快路径交付的代码，往往成本最高。</p><p>agent-skills 的解法不是让 Agent 更聪明。是让 Agent 无法说服自己跳过步骤。每个 skill 都内建了一套机制，预判 Agent 会找什么借口，提前写下反驳。Agent 读到的不只是&quot;你应该做 X&quot;，还有&quot;如果你觉得可以不做 X，看看这段话&quot;。</p><h2 id="16-3-七阶段开发生命周期"><a href="#16-3-七阶段开发生命周期" class="headerlink" title="16.3 七阶段开发生命周期"></a>16.3 七阶段开发生命周期</h2><p><img src="/images/image-20260620110502804.png"></p><p>agent-skills 把软件开发的完整生命周期编码为七个阶段。每个阶段一个斜杠命令入口，背后挂载一组专项 skill。</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line">/spec → /plan → /build → /test → /review → /code-simplify → /ship</span><br><span class="line"> │ │ │ │ │ │ │</span><br><span class="line"> ▼ ▼ ▼ ▼ ▼ ▼ ▼</span><br><span class="line">Define Plan Build Verify Review Simplify Ship</span><br></pre></td></tr></table></figure><h3 id="16-3-1-spec：先搞清楚要构建什么"><a href="#16-3-1-spec：先搞清楚要构建什么" class="headerlink" title="16.3.1 &#x2F;spec：先搞清楚要构建什么"></a>16.3.1 &#x2F;spec：先搞清楚要构建什么</h3><p><code>/spec</code> 是铁律第一条：规格先行，代码在后。</p><p>背后挂了三张 skill。<code>interview-me</code> 是一次一问式访谈，Agent 一个问题一个问题地问，直到对需求有约 95% 的置信度才停。这防止了 Agent 凭一句话猜测需求然后闷头写代码。<code>idea-refine</code> 用于模糊想法的发散和收敛思维，生成多个方向、逐一评估、浓缩为一个可执行方案。<code>spec-driven-development</code> 产出结构化 PRD，包含目标、结构、代码风格、测试策略、边界条件。</p><p>一个容易被忽略的细节：<code>/spec</code> 也接受&quot;这个太简单了不需要规格&quot;的借口。它的反合理化表里写着：简单任务不需要长规格书，但仍然需要验收标准。两行也行。写下来。</p><h3 id="16-3-2-plan：拆解为小而可验证的任务"><a href="#16-3-2-plan：拆解为小而可验证的任务" class="headerlink" title="16.3.2 &#x2F;plan：拆解为小而可验证的任务"></a>16.3.2 &#x2F;plan：拆解为小而可验证的任务</h3><p><code>/plan</code> 把规格分解为原子化任务。每个任务必须有明确的验收标准，必须能在一个上下文窗口内完成。</p><p>背后的 <code>planning-and-task-breakdown</code> skill 强制了几个约束：任务之间依赖关系显式标注、每个任务独立可验证、优先排序、预估工作量。和第 13 章 GSD 的 Plan 阶段同一个思路，计划必须能装进一个上下文窗口。</p><h3 id="16-3-3-build：增量实现，一次一片"><a href="#16-3-3-build：增量实现，一次一片" class="headerlink" title="16.3.3 &#x2F;build：增量实现，一次一片"></a>16.3.3 &#x2F;build：增量实现，一次一片</h3><p><code>/build</code> 是整个体系中最重的阶段，挂载了 7 张专项 skill。</p><p><code>incremental-implementation</code> 是核心引擎。它强制的不是&quot;写什么代码&quot;，是&quot;怎么组织写代码的过程&quot;：一次只做一片薄纵向切片，每片独立测试、独立提交、独立可回滚。特性开关包裹未完成的功能。安全默认值，不破坏已有行为。约 100 行变更粒度，保持可审查。</p><p><code>test-driven-development</code> 编码了红-绿-重构循环，但不是教科书式的教条。它把测试金字塔量化为 80&#x2F;15&#x2F;5（单元 80%&#x2F;集成 15%&#x2F;端到端 5%），强调 DAMP（描述性和有意义的外语）优于 DRY（测试之间不要过度共享），以及 Beyoncé Rule——&quot;如果你喜欢它，你应该给它写测试&quot;。</p><p><code>source-driven-development</code> 是一个容易被忽视的高杠杆 skill。它要求 Agent 将决策建立在官方文档之上：验证、引用来源、标记未验证的断言。这防止了 Agent 基于训练数据里过时或错误的 API 用法写代码。</p><p><code>doubt-driven-development</code> 是整个项目最有创意的 skill。核心理念：AI 给出的&quot;自信答案&quot;不等于&quot;正确答案&quot;。长会话会悄悄把假设转化为&quot;事实&quot;，需要新鲜上下文的审查者来发现盲点。工作流是五步对抗性审查循环：CLAIM（声明决策，为什么重要）→ EXTRACT（剥离推理，只留结论）→ DOUBT（召唤全新上下文的审查者，带对抗性提示）→ RECONCILE（逐条核实每个发现）→ STOP（满足终止条件才放行，最多 3 轮）。</p><p>触发条件写得非常具体。引入分支逻辑、跨模块边界、断言类型系统无法验证的属性、正确性依赖未来读者看不到的上下文、爆炸半径不可逆——这些都是&quot;非平凡决策&quot;，触发 doubt-driven 审查。</p><p><code>/build</code> 还有一个 <code>/build auto</code> 模式。你批准计划一次，Agent 自主实现所有任务。每个任务仍然测试驱动、独立提交，遇到失败自动暂停。和第 12 章 Loop Engineering 的 <code>/goal</code> 逻辑一致，Agent 自己跑到条件满足为止。</p><h3 id="16-3-4-test：证明它能用"><a href="#16-3-4-test：证明它能用" class="headerlink" title="16.3.4 &#x2F;test：证明它能用"></a>16.3.4 &#x2F;test：证明它能用</h3><p><code>/test</code> 的核心原则一句话：测试是证明，不是感觉。&quot;看起来对&quot;永远不够。Agent 必须提供证据，测试通过、构建输出、运行时数据。</p><p>背后两张 skill。<code>browser-testing-with-devtools</code> 利用 Chrome DevTools MCP 做运行时检查，DOM、控制台、网络、性能数据，数据驱动的验证而非&quot;页面看起来对&quot;。<code>debugging-and-error-recovery</code> 编码五步调试法：复现 → 定位 → 缩小范围 → 修复 → 加护栏防止重犯。</p><h3 id="16-3-5-review：合并前的质量门禁"><a href="#16-3-5-review：合并前的质量门禁" class="headerlink" title="16.3.5 &#x2F;review：合并前的质量门禁"></a>16.3.5 &#x2F;review：合并前的质量门禁</h3><p><code>/review</code> 是质量的门神。五轴审查：正确性、安全、性能、可维护性、代码风格。约 100 行变更粒度，使用 Nit&#x2F;Optional&#x2F;FYI 三级严重度标签。</p><p>背后四张 skill 各有专攻。<code>code-review-and-quality</code> 做结构审查。<code>security-and-hardening</code> 覆盖 OWASP Top 10、认证模式、密钥管理、三级边界系统。<code>performance-optimization</code> 的原则是&quot;先测量&quot;，Core Web Vitals、性能分析、bundle 分析。<code>code-simplification</code> 应用 Chesterton&#39;s Fence（看不懂为什么存在的东西，先搞清楚原因再删）和 Rule of 500（超过 500 行的文件必须拆分）。</p><h3 id="16-3-6-code-simplify：清晰优于聪明"><a href="#16-3-6-code-simplify：清晰优于聪明" class="headerlink" title="16.3.6 &#x2F;code-simplify：清晰优于聪明"></a>16.3.6 &#x2F;code-simplify：清晰优于聪明</h3><p>这是一个独立的、跨阶段的命令。核心信条：代码是负债。每行代码都是将来要读、要改、要调试的东西。Agent 默认倾向多写，不是少写。<code>/code-simplify</code> 强制它反过来：在所有功能都能跑的前提下，让代码更少、更清晰。</p><h3 id="16-3-7-ship：安全上线"><a href="#16-3-7-ship：安全上线" class="headerlink" title="16.3.7 &#x2F;ship：安全上线"></a>16.3.7 &#x2F;ship：安全上线</h3><p><code>/ship</code> 是最后的防线。六张 skill 覆盖从代码到生产的每一步。<code>git-workflow-and-versioning</code> 强制主干开发加原子提交。<code>ci-cd-and-automation</code> 强制左移、特性开关、质量门禁管道。<code>documentation-and-adrs</code> 强制记录&quot;为什么&quot;，不只是&quot;是什么&quot;。<code>observability-and-instrumentation</code> 强制结构化日志、RED 指标、OpenTelemetry 追踪。<code>shipping-and-launch</code> 强制上线前检查清单、分阶段发布、回滚程序。<code>deprecation-and-migration</code> 强制&quot;代码即负债&quot;心态，逐步废弃旧东西。</p><h2 id="16-4-反合理化表：Agent-自欺的克星"><a href="#16-4-反合理化表：Agent-自欺的克星" class="headerlink" title="16.4 反合理化表：Agent 自欺的克星"></a>16.4 反合理化表：Agent 自欺的克星</h2><p>走完七个阶段，你可能注意到了。<code>/spec</code> 里有一句话留给&quot;这个太简单了不需要规格&quot;。<code>/build</code> 里有一句话留给&quot;测试后面再补&quot;。<code>/review</code> 里有一句话留给&quot;这个改动不需要审查&quot;。每个阶段、每张 skill，都在做同一件事：预判 Agent 会找什么借口，提前写下反驳。</p><p>这就是反合理化表（anti-rationalization table）。agent-skills 最具辨识度的设计，也是它和所有其他技能框架最根本的区别。</p><p>每个 skill 都内嵌一张&quot;借口 vs 反驳&quot;对照表。左边是 Agent 可能会说的，统计上最可能的合理化借口。右边是提前写好的反驳，为什么这个借口不成立。</p><p>几个真实例子：</p><table><thead><tr><th>Agent 可能会说</th><th>预设的反驳</th></tr></thead><tbody><tr><td>&quot;这个太简单了，不需要 spec&quot;</td><td>简单任务不需要长规格书，但仍然需要验收标准。两行也行。写下来。</td></tr><tr><td>&quot;测试后面再补&quot;</td><td>&quot;后面&quot;永远不会来。写完代码再补的测试，只是同一份代码换了个名字。</td></tr><tr><td>&quot;我在预发布环境测过了，上生产没问题&quot;</td><td>数据不同、流量不同、边缘情况不同。</td></tr><tr><td>&quot;这个很简单，不需要 feature flag&quot;</td><td>每个功能都需要一个安全开关。没有例外。</td></tr><tr><td>&quot;这个改动不需要审查&quot;</td><td>所有改动都需要审查。变更越小，审查越容易，越没理由跳过。</td></tr></tbody></table><p>这张表的设计建立在对 LLM 行为模式的深刻理解之上。LLM 擅长为自己找合理化借口，&quot;可以根据上下文推断&quot;&quot;这种简单情况不需要&quot;——这些借口在统计上是合理的，因为训练数据里充满了人类用同样的借口跳过同样的事。</p><p>反合理化表就是提前写好的反驳，针对 Agent 还没说出口的谎言。Agent 读到一个步骤，也读到了&quot;如果你觉得可以跳过这一步，看看这段话&quot;。它被制度性地阻止自我欺骗。</p><p>Osmani 的博客里有一句话总结了这张表的意义：<strong>&quot;AI 编程代理是极其能干的初级工程师，但本能地缺少那些不出现在 diff 中的工作部分。高级工程师的工作——揭示假设、控制变更规模、写规格书、留下证据、拒绝合并不经审查的代码——正是 AI 代理会跳过的东西，除非你让它无法跳过。&quot;</strong></p><h2 id="16-5-Google-工程文化的-DNA"><a href="#16-5-Google-工程文化的-DNA" class="headerlink" title="16.5 Google 工程文化的 DNA"></a>16.5 Google 工程文化的 DNA</h2><p>agent-skills 不是凭空设计的。它深度嵌入了 Google 公开工程实践中的关键原则。</p><p><img src="/images/image-20260620111040581.png"></p><p>Hyrum&#39;s Law——&quot;如果 API 有足够多的用户，你对合约的承诺不重要，所有可观测的行为都会被某人依赖&quot;——被编码进 <code>api-and-interface-design</code> skill。Beyoncé Rule——&quot;如果你喜欢它，你应该给它写测试&quot;——被编码进 <code>test-driven-development</code>。Chesterton&#39;s Fence——&quot;别拆掉你不理解为什么存在的篱笆&quot;——被编码进 <code>code-simplification</code>。主干开发、Shift Left、特性开关被编码进 <code>git-workflow-and-versioning</code> 和 <code>ci-cd-and-automation</code>。</p><p>这不是巧合。Osmani 在 Google Chrome 领导工程团队多年，这些原则是他每天都在用的东西。agent-skills 本质上是一次大规模的工程文化蒸馏。把 Google 工程文化中那些艰难获得的最佳实践从人的脑子里提取出来，固化为 Agent 的不可绕过的工作流。</p><h2 id="16-6-与全书方法论的对接"><a href="#16-6-与全书方法论的对接" class="headerlink" title="16.6 与全书方法论的对接"></a>16.6 与全书方法论的对接</h2><p>agent-skills 和其他章节的方法论有天然的亲和力。</p><p><strong>和第 2 章 Skills 是同一个理念的全面展开。</strong> Matt Pocock 定义了&quot;原子 Skill&quot;的范式，小而可组合、模型无关、可改造。agent-skills 把这个范式推到了全生命周期覆盖的顶点。24 个 Skill 不是零散的，是按阶段组织的，从前到后形成一条完整的纪律链。</p><p><strong>和第 8 章 Goal Workflow 高度同构。</strong> <code>/spec → /plan → /build → /test → /review → /ship</code> 这条链和 <code>/prd → /prd-to-spec → /goal → /review-it → /ship-it</code> 几乎一一对应。区别在于 agent-skills 管得更细。不只是&quot;你要走这些步骤&quot;，是&quot;每一步你该怎么走，有什么坑，什么借口不能信&quot;。</p><p><strong>和第 12 章 Loop Engineering 互为表里。</strong> Addy Osmani 本人是 Loop Engineering 概念的命名者和推广者，第 12 章讲的那篇定义了&quot;五个原语加一个记忆&quot;的长文就是他写的。agent-skills 可以看作 Loop 中每个阶段的操作手册。Loop 定义了循环的结构，agent-skills 定义了循环里每个动作的纪律。</p><p><strong>和第 14 章 improve 的反合理化机制殊途同归。</strong> improve 用 STOP 条件阻止弱模型即兴发挥，agent-skills 用反合理化表阻止 Agent 跳过步骤。两者的核心信念一样：Agent 需要被制度性地阻止自我欺骗。区别在于 improve 专注前置审计，agent-skills 专注全流程纪律。</p><p><strong>和第 15 章 Compound Engineering 的复利兼容。</strong> agent-skills 的渐进式知识积累（spec → plan → ADR → pulse 报告）天然为复利提供原料。每一次循环产出的规格、计划、架构决策记录，都是下一次 Agent 启动时的默认上下文。</p><h2 id="16-7-本章小结"><a href="#16-7-本章小结" class="headerlink" title="16.7 本章小结"></a>16.7 本章小结</h2><p>agent-skills 把&quot;工程纪律&quot;从人的自觉变成了 Agent 的结构化约束。7 个命令覆盖从想法到上线的全过程，24 个 skill 将 Google 工程文化的关键原则编码为不可绕过的工作流。</p><p>反合理化表加验证门禁是它最锋利的创新。Agent 被制度性地阻止&quot;跳过测试&quot;&quot;以后再重构&quot;&quot;这个太简单了不需要规格&quot;等自欺行为。每一步都以证据收尾，测试通过、构建输出、运行时数据。&quot;看起来对&quot;不算数。</p><p>Osmani 的工程哲学全部浓缩在几个词里：流程重于文字，验证重于声称，纪律重于速度。这不是贴在 README 里的口号。是写进了每一个 skill 文件、每一张反合理化表、每一步验证门禁的设计决策。</p>