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.

•

Send voice notification:

bash

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

•

Output text notification:

code

📋 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生命周期

code

提议 (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)

markdown

# 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
[补充说明]

简化模板

markdown

# ADR-XXX: [决策标题]

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

## Context
[背景]

## Decision
[决策]

## Consequences
[后果]

详细模板 (Nygard风格)

markdown

# 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的完整流程

code

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

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

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

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

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

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

QueryADR 工作流

查询历史决策

code

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

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

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

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

ReviewADR 工作流

评审待定ADR

code

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

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

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

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

ADR 编号规则

编号格式

code

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

序号规则

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

前缀选项

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

ADR 目录结构

code

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

索引文件模板

markdown

# 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 审查报告

markdown

# ADR 审查报告

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

## 审查意见

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

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

集成模式

与architecture-design协作

markdown

## ADR管理流程

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

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

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

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

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

与formal-methods协作

markdown

## 决策验证流程

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

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

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

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

使用示例

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

markdown

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

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

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

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

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

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

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

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

markdown

# 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管理工具:

bash

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

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

# 接受ADR
adr accept 1

# 废弃ADR
adr deprecate 1

# 列出ADR
adr list

dotnet-adr

.NET ADR工具:

bash

# 安装
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