adr-management

name	adr-management
description	架构决策记录管理工具。USE WHEN ADR, architecture decision record, 架构决策, decision log, decision tracking, 决策记录, 架构日志, decision record, architecture log, RFC. 提供ADR模板、生命周期管理、决策追踪、决策追溯能力。
implements	Architect
context	fork

Customization

Before executing, check for user customizations at: ~/.claude/skills/PAI/USER/SKILLCUSTOMIZATIONS/adr-management/

If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If this directory does not exist, proceed with skill defaults.

🚨 MANDATORY: Voice Notification (REQUIRED BEFORE ANY ACTION)

You MUST send this notification BEFORE doing anything else when this skill is invoked.

1. Send voice notification:

   curl -s -X POST http://localhost:8888/notify \
     -H "Content-Type: application/json" \
     -d '{"message": "Running ADR management workflow"}' \
     > /dev/null 2>&1 &
   

2. Output text notification:

   📋 Running the **adr-management** skill for [purpose]...
   

This is not optional. Execute this curl command immediately upon skill invocation.

adr-management Skill

架构决策记录(ADR)管理工具，用于记录、追踪和管理架构决策。

什么是ADR？

ADR (Architecture Decision Record) 是一种记录架构决策的文档格式。

ADR的核心要素

要素	描述
Title	决策标题
Status	提议/已接受/已废弃/已替代
Context	决策背景和问题
Decision	决策内容
Consequences	决策后果（好/坏/中立）

ADR生命周期

提议 (Proposed)
    ↓
评审 (Review)
    ↓
接受 (Accepted) ←→ 拒绝 (Rejected)
    ↓
实施 (Implemented)
    ↓
废弃 (Deprecated) / 替代 (Superseded)

Workflow Routing

Route to the appropriate workflow based on the request.

场景路由

场景	工作流	说明
新决策记录	Workflows/NewADR.md	创建新ADR
决策查询	Workflows/QueryADR.md	搜索历史决策
决策评审	Workflows/ReviewADR.md	评审待定ADR
决策更新	Workflows/UpdateADR.md	更新状态/废弃
决策索引	Workflows/IndexADR.md	生成索引目录
批量创建	Workflows/BulkADR.md	批量记录决策

ADR模板

标准模板 (MADR)

# ADR-XXX: [决策标题]

## Status
[Proposed | Accepted | Deprecated | Superseded]

## Date
[YYYY-MM-DD]

## Context
[需要决策的问题背景]

## Decision
[决策内容]

## Consequences
### Positive
- [正面后果1]

### Negative
- [负面后果1]

### Neutral
- [中性后果]

## Alternatives Considered
### Alternative 1: [方案名称]
- Pros: [优点]
- Cons: [缺点]

### Alternative 2: [方案名称]
- Pros: [优点]
- Cons: [缺点]

## Notes
[补充说明]

简化模板

# ADR-XXX: [决策标题]

**Status**: [状态]
**Date**: [日期]

## Context
[背景]

## Decision
[决策]

## Consequences
[后果]

详细模板 (Nygard风格)

# ADR XXX: [标题]

## Metadata

| Field | Value |
|-------|-------|
| Author | [Author] |
| Date | [YYYY-MM-DD] |
| Status | [Proposed | Accepted | Deprecated | Superseded] |
| Superseded by | [ADR-XXX] |
| Supersedes | [ADR-XXX] |

## Summary

One paragraph explaining the decision.

## Context

The issue motivating this decision and the context surrounding it.

## Decision

What is the change that we're proposing and/or doing.

## Rationale

The reasoning behind the decision. Include alternatives considered.

## Consequences

What becomes easier or more difficult because of this change.

### Positive
- ...

### Negative
- ...

### Neutral
- ...

## Implementation

How this decision will be implemented.

工作流详情

NewADR 工作流

创建新ADR的完整流程

步骤1: 识别决策
    └── 什么需要决策？背景是什么？

步骤2: 收集上下文
    └── 问题是什么？约束是什么？

步骤3: 评估方案
    └── 方案A/B/C对比

步骤4: 编写ADR
    └── 按模板填写

步骤5: 编号
    └── ADR-XXX 格式

步骤6: 存储
    └── 保存到决策记录库

QueryADR 工作流

查询历史决策

步骤1: 定义查询
    └── 关键词/日期/状态/系统

步骤2: 搜索
    └── 遍历ADR库

步骤3: 呈现结果
    └── 格式化输出

步骤4: 关联分析
    └── 找出相关决策链

ReviewADR 工作流

评审待定ADR

步骤1: 收集意见
    └── 收集各方观点

步骤2: 分析
    └── 风险/收益分析

步骤3: 决策
    └── 接受/拒绝/修改

步骤4: 更新状态
    └── 更新ADR状态

ADR 编号规则

编号格式

