adr-decision-extraction

ADR 决策提取

从对话上下文中提取架构决策，用于生成 ADR。

检测信号

信号类型	示例
显式标记	[ADR]、“decided:”、“the decision is”
选择模式	“let's go with X”、“we'll use Y”、“choosing Z”
权衡讨论	“X vs Y”、“pros/cons”、“considering alternatives”
问题—解决方案对	“the problem is... so we'll...”

提取规则

显式标签（保证纳入）

标记为 [ADR] 的文本始终会被提取：

[ADR] Using PostgreSQL for user data storage due to ACID requirements

这些内容会自动获得 confidence: "high"。

AI 检测的决策

未使用显式标签检测到的模式需要评估置信度：

置信度	标准
high	清楚说明选择并给出理由
medium	根据已采取的行动推断出决策
low	基于上下文推断，可能需要核实

输出格式

{
  "decisions": [
    {
      "title": "Use PostgreSQL for user data",
      "problem": "Need ACID transactions for financial records",
      "chosen_option": "PostgreSQL",
      "alternatives_discussed": ["MongoDB", "SQLite"],
      "drivers": ["ACID compliance", "team familiarity"],
      "confidence": "high",
      "source_context": "Discussion about database selection in planning phase"
    }
  ]
}

字段定义

字段	必填	描述
title	是	简洁的决策摘要
problem	是	推动该决策的问题或背景
chosen_option	是	选定的解决方案或方法
alternatives_discussed	否	提及的其他选项（若无则为空数组）
drivers	否	影响决策的因素
confidence	是	high、medium 或 low
source_context	否	对决策出现位置的简要说明

提取工作流

1. 扫描显式标记 — 查找所有带 [ADR] 标签的内容
2. 识别选择模式 — 查找决策相关表述
3. 提取权衡讨论 — 记录备选方案和理由
4. 评估置信度 — 为每项非显式决策评级
5. 记录上下文 — 记录周边讨论，供 ADR 撰写者参考

硬性门槛

完成上述工作流后、返回输出前，按顺序执行以下步骤。每一步都有客观的通过条件。

1. 显式 [ADR] 清单 — 从完整源文本中捕获每个 [ADR] 片段（在工作笔记中逐字记录）。**通过条件：**再次检查同一源文本时，没有发现新的 [ADR] 区块。
2. 去重 — 合并或删除重复显式 [ADR] 决策的推断条目（参见合并相关决策）。**通过条件：**每个不同决策最多对应一个条目。
3. 架构校验 — 序列化后的 JSON 符合输出格式和字段定义。**通过条件：**解析成功；每个 decisions[] 项的 title、problem、chosen_option 均非空；confidence ∈ {high,medium,low}；alternatives_discussed 为数组（没有备选方案时使用 []）；其他可选字段符合表格要求。
4. 低置信度审查 — 对于任何 confidence: "low"，source_context 都应说明缺失、薄弱或矛盾之处。**通过条件：**读者可以看出评级为何没有更高。

模式示例

高置信度

"We decided to use Redis for caching because of its sub-millisecond latency
and native TTL support. Memcached was considered but lacks persistence."

提取结果：

• 标题：使用 Redis 进行缓存
• 问题：需要具备 TTL 的快速缓存
• 选择：Redis
• 备选方案：Memcached
• 推动因素：亚毫秒级延迟、原生 TTL、持久化
• 置信度：high

中置信度

"Let's go with TypeScript for the frontend since we're already using it
in the backend."

提取结果：

• 标题：前端使用 TypeScript
• 问题：前端语言选择
• 选择：TypeScript
• 备选方案：（未说明）
• 推动因素：与后端保持一致
• 置信度：medium

低置信度

"The API seems to be working well with REST endpoints."

提取结果：

• 标题：REST API 架构
• 问题：API 设计方法
• 选择：REST
• 备选方案：（未说明）
• 推动因素：（未说明）
• 置信度：low

最佳实践

捕获上下文

始终捕获足够的上下文，供 ADR 撰写者参考：

• 讨论的主题是什么？
• 有哪些人参与（如果已知）？
• 是什么促成了这项决策？

合并相关决策

如果多条陈述涉及同一项决策，请将它们合并：

• 汇总不同提及中的备选方案
• 汇总推动因素
• 使用最高置信度

标记歧义

当决策不明确或相互矛盾时：

• 在 source_context 中注明歧义
• 将置信度设为 low
• 如果存在多种解读，请全部列出

何时使用此技能

• 分析会话记录以生成 ADR
• 审查对话历史以编写文档
• 从设计讨论中提取决策
• 为 ADR 编写工具准备输入