adr-writing

by anderskev

Write Architectural Decision Records following MADR template. Applies Definition of Done criteria, marks gaps for later completion. Use when generating ADR documents from extracted decisions.

3.7k内容与创意未扫描2026年3月23日

安装

claude skill add --url github.com/openclaw/skills/tree/main/skills/anderskev/adr-writing

文档

ADR Writing

Overview

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

Quick Reference

code
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  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):

bash
python scripts/next_adr_number.py

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

For parallel allocation (used by parent commands):

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

Step 2: Explore Context

Before writing, gather additional context:

  1. Related code - Find implementations affected by this decision
  2. Existing ADRs - Check docs/adrs/ for related or superseded decisions
  3. 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:

SectionSource
TitleDecision summary (imperative mood)
StatusAlways draft initially
ContextProblem statement, constraints
Decision DriversPrioritized requirements
Considered OptionsAll viable alternatives
Decision OutcomeChosen option with rationale
ConsequencesGood, bad, neutral impacts

Step 5: Apply Definition of Done

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

  • Explicit problem statement
  • Comprehensive options analysis
  • Actionable decision
  • Documented consequences
  • Reviewable by stakeholders

Step 6: Mark Gaps

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

markdown
* [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:

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

Full frontmatter template:

yaml
---
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:

code
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:

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

File Naming Convention

Format: NNNN-slugified-title.md

ComponentRule
NNNNZero-padded sequence number from script
-Separator
slugified-titleLowercase, hyphens, no special characters
.mdMarkdown 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

markdown
---
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

相关 Skills

主题工厂

by anthropics

Universal
热门

给幻灯片、文档、报告和 HTML 落地页快速套用专业配色与字体主题,内置 10 套预设风格并支持现场生成新主题,适合统一品牌或内容视觉。

主题工厂能帮你把幻灯片、文档到落地页快速统一视觉风格,内置 10 套主题,还能按需即时生成新主题。

内容与创意
未扫描109.6k

品牌规范

by anthropics

Universal
热门

把文档、幻灯片等内容快速套用 Anthropic 官方品牌配色与字体规范,统一标题、正文和图形视觉风格,适合做品牌化排版、视觉润色和公司设计标准校准。

把文档、页面和素材快速套用 Anthropic 官方色彩与字体系,少翻设计手册也能稳稳保持统一品牌感。

内容与创意
未扫描109.6k

文档共著

by anthropics

Universal
热门

围绕文档、提案、技术规格、决策记录等写作任务,按上下文收集、结构迭代、读者测试三步协作共创,减少信息遗漏,写出更清晰、经得起他人阅读的内容。

写文档、方案或技术规格时容易思路散、信息漏,它用结构化共著流程帮你高效传递上下文、反复打磨内容,还能从读者视角做验证。

内容与创意
未扫描109.6k

相关 MCP 服务

热门

免费的加密新闻聚合 MCP,汇集 Bitcoin、Ethereum、DeFi、Solana 与 altcoins 资讯源。

内容与创意
111

by ProfessionalWiki

让 Large Language Model 客户端无缝连接任意 MediaWiki 站点,可创建、更新、搜索页面,并通过 OAuth 2.0 安全管理内容。

内容与创意16 个工具
72

借助 86+ 个云端 media processing robots,处理视频、音频、图像和文档。

内容与创意
71

评论