← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 18:56
commonid: adr-0023type: adrstatus: accepted
pagemode: Criticalkruchten: Propertyscope: platformimplementation_status: Done (ADR 構造業界標準化テンプレ実装済)proposed_at: 2026-05-12 22:08approved_at: 2026-05-12 22:18business: meta
型付き辺: 出 17 / 入 3
関連: ADR-0010 ADR-0021 ADR-0036 ADR-0049 ADR-0050 ADR-0105 ADR-0114 ADR-0131 ADR-0018 ADR-0022 ADR-0030 ADR-0032 ADR-0039 ADR-0054 ADR-0065 ADR-0113 ADR-0117 細分化された: ADR-0053 前提とされる: ADR-0024 ADR-0038全体は INDEX →

ADR-0023: ADR ドキュメント群の構造を業界標準 (Nygard + MADR 4.0 ミニマル) に整える

  • Status: Accepted
  • Mode: Critical
  • Kruchten Type: Property
  • Scope: platform
  • Implementation Status: Done (ADR 構造業界標準化テンプレ実装済)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-12 22:08
  • 承認日時 (JST): 2026-05-12 22:18

Kruchten Type は ADR-0031 (2026-05-13) で遡及追加。分類根拠は ADR-0031 §決定セクションおよび docs/adr/README.md の Kruchten 3 分類ガイドを参照。 Status / Mode / Scope は 2026-06-11 に遡及追加 (ADR-0031 corrigendum パターン)。出典: Status = 旧形式「## ステータス」節の機械転記 / Mode = 旧 README §既存 ADR 一覧の推定値 (git 履歴) / Scope = ADR-0049 4 層分類の遡及付与 (PR レビューで確定)。

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

本節は ADR-0140 の方針で遡及追加された本文の要約で、新しい意味は加えていない (意思決定内容は不変)。「文脈で問題に直面し、対抗案でなくこの案を選び、目的のため代償を受け入れる」と読む。詳細はコンテキスト以降の本文に展開する。

  • 文脈: ADR-0001〜0022 (計 22 本) は、ADR の運用方法を体系的に検討する前に作成された。2026-10 に Jr エンジニアの入社を予定している。
  • 問題: 採番・区切り文字・テンプレート位置などが業界標準と乖離し、adr-tools / adr-log / Log4brains 等のツールチェーン互換性が不完全。新規参加者が外部の解説記事と異なる慣習を学ぶ必要があり、認知負荷が高い。
  • 問題点と課題（直せる原因 → 発生を止めるためにやること）:
    • 3 桁連番 + アンダースコアの命名 → 既存 22 ADR を 4 桁 + ハイフンへ renaming する。
    • メタ ADR が不在 (README が暗黙的に役割を兼任) → 0000-record-architecture-decisions.md を新設する。
    • テンプレート位置が非標準 → docs/adr/templates/template.md へ移動する。
    • タイトルが名詞ベース → 新規 ADR は動詞形を推奨する (既存は据え置き)。
  • 前提（解決を課題に立てない与件）:
    • Markdown 単一ファイル維持方針 (ADR-0018) は不変のまま拡張する。
    • GAS ソースコードの 3 桁プレフィックス命名 (ADR-0010) は対象外で干渉しない。
  • 決定（対応策）: 新規のみ新規約適用 (案 B) やメタ ADR + テンプレート移動のみ (案 C) でなく、全件 renaming を含む 7 項目 (案 A) で業界標準 (Nygard + MADR 4.0 ミニマル統合) に揃える。
  • 目的: 業界ツールチェーンとの互換性を確保し、新規参加者の認知負荷を下げる。将来の自動化 (TOC 自動生成 / 連番衝突検知 CI 等) への布石とする。
  • 代償: renaming + 約 40 箇所の内部参照更新で約 3 時間の作業が発生する。外部 URL ブックマーク (GitHub の旧ファイルパス) は無効化される。
  • 詳細は本文の影響・撤退条件セクションを参照のこと

コンテキスト

