| name | tech-decision-adr |
| description | 作成手順「tech-decision-adr」(self-evolving-agent から自動同期): 技術判断ドキュメント(ADR)作成手順 |
技術判断ドキュメント(ADR)作成手順
用途: チームの技術判断(アーキテクチャ・ライブラリ選定・設計方針・運用方式)を構造化記録するとき。workspace/adr-YYYYMMDD-[トピック略称].md に作成。所要 30〜60 分。
Step 0:ADR を書くかどうかの判断(15 秒)
以下のいずれか 1 つに当てはまる → 書く。それ以外 → PR コメント・口頭で十分。
- 複数選択肢があり、選択で 2 週間以上の工数差が生じる(モジュール分割方針・テスト基盤選定 等)
- チーム複数人が関与し、後から「なぜそう決めたか」を問われる可能性がある
- 過去に同じ議論が出た/今後再燃しそう
- 外部ステークホルダー(PM・電通等)の判断に影響する技術選択
省略可: 1 ファイル・1 関数の実装詳細/ベストプラクティスが 1 つしかない当然の選択/即合意できた小さな方針変更。
Step 1:メタデータ冒頭表
| 項目 | 値 |
|---|
| プロジェクト/モジュール | [対象範囲] |
| 論点 | [「〇〇 vs 〇〇」で 1 行] |
| 作成日 | [今日の日付] |
| 委任度 | Andy 決定 / チーム提案・Andy 承認 / チーム決定(後報) |
| ステータス | 草案 / レビュー中 / 決定済み / 廃止 |
| 決定期限 | [YYYY-MM-DD — なぜその日までか 1 行](Lesson C:平日確認) |
委任度の 3 分類(EM として使い分ける): Andy 決定=アーキ全体・チームパターン変更・外部影響あり/チーム提案・Andy 承認=実装詳細・モジュール内設計で Andy はゲート/チーム決定(後報)=影響限定でチーム自律、ADR は事後報告。
Step 2:TL;DR(推奨を 2〜3 行)
「何を選んだか+なぜ+前提が変わる条件」を冒頭に置き、長文前に判断できるようにする。
Step 3:前提・制約の整理
フェーズ/状況・最優先事項(犠牲にできないもの)・チームリソース・時間制約・技術スタック制約を表で明示。「なぜそこまで慎重にしたか」を後から復元可能にする。
Step 4:評価軸と重みの設定
案を評価する前に「何を基準に比べるか」を合意し、各軸に重み(⭐⭐⭐〜⭐)と重み付けの根拠 1 行を付ける。順序が逆だと「決めた後に理由を作る」になる。EM 頻出軸:本番安定性・チームスキル親和性・長期保守コスト・今期工数負荷・外部依存/ロックイン・テスト容易性。
Step 5:選択肢のトレードオフ
各案を評価軸ごとに ✅/⚠️/❌+根拠 1 行で評価し、最後に「本質的な問題/強み」を 2〜3 文で言語化(評価表の要約でなく採否の核心)。
Step 6:推奨と根拠 —— 却下した理由を必ず書く(最重要)
採用案の説明より「なぜ他を選ばなかったか」の方が価値が高い。これがないと数ヶ月後に同じ議論が再燃する。各却下案について「長期的には良いが現在の制約 X のため今は採れない」等の具体的根拠を書く。
Step 7:リスクと対策+再検討トリガー
リスク/深刻度(🔴🟡🟢)/対策を表に。再検討トリガーを最低 1 件必須(例「工数が想定の 2 倍超」「2 人以上が実装困難と報告」)。制約で見送った案は、その制約が消えたときの再検討条件とセットで残す。
Step 8:次アクション(担当/期限/優先度)
空欄禁止。不明は [未定] プレースホルダー。
Step 9:ステークホルダーへの共有方法(EM 固有)
対象(チームエンジニア/PM/外部パートナー)ごとに 共有方法・伝える内容・期限を表で明示。書いても共有されなければ決定は広まらない。
Step 10:出力前チェック(30 秒)
取り込み経緯: 2026-06-17 の auto-kaizen で「技術判断(ADR)が唯一 eval 例あり×手順なしの最大ギャップ」と自己診断(スコア 88)。workspace/auto-kaizen.md に作成後 procedure として昇格。