adr-skill

adr-skill 技能概览

adr-skill 能做什么

adr-skill 用来创建和维护 Architecture Decision Records，让 ADR 不只是事后归档的历史说明，而是真正能指导落地实施的决策文档。它的核心价值，在于把一个架构选择整理成 AI coding agent 也能直接执行、几乎不需要来回追问的 ADR：约束清晰、非目标明确、点名需要修改的文件、写明验证步骤，并说明实际后果。

adr-skill 最适合谁

这个技能尤其适合 engineering leads、staff engineers、平台团队，以及需要沉淀技术决策的技术写作者。它在以下场景里尤其有用：决策一旦做出就不容易回滚、会影响多个协作者，或者需要同时让人类和 AI agents 都能准确理解。

它要解决的核心任务

当你需要做以下事情时，就该用 adr-skill：

• 提出新的架构决策
• 在实现开始前先把决策文档化
• 更新现有 ADR，或用新 ADR 替代旧 ADR
• 在还没有 ADR 体系的仓库里快速搭建 ADR
• 在整个代码库中统一 ADR 的结构和写法

对于 adr-skill for Technical Writing 来说，它最强的适配点，是能产出既方便利益相关方阅读、又足够具体到实现人员可以直接执行的决策文档。

为什么这个技能更突出

adr-skill 最明显的差异化在于它是以 agent-first 的方式来组织 ADR。它不会停留在背景、决策、后果这些基础段落上，而是会继续推动你写出实施计划，包括受影响路径、依赖关系、应遵循的模式、应避免的模式、配置变更，以及验证标准。相比普通的“帮我写个 ADR”提示词，这种产出更能直接进入执行。

采用前要先确认什么

在安装或正式依赖 adr-skill 之前，先确认你的团队是否真的希望用 ADR 来驱动后续实施。如果你的流程只需要轻量级的决策说明，这个技能可能会显得比实际需要更重、更结构化。但如果你需要 ADR 在交接后仍然可用、能减少实现歧义，那么这种额外的严谨性正是它的价值所在。

如何使用 adr-skill 技能

adr-skill 的安装上下文

仓库片段里没有在 SKILL.md 中直接给出这个技能专属的安装命令，但常见安装方式通常是：

npx skills add vercel/ai --skill adr-skill

添加完成后，就可以在你的 AI coding 环境中，在准备制定或记录架构决策时调用它。

先读这些文件

如果你想最快进入有效的 adr-skill usage，建议按这个顺序阅读：

1. SKILL.md
2. references/adr-conventions.md
3. references/review-checklist.md
4. references/template-variants.md
5. references/examples.md

然后再查看：

• scripts/bootstrap_adr.js
• scripts/new_adr.js
• scripts/set_adr_status.js

这个顺序很重要：约定文件会告诉你 ADR 应该放在哪里；checklist 解释了质量门槛；模板变体帮助你选结构；examples 则展示了 ADR 应该具体到什么程度。

使用 adr-skill 时，你需要提供什么输入

当你提供以下信息时，adr-skill 表现最好：

• 这次要做出的决策是什么
• 是什么触发条件或问题迫使你现在必须做这个决策
• 仓库上下文和现有架构情况
• 延迟、成本、合规、部署模型、团队能力等约束
• 非目标
• 预期会受到影响的文件、模块、服务或工作流
• 已经考虑过的备选方案

如果缺少这些输入，技能仍然能起草 ADR，但往往会更偏“泛泛而谈”的模板化文档，而不是一个可执行的 ADR。

如何把模糊想法变成高质量提示词

一个较弱的提示词：

• “Write an ADR for switching databases.”

一个更强、适合 adr-skill usage 的提示词：

• “Create an ADR proposing SQLite for local dev and CI while keeping PostgreSQL in production. Context: shared Postgres makes tests flaky and adds 3+ minutes to CI setup. Constraints: local setup must work offline, CI setup under 10 seconds, production schema remains Postgres-compatible. Non-goals: no production migration, no full ORM rewrite. Affected paths likely include src/db/, test setup, and CI config. Include implementation plan and verification steps.”

第二种写法给了技能足够多的材料，能产出另一位工程师或 agent 真正可以据此实施的决策文档。

有意识地选择合适模板

