Appearance
Architecture Decision Records Skill（ADR Skill）为 Claude Code 等 AI 编程助手提供自动检测和记录架构决策的能力。它能在关键决策时机（如选型、架构权衡、API 设计等）主动提示并协助生成标准化 ADR 文档，详细涵盖决策背景、可选方案、取舍理由与影响，确保团队知识沉淀与决策透明，支持后续追溯和团队协作。Skill 可与 Planner、Code Reviewer 等 Agent 配合，自动发现遗漏的架构决策记录，是生产级 AI 辅助开发不可或缺的知识管理基石。
Everything Claude Code Architecture Decision Records Skill：自动检测架构决策时机并记录 ADR 含背景与备选方案
在现代 AI 辅助编程实践中，架构决策往往零散分布于 Slack、PR 评论、会议记录甚至团队成员的记忆中，难以追溯和复用。Everything Claude Code 的 Architecture Decision Records Skill（简称 ADR Skill），正是为了解决这一痛点：它能在 Claude Code 或 Cursor、Codex 等 AI 编程助手的实际开发流程中，自动检测架构决策时机，辅助开发者标准化记录决策背景、权衡过程、备选方案和最终结论，生成结构化的 ADR 文档并维护索引，极大提升团队的知识传承与决策透明度。
本指南将详细介绍 ADR Skill 的激活时机、使用流程、输出示例、与常见 Agent/Skill 的协作关系，以及实际项目中如何用好这一能力。
1. 这个 Skill 解决了什么问题？
传统做法的不足：
- 架构决策常被遗忘、口头传递或仅存于 PR 评论，难以系统追溯
- 新成员难以理解项目为何采用某种技术、模式或流程
- 反复讨论同一问题，浪费团队沟通成本
- 决策依据、权衡点、被否决的方案缺失，影响后续维护和演进
ADR Skill 的优势：
- 自动检测决策时机，主动提示记录，防止遗漏
- 以 Michael Nygard 轻量 ADR 格式标准化输出，便于阅读和维护
- 自动管理 ADR 目录和索引，支持增量维护与回溯
- 明确记录背景、备选方案、取舍理由与影响，方便后续查阅
- 支持与 Planner、Code Reviewer 等 Agent 协作，保障决策链完整
2. 触发条件：什么时候会自动提示或激活？
ADR Skill 通过分析用户输入和对话内容，捕捉如下典型信号：
显式信号（自动建议记录 ADR）
- 用户说“let's record this decision”“ADR this”“记录为 ADR”
- 明确表达“我们决定用 X 替代 Y”“我们之所以选 X 是因为...”
- 规划阶段主动讨论架构权衡
隐式信号（建议但不自动创建，需用户确认）
- 比较两个框架/库并做出选择
- 讨论数据库、架构模式、API 设计等有重大影响的决策
- 选择认证/授权方案、部署基础设施等
- 用户问“为什么我们选了 X？”（触发查阅 ADR）
Skill 会根据这些信号主动询问用户是否要记录为 ADR，绝不在未获同意时自动写入文件，保障开发流程的可控性。
3. 使用流程 Step by Step
3.1 新建 ADR 的完整流程
检测到决策时机
例如，在讨论“前端用 Next.js 还是 Nuxt.js”并做出选择时，Skill 自动提示：“检测到架构决策，是否记录为 ADR？”初始化目录（首次使用）
若docs/adr/目录不存在，Skill 会询问：“是否创建 ADR 目录和模板？”用户同意后，自动生成：docs/adr/README.md（含 ADR 索引表头）docs/adr/template.md（空白模板，供手动补充）
提取决策核心内容
Skill 引导用户补充/确认以下要素：- 决策标题（如“使用 Next.js 作为前端框架”）
- 决策背景（遇到的问题、约束、动因）
- 备选方案（每个方案的优缺点、被否决理由）
- 最终决策内容
- 影响与风险（正面/负面/风险及缓解）
分配编号并生成草稿
Skill 自动扫描现有 ADR，分配下一个编号（如0004），生成标准 ADR 草稿。用户确认并写入
草稿展示给用户，确认无误后，Skill 写入docs/adr/0004-xxx.md，并自动更新README.md索引。后续维护
若后续有决策被废弃或替换，可通过Status字段标记deprecated或superseded by ADR-XXXX，保持历史链路清晰。
示例输出（ADR 文档片段）
markdown
# ADR-0004: Use Next.js as frontend framework
**Date**: 2026-03-01
**Status**: accepted
**Deciders**: [Alice, Bob, Claude Code]
## Context
项目需要 SSR 支持，团队熟悉 React，目标是快速上线 MVP。Nuxt.js 虽然支持 Vue，但团队缺乏经验。
## Decision
采用 Next.js 作为前端框架，利用其 SSR 能力和丰富生态。
## Alternatives Considered
### Alternative 1: Nuxt.js
- **Pros**: Vue 生态，良好文档
- **Cons**: 团队不熟悉，迁移成本高
- **Why not**: 学习曲线不符合当前进度需求
### Alternative 2: Create React App
- **Pros**: 纯 React，配置简单
- **Cons**: 不支持 SSR
- **Why not**: 不满足 SEO 和首屏性能要求
## Consequences
### Positive
- 团队可快速开发上线
- 生态资源丰富
### Negative
- 未来如需切换到 Vue 需较大重构
### Risks
- Next.js 版本升级带来的兼容性风险，可通过锁定版本和测试缓解ADR 索引自动维护示例
markdown
| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-03-01 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-03-02 |3.2 查阅和追溯 ADR
- 用户问：“为什么我们选了 PostgreSQL？”
- Skill 检查
docs/adr/是否存在，若无则提示“本项目尚未记录 ADR，是否现在开始？” - 若已存在，自动检索
README.md索引，找到相关 ADR，提取并展示 Context 和 Decision 部分，便于快速理解历史决策。
4. 与 Agent/Skill 的协作关系
- Planner Agent
在功能规划或重构方案中，若涉及架构调整，Planner 会调用 ADR Skill，建议同步记录决策，防止遗漏。 - Code Reviewer Agent
审查 PR 时，若检测到架构层面变更但无对应 ADR，自动提醒补充，保障代码与决策文档一致。 - 与 Verification Loop Skill 等自动化流程结合
可在发布前自动检查 ADR 覆盖率，防止关键决策缺失文档。
5. 实践建议与常见场景
- 记录“选型、架构模式、API 设计、数据建模、基础设施、认证安全、测试体系、流程规范”等关键决策，避免琐碎内容（如变量命名）泛滥
- 每次有团队成员提出“我们为什么不用 X？”时，优先查阅 ADR，若无则补充
- 被废弃、替换的决策及时更新
Status字段并链向新 ADR，维护历史脉络 - ADR 文件保持简洁，2 分钟内可读完，重点突出“背景-权衡-结论-影响”
FAQ
Q: ADR Skill 会自动修改代码库吗？ A: 不会。Skill 仅在用户明确同意后才写入 docs/adr/ 相关文件，绝不自动更改代码或文档。
Q: 记录哪些决策最有价值？ A: 技术选型、架构模式、API 设计、数据建模、CI/CD、认证安全、测试体系等影响全局或长期维护的决策最值得记录。
Q: 团队已有部分历史决策未记录，如何补全？ A: 可手动补录历史 ADR，并在文档中注明原始决策日期，Skill 支持补录和后续维护。
通过引入 Architecture Decision Records Skill，AI 编程助手不仅提升了开发效率，更为团队决策透明、知识传承和后续维护打下坚实基础。推荐结合 Claude Code 完全指南 与 Planner Agent 等组件，打造高效、可追溯的 AI 辅助开发流程。