エンジン: Anthropic Claude Research 実行日: 2026-05-13 (推定) 調査トリガー: ADR-0021 周辺整備中に「ADR ドキュメント群の構造を最初に作り直したい」というユーザー要望から派生 ペア結果 (Gemini Deep Research): RQ-041_adr_repo_structure_result_gemini.md 突合: RQ-041_adr_repo_structure_synthesis.md

本ファイルの位置付け: Claude Research の回答を改変なしで保存。整理・解釈は突合フェーズで行う。

ADRリポジトリのディレクトリ構造ベストプラクティス —— 初期マスターADR・運用ガイド・個別ADRをどう分離するか

TL;DR

• **業界標準は「フラットな単一ディレクトリ + メタADR #1で意思決定の記録自体を宣言」**である。docs/adr/ または doc/adr/ 配下に 0001-record-architecture-decisions.md を置き、以降は連番で個別ADRを並べる構成が、Nat Pryce の adr-tools、Michael Nygard の原典、Spotify Backstage、GOV.UK、MADR、Log4brains に共通する。ステータス別フォルダ分けはアンチパターン(ADRはイミュータブルでステータスはファイル内に記録するため、フォルダ移動が履歴を壊す)。
• 運用ガイドは「ADRの中」ではなく docs/adr/README.md(または別の CONTRIBUTING.md)に置くのが定石。テンプレートは adr-tools 流(templates/template.md)か MADR 流(template/ サブフォルダに full/minimal の2〜4種)。「ADRを採用する」「MADR形式を使う」「Markdownを使う」は1本のメタADRにまとめて、後から増えた運用ルールは個別ADRとして追記する。
• 個人開発(代表取締役のGAS会計システム)では、最初に作るのは5ファイル:docs/adr/README.md(目次+書き方)、docs/adr/template.md、docs/adr/0001-record-architecture-decisions.md、docs/adr/0002-use-madr-format.md、最初の実決定 docs/adr/0003-<最初の技術選定>.md。これ以上は最初から作らない。ADRが10本を超えてから階層化や Log4brains 導入を検討すれば十分。

Key Findings

