重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
npx skills add https://github.com/vercel/ai --skill adr-skill通过此技能创建的 ADR 是面向编码智能体的可执行规范。人类批准决策;智能体负责实施。ADR 必须包含智能体编写正确代码所需的一切信息,无需提出后续问题。
这意味着:
当一项决策符合以下情况时,应编写 ADR:
不应为以下情况编写 ADR:
如有疑问:如果未来在此代码库工作的智能体将受益于了解为何做出此选择,则编写 ADR。
如果你是正在代码库中编码的智能体,并且遇到以下任何情况,请停止并在继续之前提议一个 ADR:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
如何提议:告知人类你遇到了什么决策,为什么它很重要,并询问他们是否希望将其记录为 ADR。如果是,则运行完整的四阶段工作流程。如果否,则在代码注释中记录该决策并继续。
每个 ADR 都经历四个阶段。不要跳过任何阶段。
在提出任何问题之前,先从代码库收集上下文:
contributing/decisions/、docs/decisions/、adr/、docs/adr/、decisions/ 以查找现有记录。阅读它们。注意:
package.json、go.mod、requirements.txt、Cargo.toml 或等效文件。注意相关依赖项和版本。访谈人类以理解决策空间。一次只问一个问题,基于之前的回答进行提问。不要一次性抛出所有问题。
核心问题(大致按此顺序提问,跳过从上下文或阶段 0 已明确的内容):
适应性后续问题:根据答案,在决策模糊的地方深入探究。常见的后续问题:
何时停止:当你能够填写 ADR 的每个部分(包括实施计划)而无需编造内容时,你就掌握了足够的信息。如果你对任何部分有猜测,请再问一个问题。
意图摘要确认关口:在进入阶段 2 之前,呈现你所捕获内容的结构化摘要,并请人类确认或更正:
以下是我为 ADR 捕获的内容:
- 标题:{标题}
- 触发因素:{为什么是现在}
- 约束:{列表}
- 选项:{选项 1} 对比 {选项 2} [对比 ...]
- 倾向:{哪个选项及原因}
- 非目标:{明确超出范围的内容}
- 相关 ADR/代码:{与此交互的现有内容}
- 受影响的文件/区域:{在代码库中的位置}
- 验证:{如何知道它被正确实施}
这捕捉到你的意图了吗?有什么需要补充或更正的吗?
在人类确认摘要之前,不要进入阶段 2。
contributing/decisions/(如果存在 contributing/)、docs/decisions/(MADR 默认)或 adr/(更简单的代码库)。YYYY-MM-DD-...),则继续使用。choose-database.md)。assets/templates/adr-simple.md。assets/templates/adr-madr.md。references/template-variants.md。scripts/new_adr.js(处理目录、命名和可选的索引更新)。assets/templates/ 复制模板并手动填写。起草后,根据 references/review-checklist.md 中的智能体就绪检查清单审查 ADR。
以摘要形式呈现审查结果,而不是原始检查清单转储。格式如下:
ADR 审查
✅ 通过项:{列出哪些方面很扎实——例如,“上下文是自包含的,实施计划覆盖了受影响的文件,验证标准是可检查的”}
⚠️ 发现的差距:
- {具体差距 1——例如,“实施计划未提及测试文件——哪个测试套件应覆盖此内容?”}
- {具体差距 2}
建议:{直接发布 / 先修复差距 / 需要更多阶段 1 的工作}
仅列出失败项和显著优势——不要复述每个通过的检查项。
如果存在差距,提出具体的修复建议。不要仅仅标记问题——提供解决方案并请人类批准。
在 ADR 通过检查清单或人类明确接受差距之前,不要最终确定。
智能体在实施对拥有 ADR 的代码库的更改之前,应阅读现有 ADR。这不是创建 ADR 工作流程的一部分——它是任何智能体都应执行的独立操作。
contributing/decisions/、docs/decisions/、adr/、docs/adr/、decisions/。同时检查索引文件(README.md 或 index.md)。accepted 状态的 ADR——这些是活跃的决策。src/db/ 中的数据访问层”,请照做。ADR 应与其管辖的代码进行双向链接。
实施计划部分指定了具体的文件、目录和模式:
## 实施计划
- **受影响的路径**:`src/db/`、`src/config/database.ts`、`tests/integration/`
- **模式**:所有数据库查询都通过 `src/db/client.ts`
在实施受 ADR 指导的代码时,添加引用它的注释:
// ADR: 使用 better-sqlite3 作为测试数据库
// 参见:docs/decisions/2025-06-15-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';
保持这些注释轻量——在入口点添加一个注释,而不是每一行。目标是可发现性:当未来的智能体阅读此代码时,他们可以找到推理依据。
src/db/ 中工作的智能体可以找到管辖该区域的 ADRdeprecated,解释替换路径。## 更多信息 部分追加带有时间戳的内容。不要重写历史。scripts/set_adr_status.js 进行状态更改(支持 YAML 前言、项目符号状态和章节状态)。ADR 被接受后:
contributing/decisions/2025-06-15-use-sqlite-for-test-database.md。”## 更多信息 中更新 ADR 的结果。如果代码库有 ADR 索引/日志文件(通常是 ADR 目录中的 README.md 或 index.md),请保持其更新。
首选:让 scripts/new_adr.js --update-index 来完成。否则:
当向没有 ADR 的代码库引入 ADR 时:
node /path/to/adr-skill/scripts/bootstrap_adr.js
这将创建目录、索引文件和一个已填写的第一个 ADR(“采用架构决策记录”),其中包含解释团队为何使用 ADR 的真实内容。使用 --json 获取机器可读输出。使用 --dir 覆盖目录名称。
对于拥有许多 ADR 的代码库,按子目录组织:
docs/decisions/
backend/
2025-06-15-use-postgres.md
frontend/
2025-06-20-use-react.md
infrastructure/
2025-07-01-use-terraform.md
日期前缀在每个类别内是独立的。尽早选择分类方案(按层、按领域、按团队),并在索引中记录。
scripts/new_adr.js — 根据模板创建新的 ADR 文件,使用代码库约定。scripts/set_adr_status.js — 就地更新 ADR 状态(YAML 前言或内联)。使用 --json 获取机器输出。scripts/bootstrap_adr.js — 创建 ADR 目录、README.md 和初始的“采用 ADR”决策。references/review-checklist.md — 用于阶段 3 审查的智能体就绪检查清单。references/adr-conventions.md — 目录、文件名、状态和生命周期约定。references/template-variants.md — 何时使用简单模板与 MADR 风格模板。references/examples.md — 带有实施计划的已填写的简短和长篇 ADR 示例。assets/templates/adr-simple.md — 用于简单决策的精简模板。assets/templates/adr-madr.md — 用于具有多个选项和结构化权衡的决策的 MADR 4.0 模板。assets/templates/adr-readme.md — 由 scripts/bootstrap_adr.js 使用的默认 ADR 索引脚手架。从目标代码库根目录:
# 简单 ADR
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed
# MADR 风格,带选项
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --template madr --status proposed
# 带索引更新
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed --update-index
# 引导新代码库
node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions
注意:
--dir 和 --strategy 进行覆盖。--json 输出机器可读内容。每周安装次数
67
代码仓库
GitHub 星标数
23.0K
首次出现
13 天前
安全审计
安装于
cursor64
github-copilot60
gemini-cli59
codex59
opencode58
kimi-cli58
ADRs created with this skill are executable specifications for coding agents. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.
This means:
Write an ADR when a decision:
Do NOT write an ADR for:
When in doubt: if a future agent working in this codebase would benefit from knowing why this choice was made, write the ADR.
If you are an agent coding in a repo and you encounter any of these situations, stop and propose an ADR before continuing:
How to propose : Tell the human what decision you've hit, why it matters, and ask if they want to capture it as an ADR. If yes, run the full four-phase workflow. If no, note the decision in a code comment and move on.
Every ADR goes through four phases. Do not skip phases.
Before asking any questions, gather context from the repo:
Find existing ADRs. Check contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/ for existing records. Read them. Note:
Check the tech stack. Read package.json, go.mod, requirements.txt, Cargo.toml, or equivalent. Note relevant dependencies and versions.
Interview the human to understand the decision space. Ask questions one at a time , building on previous answers. Do not dump a list of questions.
Core questions (ask in roughly this order, skip what's already clear from context or Phase 0):
Adaptive follow-ups : Based on answers, probe deeper where the decision is fuzzy. Common follow-ups:
When to stop : You have enough when you can fill every section of the ADR — including the Implementation Plan — without making things up. If you're guessing at any section, ask another question.
Intent Summary Gate : Before moving to Phase 2, present a structured summary of what you captured and ask the human to confirm or correct it:
Here's what I'm capturing for the ADR:
- Title : {title}
- Trigger : {why now}
- Constraints : {list}
- Options : {option 1} vs {option 2} [vs ...]
- Lean : {which option and why}
- Non-goals : {what's explicitly out of scope}
- Related ADRs/code : {what exists that this interacts with}
- Affected files/areas : {where in the codebase this lands}
- Verification : {how we'll know it's implemented correctly}
Does this capture your intent? Anything to add or correct?
Do NOT proceed to Phase 2 until the human confirms the summary.
Choose the ADR directory.
contributing/decisions/ (if contributing/ exists), docs/decisions/ (MADR default), or adr/ (simpler repos).Choose a filename strategy.
YYYY-MM-DD-...), continue that.choose-database.md).Choose a template.
assets/templates/adr-simple.md for straightforward decisions (one clear winner, minimal tradeoffs).After drafting, review the ADR against the agent-readiness checklist in references/review-checklist.md.
Present the review as a summary , not a raw checklist dump. Format:
ADR Review
✅ Passes : {list what's solid — e.g., "context is self-contained, implementation plan covers affected files, verification criteria are checkable"}
⚠️ Gaps found :
- {specific gap 1 — e.g., "Implementation Plan doesn't mention test files — which test suite should cover this?"}
- {specific gap 2}
Recommendation : {Ship it / Fix the gaps first / Needs more Phase 1 work}
Only surface failures and notable strengths — do not recite every passing checkbox.
If there are gaps, propose specific fixes. Do not just flag problems — offer solutions and ask the human to approve.
Do not finalize until the ADR passes the checklist or the human explicitly accepts the gaps.
Agents should read existing ADRs before implementing changes in a codebase that has them. This is not part of the create-an-ADR workflow — it's a standalone operation any agent should do.
Find the ADR directory. Check contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/. Also check for an index file (README.md or index.md).
Scan titles and statuses. Read the index or list filenames. Focus on accepted ADRs — these are active decisions.
Read relevant ADRs fully. Don't just read the title — read context, decision, consequences, non-goals, AND the Implementation Plan. The Implementation Plan tells you what patterns to follow and what files are governed by this decision.
ADRs should be bidirectionally linked to the code they govern.
The Implementation Plan section names specific files, directories, and patterns:
## Implementation Plan
- **Affected paths**: `src/db/`, `src/config/database.ts`, `tests/integration/`
- **Pattern**: all database queries go through `src/db/client.ts`
When implementing code guided by an ADR, add a comment referencing it:
// ADR: Using better-sqlite3 for test database
// See: docs/decisions/2025-06-15-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';
Keep these lightweight — one comment at the entry point, not on every line. The goal is discoverability: when a future agent reads this code, they can find the reasoning.
src/db/ can find which ADRs govern that areaIdentify the intent:
deprecated, explain replacement path.## More Information with a date stamp. Do not rewrite history.Use scripts/set_adr_status.js for status changes (supports YAML front matter, bullet status, and section status).
After an ADR is accepted:
contributing/decisions/2025-06-15-use-sqlite-for-test-database.md."## More Information.If the repo has an ADR index/log file (often README.md or index.md in the ADR dir), keep it updated.
Preferred: let scripts/new_adr.js --update-index do it. Otherwise:
When introducing ADRs to a repo that has none:
node /path/to/adr-skill/scripts/bootstrap_adr.js
This creates the directory, an index file, and a filled-out first ADR ("Adopt architecture decision records") with real content explaining why the team is using ADRs. Use --json for machine-readable output. Use --dir to override the directory name.
For repos with many ADRs, organize by subdirectory:
docs/decisions/
backend/
2025-06-15-use-postgres.md
frontend/
2025-06-20-use-react.md
infrastructure/
2025-07-01-use-terraform.md
Date prefixes are local to each category. Choose a categorization scheme early (by layer, by domain, by team) and document it in the index.
scripts/new_adr.js — create a new ADR file from a template, using repo conventions.scripts/set_adr_status.js — update an ADR status in-place (YAML front matter or inline). Use --json for machine output.scripts/bootstrap_adr.js — create ADR dir, README.md, and initial "Adopt ADRs" decision.references/review-checklist.md — agent-readiness checklist for Phase 3 review.references/adr-conventions.md — directory, filename, status, and lifecycle conventions.references/template-variants.md — when to use simple vs MADR-style templates.references/examples.md — filled-out short and long ADR examples with implementation plans.assets/templates/adr-simple.md — lean template for straightforward decisions.assets/templates/adr-madr.md — MADR 4.0 template for decisions with multiple options and structured tradeoffs.assets/templates/adr-readme.md — default ADR index scaffold used by scripts/bootstrap_adr.js.From the target repo root:
# Simple ADR
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed
# MADR-style with options
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --template madr --status proposed
# With index update
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed --update-index
# Bootstrap a new repo
node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions
Notes:
--dir and --strategy to override.--json to emit machine-readable output.Weekly Installs
67
Repository
GitHub Stars
23.0K
First Seen
13 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
cursor64
github-copilot60
gemini-cli59
codex59
opencode58
kimi-cli58
超能力技能使用指南:AI助手技能调用优先级与工作流程详解
53,700 周安装
Apple Search Ads (ASA) 投放指南:从账户结构到出价策略的完整教程 | ASO专家必备
256 周安装
本地Whisper语音转文字工具 - 完全离线运行,支持多种模型和输出格式
109 周安装
虚荣工程审查:识别无价值代码与架构,降低维护成本,提升工程效率
63 周安装
PUA P7 骨干方案驱动执行:AI编程助手,遵循协议实现方案设计与代码审查
514 周安装
session-learner 智能代理技能 | AI会话学习与代码助手集成工具
120 周安装
Obsidian Agent Skill - 知识管理与笔记工具集成,提升AI助手工作效率
122 周安装
Find related code patterns. If the decision involves a specific area (e.g., "how we handle auth"), scan for existing implementations. Identify the specific files, directories, and patterns that will be affected by the decision.
Check for ADR references in code. Look for ADR references in comments and docs (see "Code ↔ ADR Linking" below). This reveals which existing decisions govern which parts of the codebase.
Note what you found. Carry this context into Phase 1 — it will sharpen your questions and prevent the ADR from contradicting existing decisions.
assets/templates/adr-madr.md when you need to document multiple options with structured pros/cons/drivers.references/template-variants.md for guidance.Fill every section from the confirmed intent summary. Do not leave placeholder text. Every section should contain real content or be removed (optional sections only).
Write the Implementation Plan. This is the most important section for agent-first ADRs. It tells the next agent exactly what to do. See the template for structure.
Write Verification criteria as checkboxes. These must be specific enough that an agent can programmatically or manually check each one.
Generate the file.
scripts/new_adr.js (handles directory, naming, and optional index updates).assets/templates/ and fill it manually.Respect the decisions. If an accepted ADR says "use PostgreSQL," don't propose switching to MongoDB without creating a new ADR that supersedes it. If you find a conflict between what the code does and what the ADR says, flag it to the human.
Follow the Implementation Plan. When implementing code in an area governed by an ADR, follow the patterns specified in its Implementation Plan. If the plan says "all new queries go through the data-access layer in src/db/," do that.
Reference ADRs in your work. Add ADR references in code comments and PR descriptions (see "Code ↔ ADR Linking" below).