ADR-001
  ↑ ↑
  │ └── 序号 (001-999)
  └────── 前缀

序号规则

• 使用3位数字 (001, 002, ...)
• 永不重复
• 废弃的ADR保持原编号
• 被替代的ADR标注supersedes

前缀选项

前缀	用途
ADR	标准架构决策
ADRS	基础设施决策
ADRD	数据架构决策
ADRT	技术决策

ADR 目录结构

docs/
├── adr/
│   ├── index.md              # ADR索引
│   ├── status.md            # 状态说明
│   ├── template.md          # 模板
│   └── records/
│       ├── ADR-001-xxx.md
│       ├── ADR-002-xxx.md
│       └── ...

索引文件模板

# Architecture Decision Records Index

## Statistics
- Total: N
- Accepted: N
- Proposed: N
- Deprecated: N
- Superseded: N

## Records

| ID | Title | Status | Date |
|----|-------|--------|------|
| ADR-001 | [Title] | Accepted | YYYY-MM-DD |
| ADR-002 | [Title] | Proposed | YYYY-MM-DD |

## By Status

### Accepted
- [ADR-001](./records/ADR-001-xxx.md)

### Proposed
- [ADR-002](./records/ADR-002-xxx.md)

决策分类

常见决策类型

类型	描述	示例
架构风格	微服务/单体/分层	采用微服务架构
技术选型	语言/框架/数据库	使用PostgreSQL
集成模式	API/事件/MQ	采用事件驱动
基础设施	部署/监控/CI/CD	使用Kubernetes
流程	开发/部署/运维	实施GitFlow

输出格式

ADR 审查报告

# ADR 审查报告

## 待审查
| ID | Title | 提交者 | 日期 |
|----|-------|--------|------|
| ADR-001 | [Title] | [Author] | Date |

## 审查意见

### ADR-001
- **完整性**: ✅ 完整
- **清晰度**: ⚠️ 需要澄清
- **风险**: 中
- **建议**: [建议内容]

## 决策
- ADR-001: ✅ 接受
- ADR-002: ❌ 拒绝

集成模式

与architecture-design协作

## ADR管理流程

1. **架构设计**
   → architecture-design skill 完成方案设计

2. **方案评估**
   → 评估多个方案

3. **决策记录**
   → 本skill创建ADR

4. **C4建模**
   → c4-modeling skill 可视化

5. **形式验证** (关键系统)
   → formal-methods skill 验证

与formal-methods协作

## 决策验证流程

1. **架构决策**
   → 识别关键决策

2. **形式化建模**
   → formal-methods skill 建立模型

3. **验证**
   → Model Check验证

4. **ADR记录**
   → 本skill记录验证结果

使用示例

示例1: 记录技术选型决策

# ADR-001: 采用文件系统作为主要存储

**Status**: Accepted
**Date**: 2026-02-11
**Author**: PAI

## Context
SharedBrain需要选择存储方案。选项包括文件系统、SQLite、专用数据库。

## Decision
采用文件系统作为主要存储，具体为Markdown文件 + iCloud同步。

## Consequences
### Positive
- 简单直观，易于理解
- 版本控制友好
- iCloud零配置同步
- 离线可用

### Negative
- 查询能力弱
- 关系表达有限
- 并发冲突需手动处理

### Neutral
- 适合当前规模
- 可在未来迁移到数据库

示例2: 记录协议设计决策

# ADR-002: 采用Protocol状态机模式

**Status**: Accepted
**Date**: 2026-02-11

## Context
需要定义人-AI交互的模式。选项包括: 自由对话/固定流程/状态机。

## Decision
采用Protocol状态机模式，定义R/A/B/C/D/H六种协议状态。

## Consequences
### Positive
- 结构化程度高
- 易于理解和维护
- 支持复杂决策流程

### Negative
- 学习成本增加
- 灵活性降低

## Alternatives Considered
### Alternative 1: 自由对话
- Pros: 灵活
- Cons: 难以标准化

### Alternative 2: 固定流程
- Pros: 简单
- Cons: 无法处理复杂场景

质量标准

• 每个重大架构决策必须有ADR
• ADR必须包含Context、Decision、Consequences
• 决策状态必须保持更新
• 索引必须反映最新状态

工具支持

adr-tools

命令行ADR管理工具:

# 初始化ADR目录
adr init doc/adr

# 创建新ADR
adr new "采用文件系统存储"

# 接受ADR
adr accept 1

# 废弃ADR
adr deprecate 1

# 列出ADR
adr list

dotnet-adr

.NET ADR工具:

# 安装
dotnet tool install -g dotnet-adr

# 使用
adr new "决策标题"

资源

• ADR官网: https://adr.github.io/
• MADR模板: https://github.com/adr/madr
• Nygard模板: https://github.com/joelparkerhenderson/architecture-decision-record

---

工具: Markdown, adr-tools, dotnet-adr