agent-skills 采用指南：Greenfield 与 Brownfield 两条落地路径的工程实践

agent-skills 采用指南：Greenfield 与 Brownfield 两条落地路径的工程实践

【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills

在 agent-skills（"Production-grade engineering skills for AI coding agents"）中，25 个技能覆盖了从规格到发布的完整生命周期，但"装好之后如何用"同样关键：全新项目可以从第一个提交起就运行全生命周期，而已有多年历史的代码库必须走一条渐进的、验证优先的落地路径。本篇基于仓库中的 Adoption Guide 展开，结合各技能的SKILL.md源码实现，讲清两条路径的适用信号、分阶段动作、反模式与最终收敛状态，帮助你在自己的仓库里做出可执行、可验证的采用决策。

先判断：你处在 Greenfield 还是 Brownfield？

采用策略的核心变量是代码库所处的生命周期阶段。判断信号如下（继承自 adoption-guide.md 的对照表）：

如果你的项目介于两者之间（比如一个已经上线但还很年轻的项目），指南给出的建议是：从 Brownfield 路径起步，然后加速——两条路径最终收敛到同一个终态。

路径 A：Greenfield，从第一个提交起的全生命周期

新项目是最佳场景：没有需要保留的遗留行为，技能内置的质量门几乎零成本，并且从第一个提交开始产生复利。

第 0 天：安装与接线

1. 安装技能包。最快路径是开放的 skills CLI：npx skills add addyosmani/agent-skills（安装全部 25 个技能）或npx skills add addyosmani/agent-skills --list（先浏览再安装）。偏好原生集成的工具（Claude Code、Cursor、Gemini CLI、Codex 等）可走各自的安装方式，详见 getting-started.md 及 docs/ 目录下的各工具配置指南。
2. 加载using-agent-skills元技能，让 Agent 自行把任务路由到正确的技能。从 skills/using-agent-skills/SKILL.md 可以看到，它内置了一张"任务到达 → 判断开发阶段 → 分派技能"的决策流程图：新项目走spec-driven-development，写测试走test-driven-development，出故障走debugging-and-error-recovery，评审走code-review-and-quality，以此类推。
3. 添加一份简短的项目规则文件（CLAUDE.md、.cursorrules等），写明技术栈、命令与边界。这一步由context-engineering技能定义"什么该放进去"。

从 skills/context-engineering/SKILL.md 可以看到规则文件的推荐结构：Tech Stack、Commands（build/test/lint/dev/type check）、Code Conventions、Boundaries（"永不提交 .env"、"改数据库 schema 前先询问"等）、Patterns（一个符合你风格的简短范例）。该技能还给出了其他工具的等价文件对照（.cursorrules、.windsurfrules、.github/copilot-instructions.md、AGENTS.md）。

第 0 天：先定义，再构建

对项目的第一个真实功能，按顺序运行生命周期（原文档中的命令到产物的映射）：

/spec → SPEC.md (spec-driven-development) /plan → tasks/plan.md (planning-and-task-breakdown) /build → one slice at a time (incremental-implementation + test-driven-development) /review → before every merge (code-review-and-quality) /ship → when going live (shipping-and-launch)

这些不是纸面口号：/spec的命令提示词明确要求"先澄清目标、核心功能与边界，再生成覆盖六大核心区域的规格，保存为项目根目录的SPEC.md"，见 commands/spec.toml；/review则要求对 staged 或最近提交做五轴审查，见 commands/review.toml；/ship是一个并行 fan-out 编排器，同时派发code-reviewer、security-auditor、test-engineer三个 persona，再合并出 GO/NO-GO 决策与回滚方案，见 commands/ship.toml。

关于产物管理，docs/getting-started.md 特别强调SPEC.md与tasks/是活文档：开发期间保持在版本控制中，让人与 Agent 共享同一事实源；范围或决策变化时同步更新。

/build auto是 Greenfield 的好选择：你只批准一次计划，之后每个任务仍然逐个测试驱动（TDD）驱动、逐个独立提交；失败或有风险的操作会暂停。README 明确说明它移除的是任务之间的人工介入，而不是验证本身。

从第一天起就"常开"的四个技能

