Write ADR
Generate Architecture Decision Records (ADRs) from decisions made during the current session.
Workflow Overview
- 1. 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
CODEBLOCK0
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:
CODEBLOCK1
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:
CODEBLOCK2
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 - INLINECODE2 or empty - Skip with message "No ADRs will be created."
- INLINECODE3 or
"1-2" - Process specified decisions
Step 4: Write ADRs (Parallel)
Pre-allocate ADR numbers before launching subagents to prevent numbering conflicts:
CODEBLOCK3
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:
CODEBLOCK4 json
{decision JSON}
CODEBLOCK5
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:
CODEBLOCK6
If no decisions were processed:
CODEBLOCK7
Step 6: Verify Generated ADRs
For each created ADR, validate against Definition of Done:
CODEBLOCK8
Verification steps:
- 1. Open each generated ADR file
- Confirm filename follows
NNNN-slugified-title.md pattern - 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
- 4. 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
draft until gaps are resolved - Use
[INVESTIGATE] prompts to guide follow-up session - Schedule review with stakeholders before changing to INLINECODE14
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
CODEBLOCK9
Write ADR
根据当前会话期间做出的决策生成架构决策记录（ADR）。
工作流程概览
- 1. 上下文 - 收集仓库上下文和现有 ADR
- 提取 - 使用子代理分析对话中的决策
- 确认 - 向用户展示决策供选择
- 编写 - 使用子代理并行生成 ADR
- 报告 - 汇总创建的文件和状态
- 验证 - 根据完成标准验证生成的 ADR
步骤 1：收集上下文
bash
获取当前分支和最近提交
git branch --show-current
git log --oneline -5
检查现有 ADR
ls docs/adrs/ 2>/dev/null || echo 未找到 ADR 目录
统计现有 ADR 数量用于编号
find docs/adrs -name *.md 2>/dev/null | wc -l
此上下文帮助 ADR 编写者：
- - 在 ADR 中引用相关提交
- 避免为已记录的决策创建重复 ADR
- 确定正确的序列编号
步骤 2：提取决策
启动子代理分析当前会话中的架构决策：
text
Task(
description: 分析对话并提取架构决策,
model: sonnet,
prompt: |
加载技能：Skill(skill: beagle-analysis:adr-decision-extraction)
分析对话中需要 ADR 的决策：
- 技术选择、架构模式、设计权衡
- 被拒绝的备选方案、重要的实现方法
返回 JSON：
{
decisions: [
{
id: 1,
title: 使用 PostgreSQL 作为主数据存储,
context: 关于为何出现此问题的简要上下文,
decision: 已决定的内容,
alternatives: [已考虑但被拒绝的方案],
rationale: 做出此选择的原因
}
]
}
)
如果子代理返回空的 decisions 数组，则跳至步骤 5，并显示消息：本次会话未检测到架构决策。
步骤 3：与用户确认
显示所有提取的决策及其完整详情，然后请用户选择：
text
检测到的决策
1. 使用 PostgreSQL 作为主数据存储
置信度： 高
问题： 财务记录需要 ACID 事务
决策： 使用 PostgreSQL 存储用户数据
讨论过的备选方案：
理由： ACID 合规性、团队熟悉度、成熟生态系统
来源： 规划阶段关于数据库选择的讨论
2. 为审计追踪实现事件溯源
置信度： 中
问题： 合规性要求完整的审计历史
决策： 对状态变更采用事件溯源模式
讨论过的备选方案：
理由： 不可变审计追踪、时间查询、调试能力
来源： 合规性要求讨论
选择
我应该为哪些决策编写 ADR？
- - 输入数字（例如 1,2 或 1-2）、all 或 none 跳过
重要： 在请求选择之前，始终显示提取输出中的完整决策详情（问题、决策、备选方案、理由）。不要仅截取标题和上下文。
解析用户响应：
- - all - 处理所有决策
- none 或空 - 跳过并显示消息不会创建 ADR。
- 1,2 或 1-2 - 处理指定的决策
步骤 4：编写 ADR（并行）
在启动子代理之前预分配 ADR 编号，以防止编号冲突：
bash
为所有确认的决策预分配编号
示例：如果用户选择了 3 个决策
python skills/adr-writing/scripts/next
adrnumber.py --count 3
输出：
0003
0004
0005
在启动子代理之前，将每个预分配的编号分配给相应的决策。
对于每个确认的决策，在后台启动一个 ADR 编写子代理，并传入其预分配编号：
text
Task(
description: 为以下决策编写 ADR：{decision.title},
model: sonnet,
runinbackground: true,
prompt: |
加载技能：Skill(skill: beagle-analysis:adr-writing)
为此决策编写 ADR：
json
{decision JSON}
重要：使用此预分配的 ADR 编号：{assigned_number}
说明：
1. 探索代码库以获取额外上下文
2. 将 MADR 格式的 ADR 写入 docs/adr/
3. 使用预分配编号 {assignednumber} - 不要调用 nextadr_number.py
4. 文件名格式：{assigned_number}-slugified-title.md
5. 返回创建的文件路径
)
关键： 将预分配的编号传递给每个子代理。子代理不得自行调用 nextadrnumber.py - 这会导致并行运行时出现重复编号。
所有子代理并行运行。等待所有子代理完成后再继续。
步骤 5：报告结果
收集所有子代理的输出并呈现摘要：
markdown
ADR 生成完成
| 文件 | 决策 | 状态 |
|---|
| docs/adr/0003-use-postgresql.md | 使用 PostgreSQL 作为主数据存储 | 草稿 |
后续步骤
- - 检查生成的 ADR 的准确性
- 最终确定后将状态从提议更新为已接受
需要调查的差距
如果未处理任何决策：
text
未创建 ADR。在做出架构决策后再次运行此命令。
步骤 6：验证生成的 ADR
对于每个创建的 ADR，根据完成标准进行验证：
markdown
验证检查清单
| ADR | E | C | A | D | R | 状态 |
|---|
| 0003-use-postgresql.md | ✓ | ✓ | ✓ | ⚠ | ✗ | 不完整 |
图例：E=证据，C=标准，A=协议，D=文档，R=实现
验证步骤：
- 1. 打开每个生成的 ADR 文件
- 确认文件名遵循 NNNN-slugified-title.md 模式
- 验证文件开头存在 YAML 前置元数据：
- 文件必须以 --- 开头
- 包含 status: draft（或有效状态）
- 包含 date: YYYY-MM-DD（实际日期）
- 在标题前以 --- 结束
- 如果缺少前置元数据，立即添加
- 4. 检查 [INVESTIGATE] 提示 - 这些需要跟进
- 验证至少记录了 2 个备选方案
- 确认后果部分同时包含正面和负面项
如果存在差距：
- - 在差距解决前保持状态为 draft
- 使用 [INVESTIGATE] 提示指导后续会话
- 在将状态更改为 accepted 前安排与利益相关者审查
输出位置
ADR 写入 docs/adr/。如果 ADR 目录不存在，则创建该目录并附带初始的 0000-use-madr.md 模板记录。
MADR 格式参考
markdown
status: draft
date: YYYY-MM-DD
{标题}
上下文和问题陈述
{促使此决策的问题是什么？}
决策驱动因素
决策结果
选择的方案：{方案}，因为{原因}。
后果