如果决策其实已经基本定下来了，你主要是要说明为什么这样做、改了什么、以及如何实施，那么用 simple template 更合适。

如果存在真实的竞争方案、多个决策驱动因素，或者利益相关方需要审阅取舍过程，那么更适合使用 MADR 风格模板。这个技能同时提供了这两种模式：

• assets/templates/adr-simple.md
• assets/templates/adr-madr.md

实际工作中的典型 adr-skill 工作流

一套比较实用的流程通常是这样的：

1. 先让技能判断这次变更是否值得写 ADR。
2. 让它反问你上下文、约束和非目标。
3. 用合适的模板起草 ADR。
4. 依据 references/review-checklist.md 做校验。
5. 按仓库实际路径、命名和约定进行编辑。
6. 在选定的 ADR 目录中创建或更新文件。
7. 如果后续需要，再修改生命周期状态。

这正是 adr-skill guide 价值体现的地方：它支持的是完整生命周期，而不只是第一次起草。

如何在没有 ADR 的仓库里快速搭建体系

如果你的仓库还没有任何 ADR 结构，那么自带脚本会非常有用：

• scripts/bootstrap_adr.js

它可以创建 ADR 目录、生成索引/README，并加入一份初始的 “Adopt architecture decision records” 文档。相比手动拍脑袋决定文件夹结构，这种方式更稳妥，因为仓库里已经把目录探测和命名策略等约定编码进去了。

如何更快创建新的 ADR

如果你希望重复、标准化地创建 ADR，可以重点看 scripts/new_adr.js。它支持很多很实用的选项，例如：

• repo root
• ADR directory override
• title
• status
• template choice: simple or madr
• filename strategy
• deciders, consulted, and informed fields
• index updates

对于希望追求可重复流程、而不只是一次性生成文案的团队来说，这也是 adr-skill install 更值得的原因。

状态变更是如何处理的

仓库内置的 scripts/set_adr_status.js 可以直接原地更新 ADR 状态。如果你的团队把 ADR 当作有生命周期的活文档，而不是静态 markdown 文件，这一点就很重要，比如 proposed、accepted、rejected、deprecated 或 superseded 这类状态。

会影响产出质量的仓库约定

这个技能对 ADR 质量有明确偏好：

• 约束应当可衡量
• 非目标应当明确写出
• 后果应当能驱动后续任务
• 实施计划应当点名真实路径
• 验证部分应说明如何确认决策已被正确实现

如果你的提示词里缺少这些内容，即使文字表面上看起来还算完整，实际输出质量也会明显下降。

目录与命名约定需要对齐什么

根据 references/adr-conventions.md，这个技能会优先遵循仓库里已有的约定；如果没有现成约定，则会建议使用类似 docs/decisions/ 或 adr/ 这样的目录。文件命名方面，它也偏好可预测的形式，比如 YYYY-MM-DD-title-with-dashes.md，除非仓库本身已经采用了别的规范。

这也意味着，不要不加判断地把技能默认值强行套到一个已有成熟项目规范的仓库上。

adr-skill 技能常见问题

adr-skill 比普通提示词更好吗？

如果你的目标是写出一份耐用、面向实施的 ADR，那么答案是肯定的。普通提示词也许能生成一篇可读性不错的文档，但 adr-skill 会额外补上触发因素、可衡量约束、非目标、实施规划和审查标准这些结构。相比临时拼出来的 prompt，这通常能更有效地降低歧义。

adr-skill 适合新手吗？

适合，但有一个前提：它能帮助新手把 ADR 写得更好，却不能凭空补出缺失的架构背景。如果你是 ADR 新手，examples 和 template variants 会让学习曲线平缓很多；但如果你对正在记录的那个系统本身还不熟，就要先补齐更多输入信息。

什么情况下不适合用 adr-skill？

以下情况建议跳过 adr-skill：

• 变更很小，而且容易回滚
• 你只需要一份简短的设计说明
• 团队不会长期维护 ADR
• 没有人会真正用这份文档来指导实现

在这些场景里，这套结构可能会显得比决策本身更重。

adr-skill 能处理更新和被替代的 ADR 吗？

可以。这个技能不只适用于新建 ADR，也支持更新、接受、拒绝、废弃和 supersede 既有决策。这对那些架构会持续演进、而不是一成不变的仓库尤其重要。