• test-driven-development：覆盖债在零覆盖时最便宜，一旦欠下就指数级昂贵。
• git-workflow-and-versioning：原子提交与 ~100 行变更是"习惯"而非"返工"。这一点在技能源码中有硬约束：skills/git-workflow-and-versioning/SKILL.md 写明"Target ~100 lines per commit/PR，超过 ~1000 行必须拆分"。
• security-and-hardening：认证、输入校验、密钥处理是结构性的；事后补装就是一项迁移工程。
• documentation-and-adrs：最早期的架构决策恰恰是两年后没人记得"为什么"的那些。现在写一条 ADR，就能避免路径 B 里描述的"brownfield 考古"。

随项目成长按需加载

Greenfield 反模式

• 因为是"原型"就跳过/spec。原型会变成产品。规格是你为这个代码库写过的最便宜的文档。
• 每个会话加载全部 25 个技能。浪费上下文，稀释真正关键的技能。应按阶段加载，让using-agent-skills负责路由——docs/getting-started.md 也把"Context-Aware Loading"列为原则：做 UI 才加载frontend-ui-engineering，调试才加载debugging-and-error-recovery。
• 把可观测性推迟到"有东西可观测的时候"。边构建边埋点；事后补结构化日志，是你亲手制造的一个路径 B 问题。

路径 B：Brownfield，渐进式、验证优先

在存量代码库中，风险画像是反转的：危险不在于"构建错了东西"，而在于变更一个没有人完整描述过行为的系统。因此采用顺序从"读取并保护"代码库的技能开始，最后才轮到"修改"代码库的技能。

阶段 1：上下文与只读技能

目标：Agent 在动任何东西之前先理解代码库。

1. 先上context-engineering。写一份描述"代码里真实约定"（而不是 wiki 里写的）的规则文件：构建/测试命令、目录含义、已知地雷（例如"别碰legacy/billing，它没有测试、有三处已知变通"）。这直接对应 skills/context-engineering/SKILL.md 中列的反模式——"隐含知识"（没写下来的规则等于不存在）与"上下文缺料"（Agent 凭空发明 API）。
2. code-review-and-quality用于所有 incoming 变更。评审是零风险且立竿见影的：从 skills/code-review-and-quality/SKILL.md 可以看到五轴评审（correctness / readability / architecture / security / performance）与严重度标签体系——无前缀 = Required（合并前必须处理）、Critical:阻断合并、Nit:可忽略、Optional:/Consider:建议、FYI纯信息。这套分级让"什么阻断合并、什么不阻断"在任何代码库状态下都清晰。
3. debugging-and-error-recovery用于你本来就要修的 bug。五步分诊（reproduce → localize → reduce → fix → guard）在陌生代码上尤其有效。从 skills/debugging-and-error-recovery/SKILL.md 的 Stop-the-Line 规则可以看到其纪律性：先停（停止堆功能）、保留证据、诊断、修根因、加防护（guard），最后才恢复开发。"guard" 这一步正是开始为你缺失的回归测试套件添砖加瓦。
4. doubt-driven-development作为安全网。遗留代码正是该技能的目标场景——"陌生代码、出错代价高"。从 skills/doubt-driven-development/SKILL.md 的 CLAIM → EXTRACT → DOUBT → RECONCILE → STOP 流程可以看到，它用一个全新上下文的对抗性评审者（"假设作者过于自信，找问题，不要验证"）来拦截 Agent 对遗留系统工作原理的自信幻觉，在它们变成提交之前。

阶段 2：变更之前先有测试

目标：Agent 将要触碰的每个区域先有安全网。

• test-driven-development，选择性应用。不要追求全局覆盖率；追求计划变更之处的覆盖。对无测试的遗留行为，先写特征化测试（characterization tests）——把代码当前的行为（无论对错）钉住，再动手改。指南在此引用了 Beyonce Rule，它在 skills/test-driven-development/SKILL.md 中有原文定义："If you liked it, you should have put a test on it"——如果你依赖了某个行为，你就应该为它写了测试；基础设施变更、重构和迁移没有义务替你兜底。
• code-simplification用于最糟的热点。Chesterton's Fence 是核心原则：从 skills/code-simplification/SKILL.md 可以看到其第一原则"Preserve Behavior Exactly"——简化只改表达方式，不改输入输出、副作用与错误行为，每个简化都要回答"新成员能否比看原代码更快理解它"。行为保持的简化 + 特征化测试，是让遗留代码变得"可改"的最低风险方式。
• git-workflow-and-versioning无处不在。原子小提交在 brownfield 中更重要：当对老代码的变更破坏了微妙的东西时，~100 行的提交可以二分定位（bisect），2000 行的"现代化"提交不能。