bizlp-gas-accounting プロジェクトの ADR-0001〜0022 (計 22 本) は、ADR の運用方法を体系的に検討する前に作成されたため、業界標準と乖離した運用になっている。具体的なギャップは以下:

  • 採番: 3 桁連番 (例: 021_*.md) ← 業界標準は 4 桁 (0021-*.md)
  • 区切り文字: アンダースコア (021_adopt_uc_slice_development.md) ← 業界標準はハイフン (0021-adopt-uc-slice-development.md)
  • メタ ADR が不在: docs/adr/README.md が暗黙的に「ADR を採用する決定」の役割を兼ねている ← 業界標準は明示的に 0000-record-architecture-decisions.md を置く
  • テンプレート位置: docs/adr/_template.md (root + アンダースコア prefix) ← 業界標準は docs/adr/templates/template.md
  • タイトル形式: 名詞ベース (例: modular_monolith_numbering) ← 業界標準は動詞形 (use-modular-monolith-numbering)

このギャップにより、adr-tools / adr-log / Log4brains 等の業界ツールチェーンとの互換性が不完全であり、2026-10 入社予定の Jr エンジニアが外部の ADR 解説記事と本プロジェクトの構造で異なる慣習を学ぶ必要が生じ認知負荷が高い。また将来「ADR を採用する決定」を Supersede したくなった時、暗黙的な README.md ではなく明示的な ADR-0000 が必要 (Nygard イミュータブル原則)。

本決定は RQ-041 (Claude Research + Gemini Deep Research 並列調査) の synthesis (docs/_internal/research_prompts/RQ-041_adr_repo_structure_synthesis.md) を素材とし、両エンジンが完全一致で推奨した業界標準 (Nygard + MADR 4.0 ミニマル統合) を採用する。ADR-0018 (TODO 管理の Phase・優先度・レイヤー 3 軸グルーピング / GitHub Issues 移行保留) で確立した Markdown 単一ファイル維持方針を拡張し、ADR-0021 (UC スライス開発と監査ログ機構の採用) で確立したメタデータ・タイムスタンプ運用と整合、ADR-0010 (Modular Monolith Numbering) の数値プレフィックス命名規約は技術カテゴリ命名にスコープ限定して干渉しない。

決定

