生成ADR
write-adr
by anderskev
Generate ADRs from decisions made in the current session. Extracts decisions, confirms with user, writes MADR-formatted documents.
安装
claude skill add --url https://github.com/openclaw/skills文档
Write ADR
Generate Architecture Decision Records (ADRs) from decisions made during the current session.
Workflow Overview
- Context - Gather repository context and existing ADRs
- Extract - Analyze conversation for decisions using a subagent
- Confirm - Present decisions to user for selection
- Write - Generate ADRs in parallel using subagents
- Report - Summarize created files and status
- Verify - Validate generated ADRs against Definition of Done
Step 1: Gather Context
# Get current branch and recent commits
git branch --show-current
git log --oneline -5
# Check for existing ADRs
ls docs/adrs/ 2>/dev/null || echo "No ADR directory found"
# Count existing ADRs for numbering
find docs/adrs -name "*.md" 2>/dev/null | wc -l
This context helps the ADR writer:
- Reference related commits in the ADR
- Avoid duplicate ADRs for already-documented decisions
- Determine correct sequence numbering
Step 2: Extract Decisions
Launch a subagent to analyze the current conversation for architectural decisions:
Task(
description: "Analyze conversation and extract architectural decisions",
model: "sonnet",
prompt: |
Load the skill: Skill(skill: "beagle-analysis:adr-decision-extraction")
Analyze the conversation for decisions that warrant ADRs:
- Technology choices, architecture patterns, design trade-offs
- Rejected alternatives, significant implementation approaches
Return JSON:
{
"decisions": [
{
"id": 1,
"title": "Use PostgreSQL for primary datastore",
"context": "Brief context about why this came up",
"decision": "What was decided",
"alternatives": ["What was considered but rejected"],
"rationale": "Why this choice was made"
}
]
}
)
If the subagent returns an empty decisions array, skip to Step 5 with message: "No architectural decisions detected in this session."
Step 3: Confirm with User
Display all extracted decisions with full details, then ask user to select:
## Detected Decisions
### 1. Use PostgreSQL for primary datastore
**Confidence:** high
**Problem:** Need ACID transactions for financial records
**Decision:** PostgreSQL for user data storage
**Alternatives discussed:**
- MongoDB
- SQLite
**Rationale:** ACID compliance, team familiarity, mature ecosystem
**Source:** Discussion about database selection in planning phase
---
### 2. Implement event sourcing for audit trail
**Confidence:** medium
**Problem:** Compliance requires complete audit history
**Decision:** Event sourcing pattern for state changes
**Alternatives discussed:**
- Database triggers
- Application-level logging
**Rationale:** Immutable audit trail, temporal queries, debugging capability
**Source:** Compliance requirements discussion
---
## Selection
Which decisions should I write ADRs for?
- Enter numbers (e.g., "1,2" or "1-2"), "all", or "none" to skip
Important: Always display the full decision details (problem, decision, alternatives, rationale) from the extraction output BEFORE asking for selection. Do not truncate to just title and context.
Parse user response:
"all"- Process all decisions"none"or empty - Skip with message "No ADRs will be created.""1,2"or"1-2"- Process specified decisions
Step 4: Write ADRs (Parallel)
Pre-allocate ADR numbers before launching subagents to prevent numbering conflicts:
# Pre-allocate numbers for all confirmed decisions
# Example: If user selected 3 decisions
python skills/adr-writing/scripts/next_adr_number.py --count 3
# Output:
# 0003
# 0004
# 0005
Assign each pre-allocated number to its corresponding decision before launching subagents.
For each confirmed decision, launch an ADR Writer subagent in background with its pre-assigned number:
Task(
description: "Write ADR for: {decision.title}",
model: "sonnet",
run_in_background: true,
prompt: |
Load the skill: Skill(skill: "beagle-analysis:adr-writing")
Write an ADR for this decision:
```json
{decision JSON}
```
**IMPORTANT: Use this pre-assigned ADR number: {assigned_number}**
Instructions:
1. Explore codebase for additional context
2. Write MADR-formatted ADR to docs/adr/
3. Use the pre-assigned number {assigned_number} - DO NOT call next_adr_number.py
4. Filename format: {assigned_number}-slugified-title.md
5. Return created file path
)
Critical: Pass the pre-allocated number to each subagent. Subagents must NOT call next_adr_number.py themselves - this causes duplicate numbers when running in parallel.
All subagents run in parallel. Wait for all to complete before proceeding.
Step 5: Report Results
Collect outputs from all subagents and present summary:
## ADR Generation Complete
| File | Decision | Status |
|------|----------|--------|
| docs/adr/0003-use-postgresql.md | Use PostgreSQL for primary datastore | Draft |
### Next Steps
- Review generated ADRs for accuracy
- Update status from "proposed" to "accepted" when finalized
### Gaps Requiring Investigation
- [List any decisions where subagent noted missing context]
If no decisions were processed:
No ADRs were created. Run this command again after making architectural decisions.
Step 6: Verify Generated ADRs
For each created ADR, validate against Definition of Done:
## Verification Checklist
| ADR | E | C | A | D | R | Status |
|-----|---|---|---|---|---|--------|
| 0003-use-postgresql.md | ✓ | ✓ | ✓ | ⚠ | ✗ | Incomplete |
Legend: E=Evidence, C=Criteria, A=Agreement, D=Documentation, R=Realization
Verification steps:
- Open each generated ADR file
- Confirm filename follows
NNNN-slugified-title.mdpattern - Verify YAML frontmatter exists at file start:
- File MUST begin with
--- - Contains
status: draft(or valid status) - Contains
date: YYYY-MM-DD(actual date) - Ends with
---before title - If frontmatter is missing, add it immediately
- File MUST begin with
- Review for
[INVESTIGATE]prompts - these need follow-up - Verify at least 2 alternatives are documented
- Confirm consequences section has both Good and Bad items
If gaps exist:
- Keep status as
draftuntil gaps are resolved - Use
[INVESTIGATE]prompts to guide follow-up session - Schedule review with stakeholders before changing to
accepted
Output Location
ADRs are written to docs/adr/. If no ADR directory exists, create it with an initial 0000-use-madr.md template record.
MADR Format Reference
---
status: draft
date: YYYY-MM-DD
---
# {TITLE}
## Context and Problem Statement
{What is the issue motivating this decision?}
## Decision Drivers
* {driver 1}
* {driver 2}
## Decision Outcome
Chosen option: "{option}", because {reason}.
### Consequences
* Good, because {positive}
* Bad, because {negative}
相关 Skills
文档共著
by anthropics
围绕文档、提案、技术规格、决策记录等写作任务,按上下文收集、结构迭代、读者测试三步协作共创,减少信息遗漏,写出更清晰、经得起他人阅读的内容。
✎ 写文档、方案或技术规格时容易思路散、信息漏,它用结构化共著流程帮你高效传递上下文、反复打磨内容,还能从读者视角做验证。
内部沟通
by anthropics
按公司常用模板和语气快速起草内部沟通内容,覆盖 3P 更新、状态报告、领导汇报、项目进展、事故复盘、FAQ 与 newsletter,适合需要统一格式的团队沟通场景。
✎ 按公司偏好的模板快速产出状态汇报、领导更新和 FAQ,既省去反复改稿,也让内部沟通更统一、更专业。
平面设计
by anthropics
先生成视觉哲学,再落地成原创海报、艺术画面或其他静态设计,输出 .png/.pdf,强调构图、色彩与空间表达,适合需要高完成度视觉成品的场景。
✎ 做海报、插画或静态视觉稿时,用它能快速产出兼顾美感与版式的PNG/PDF成品,原创设计更省心,也更适合规避版权风险。
相关 MCP 服务
by nirholas
免费的加密新闻聚合 MCP,汇集 Bitcoin、Ethereum、DeFi、Solana 与 altcoins 资讯源。
by ProfessionalWiki
让 Large Language Model 客户端无缝连接任意 MediaWiki 站点,可创建、更新、搜索页面,并通过 OAuth 2.0 安全管理内容。
by alisaitteke
用于Adobe Photoshop自动化的MCP server,让AI assistants直接控制Photoshop。