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.
安装
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
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ 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:
- 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:
* [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-DDwith 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 structurereferences/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
相关 Skills
主题工厂
by anthropics
给幻灯片、文档、报告和 HTML 落地页快速套用专业配色与字体主题,内置 10 套预设风格并支持现场生成新主题,适合统一品牌或内容视觉。
✎ 主题工厂能帮你把幻灯片、文档到落地页快速统一视觉风格,内置 10 套主题,还能按需即时生成新主题。
品牌规范
by anthropics
把文档、幻灯片等内容快速套用 Anthropic 官方品牌配色与字体规范,统一标题、正文和图形视觉风格,适合做品牌化排版、视觉润色和公司设计标准校准。
✎ 把文档、页面和素材快速套用 Anthropic 官方色彩与字体系,少翻设计手册也能稳稳保持统一品牌感。
文档共著
by anthropics
围绕文档、提案、技术规格、决策记录等写作任务,按上下文收集、结构迭代、读者测试三步协作共创,减少信息遗漏,写出更清晰、经得起他人阅读的内容。
✎ 写文档、方案或技术规格时容易思路散、信息漏,它用结构化共著流程帮你高效传递上下文、反复打磨内容,还能从读者视角做验证。
相关 MCP 服务
by nirholas
免费的加密新闻聚合 MCP,汇集 Bitcoin、Ethereum、DeFi、Solana 与 altcoins 资讯源。
by ProfessionalWiki
让 Large Language Model 客户端无缝连接任意 MediaWiki 站点,可创建、更新、搜索页面,并通过 OAuth 2.0 安全管理内容。
by transloadit
借助 86+ 个云端 media processing robots,处理视频、音频、图像和文档。