Write ADR

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

工作流程概览

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

第一步：收集上下文

# 获取当前分支和最近的提交
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
• 确保正确的序列编号

第二步：提取决策

启动子代理以分析当前对话，提取架构决策：

Task(
  description: "分析对话并提取架构决策",
  model: "sonnet",
  prompt: |
    Load the skill: Skill(skill: "beagle-analysis:adr-decision-extraction")

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

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

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

第三步：与用户确认

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

## 检测到的决策

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

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

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

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

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

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

---

### 2. 实施事件溯源以构建审计日志
**置信度：** 中等

**问题：** 合规要求保留完整的审计历史

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

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

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

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

---

## 选择

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

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

解析用户输入：

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

第四步：编写 ADR（并行）

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

# 为所有确认的决策预分配编号
# 示例：若用户选择了 3 个决策
python skills/adr-writing/scripts/next_adr_number.py --count 3
# 输出：
# 0003
# 0004
# 0005

将预分配的编号与对应决策一一对应后，再启动子代理。

针对每个确认的决策，启动一个后台运行的 ADR 编写子代理，并传入其预分配的编号：

Task(
  description: "为以下决策撰写 ADR：{decision.title}",
  model: "sonnet",
  run_in_background: true,
  prompt: |
    Load the skill: Skill(skill: "beagle-analysis:adr-writing")

    为该决策撰写 ADR：

{decision JSON}

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

    指令：
    1. 查看代码库获取额外上下文
    2. 以 MADR 格式编写 ADR 并保存至 docs/adr/
    3. 使用预分配编号 {assigned_number} —— 严禁调用 next_adr_number.py
    4. 文件命名格式：{assigned_number}-slugified-title.md
    5. 返回生成的文件路径
)

关键点： 必须向每个子代理传递预分配的编号。子代理不得自行调用 next_adr_number.py，否则在并行执行时会导致编号重复。

所有子代理并行运行。需等待全部完成后再继续下一步。

第五步：报告结果

收集所有子代理的输出，呈现汇总信息：

## ADR 生成完成

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

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

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

若未处理任何决策：

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

第六步：验证生成的 ADR

对每个生成的 ADR 进行完成标准检查：

## 验证检查清单

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

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

验证步骤：

1. 打开每个生成的 ADR 文件
2. 确认文件名符合 NNNN-短横线化标题.md 的格式
3. 验证 YAML frontmatter 是否存在于文件开头：

- 文件必须以 --- 开头

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

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

- 在标题前以 --- 结束

- 如果缺少 frontmatter，请立即补充

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

若发现缺失项：

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

输出位置

ADRs 保存在 docs/adr/ 目录下。如果该目录不存在，请创建并添加初始模板文件 0000-use-madr.md。

MADR 格式参考

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

# {标题}

## 背景与问题陈述

{是什么问题促使做出此决策？}

## 决策驱动因素

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

## 决策结果

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

### 后果

* 优点：因为 {积极影响}
* 缺点：因为 {负面后果}