最終更新: 2026/06/22 18:56
ADR 運用の現場知見(日本語一次情報からの肉付け)
日本企業の技術ブログ(生々しい一次情報)を 2026-06-08 に WebFetch で読み込み、ADR 運用の実務知見を抽出したもの。情報源カタログは adr_japanese_resources.md。 位置づけ: deep research(RQ-098/RQ-100)が「骨格(理論・標準・機構)」なら、本ノートは「肉(現場の運用現実)」。 注意: ブログ記事=単一企業の逸話で厳密エビデンスではない。当プロジェクトは LLM 自動パイプライン + ソロ + 監査要件という特殊文脈のため部分転用。骨格判断には使わず、運用設計の色付けに使う。
テーマ別の現場知見(出典付き)
1. 軽量化・書くハードルを下げる(最頻出・最重要)
- 「重要な意思決定を漏らさない > リッチに書く」を優先順位として明言(一休)。1 ADR に力を入れすぎると書かなくなる。
- 結論未定でも draft で書き始め、未定部分は仮置き(一休)。
- 初期はステータス・コンプライアンス項目をあえて採用しないでハードルを下げる(CARTA)。
- 小さくモジュール化された文書ほど更新される。大きな文書は最新に保たれない(ZOZO)。
2. ステータス遷移は各社ほぼ共通
draft → proposed → accepted(+rejected / deprecated / superseded)(一休・ZOZO・電通総研)。当プロジェクトの ADR ステータスと一致。- MTG 終了時に「ADR に書いておきましょう」を定着させる(一休)。proposed で書いてから議論開始(ZOZO)。
3. 関連・supersession の扱い = 「修正せず新規作成」
- 決定が覆ったら元 ADR を rejected/superseded にして新規 ADR を起こす。元は直さない(一休「rejected: ADR-2 に伴い」/ 電通総研「内容更新せず新規作成して Superseded 関連付け」)。= append-only + supersede。
- 関連付けは Discussion と Issue の相互リンク(電通総研)。ただし現状の業界実務は軽量な prose リンクで、重い依存グラフは保守していない。
4. 管理場所は複数の現実解
docs/adr/ファイル + PR レビュー(エス・エム・エス・一休 一部チーム)。- GitHub Discussions(電通総研): 構成管理・テンプレ・検索・1クリックフィルタ・本体とレビューコメント同一ページ、の5観点で最高評価。欠点=Copilot 非対応(docs/README に複製で代替)。
- Confluence(一休 宿泊)/ GitHub Issues + Projects も事例あり。
5. 記載観点・テンプレ
- Nygard 形式(タイトル/ステータス/コンテキスト/決定/影響)が基本(一休・ZOZO)。
- 5 観点で意思決定を分類: 構造・非機能特性・依存関係・インターフェイス・構築手法(エス・エム・エス)。
- コンプライアンス節(遵守確認方法)を持つ(電通総研・エス・エム・エス)= 当プロジェクトの Confirmation に相当。
- 検索性: ファイル名/タイトルに結論を入れる(CARTA「xxx の設計について」→ 結論を含む名称)。検討選択肢に「利点と懸念点」を必須化(CARTA)。SCQA でコンテキストを書く(一休)。
6. 形骸化・つまずき(我々の宿題と同型)
- **「ツール導入が目的化」**してつまずいた → 課題に立ち返って取り入れ直した(CARTA)。
- ステータス更新が忘れがち・文書化は意識しないと行われない・旗振り役の啓蒙が要る(ZOZO)。
- 「見送り候補も詳細記録」する運用は初期作成負荷が大きい(電通総研)。
我々の設計への含意(肉付けの本体)
| 現場知見 | 我々の決定への含意 |
|---|---|
| 軽量化が継続の鍵・重い文書は腐る | RQ-100 のグラフ/lint は最小から。型付き辺・lint を重装備にすると保守されず形骸化する。「最小必須 lint + 自動生成 _graph.json」の方向は現場知見と整合 |
| 「修正せず新規作成 + supersede」が各社共通 | RQ-100 の append-only + supersede 辺設計を実務が裏づけ。re-home の follow_up_required(RQ-098)も同じ append-only 思想 |
| 重い依存グラフは誰も保守していない | 型付きグラフは人手保守を前提にしない。bootstrap + 自動生成 + lint 強制(=人が手で辺を張り続けない)が必須。手作業前提なら採用すべきでない |
| 「ツール導入が目的化」して失敗 | 我々の自動パイプライン + scope-aware critic + グラフも同じ罠。ADR-0109 の自己反省(過剰審査を直す ADR が過剰審査でループ)と同型。課題起点で最小からを徹底 |
| GitHub Discussions という現実解 | ファイル + グラフが唯一でない。ただし当プロジェクトは機械可読 frontmatter が前提(critic が引く)なので Discussions は不適。この差は文脈差として記録 |
| コンプライアンス節 = Confirmation | 既存の Confirmation 規約は業界実務と整合。逸脱でない |
転用しない部分(正直に)
- FN=0 critic の機構・スコープ判定: JP に前例なし。骨格は RQ-098 の deep research が正。
- 型付き辺スキーマの細部: MADR 等 Western 標準が正(RQ-100)。
- 本ノートは「運用が形骸化しない/重くしすぎない」ための色付けであり、機構の正否判断には使わない。
出典(WebFetch 2026-06-08)
- 一休.com ADR を1年間書いてみた感想
- CARTA ADR 導入・運用時に取り組んだこと
- 電通総研 GitHub Discussions で ADR を管理する
- ZOZO ZOZOFIT における ADR 文化作り
- エス・エム・エス ADRはじめました