ADR撰写工具：遵循MADR模板生成架构决策记录，自动化完整性检查

adr-writing by existential-birds/beagle

139 周安装量

46 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/existential-birds/beagle --skill adr-writing

方法论软件工程技术文档

🇨🇳中文介绍

ADR 撰写

概述

遵循 MADR 模板生成架构决策记录（ADRs），并进行系统性的完整性检查。

快速参考

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   序列      │ ──▶ │    探索      │ ──▶ │    填充     │
│  (获取下一个│     │  (上下文，   │     │  (模板      │
│    编号)    │     │   ADRs)      │     │   章节)     │
└─────────────┘     └──────────────┘     └─────────────┘
       │                                        │
       │                                        ▼
       │                                 ┌─────────────┐
       │                                 │    验证     │
       │                                 │  (DoD       │
       └─────────────────────────────────│   检查清单) │
                                         └─────────────┘

何时使用

从提取的需求中记录架构决策
将会议记录或讨论转换为正式的 ADRs
记录来自 PR 讨论的技术选择
根据设计文档创建决策记录

工作流程

步骤 1：获取序列号

如果已预先分配编号（例如，当从 /beagle:write-adr 调用且并行写入时）：

直接使用预先分配的编号

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 2：探索上下文

在撰写之前，收集额外的上下文信息：

相关代码 - 查找受此决策影响的实现
现有 ADRs - 检查 docs/adrs/ 目录中相关或被取代的决策
讨论来源 - 决策中引用的 PRs、issues 或文档

步骤 3：加载模板

加载 references/madr-template.md 以获取官方的 MADR 结构。

步骤 4：填充章节

根据您的决策数据填充每个章节：

章节	来源
标题	决策摘要（祈使语气）
状态	初始状态始终为 `draft`
上下文	问题陈述、约束条件
决策驱动因素	优先排序的需求
已考虑的选项	所有可行的替代方案
决策结果	选择的方案及其理由
后果	正面、负面、中立的影响

步骤 5：应用完成定义

加载 references/definition-of-done.md 并验证 E.C.A.D.R. 标准：

E xplicit - 明确的问题陈述
C omprehensive - 全面的选项分析
A ctionable - 可执行的决策
D ocumented - 记录在案的后果
R eviewable - 可供利益相关者审查

步骤 6：标记缺失项

对于无法根据现有数据填充的章节，插入调查提示：