adr-skill 是帮助技术写作者，还是只适合工程师？

两者都适用。对于 Technical Writing 场景，adr-skill 的价值在于它会强制决策文档回答这些关键问题：改了什么、为什么是现在、哪些内容不在范围内、以及应该如何验证实现。这会让文档对工程团队和未来维护者都更有用。

我一定要用仓库里附带的脚本吗？

不需要。你完全可以把 adr-skill 只当成 ADR 起草和审查辅助工具来用。只有当你需要在整个仓库里标准化创建流程、初始化 ADR 体系或统一更新状态时，这些脚本才特别关键。

如何把 adr-skill 用得更好

给 adr-skill 提供决策触发因素，而不只是主题

你能做的最大提升，就是说明“为什么这个 ADR 是现在必须写”。“Need an ADR for caching” 这种输入太弱；“Current API p95 is 900ms, traffic doubled, and we need sub-200ms reads for product search” 就强得多。触发因素会直接塑造整份文档。

把约束和阈值说具体

adr-skill 是为可衡量决策设计的。能给数字和边界，就尽量给：

• latency targets
• cost ceilings
• compatibility requirements
• rollout windows
• compliance constraints
• operational ownership boundaries

这样输出就会从抽象的架构写作，升级为真正可用于决策的文档。

尽早写明非目标

很多 ADR 之所以失败，是因为它暗含了过多范围。要明确告诉 adr-skill 哪些内容不在本次范围内：

• no migration of production data
• no API version change
• no vendor lock-in decision in this ADR
• no UI redesign

清晰的非目标可以减少范围蔓延，也能生成更靠谱的实施计划。

指向真实路径和现有模式

如果你希望得到真正可用的实施计划，就要提供仓库里真实存在的文件、模块，或者可参考的类似代码模式。例如：

• “Follow the pattern in src/payments/stripe.ts.”
• “Avoid adding logic to pages/api/*; use route handlers under app/api/.”
• “Config lives in infra/terraform/ and .github/workflows/.”

这也是提升 adr-skill skill 输出质量最有效的杠杆之一。

首稿出来后，用 review checklist 再过一遍

不要停在第一次输出。把 ADR 对照 references/review-checklist.md 重新检查，尤其看这几件事：

• 新加入的人能否看懂触发因素？
• 约束是否足够具体，能支持实际行动？
• 是否点名了受影响路径？
• 后续任务和验证步骤是否写明确了？
• 有没有哪条 consequence 只是把 decision 换个说法重复一遍？

这个 checklist 本身就承载了技能很大一部分实用价值。

让模板匹配决策形态

一个常见失败模式，是把选项很多的 MADR 结构用在简单决策上，或者在需要记录取舍的场景里反而用了 simple template。模板要和决策复杂度匹配，ADR 才能既完整又好读。

避免占位符级别的空话

仓库里的 examples 已经明确表明：占位符式文字不应该留在正式 ADR 中。如果首稿里出现了 “use best practices” 或 “update relevant files” 这种模糊表述，就要把它们改写成可执行的细节，比如：

• 具体 dependency versions
• 点名配置项
• migration order
• rollout or rollback checks
• exact test classes or suites

不只打磨 Decision，也要反复推敲 Consequences

很多人会不断修改 Decision 部分，却忽略 Consequences，这其实是个常见误区。强有力的 consequences 应该告诉未来的实现者：哪些事情会变得更容易、更困难、风险更高、成本更高，或者接下来哪些动作会变成必须。如果 consequences 写得弱，ADR 对执行的指导作用就会明显打折。

想让团队更容易采用 adr-skill，可以先统一三件事

如果你希望 adr-skill 在团队里被更广泛使用，建议先围绕它标准化三项内容：

• 一个统一的 ADR 目录约定
• 一套按决策类型选默认模板的规则
• 一套统一的状态词汇

这样可以减少协作摩擦，也能让技能自带脚本在不同仓库里更好发挥作用。

发布前最值得做的最后检查

在正式接受一份由 adr-skill 起草的 ADR 之前，先问一个很硬的问题：一个 coding agent 能不能在不依赖隐性团队经验的前提下，直接据此实现这次变更？如果答案是否定的，就继续补充上下文、路径、模式、约束或验证步骤，直到答案变成肯定。