1. デファクトのパスは doc/adr/(adr-tools 既定)、docs/adr/(Log4brains 既定、Backstage ADRプラグイン推奨)、docs/decisions/(MADR 4.0 推奨)、doc/architecture/decisions/(GOV.UK・govuk-infrastructure)の4種。意味的な差はほぼなく、どれを選んでも業界互換性がある。Martin Fowler の bliki "Architecture Decision Record"(martinfowler.com、2026年3月24日改訂)は次のように書いている: 「The common advice is to keep decision records in the source repository of the code base to which they apply. A common choice for their location is doc/adr」。
2. メタADR #1 はほぼテンプレ化されている。adr-tools の adr init は 0001-record-architecture-decisions.md を自動生成し、その本文はわずか5行(Context: We need to record the architectural decisions made on this project / Decision: We will use Architecture Decision Records, as described by Michael Nygard… / Consequences: See Michael Nygard's article…)。これが業界の事実上の定型。
3. 「ADR形式を採用する」を別ADRに切り出す流派もある。MADR プロジェクト自身は 0000-use-markdown-architectural-decision-records.md(ADRの記録自体ではなく「MADR形式の採用」)を分離して持つ。さらに 0002-do-not-use-numbers-in-headings、0005-use-dashes-in-filenames、0010-support-categories のように、運用ルール1個=ADR1本で積み上げている。これは「メタADRも個別ADRと同じテンプレで書く」流派。
4. テンプレート配置は2方式が支配的。(a) adr-tools 方式: {adr-dir}/templates/template.md(adr new が自動参照、なければ組み込みデフォルト)。(b) MADR 方式: 別の template/ フォルダに adr-template.md(フル)、adr-template-minimal.md(必須項目のみ)、adr-template-bare.md、adr-template-bare-minimal.md の4種を置き、ユーザーは手動で docs/decisions/ にコピー。前者は「1ツール1テンプレ」、後者は「複数フォーマットから選べる図書館」。
5. ステータス別フォルダ(accepted/, proposed/, superseded/)はアンチパターン。理由は明快で、ADRはイミュータブル(変更不可)で「ステータス」だけがファイル内で変わる append-only ログだから。フォルダ移動するとGitの履歴やリンクが壊れ、連番の意味が消える。Martin Fowler(martinfowler.com/bliki/ArchitectureDecisionRecord.html、2026年3月24日)は明確にこう述べている: 「Once an ADR is accepted, it should never be reopened or changed - instead it should be superseded. That way we have a clear log of decisions and how long they governed the work」。
6. ドメイン別サブディレクトリは "後から" 必要になった場合のみ採用。MADR 公式ドキュメント(adr.github.io/madr/)は「MADR does not enforce any repository or directory organization structure」と明記したうえで、decisions/backend/、decisions/ui/ のような分割例を「community proposal」として紹介している。代償として「numbers of ADRs are no longer unique throughout the repository, but locally within a category only」(連番のグローバル一意性が失われる)とも明示。Wantedly は組織レベルで wantedly/dev リポジトリの ./docs/<領域>/adr を採用し、プロジェクトレベルは各リポジトリの ./docs/adr に分離している。
7. インデックスは README.md が定番。adr-tools の adr generate toc > docs/adr/README.md、または adr-log の <!-- adrlog --> プレースホルダ注入で自動生成可能。Log4brains は静的サイト(検索・グラフ・履歴)を別途生成。ADR本数が少ない間はGitHubのディレクトリ表示で十分。
8. 個別事例の比較: Backstage は docs/architecture-decisions/ + adr000-template.md(連番衝突を避けるため000をテンプレに固定) + 個別ADRは adr001-…〜adrNNN-…、運用ガイドは同フォルダの index.md(『Records should be stored under the architecture-decisions directory』『Records are never deleted but can be marked as superseded』)。adr-tools 自身は doc/adr/0001-record-architecture-decisions.md〜 でメタADR1本のみ。MADR 自身は docs/decisions/ に**ちょうど19本(0000〜0018)**のメタADRを並べる(adr.github.io/madr/decisions/ の TOC で 0000-use-markdown-architectural-decision-records から 0018-use-confirmation-as-heading まで列挙)。GOV.UK は docs/architecture-decisions/ または adr/ を各レポで採用、フレームワーク全体は GDS Way の標準ドキュメント側に分離。
9. Kubernetes KEP は ADR の親戚で、サブディレクトリ分割の参考になる。KEP は keps/sig-<sig-name>/NNNN-short-title/README.md の構造で SIG ごとに分割しており、「KEPs about KEPs」だけはルートに置く(KEP-0000)。これはまさに「メタADRと個別ADRを物理的に分離する」発想。
10. 「ADRを採用する」自体のADR化は再帰だが問題ない。adr-tools・MADR・GOV.UK のいずれも、ADR #1 をメタADRに固定する習慣を採用しており、これが暗黙の慣習。

Details

1. フラット vs 階層: どちらを選ぶか

結論: 100本未満ならフラット一択。ドメイン別やステータス別の階層は、明確な問題が顕在化してから導入する。

2. メタADR(初期マスターADR)の中身と分割

adr-tools が adr init で自動生成する 0001-record-architecture-decisions.md の中身は、業界の事実上の定型:

# 1. Record architecture decisions

Date: YYYY-MM-DD

## Status
Accepted

## Context
We need to record the architectural decisions made on this project.

## Decision
We will use Architecture Decision Records,
as described by Michael Nygard in this article:
http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

## Consequences
See Michael Nygard's article, linked above.
For a lightweight ADR toolset, see Nat Pryce's adr-tools at https://github.com/npryce/adr-tools.

これは Nygard 原典、GOV.UK、Apache James、Embedded Artistry、Cloud Posse など多くのプロジェクトにほぼそのままコピペで採用されている。

メタADRを1本にまとめるか分けるか:

• 1本派(多数派): adr-tools、Backstage、Apache James、GOV.UK 系。「ADRを記録する」というメタ決定だけを ADR-0001 にし、形式(Markdown / Nygard 形式)も同じADRで宣言。
• 複数本派: MADR 自身。0000-use-madr(形式選定)、0001-use-CC0-or-MIT-as-license、0002-do-not-use-numbers-in-headings、0005-use-dashes-in-filenames、0006-use-names-as-identifier、0008-add-status-field、0010-support-categories、0013-use-yaml-front-matter-for-meta-data、0017-use-same-format-for-outcomes-and-options、0018-use-confirmation-as-heading のように運用ルール1個=ADR1本で積み上げる(19本)。これは MADR が「ADRフォーマット自体の研究プロジェクト」であるための例外的構造で、一般プロジェクトには冗長すぎる。

