写作 ADR

从当前会话中生成架构决策记录（ADRs）。

工作流程概览

1. 上下文收集 - 获取仓库上下文和现有的 ADR
2. 决策提取 - 使用子代理分析对话内容，识别决策
3. 用户确认 - 向用户展示提取出的决策并进行选择
4. 生成 ADR - 通过子代理并行生成 ADR
5. 结果报告 - 汇总生成的文件及状态
6. 验证 - 根据完成标准验证生成的 ADR

门禁条件（客观通过标准）

仅当满足通过条件时才可进入下一步。这些条件应可独立验证，无需依赖“内部已验证”。

第1步：收集上下文

# 获取当前分支和最近提交
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 中引用相关提交
• 避免重复记录已文档化的决策
• 确定正确的序列编号

第2步：提取决策

分析当前对话内容，识别可能需要撰写 ADR 的架构决策。如果代理支持子代理，则以单个提取子代理方式调用；否则，直接内联执行相同逻辑——输出一致。使用如下提示：

加载 **adr-decision-extraction** 技能 ([../adr-decision-extraction/SKILL.md](../adr-decision-extraction/SKILL.md))。

分析对话内容，识别需记录为 ADR 的决策：
- 技术选型、架构模式、设计权衡
- 被否决的备选方案、重要实现方法

返回 JSON 格式：
{
  "decisions": [
    {
      "id": 1,
      "title": "使用 PostgreSQL 作为主数据存储",
      "context": "关于该议题的简要背景",
      "decision": "最终决定的内容",
      "alternatives": ["曾考虑但被拒绝的选项"],
      "rationale": "选择该方案的原因"
    }
  ]
}

若子代理返回空的 decisions 数组，则跳至第5步，提示：“本次会话中未检测到架构决策。”

门禁条件：在进入第3步前，必须满足第2步的门禁条件。

第3步：与用户确认

显示所有提取出的决策及其完整细节，然后请求用户选择：

## 检测到的决策

### 1. 使用 PostgreSQL 作为主数据存储
**置信度：** 高

**问题背景：** 需要对财务记录支持 ACID 事务

**决策内容：** 使用 PostgreSQL 存储用户数据

**讨论过的备选方案：**
- MongoDB
- SQLite

**理由：** 支持 ACID，团队熟悉度高，生态成熟

**来源：** 规划阶段关于数据库选型的讨论

---

### 2. 采用事件溯源实现审计追踪
**置信度：** 中等

**问题背景：** 合规要求完整的审计历史

**决策内容：** 采用事件溯源模式记录状态变更

**讨论过的备选方案：**
- 数据库触发器
- 应用层日志

**理由：** 审计记录不可篡改，支持时间查询，便于调试

**来源：** 合规性要求讨论

---

## 选择

请指定要撰写 ADR 的决策：
- 输入编号（如“1,2”或“1-2”）、“all”表示全部，或“none”跳过

重要提示：在询问选择前，必须完整展示每个决策的详细信息（问题、决策、备选方案、理由），不得仅保留标题和上下文。

解析用户输入：

• "all" - 处理所有决策
• "none" 或空输入 - 跳过，提示：“不会创建 ADR。”
• "1,2" 或 "1-2" - 处理指定的决策

第4步：并行生成 ADR

在启动子代理前，预先分配 ADR 编号，防止编号冲突：

# 为所有确认的决策预分配编号（从仓库根目录执行）
# 示例：用户选择了3个决策
python plugins/beagle-analysis/skills/adr-writing/scripts/next_adr_number.py --count 3
# 输出：
# 0003
# 0004
# 0005

将每个预分配的编号对应到其对应的决策，再启动子代理。

门禁条件：在启动第一个 ADR 编写单元前，必须满足第4步的门禁条件。

针对每个确认的决策，使用其预分配的编号运行 ADR 编写单元。如果代理支持子代理，则并行启动每个决策的编写任务；否则，按顺序逐个生成——输出一致。使用如下提示：

加载 **adr-writing** 技能 ([../adr-writing/SKILL.md](../adr-writing/SKILL.md))。

为以下决策撰写 ADR：

{decision JSON}

**重要：使用以下预分配的 ADR 编号：{assigned_number}**

指令：
1. 查阅代码库获取额外上下文
2. 以 MADR 格式生成 ADR 至 docs/adrs/
3. 使用预分配编号 {assigned_number} —— **切勿调用 next_adr_number.py**
4. 文件名格式：{assigned_number}-slugified-title.md
5. 返回生成的文件路径

关键提醒：必须将预分配编号传递给每个编写单元。编写者**不得自行调用 next_adr_number.py**，否则在并行运行时会导致编号重复。

等待所有编写单元完成后，方可继续。

第5步：报告结果

门禁条件：构建摘要时，必须满足第5步的门禁条件（路径来自子代理输出；可选 test -f 检查）。

收集所有子代理的输出，生成总结：

## ADR 生成完成

| 文件 | 决策 | 状态 |
|------|------|------|
| docs/adrs/0003-use-postgresql.md | 使用 PostgreSQL 作为主数据存储 | 草稿 |

### 下一步
- 审查生成的 ADR 是否准确
- 最终确认后，将状态从“草稿”更新为“已接受”

### 需进一步调查的缺口
- [列出子代理指出缺少上下文的决策]

若无决策被处理：

未创建任何 ADR。请在做出架构决策后再次运行此命令。

第6步：验证生成的 ADR

对每个生成的 ADR 进行完成标准验证：

## 验证检查清单

| ADR | E | C | A | D | R | 状态 |
|-----|---|---|---|---|---|------|
| 0003-use-postgresql.md | ✓ | ✓ | ✓ | ⚠ | ✗ | 不完整 |

说明：E=证据，C=标准，A=共识，D=文档，R=实现

门禁条件：每个生成的 ADR 必须满足第6步的门禁条件。

验证步骤：

1. 打开每个生成的 ADR 文件
2. 确认文件名符合 NNNN-slugified-title.md 格式
3. 验证文件开头存在 YAML frontmatter：

- 文件必须以 --- 开头

- 包含 status: draft（或有效状态值）

- 包含 date: YYYY-MM-DD（实际日期）

- 在标题前以 --- 结束

- 若缺失 frontmatter，立即补全

1. 检查是否存在 [INVESTIGATE] 提示——这些需后续跟进
2. 确保至少记录了两个备选方案
3. 确认后果部分包含“优点”和“缺点”两项

若存在遗漏：

• 保持状态为 draft，直至问题解决
• 使用 [INVESTIGATE] 提示引导后续会话
• 在更改状态为 accepted 前，安排与相关方评审

输出位置

ADRs 保存在 docs/adrs/ 目录下（与 [adr-writing](../adr-writing/SKILL.md) 保持一致的命名规范）。若该目录不存在，需创建，并添加初始模板文件 0000-use-madr.md。

MADR 格式参考

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

# {标题}

## 上下文与问题陈述

{引发此决策的问题是什么？}

## 决策驱动因素

* {驱动因素1}
* {驱动因素2}

## 决策结果

选择项："{选项}"，因为 {原因}。

### 后果

* 优点：因为 {积极影响}
* 缺点：因为 {消极影响}