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] の決定を繰り返す推定項目を統合または削除します（関連する決定の統合を参照）。合格条件： 異なる決定ごとに最大 1 つの項目であること。
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 作成ツールに渡す入力を準備する