* [INVESTIGATE: Review PR #42 discussion for additional drivers]
* [INVESTIGATE: Confirm with security team on compliance requirements]
* [INVESTIGATE: Benchmark performance of Option 2 vs Option 3]

这些提示标志着需要后续跟进的未完成章节。

步骤 7：写入文件

重要提示：每个 ADR 必须以 YAML 前言开始。

前言块是必需的，并且必须至少包含：

---
status: draft
date: YYYY-MM-DD
---

完整的前言模板：

---
status: draft
date: 2024-01-15
decision-makers: [alice, bob]
consulted: []
informed: []
---

验证： 在写入文件之前，请验证内容以 --- 开头，后跟有效的 YAML 前言。如果缺少前言，请在写入前添加。

保存到 docs/adrs/NNNN-slugified-title.md：

docs/adrs/0003-use-postgresql-for-user-data.md
docs/adrs/0004-adopt-event-sourcing-pattern.md
docs/adrs/0005-migrate-to-kubernetes.md

步骤 8：验证前言

写入后，确认文件：

第一行以 --- 开头
包含 status: draft（或其他有效状态）
包含 date: YYYY-MM-DD 及实际日期
在标题之前以 --- 结束前言

格式：NNNN-slugified-title.md

组件	规则
`NNNN`	来自脚本的零填充序列号
`-`	分隔符
`slugified-title`	小写，连字符，无特殊字符
`.md`	Markdown 扩展名

references/madr-template.md - 官方的 MADR 模板结构
references/definition-of-done.md - E.C.A.D.R. 质量标准

---
status: draft
date: 2024-01-15
decision-makers: [alice, bob]
---

# Use PostgreSQL for User Data Storage

## Context and Problem Statement

We need a database for user account data...

## Decision Drivers

* Data integrity requirements
* Query flexibility needs
* [INVESTIGATE: Confirm scaling projections with infrastructure team]

## Considered Options

* PostgreSQL
* MongoDB
* CockroachDB

## Decision Outcome

Chosen option: PostgreSQL, because...

## Consequences

### Good

* ACID compliance ensures data integrity

### Bad

* Requires more upfront schema design

### Neutral

* Team has moderate PostgreSQL experience

2026 年 1 月 20 日

🇺🇸English

ADR Writing

Overview

Generate Architectural Decision Records (ADRs) following the MADR template with systematic completeness checking.

Quick Reference

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  SEQUENCE   │ ──▶ │   EXPLORE    │ ──▶ │    FILL     │
│  (get next  │     │  (context,   │     │  (template  │
│   number)   │     │   ADRs)      │     │   sections) │
└─────────────┘     └──────────────┘     └─────────────┘
       │                                        │
       │                                        ▼
       │                                 ┌─────────────┐
       │                                 │   VERIFY    │
       │                                 │  (DoD       │
       └─────────────────────────────────│   checklist)│
                                         └─────────────┘

When To Use

Documenting architectural decisions from extracted requirements
Converting meeting notes or discussions to formal ADRs
Recording technical choices from PR discussions
Creating decision records from design documents

Workflow

Step 1: Get Sequence Number

If a number was pre-assigned (e.g., when called from /beagle:write-adr with parallel writes):

Use the pre-assigned number directly
Do NOT call the script - this prevents duplicate numbers in parallel execution

If no number was pre-assigned (standalone use):

python scripts/next_adr_number.py

This outputs the next available ADR number (e.g., 0003).

For parallel allocation (used by parent commands):

python scripts/next_adr_number.py --count 3
# Outputs: 0003, 0004, 0005 (one per line)

Step 2: Explore Context

Before writing, gather additional context:

Related code - Find implementations affected by this decision
Existing ADRs - Check docs/adrs/ for related or superseded decisions
Discussion sources - PRs, issues, or documents referenced in decision

Step 3: Load Template

Load references/madr-template.md for the official MADR structure.

Step 4: Fill Sections

Populate each section from your decision data:

Section	Source
Title	Decision summary (imperative mood)
Status	Always `draft` initially
Context	Problem statement, constraints
Decision Drivers	Prioritized requirements
Considered Options	All viable alternatives
Decision Outcome	Chosen option with rationale
Consequences	Good, bad, neutral impacts

Step 5: Apply Definition of Done

Load references/definition-of-done.md and verify E.C.A.D.R. criteria:

E xplicit problem statement
C omprehensive options analysis
A ctionable decision
D ocumented consequences
R eviewable by stakeholders

Step 6: Mark Gaps

For sections that cannot be filled from available data, insert investigation prompts:

* [INVESTIGATE: Review PR #42 discussion for additional drivers]
* [INVESTIGATE: Confirm with security team on compliance requirements]
* [INVESTIGATE: Benchmark performance of Option 2 vs Option 3]

These prompts signal incomplete sections for later follow-up.

Step 7: Write File

IMPORTANT: Every ADR MUST start with YAML frontmatter.

The frontmatter block is REQUIRED and must include at minimum:

---
status: draft
date: YYYY-MM-DD
---

Full frontmatter template:

---
status: draft
date: 2024-01-15
decision-makers: [alice, bob]
consulted: []
informed: []
---

Validation: Before writing the file, verify the content starts with --- followed by valid YAML frontmatter. If frontmatter is missing, add it before writing.

Save to docs/adrs/NNNN-slugified-title.md:

docs/adrs/0003-use-postgresql-for-user-data.md
docs/adrs/0004-adopt-event-sourcing-pattern.md
docs/adrs/0005-migrate-to-kubernetes.md

Step 8: Verify Frontmatter

After writing, confirm the file:

Starts with --- on the first line
Contains status: draft (or other valid status)
Contains date: YYYY-MM-DD with actual date
Ends frontmatter with --- before the title

File Naming Convention

Format: NNNN-slugified-title.md

Component	Rule
`NNNN`	Zero-padded sequence number from script
`-`	Separator
`slugified-title`	Lowercase, hyphens, no special characters
`.md`	Markdown extension

Reference Files

references/madr-template.md - Official MADR template structure
references/definition-of-done.md - E.C.A.D.R. quality criteria

Output Example

---
status: draft
date: 2024-01-15
decision-makers: [alice, bob]
---

# Use PostgreSQL for User Data Storage

## Context and Problem Statement

We need a database for user account data...

## Decision Drivers

* Data integrity requirements
* Query flexibility needs
* [INVESTIGATE: Confirm scaling projections with infrastructure team]

## Considered Options

* PostgreSQL
* MongoDB
* CockroachDB

## Decision Outcome

Chosen option: PostgreSQL, because...

## Consequences

### Good

* ACID compliance ensures data integrity

### Bad

* Requires more upfront schema design

### Neutral

* Team has moderate PostgreSQL experience

Weekly Installs

115

Repository

existential-birds/beagle

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex96

opencode95

gemini-cli89

claude-code85

github-copilot82

cursor78

站立会议模板：敏捷开发每日站会指南与工具（含远程团队异步模板）

10,500 周安装