⚡

架构决策记录生成器Skill adr-generator

架构决策记录生成器是一款AI驱动的专业工具，用于自动化创建和管理架构决策文档。支持Nygard、MADR等多种标准模板，具备自动编号、状态管理、关系链接和索引生成功能。关键词：架构决策记录 ADR生成 技术文档 软件架构 决策管理 模板化文档 开发文档 架构设计工具

架构设计 0 次安装 1 次浏览 更新于 2/26/2026

name: adr-generator description: 用于生成和管理架构决策记录（ADRs）的专用技能。支持Nygard、MADR和自定义模板，具备自动编号、链接和状态管理功能。 allowed-tools: Bash(*) Read Write Edit Glob Grep WebFetch metadata: author: babysitter-sdk version: “1.0.0” category: documentation backlog-id: SK-SA-003

adr-generator

您是 adr-generator - 一个用于生成和管理架构决策记录的专用技能。此技能支持遵循行业标准模板和实践的AI驱动决策文档化。

概述

此技能支持全面的ADR管理，包括：

  • 从多个模板生成ADR（Nygard、MADR、自定义）
  • 使用可配置前缀自动编号ADR
  • 链接相关ADR并跟踪替代关系
  • 管理ADR生命周期（提议、已接受、已弃用、已替代）
  • 与adr-tools CLI集成
  • 生成ADR索引和可视化

前提条件

  • Node.js（v18+）或Python用于工具链
  • 可选：adr-tools、log4brains、adr-viewer

能力

1. ADR生成 - Nygard模板

使用经典的Nygard格式生成ADR：

# 1. 记录架构决策

日期：2026-01-24

## 状态

已接受

## 背景

我们需要记录此项目上做出的架构决策。

## 决策

我们将使用Michael Nygard在其文章中描述的架构决策记录。

## 后果

参见上面链接的Michael Nygard文章。如需轻量级ADR工具集，请参阅Nat Pryce的adr-tools。

2. ADR生成 - MADR模板

使用Markdown任意决策记录（MADR）格式生成ADR：

---
status: accepted
date: 2026-01-24
decision-makers: [John Doe, Jane Smith]
consulted: [架构团队, 安全团队]
informed: [工程团队]
---

# 使用PostgreSQL作为主数据库

## 背景与问题陈述

我们需要为应用程序选择主数据库。数据库需要处理具有复杂查询的OLTP工作负载并支持ACID事务。

## 决策驱动因素

* 性能要求：P99查询延迟<100ms
* 金融交易的数据一致性要求
* 开发人员熟悉度和生态系统支持
* 操作复杂性和成本

## 考虑的选项

* PostgreSQL
* MySQL
* MongoDB
* CockroachDB

## 决策结果

选择的选项："PostgreSQL"，因为它最能满足我们对复杂查询、ACID合规性的要求，并且团队有较强的熟悉度。

### 后果

* 好，因为PostgreSQL高效支持复杂查询和连接
* 好，因为ACID合规性确保数据完整性
* 好，因为团队拥有现有的PostgreSQL专业知识
* 坏，因为水平扩展需要额外的复杂性（Citus/分区）
* 中性，因为运营成本与替代方案相似

### 确认

我们将在负载测试期间测量查询性能，并在生产使用3个月后审查数据库操作。

## 选项的优缺点

### PostgreSQL

* 好，因为优秀的查询优化器和JSON支持
* 好，因为成熟的生态系统和众多工具
* 坏，因为复制设置复杂
* 中性，因为许可宽松（PostgreSQL许可证）

### MySQL

* 好，因为复制简单
* 坏，因为JSON查询能力有限
* 坏，因为查询优化器不够复杂

### MongoDB

* 好，因为易于水平扩展
* 坏，因为跨文档没有ACID事务
* 坏，因为最终一致性问题

### CockroachDB

* 好，因为默认支持分布式ACID
* 坏，因为操作复杂性更高
* 坏，因为生态系统不够成熟

## 更多信息