業界標準 (Nygard + MADR 4.0 ミニマル統合) に揃えるため、以下 7 項目を採用する:

  1. 採番: 既存 22 ADR を 4 桁化 (010_* → 0010-*)、新規は 4 桁開始
  2. 区切り: アンダースコア → ハイフン (010_modular_* → 0010-modular-*)
  3. メタ ADR 新設: docs/adr/0000-record-architecture-decisions.md で ADR 採用の決定を不変記録
  4. テンプレート移動: docs/adr/_template.md → docs/adr/templates/template.md
  5. タイトル命令形: 新規 ADR は動詞形 (use-X, adopt-Y, migrate-Z) を推奨、既存は据え置き (renaming の本質的価値が薄いため)
  6. README.md 維持: 運用ガイドは現状の docs/adr/README.md を維持 (前 PR #624 で初期マスター ADR 役割として共通方針・用語定義・リスク受容方針を移管済)
  7. MOC / Backstage / Log4brains 等の高度な可視化: 今は導入しない。再評価トリガー (ADR 50 本超 / 複数プロジェクト化 / 非開発者への公開要件発生時) を README.md に明文化

判断基準 (重み付き)

  1. 業界標準準拠 (最重要) — ツールチェーン互換性、新規参加者の認知負荷低減
  2. 既存 ADR への影響最小化 (高) — 内部参照リンクの破損リスク管理
  3. 個人開発の運用コスト (高) — renaming 作業時間を実装時間から侵食しない
  4. Nygard イミュータブル原則 (中) — メタ ADR 明示で過去決定の文脈保全
  5. Decision Pipeline 採番ロジック互換性 (中) — ハイフン形式での自動採番動作確認

影響範囲

改修対象

  • docs/adr/*.md: 既存 22 ファイルの renaming (3 桁 → 4 桁、_ → -)
  • docs/adr/_template.md: docs/adr/templates/template.md へ移動
  • docs/adr/README.md: 命名規則セクションの更新、ADR 一覧テーブルのファイルパス更新
  • docs/_config.json: nav の adr/NNN_*.md パス全件更新 (約 21 件)
  • 内部相互参照: ADR 本文内の ADR-0010 等の表記は維持 (人間可読性のため)、ファイルへのリンク (./010_*.md) は新パスに更新

新規作成

  • docs/adr/0000-record-architecture-decisions.md: メタ ADR (Nygard 形式 5 行+α、ADR 採用の決定とトレードオフを宣言)
  • docs/adr/templates/template.md: 既存 _template.md の内容をそのまま移動

不変対象

  • ADR の決定内容 (Status / 採用方針 / Consequences 等の本文)
  • docs/adr/README.md の内容自体 (パスのみ更新)
  • 既存 ADR の Status (Accepted/Proposed は維持)
  • Decision Pipeline (drp/) のコード、webhook ノード等は変更なし (採番ロジックが新形式に対応するかは要動作確認)

コスト試算

項目見積もり
既存 22 ADR の renaming (git mv 一括)30 分
内部相互参照の更新 (約 40 箇所)1 時間
docs/_config.json 更新15 分
メタ ADR 0000 起案 + 内容執筆30 分
テンプレート移動 + README.md 命名規則セクション更新15 分
Decision Pipeline 採番動作確認 (ハイフン形式での自動採番テスト)30 分
合計約 3 時間

完了条件 (検証可能メトリクス)

  1. ADR-0023 (本 ADR) が Accepted 化: Status / 承認日時が埋まる
  2. 既存 22 ADR の renaming PR がマージされる: docs/adr/ 配下に旧形式 (NNN_*.md) ファイルが 0 件、新形式 (NNNN-*.md) ファイルが 22 件存在
  3. docs/adr/0000-record-architecture-decisions.md が存在: Status = Accepted、内容が Nygard 形式で揃っている
  4. docs/adr/templates/template.md が存在: docs/adr/_template.md は削除済
  5. docs/_config.json nav が新パスを参照: 旧パス (adr/NNN_*.md) を含む行が 0 件
  6. 内部相互参照のリンク切れが 0 件: grep -r "adr/0[0-9][0-9]_" docs/ で hits 0
  7. Decision Pipeline で動作確認: 新形式での自動採番が成功 (次の ADR 起案で 0024-*-*.md 形式のファイルが生成される)

検討した代替案 (Alternatives Considered)

  • 案 A: 全件 renaming (4 桁 + ハイフン) ← 採択

    • Good, because 業界標準準拠、二重採番なし、新規参加者の認知負荷最小
    • Good, because adr-tools / adr-log / Log4brains 等のツールチェーン互換性確保
    • Good, because 将来の自動化 (TOC 自動生成 / 連番衝突検知 CI 等) に布石
    • Bad, because 22 ファイル + 約 40 内部参照を更新する 3 時間規模の作業
    • Bad, because 外部 URL ブックマーク (GitHub 旧ファイルパス) が無効化

  • 案 B: 新規のみ新規約適用、既存据え置き — 不採用理由:

    • Good, because 移行コスト 0 (renaming 不要)
    • Bad, because 二重採番が永続化 (3 桁旧形式 + 4 桁新形式が混在)
    • Bad, because 新規参加者が「どちらが正しい形式か」を毎回判断する必要、認知負荷大
    • Bad, because Decision Pipeline の slug 生成ロジックを新形式対応にした場合、旧形式 ADR の検索互換性が不安定

  • 案 C: メタ ADR + テンプレート移動のみ、命名はそのまま — 不採用理由:

    • Good, because 影響範囲を限定 (新規 1 ファイル + テンプレ移動の 2 操作のみ)
    • Bad, because 業界標準準拠が半端 (採番 / 区切りは旧形式のまま)
    • Bad, because ツールチェーン互換性が依然として不完全
    • Bad, because 「業界標準に整える」目的に対する達成度が低く、後で結局案 A を実施することになる可能性大

影響 (Consequences)

  • 正の影響:

    • 業界標準 (Nygard + MADR 4.0 ミニマル) 準拠により、adr-tools / adr-log / Log4brains 等のツールチェーン互換性を確保
    • 2026-10 入社予定の Jr エンジニアが外部の ADR 解説記事と本プロジェクトの慣習を一致させて学習可能、認知負荷低減
    • メタ ADR 0000 新設により「ADR を採用する決定」が不変文書として記録され、Nygard イミュータブル原則を遵守
    • 将来の自動化 (TOC 自動生成 / 連番衝突検知 CI 等) への布石

  • 負の影響:

    • 既存 22 ADR の renaming + 約 40 内部参照更新で約 3 時間の作業発生
    • 外部 URL ブックマーク (GitHub の旧ファイルパス) は無効化される (Git の git mv で履歴は保持)
    • 「README.md だけで運用説明」のシンプルさを捨てる (メタ ADR 0000 を新設するため)

  • リスク:

    • Decision Pipeline の採番ロジック (slug 生成) がハイフン形式に未対応の場合、自動採番エラーが発生する可能性
    • 内部参照リンクの更新漏れによるリンク切れ
    • 外部の暗黙参照 (ブログ / GitHub Issues 等) からのリンク切れ
    • MOC / Backstage / Log4brains 等の高度な可視化機能を見送るため、ADR 本数 50 本超等の閾値超過時に再評価コストが発生

採用に伴うトレードオフ — 何を捨てたか

  • 既存 ADR-0001〜0022 のファイル名連続性: Git の git mv で履歴は保持されるが、外部の URL ブックマーク (GitHub の旧ファイルパス) は無効化
  • 「README.md だけで運用説明」のシンプルさ: メタ ADR 0000 を新設することで「ADR を採用する決定」の根拠を README とは別の不変文書として記録
  • MOC / Backstage / Log4brains 等の可視化機能の早期導入: 現規模 (22 本 / 1 人開発) には過剰投資、再評価トリガーで判断遅延

撤退条件 (Rollback Plan)

判定指標

判定指標閾値対応
Decision Pipeline 採番がハイフン形式で失敗自動採番エラー発生時webhook / numbering node の slug 生成ロジック修正 (本 ADR の決定は撤退不要、Pipeline 側で対応)
内部参照リンク切れが多発5 件以上発見個別修正 PR で順次対応 (renaming 自体のロールバックは不要)
既存 ADR 番号の暗黙参照 (外部ブログ / GitHub Issues 等)報告あり次第リダイレクト or 個別修正
既存 580+ PR 内のリンク切れが大規模100 件超 (renaming 前の事前計測値の 30% 超)renaming 一括差し戻し (下記手順)

renaming 前の影響範囲計測 (必須事前作業)

renaming 着手前に過去 580+ PR / Issue 内のファイルパス参照数を定量計測し、影響範囲を可視化する (Policy Alignment Gate の指摘対応):

# 過去全 PR / Issue / コミットメッセージ内の旧形式 ADR ファイルパス参照を計測
git log --all -p | grep -E 'docs/adr/0[0-9][0-9]_[a-z_]+\.md' | wc -l

# 個別ファイルごとの参照数を把握 (renaming 影響度の優先順位付け)
for f in docs/adr/0[0-9][0-9]_*.md; do
  basename=$(basename "$f")
  count=$(git log --all -p | grep -c "$basename")
  echo "$basename: $count refs"
done

計測結果を docs/_internal/changelog.md に記録し、Renaming PR の ## Test plan に「事前計測値 X 件 / 修正対象 Y 件」として明記する。

renaming 一括差し戻し手順 (Claude / Policy Alignment 指摘対応)

renaming 一括 PR を単一 PR + 単一マージコミットで構成しておけば、git revert 一発で差し戻し可能:

  1. renaming PR は git mv の単一コミット (= 1 つのマージコミット) として構成する
  2. 差し戻しが必要な場合: git revert <renaming-merge-commit-sha> -m 1 で 1 コマンド差し戻し
  3. revert 後の対応: docs/_config.json の nav 旧パス復元、メタ ADR 0000 削除 (or Status: Deprecated 化)、docs/adr/templates/template.md を docs/adr/_template.md に戻す
  4. 所要時間: 30 分以内 (renaming 反映と逆の手順を機械的に実施)

renaming 自体のロールバックは想定外だが、上記手順により理論的可能性を担保する。

長期影響 (Long-term Impact)

再評価条件 (発生したら検討)

3 つのトリガー条件のいずれかが発生したら、高度な可視化ツールの導入を再評価する:

トリガー検討する追加ツール評価軸
ADR 本数 50 本超Log4brains (静的サイト) or adr-log (自動 TOC)手書き索引 + ディレクトリ一覧では全体把握が困難になる閾値
複数プロジェクト化 (副業 / 別事業を別リポで運営開始 等)Backstage (組織横断ポータル) or Wantedly モデル (組織レベル ADR リポ分離)単一リポ内検索では足りなくなる
非開発者への公開要件 (税理士 / 監査人 / 投資家 / 採用候補者向け)Log4brains (静的サイト)GitHub UI は技術者前提、第三者には Web サイト化が必要

Review After タイミング (定期的に確認)

  • 3 ヶ月後 (2026-08-12 前後): 全 ADR が新形式に揃っているか確認、新規 ADR 起案で動詞形タイトルが定着しているか確認
  • 6 ヶ月後 (2026-11-12 前後): Jr エンジニア入社後の ADR 学習コストを定性評価。「外部解説記事と本プロジェクトの慣習が一致しているため学習がスムーズ」が確認できれば成功
  • 1 年後 (2027-05-12 前後): ADR 本数 50 本超に近づいたら MOC / Log4brains 導入を再評価 (上記「再評価条件」トリガー #1 該当)
  • 以降 6 ヶ月ごと: 上記 3 トリガー条件のチェックリスト確認、いずれか該当すれば即座に検討開始

判定主体・観測手段

項目判定主体観測手段
ADR 本数のカウント代表取締役ls docs/adr/*.md | wc -l で月次確認
複数プロジェクト化代表取締役bizlp 関連の新規 GitHub リポジトリ作成時
非開発者への公開要件代表取締役クライアント / 税理士からの ADR 閲覧依頼発生時
定期 Review (3/6/12 ヶ月)代表取締役カレンダーリマインダー + docs/_internal/changelog.md に Review エントリ追加

Confirmation (準拠確認 / Fitness Function)

本セクションは ADR-0036 (Accepted 2026-05-14) で遡及追加された。ADR-0031 パターン (業界標準準拠メタデータ後付け = 誤字修正範疇) に準拠する遡及で本文の意思決定内容は不変。

  • 検証手段: scripts/adr-lint.mjs の規約チェック + 手動レビュー
  • 実行頻度: PR ごと
  • 違反時の対応: 自動 fail

参照 (References)

  • 関連 ADR:
    • ADR-0018 (TODO 管理の Phase・優先度・レイヤー 3 軸グルーピング / GitHub Issues 移行保留): Markdown 単一ファイル維持方針を本 ADR で拡張 (ファイル命名規約のみ業界標準化、Markdown 維持は不変)
    • ADR-0021 (UC スライス開発と監査ログ機構の採用): メタデータ・タイムスタンプ運用 (起案日時 (JST) / 承認日時 (JST)) と整合、本 ADR でも踏襲
    • ADR-0010 (Modular Monolith Numbering): GAS ソースコード命名規約 (3 桁プレフィックス) は不変、本 ADR は ADR ドキュメント命名のみを対象としてスコープ干渉なし
    • ADR-0022 (Decision Pipeline への Policy Alignment ノード追加): Accepted 済、本 ADR は Pipeline 経由起案で Policy Alignment Gate を通過済
  • 関連 PR/Issue:
    • 前 PR #624 (README.md への共通方針・用語定義・リスク受容方針移管)
    • 本 ADR マージ後の renaming PR (要追記)
  • 外部資料:
    • docs/_internal/research_prompts/RQ-041_adr_repo_structure_result_claude.md
    • docs/_internal/research_prompts/RQ-041_adr_repo_structure_result_gemini.md
    • docs/_internal/research_prompts/RQ-041_adr_repo_structure_synthesis.md (本 ADR の素材)
    • docs/adr/README.md (現状の初期マスター ADR 役割 / 命名規則は本 ADR で更新予定)
    • Michael Nygard "Documenting Architecture Decisions" (Nygard 形式の原典)
    • MADR (Markdown Architecture Decision Records) 4.0 ミニマル仕様