mcpField
A
architecture-decision-records

architecture-decision-records

github.com/wshobson开发41.9k22.9k 次安装2 周前更新
代码仓库

关于 architecture-decision-records

architecture-decision-records 用于创建和维护重要技术决策记录，帮助团队记录背景、选择、权衡、后果和状态，便于后续审阅与新成员了解。

主要功能

  1. 01ADR 内容与生命周期
  2. 02撰写时机判断
  3. 03决策目录与索引管理
  4. 04提案审查清单
  5. 05弃用与替代记录

适用场景

  1. 01记录架构技术选型
  2. 02说明设计权衡与后果
  3. 03向新团队成员介绍历史决策
  4. 04管理已弃用或被替代的决策

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wshobson/agents --skill architecture-decision-records

安装后在 Claude Code 中输入/architecture-decision-records确认已加载。

附带文件references/decision-templates.mdreferences/deprecation-rfc-templates.md

详细介绍

架构决策记录

关于创建、维护和管理架构决策记录（ADR）的全面模式，用于记录重大技术决策背后的背景和理由。

何时使用此技能

  • 做出重大的架构决策
  • 记录技术选型
  • 记录设计权衡
  • 帮助新团队成员熟悉项目
  • 回顾历史决策
  • 建立决策流程

核心概念

1. 什么是 ADR？

架构决策记录包含：

  • 背景：我们为什么需要做出决策
  • 决策：我们做出了什么决定
  • 后果：由此会产生什么结果
2. 何时编写 ADR
编写 ADR跳过 ADR
采用新框架小版本升级
选择数据库技术修复 Bug
API 设计模式实现细节
安全架构日常维护
集成模式配置变更
3. ADR 生命周期
Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected

在起草标准型、轻量型或 Y 声明 ADR 之前，请阅读决策模板。

在起草弃用 ADR 或 RFC 之前，请阅读弃用和 RFC 模板。

ADR 管理

目录结构
docs/
├── adr/
│   ├── README.md           # Index and guidelines
│   ├── template.md         # Team's ADR template
│   ├── 0001-use-postgresql.md
│   ├── 0002-caching-strategy.md
│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
│   └── 0020-deprecate-mongodb.md      # Supersedes 0003
ADR 索引（README.md）
# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for [Project Name].

## Index

| ADR                                   | Title                              | Status     | Date       |
| ------------------------------------- | ---------------------------------- | ---------- | ---------- |
| [0001](0001-use-postgresql.md)        | Use PostgreSQL as Primary Database | Accepted   | 2024-01-10 |
| [0002](0002-caching-strategy.md)      | Caching Strategy with Redis        | Accepted   | 2024-01-12 |
| [0003](0003-mongodb-user-profiles.md) | MongoDB for User Profiles          | Deprecated | 2023-06-15 |
| [0020](0020-deprecate-mongodb.md)     | Deprecate MongoDB                  | Accepted   | 2024-01-15 |

## Creating a New ADR

1. Copy `template.md` to `NNNN-title-with-dashes.md`
2. Fill in the template
3. Submit PR for review
4. Update this index after approval

## ADR Status

- **Proposed**: Under discussion
- **Accepted**: Decision made, implementing
- **Deprecated**: No longer relevant
- **Superseded**: Replaced by another ADR
- **Rejected**: Considered but not adopted
自动化（adr-tools）
# Install adr-tools
brew install adr-tools

# Initialize ADR directory
adr init docs/adr

# Create new ADR
adr new "Use PostgreSQL as Primary Database"

# Supersede an ADR
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"

# Generate table of contents (to a separate file, so the hand-written
# index and guidelines in README.md are not overwritten)
adr generate toc > docs/adr/toc.md

# Link related ADRs
adr link 2 "Complements" 1 "Is complemented by"

审查流程

## ADR Review Checklist

### Before Submission

- [ ] Context clearly explains the problem
- [ ] All viable options considered
- [ ] Pros/cons balanced and honest
- [ ] Consequences (positive and negative) documented
- [ ] Related ADRs linked

### During Review

- [ ] At least 2 senior engineers reviewed
- [ ] Affected teams consulted
- [ ] Security implications considered
- [ ] Cost implications documented
- [ ] Reversibility assessed

### After Acceptance

- [ ] ADR index updated
- [ ] Team notified
- [ ] Implementation tickets created
- [ ] Related documentation updated

最佳实践

应该做的事
  • 尽早编写 ADR - 在开始实现之前
  • 保持简短 - 最多 1-2 页
  • 如实说明权衡 - 包括真实的缺点
  • 关联相关决策 - 构建决策关系图
  • 更新状态 - 被取代时标记为弃用
不应该做的事
  • 不要更改已接受的 ADR - 编写新的 ADR 来取代它
  • 不要省略背景 - 未来的读者需要了解背景
  • 不要掩盖失败 - 被否决的决策也很有价值
  • 不要含糊其辞 - 决策要具体，后果也要具体
  • 不要忘记实施 - 没有行动的 ADR 毫无价值

评论

支持 Markdown