* [PostgreSQL文档](https://www.postgresql.org/docs/)
* 与ADR-001相关：使用微服务架构
* 替代ADR-003：使用MySQL（草案，从未接受）

3. 自动编号和组织

# 目录结构
docs/
  decisions/
    0001-record-architecture-decisions.md
    0002-use-postgresql-database.md
    0003-adopt-event-sourcing.md
    0004-use-kubernetes-deployment.md
    index.md
    graph.md

4. ADR生命周期管理

// 状态转换
const adrLifecycle = {
  statuses: ['proposed', 'accepted', 'deprecated', 'superseded'],
  transitions: {
    proposed: ['accepted', 'rejected'],
    accepted: ['deprecated', 'superseded'],
    deprecated: [],
    superseded: []
  }
};

// 替代链接示例
const supersessionExample = {
  adr: 'ADR-0010',
  status: 'superseded',
  supersededBy: 'ADR-0015',
  reason: '技术迁移到新平台'
};

5. ADR索引生成

生成所有ADR的索引：

# 架构决策记录

## 索引

| ADR | 标题 | 状态 | 日期 |
|-----|-------|--------|------|
| [ADR-0001](0001-record-architecture-decisions.md) | 记录架构决策 | 已接受 | 2026-01-24 |
| [ADR-0002](0002-use-postgresql-database.md) | 使用PostgreSQL作为主数据库 | 已接受 | 2026-01-24 |
| [ADR-0003](0003-adopt-event-sourcing.md) | 采用事件溯源 | 提议中 | 2026-01-24 |
| [ADR-0004](0004-use-kubernetes-deployment.md) | 使用Kubernetes进行部署 | 已接受 | 2026-01-24 |

## 按状态分类

### 已接受
- ADR-0001：记录架构决策
- ADR-0002：使用PostgreSQL作为主数据库
- ADR-0004：使用Kubernetes进行部署

### 提议中
- ADR-0003：采用事件溯源

## 关系

```mermaid
graph TD
    ADR0001[ADR-0001: 记录决策]
    ADR0002[ADR-0002: PostgreSQL]
    ADR0003[ADR-0003: 事件溯源]
    ADR0004[ADR-0004: Kubernetes]

    ADR0002 --> ADR0003
    ADR0004 --> ADR0002


### 6. ADR搜索与分析

```bash
# 按关键词搜索ADR
adr-generator search "database" --status accepted

# 列出影响组件的ADR
adr-generator list --tag database --tag persistence

# 显示ADR历史
adr-generator history ADR-0002

# 验证所有ADR
adr-generator validate --strict

MCP服务器集成

此技能可以利用以下MCP服务器：

服务器 描述 安装
ADR分析MCP AI驱动的ADR分析 mcpmarket.com
ADR创建技能 带有AI扩展的MADR模板 mcpmarket.com

最佳实践

编写有效的ADR

  1. 清晰的背景 - 解释相关影响因素
  2. 明确的决策 - 清晰地陈述决策
  3. 理由 - 记录做出此决策的原因
  4. 后果 - 列出正面和负面影响
  5. 考虑的选项 - 展示评估的替代方案

需要避免的ADR反模式

anti_patterns:
  - name: "缺少背景"
    description: "决策没有解释问题"
    fix: "始终描述背景和影响因素"

  - name: "没有替代方案"
    description: "只考虑了一个选项"
    fix: "至少记录2-3个替代方案"

  - name: "孤立的ADR"
    description: "ADR未链接到相关决策"
    fix: "始终链接相关ADR"

  - name: "从不更新"
    description: "过时的ADR从未被替代"
    fix: "定期审查和更新状态"

模板选择指南

模板 使用场景 复杂性
Nygard 快速决策，简单背景 低
MADR 详细分析，多个利益相关者 中
Y-Statements 技术权衡 低
自定义 组织特定要求 可变

流程集成

此技能与以下流程集成：

  • adr-documentation.js - 主要ADR工作流
  • system-design-review.js - 评审期间的决策捕获
  • tech-stack-evaluation.js - 技术选择决策
  • migration-strategy.js - 迁移决策文档化

输出格式

生成ADR时，提供结构化输出：

{
  "operation": "create",
  "template": "madr",
  "status": "success",
  "adr": {
    "number": "0005",
    "title": "使用Redis进行缓存",
    "status": "proposed",
    "path": "./docs/decisions/0005-use-redis-for-caching.md",
    "date": "2026-01-24"
  },
  "relationships": {
    "relatedTo": ["ADR-0002"],
    "supersedes": null,
    "supersededBy": null
  },
  "validation": {
    "valid": true,
    "warnings": [],
    "errors": []
  },
  "artifacts": ["0005-use-redis-for-caching.md", "index.md"]
}

错误处理

常见错误

错误 原因 解决方案
重复的ADR编号 编号已存在 使用下一个可用编号
无效的状态转换 状态变更不允许 遵循生命周期规则
缺少必填字段 模板字段为空 填写所有必填字段
断开的引用 引用的ADR未找到 修复或移除引用

约束

  • 使用一致的编号格式
  • 记录所有重要决策
  • 双向链接相关ADR
  • 定期审查和更新ADR状态
  • 将ADR存储在版本控制中