← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:19
commonid: adr-NNNNtype: adrstatus: proposed

ADR-NNNN: <タイトル要旨 (動詞 + 目的語、30 字以内推奨)>

  • Status: Proposed
  • Mode: Standard
  • Kruchten Type: Existence | Property | Executive (該当する 1-3 個を / 区切りで列挙、複数該当時は §5.1/§5.2/§5.3 で影響を分解)
  • Scope: corporate | platform | product | ops (ADR-0049 で導入、4 層から 1 つ選択)
  • Implementation Status: Not Started | In Progress (PR #NNN) | Done (PR #NNN, #MMM) | Partial (注釈で範囲明示) | Reverted (PR #NNN, 撤退理由) | N/A (governance / process / 純ドキュメント ADR の場合)
  • 起案者: (氏名 / メール)
  • 起案日時 (JST): YYYY-MM-DD HH:MM
  • 承認日時 (JST): -
  • Approver Role: corporate | platform | product | ops (ADR-0141: Scope 由来・ちょうど 1 つ・人ではなく役割を記録)
  • Approver Who: (Approver の氏名 / メール。現在は 4 役割すべて代表取締役が兼任)
  • Driver: (起案・実装の進行役の氏名 / メール)
  • Consulted: (相談先・拒否権なし: 外部専門家 / AI critic / 3 モデル調査。カンマ区切り・無ければ行ごと削除)
  • Informed: (任意の通知先。カンマ区切り・無ければ行ごと削除)
  • Covers: (DRP スコープの決定のみ: この ADR が充足する上層 ID を列挙、例 SR-004, SR-005。該当なしならフィールドごと削除)
  • Constrains: (DRP スコープの決定のみ: この ADR が制約する下層 ID を列挙、例 EDD-002。該当なしならフィールドごと削除)

Status は Proposed → Accepted (マージ時) / Rejected (Close 時) / Superseded by ADR-NNNN (後続 ADR で更新) に遷移する。 イミュータブル原則: Accepted 後の本文編集は誤字修正のみ。決定そのものの変更は新 ADR で Supersede。 運用解釈 (ADR-0031 で明確化): 業界標準準拠のメタデータ後付け (Kruchten/Nygard 等の分類軸の遡及追加) は誤字修正範疇として許容。ただし新 ADR で明示的に承認すること (ADR-0031 が Kruchten Type 遡及追加を承認した先例)。Mode/Status/Deciders 等の既存メタデータの後付け改変は対象外。 Kruchten Type (ADR-0030 で採用): 決定の主題分類軸 (Mode = 規模軸と直交)。Existence=新要素の存在 / Property=横断ルール / Executive=技術・プロセス選定。判定フローチャートと既存 ADR の分類例は docs/adr/README.md の「Kruchten 3 分類ガイド」節を参照。 Implementation Status (ADR-0032 で採用): 実装ライフサイクル軸 (Status = 意思決定軸と直交)。新規 ADR は Not Started で起案、実装 PR open 時に In Progress (PR #NNN)、マージ時に Done (PR #NNN) へ起案者が手動更新する (誤字修正範疇)。値の詳細定義は docs/adr/README.md の「Implementation Status ガイド」節を参照。 段階的実装の詳細は impl_detail 節へ (ADR-0162 で採用): Implementation Status の追加情報が 100 文字を超える / 段階的実装 (Phase 1/2 等) を伴う場合は、本太字欄を 6 値の短縮形 (Not Started / In Progress / Done / Partial / Reverted / N/A) に保ち、詳細を任意の ## 実装状況詳細 (impl_detail) 節へ分離する。マーカーは <!-- impl_detail:start 派生・非規範: ADR本文ではない / 後から差し替え可 --> ... <!-- impl_detail:end -->。INDEX.md の「Impl状況詳細」列はこの節を派生ビューとして表示する。検査: adr-lint impl-detail-implies-short-status が error で短縮形完全一致を強制。使い方の詳細は docs/adr/README.md の「impl_detail 節で詳細を分離する」節。 承認者体系 (ADR-0141 で採用): 決定の最終責任者を 1 人 (Approver) に固定し frontmatter に構造化する。Approver Role は Scope (ADR-0049 の corporate/platform/product/ops) から導出する 4 役割で ちょうど 1 つ。役割 (role) と人 (who) を分けて記録するため、チーム化で担当者を割り当て直しても過去 ADR の書き直しは要らない。役割と人の対応 (履歴つき) は 役割割当レジストリ を正とする。検査は ④ 受理 PR 層 (adr-lint の静的検査 + CI の merge 者一致) が所有する。 deciders は廃止 (ADR-0141): 旧 Deciders 欄は新規 ADR では使わず、上記 4 欄 (Approver Role/Who・Driver・Consulted・Informed) に分解する。既存 ADR は段階移行 (ADR-0137 Phase 2 + 改訂時 touch-time)。 監査注記 (SoD 補償統制): 1 人法人では Approver = Driver が常態で職務分掌 (SoD) が成立しない。COSO の補償統制として DRP の独立 AI 審査 (Standard/Critical の起案時 1 回必須・記録は docs/_internal/drp-reviews/YYYY-MM/ADR-XXXX.md・起案者と異なる AI モデルを 1 つ以上含む 3 モデル調査) と Git の不変な承認履歴 (PR merge) を用いる。EU AI Act 第 14 条適合の根拠は別文書「DRP 独立 AI 審査手順書」。 型付き辺 (ADR-0131 で採用): ADR 間の関係は冒頭 YAML frontmatter の辺フィールド (7 種 + 逆辺) が正 (SSoT)。参照節の文章は人が読む説明として残すが、機械は frontmatter のみを読む (本文からの推測抽出はしない)。これまでの言い方の写像: Supersedes 欄→supersedes / 部分 Supersede→amends / Refine→refines / 前提→depends_on / 補完・並立・整合→relates_to / spike→follows_up_on。辺を宣言する PR は相手側 ADR への逆辺追記を同一 PR に含める。 実装フォローアップ宣言 (ADR-0144 で採用): 「実装完了時に更新する関連文書」(構造正典 §G の表・残論点台帳の行・相手側 ADR の Implementation Status 等) を frontmatter followups: に機械可読で宣言する。検知スクリプトが Implementation Status と突き合わせて未処理を検知し、DOC-OPS backlog へ残タスク化する (文書の自動書換はしない・意味判断は人に残す)。残論点台帳の散文 (「実装完了で〜を解消し本行を削除」類) は人間向けビューとして残し、機械が読むのは frontmatter のみ。 暫定 (2026-06-12 時点): 検知スクリプトと adr-lint の宣言検査は ADR-0144 の main 分実装待ち。完了までは起案者が followups: を手動で書き、PR レビューで存在と中身を確認する (main 実装 PR で本注記を確定記述へ更新する。正典の残論点台帳 P8)。 Covers / Constrains (ADR-0117 で採用): トレーサビリティ軸。Covers: = この決定が充足する上層 ID (BR-/SR-/NFR-/UC-)、Constrains: = この決定が制約する下層 ID (EDD-/IDD-)。DRP (decision_pipeline) スコープの ID のみ記入可で、DRP に関係しない ADR はフィールドごと削除する (空欄禁止)。ID 参照はこのメタデータブロック限定とし、散文中への規範的 ID 参照は書かない (CI lint の検出対象外で陳腐化するため)。DRP スコープの新規 ADR は Covers 付与必須 (100%)。規約の正典: docs/_internal/03_decisions/decision_pipeline/layers/00_entry/id_conventions.md。既存 ADR への遡及付与は追記のみ許容 (ADR-0031 の業界標準メタデータ後付け先例に準拠)。

用語 Tier・原語温存 (ADR-0105 で採用): 専門語は 3 階層で扱う。Tier 0 (IT 一般教養: API/CI/JSON/lint 等) は説明しない。Tier 1 (プロジェクト固有: INV/STL/Action A・B 等) と Tier 2 (専門フレーム: Kruchten Type/DLQ/phantom dependency 等) は 日本語に置換せず原語を残し、初出時のみ 原語〔和訳＝一句〕 を併記する (例: SSoT〔Single Source of Truth＝唯一の正データ〕)。地の文は日本語で書く。用語定義の SSoT は docs/architecture/glossary.md、検証は node scripts/adr-lint.mjs --check-terminology。 冒頭要約は「決定の早わかり」に一本化済み (ADR-0139 が ADR-0105 の旧「冒頭 TL;DR」箇条を Amend で廃止)。新規 ADR に TL;DR 枠は置かない (既存 4 本は温存)。

決定の早わかり（Y-statement）

必須 (ADR-0138 で採用): 全 Mode 必須。H1 の後の最初の H2 をこの節とする (見出しの存在・位置は adr-lint が機械検査・しきい値番号以降の新規 ADR が対象)。型の正典は ピラミッド原則 §D (D-1 4 階層連鎖 / D-2 読み筋)。実物見本は ADR-0107 冒頭 (ただし末尾の定型注記は ADR-0138 で後から必須化された要素のため ADR-0107 には無い。完全形は本節の箇条を正とする)。Decision Pipeline 経由の新規 ADR は body_generation が自動生成する (起案者の追加作業なし)。

暫定 (2026-06-12 時点): 上記の自動生成と adr-lint の機械検査は、ADR-0138 の main 分実装が完了するまで未稼働。完了までは起案者が本節を手動で書き、PR レビューで存在と型を確認する (実装完了 PR で本注記を削除する。正典の残論点台帳 P7)。

  • 文脈: <状況。問題ではない>
  • 問題: <実害 (困っている結果)>
  • 問題点と課題 (直せる原因 → 発生を止めるためにやること を 1 行 1 ペアで。課題が複数なら行を分ける・多重度は D-1 の 1:N):
    • <問題点> → <課題>
  • 前提 (与件。スコープ的与件は解決を所有する ADR・規約への行き先必須):
    • <今すぐ解決できない問題点 / この問題空間の外で扱う問題点>
  • 決定 (対応策): <対抗案でなくこの案を選ぶ (具体の打ち手)>
  • 目的: <目指す到達状態 (実害の裏返しでなく前向きに)>
  • 代償: <受け入れるコスト>
  • 詳細は本文の影響・撤退条件セクションを参照のこと (末尾の定型注記 = 必須箇条・ADR-0138 §5.2。引用ブロックでなく箇条として置く)

1. コンテキスト

書くべきこと: 何が起きていて何を解決したいか。前提条件・制約・関連する過去 ADR。価値中立に、事実のみを記述 (Nygard 原則)。 Mode 別の構造:

  • Light Mode (30-80 行): 以下のサブ見出しを使わず、単一節で 1〜3 段落にまとめる
  • Standard Mode (80-200 行) / Critical Mode (200-400 行) / Initial Master ADR (400+): §1.1〜§1.5 のサブ見出しに分解 (ADR-0024 で正式採用)
  • 「該当なし」項目: サブ見出しごと削除 (空欄禁止)、歯抜け番号 (§1.1, §1.3, §1.5 等) は許容
  • 各サブ項目の本文: 1〜2 文を目安 (Mega-ADR 回避)。Critical Mode は柔軟性を優先し 1〜2 段落まで許容

1.1 背景 (Background)

書くべきこと: いつ・なぜ議論が始まったか。きっかけイベント。1〜2 文。

(...)

1.2 現状 (Current State / As-Is)

書くべきこと: 今どうなっているか。客観的に観察可能な事実 (コード・データ・運用の現在の状態)。評価語 (「ひどい」「複雑な」) は避ける。1〜2 文。

(...)

1.3 課題 (Problem)

書くべきこと: 何がうまくいっていないか。痛みポイントを具体・数値化 (「30 分かかる」「月 2 件のミス」)。抽象論 (「保守性が低い」だけ) は避ける。1〜2 文。

(...)

1.4 制約・要件 (Constraints & Requirements)

書くべきこと: 動かせない前提と必達要件を箇条書き 2〜5 項目。技術的・予算的・スケジュール的・規制的。「あったらいいな」は書かない。

  • ...
  • ...

1.5 目標 (Goals / To-Be)

書くべきこと: To-Be 状態 + Non-Goals。動詞 + 名詞の具体的なターゲット。解決手段は §4 決定に書く。1〜2 文。

(...)

2. 判断基準 (Decision Drivers)

書くべきこと (ADR-0053 で構造化、ADR-0050 Q42 9-tag MCDA を ADR 本文にも拡張適用):

  • Standard / Critical Mode: §2.1 評価軸 + §2.2 評価軸 × 案スコア表 を 必須。Gate 4 で判断基準 ≥4/5 を狙う
  • Light Mode: §2 全体を省略可 (起案者の認知負荷とトレードオフ、推奨はする)
  • Q42 9 タグ: #reliable / #flexible / #maintainable / #efficient / #usable / #operable / #suitable / #secure / #safe
  • 重要度ラベル係数 (ADR-0050 v1 暫定): Must ×2.0 / High ×1.0 / Medium ×0.5
  • K.O. criterion: Must 軸の score < 3 は不採用 (Suhr 1999 CBA criterion)
  • 詳細は docs/_internal/05_how-to/adr_decision_drivers_guide.md 参照

2.1 評価軸 (Q42 9 タグから 3-5 個選定)

#軸重要度 (係数)案件特有の解釈
1#<tag>[Must] (×2.0)<この案件での意味>
2#<tag>[Must] (×2.0)<この案件での意味>
3#<tag>High (×1.0)<この案件での意味>
4#<tag>High (×1.0)<この案件での意味>
5#<tag>Medium (×0.5)<この案件での意味>

K.O. criterion: Must 軸の score < 3 は不採用。

2.2 評価軸 × 案スコア表

各案を 0-5 で評価。加重和は (Σ score × 係数) / (満点 × Σ 係数) で正規化 (0.0-1.0)。

軸係数採択案案 A案 B...
#<tag> [Must]×2.05.........
#<tag> High×1.0............
加重和 (正規化、満点 32.5)X.XXXX.XXXX.XXX...
K.O. 通過 (Must ≥3)✓✓/❌✓/❌...

加重和は絶対判定ではなく K.O. 通過候補のタイブレーク用。

3. 検討した代替案 (Considered Options)

必須: 最低 2 つの代替案を挙げる (Sprint / Tunnel Vision アンチパターン回避)。1 つしかない場合は本当に「決定」なのかを再考。 各案について: 採用しなかった案も Good, because ... / Bad, because ... で評価する (Fairy Tale アンチパターン回避)。

  • 案 A: <名称>
    • Good, because ...
    • Bad, because ...
  • 案 B: <名称>
    • Good, because ...
    • Bad, because ...

4. 決定 (Decision Outcome)

書くべきこと: 採用する方針を 1〜2 段落で。We will ... または 採用: <案 X>。理由: ... の能動的・命令的な表現を使う。詳細はここで完結 (Consequences に流さない)。

採用: <案 X>。理由: <一文で本質的な根拠>。

5. 影響 (Consequences)

書くべきこと: ポジティブ・ネガティブ・ニュートラル全て。Bad, because ... は必ず 1 行以上書く (Fairy Tale 回避)。 Mode 別の構造:

  • Light Mode: サブ見出しを使わず、単一節で Good/Bad/Neutral の箇条書き
  • Standard / Critical / Initial Master: §5.1〜§5.3 のサブ見出しに分解 (ADR-0024 で正式採用)
  • Initial Master ADR (例外): §5.1 正の影響 / §5.2 負の影響 / §5.3 リスク / §5.4 リスク受容方針 / §5.5 長期影響 / §5.6 採用に伴うトレードオフ までフル分解可

5.1 正の影響 (Good)

  • Good, because ...
  • Good, because ...

5.2 負の影響 (Bad) ← 必ず 1 行以上書く

  • Bad, because ...

5.3 中立 / トレードオフ (Neutral / Trade-offs)

  • Neutral, because ...

5.5 Spike Results（外部技術・ライブラリを採用する ADR のみ）

書くべきこと: 実装前に行った調査実験の結果。「動いた / 動かなかった」の証跡をここに残す。 外部 API・ライブラリのバージョン固有の挙動、パラメータ形式の確認結果、回避策の根拠など。 純粋に内部設計の決定（GAS 関数の分割方針など）には不要。

確認項目結果確認日備考
<技術/パラメータ名>✅ 動作 / ❌ 不動作 / ⚠️ 条件付きYYYY-MM-DDバージョン・回避策など

6. 撤退条件 / 再評価トリガー (Rollback Plan / More Information)

書くべきこと: どうなったら元に戻す or 再評価するか。判定指標・期限・代替案への分岐。

  • 再評価トリガー: <この前提が変わったら見直す> (例: クライアント数が 10 社超 / GAS 制限緩和 / API 単価 30% 増)
  • 判定タイミング: <月次 / 四半期 / 半年後 / 1 年後>
  • 判定主体: <氏名>

Confirmation (準拠確認 / Fitness Function)

書くべきこと: 本 ADR の決定が実装で守られていることを継続的に検証する手段。CI ルール / lint ルール / test / 手動レビューチェックリスト / 監視メトリクスのいずれか。 必須形式: 3 要素 (検証手段 / 実行頻度 / 違反時の対応) を漏れなく記述。 N/A の場合: 理由を必ず明記 (例: 「ガバナンス ADR で実装不要のため継続検証対象外」)。N/A は Light Mode + 純ドキュメント ADR でのみ許容、Standard / Critical Mode は原則 N/A 不可。

  • 検証手段: <CI ルール名 / lint ルール名 / test 名 / 手動レビューチェックリスト>
  • 実行頻度: <PR ごと | Nightly (日次バッチ) | 月次 | 四半期 | 起案時のみ>
  • 違反時の対応: <自動 fail / Slack 通知 / 月次レビューで集計>

7. 参照 (References)

7.1 プロジェクト内参照

  • 関連 ADR: ADR-NNNN (準拠 / 拡張 / Supersedes 等の関係を明示)
  • 関連 PR/Issue: #NNN
  • 関連 RQ: RQ-NNN

7.2 設計根拠 (Theoretical Foundation) — Standard/Critical 推奨

判断軸・採用 FW・参考論文の verifiable な原典を列挙。Light モードは省略可、Standard/Critical では最低 1 件推奨。書き方詳細は writing_design_rationale.md 参照。

出典タイプ別 citation 推奨形式 (信頼度高い順):

タイプ形式例
公式 canonical site[名称](https://...)[arc42](https://arc42.org/)
arXiv 論文Author et al. (Year) — "Title". arXiv: [NNNN.NNNNN](https://arxiv.org/abs/NNNN.NNNNN)Zheng et al. (2023) — "Judging LLM-as-a-Judge...". arXiv: [2306.05685](https://arxiv.org/abs/2306.05685)
論文 DOIAuthor et al. (Year) — "Title". DOI: [10.xxxx/yyyy](https://doi.org/10.xxxx/yyyy)Kruchten et al. (2006) — "Building Up and Reasoning...". DOI: [10.1007/11921998_8](https://doi.org/10.1007/11921998_8)
書籍 (ISBN)Author, *Title*, Publisher, Year (ISBN: X-XXXXX-XXX-X)Suhr, *The Choosing By Advantages Decisionmaking System*, Quorum Books, 1999 (ISBN: 1-56720-217-9)
Blog 原典Author (Year) — [Title](URL)Nygard (2011) — [Documenting Architecture Decisions](https://www.cognitect.com/...)

CLAUDE.md「URL 生成禁止 (programming help 例外)」原則遵守: canonical / arXiv / DOI / ISBN のみ。記憶や推測で URL を作らない。確信がない場合は author/year/title だけ書いて URL は空欄にする。

起案前チェックリスト

以下にすべて Yes が出る決定だけを ADR として残す。No なら ADR ではなくコメント / README / 設計メモで十分。

  • 6〜12 ヶ月後に再議論しそうな決定か？ (Yes なら ADR / No ならスキップ)
  • 代替案を 2 つ以上挙げたか？ (1 つしかない = 本当に決定か疑う / Sprint アンチパターン)
  • Bad, because ... を 1 行以上書いたか？ (Fairy Tale アンチパターン回避)
  • 1 スクロール画面 (約 400 行以内) に収まっているか？ (Mega-ADR アンチパターン回避、超える場合は分割を検討)
  • 命令調・規則調になっていないか？ (「採用する」「決定する」は OK、「すべき」「禁止」の連発は Blueprint in Disguise アンチパターン)
  • 再評価トリガーを書いたか？ (前提が変わった時の見直し条件)
  • タイトルが動詞 + 目的語か？ (「採用する」「移行する」「廃止する」など能動的)
  • 実装を伴う ADR でコストを記載する場合: 「AI 支援あり」と「手作業（AI 非対応）」の両軸で記載したか？ (生成 AI が自動化できる作業は AI 支援工数を一次見積もりとし、手作業工数を参考値として併記)

アンチパターン警告 (Olaf Zimmermann)

アンチパターン何が問題か回避方法
Fairy Tale都合の良い理由しか書かないBad, because ... を必ず 1 行書く
Sprint / Rush代替案を 1 つしか検討しないConsidered Options は最低 2 つ
Tunnel Vision局所最適しか見ない運用・保守・将来の移行を必ず 1 行考える
Mega-ADR1 つに詰め込みすぎ1 スクロール画面を超えたら分割 (例外: ADR-0021 のような初期マスター ADR)
Blueprint in Disguise命令調・規則調「決定の記録」であって「規則」ではない

量の目安 (粒度別)

ADR タイプ行数目安例
Light Mode (Triage で Light 判定)30-80 行ライブラリ選定、命名規約の小変更、コーディング規約の追加
Standard Mode80-200 行データストア選定、認証方式、API 連携設計、リトライ方針
Critical Mode200-400 行開発プロセス変更、監査要件影響、マイグレーション、不可逆判断
Initial Master ADR (例外)400+ 行プロジェクト初期の包括的方針 (ADR-0021 がこれに該当)。継続的に書くものではない

参考文献