3. 運用ガイドの配置: ADRで書くな、READMEで書け

結論: 運用ガイドは docs/adr/README.md に書く。これは Cloud Posse、Thunderbird Android、Cognitect/Nygard、GOV.UK の各プロジェクトに共通する。理由は次の3つ:

1. ADRはイミュータブルだが運用ルールは進化する。Accepted ADR を編集することは Nygard 原則違反だが、README は自由に編集できる。
2. GitHub がディレクトリの README を自動表示するので、docs/adr/ を開いた人が最初に読む文書になる。
3. GitHub の CONTRIBUTING.md 慣習との衝突を避けやすい。リポジトリルートの CONTRIBUTING.md は「コード貢献」、docs/adr/README.md は「ADR運用」と役割分担する。

4. テンプレートの配置: adr-tools 方式 vs MADR 方式

6. 実在プロジェクトの構造比較

9. アンチパターン早見表

Recommendations

個人開発(代表取締役のGAS会計システム想定): 明日から作る5ファイル

ステップ1(今日):

your-gas-accounting/
├── src/                              # GASコード
├── README.md                         # プロジェクトのREADME
└── docs/
    └── adr/
        ├── README.md                 # ADR運用ガイド + 目次
        ├── template.md               # ADRテンプレート(MADR minimal)
        ├── 0001-record-architecture-decisions.md
        ├── 0002-use-madr-minimal-format.md
        └── 0003-<最初の実技術選定>.md   # 例: 0003-use-clasp-for-deployment.md

拡張の分岐点(個人開発 → チーム開発への閾値)

やってはいけないこと(優先順)

1. ステータスごとのフォルダ分け(accepted/, superseded/)を絶対にしない
2. Accepted ADR の本文を編集しない(typo修正と broken link 修正を除く)
3. 運用ガイドを ADR に混ぜない。README.md に書く
4. 最初から MADR full テンプレを使わない。minimal で始める
5. 連番をリセット/スキップしない
6. ADR を Notion/Confluence/Google Docs に置かない(コードと同期しない)

Caveats

• 「ADR」という言葉の指す範囲は揺れている。狭義(Nygard原典: アーキテクチャ的に重要な決定のみ)と広義(joelparkerhenderson: any decision)があり、後者はディレクトリ名を decisions/ にすべきと推奨している。本レポートは狭義寄りで構成したが、代表取締役のGAS会計のような小規模プロジェクトでは「広義の決定」(ベンダー選定、料金プラン選定、API選定)も同じテンプレで書いて差し支えない。
• Log4brains が日付ベース命名(YYYYMMDD-)を採用しているのは、複数人開発でのマージ衝突回避が主目的。個人開発では連番が一意に振れるので連番でよい。チーム開発に移行する際は Log4brains 形式へ移行する ADR を書く判断もある。
• MADR 自身の 0000-use-markdown-any-decision-records.md というファイル名は MADR 3.x「Any Decision Records」時代の名残で、公式サイトの URL スラッグは 0000-use-markdown-architectural-decision-records.html と表記揺れがある。これは MADR プロジェクト内部の運用例外で、一般プロジェクトは ADR-0001 から始めるのが無難。
• adr-tools の最新リリースは 3.0.0(GitHub Releases で "Latest" 表示)。リリースノートには「Search parent directories for the ADR directory (see issue #62) / Better layout of generated graph visualisations」とあり、開発は継続している。ただし更新頻度は低めで、代替として adr-log(npm)、Log4brains、adr-manager が活発。
• GOV.UK は2025年12月に新しい ADR フレームワーク(GDS Enterprise Architecture チーム策定)を公開しており、英国公共セクター横断の意思決定では新フレームワークがマンデートされる。一般プロジェクトには無関係だが、英国公共セクター案件に関わる場合は要確認。
• 本レポートで言及した実プロジェクトのディレクトリ構造は2026年5月時点のもので、Backstage の docs/architecture-decisions/ などはツール側プラグイン(MADR v2/v3 デフォルト)との互換性を考慮して docs/adrs/ に移行する可能性がある。