阶段 3：新工作运行全生命周期

目标：双速采用——遗留代码维持阶段 1–2 的管控，新功能享受 Greenfield 待遇。

• 老代码库里的新功能？照跑/spec → /plan → /build → /review。规格的 boundaries 部分就是声明"该功能可以触碰、不得触碰哪些遗留接口"的地方（/spec提示词明确要求澄清"known boundaries: what to always do, ask first about, and never do"，见 commands/spec.toml）。
• api-and-interface-design用在接缝处。新代码必须与老代码对话时，契约先行地设计边界。Hyrum's Law 在多年历史的代码库里不是理论问题——有人依赖每个可观察行为，包括 bug。
• security-and-hardening先审计、后设门。对现有攻击面（认证、输入处理、依赖）跑一次全量审计——单是依赖审计通常就回本——把发现立案（file），之后对新变更强制执行。

阶段 4：偿还、弃用、观测

• deprecation-and-migration是 brownfield 的"招牌技能"。从 skills/deprecation-and-migration/SKILL.md 可以看到其核心立场："Code is a liability, not an asset"，且"Hyrum's Law 让删除变难"——弃用需要主动迁移而非仅仅公告。强制弃用（compulsory）与咨询式弃用（advisory）的区分、僵尸代码清除，给了你一种纪律化的方式去缩小遗留面，而不是仅仅把它包起来。
• observability-and-instrumentation沿你真正在调试的路径后装。先对事故最多的源头做结构化日志与 RED 指标。
• performance-optimization在回归真正要紧时介入。它的 measure-first（先测量）规则，正是防止掉进"优化一段从来不是瓶颈的遗留代码"这个经典陷阱。

Brownfield 反模式

• "Big bang" 采用。第一天就把全生命周期压到遗留代码库上，只会得到"为已存在代码写的规格"和"没有安全网的重构"。要排序。
• 让 Agent 重构无测试的代码。没有特征化测试，就没有重构。这是 brownfield 采用中最贵的一次性捷径。
• 跳过context-engineering，理由是"代码即文档"。Agent 会从它恰好读到的最糟糕的文件里推断约定。把真实约定写下来。
• 默认认为遗留系统行为是错的。Chesterton's Fence：那个怪异的 retry 循环可能承着重载。先理解，再变更。
• 什么都不棘轮化（ratchet）。采用应让质量单调变好：每个阶段增加一个不会撤掉的质量门。如果一个月后你说不清"现在多强制了哪些之前不强制的东西"，说明推广已经停滞。

两条路径的收敛

两条路径最终抵达同一个稳态：新工作走/spec → /plan → /build → /review → /ship，TDD 与 git 纪律常开，合并前设评审门，技能按阶段加载而非一次性全量加载。Greenfield 几天到达，Brownfield 大约一个季度到达——差距恰恰来自老代码库从来没有过的那些安全网（上下文、特征化测试、边界）。

延伸阅读（仓库内）

• 安装与各工具（Claude Code / Cursor / Codex / Gemini CLI / Antigravity 等）的具体接线：docs/getting-started.md
• 25 个技能的完整目录与"何时用哪个"：README.md
• 技能的结构规范（Frontmatter / When to Use / Process / Rationalizations / Red Flags / Verification）：docs/skill-anatomy.md
• 本仓库自带的规则文件范例，可直接参照 CLAUDE.md 编写你项目的版本
• 供 Agent 直接执行的四类 persona（code-reviewer、test-engineer、security-auditor、web-performance-auditor）与组合编排规则：docs/agents.md 与 references/orchestration-patterns.md

一句话总结：采用 agent-skills 不是"装完即用"，而是一次与代码库年龄匹配的分级推进——新项目用全生命周期把质量门从第一天扣进成本结构，老项目用"先读懂、再补网、后变更、最后棘轮化"的顺序，把每一次 Agent 变更都放在可验证的约束之内。

【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills