設計根拠 (Theoretical Foundation) の書き方 (citation 形式 / Mode 別網羅レベル / URL 生成禁止原則)
目的: ADR / 主要 README に「設計根拠 (Theoretical Foundation)」を書く際の citation 形式 + 出典タイプ別の信頼度評価 + Mode 別の網羅性ガイドラインを集約。 対象: ADR 起案者 + 主要 doc 執筆者 (社内メンバー / 業務委託パートナー / 代表取締役 / AI Agent) 読了時間目標: 15 分以内 (Jr 入社 2026-10 onboarding 主参照)
1. なぜ設計根拠が重要か
| 観点 | 設計根拠なしのリスク | 設計根拠ありの効果 |
|---|---|---|
| Bus factor | 起案者が離脱すると「なぜこの形か」が失われる | 原典に立ち戻れる |
| Jr onboarding (2026-10) | 暗黙の判断軸を 1 件ずつ説明する必要 | 原典を読めば前提を再現可能 |
| AI Agent grounding | Claude 5+ など世代交代で文脈ロスト | 原典 URL から再 verify 可能 |
| ADR longevity | 6-12 ヶ月後の再議論で前提が揺らぐ | 原典に当たって再評価できる |
| drift 防止 | 引用なしの主張は時間とともに弱体化 | 原典で再確認できる |
2. 出典タイプ別 citation 形式
CLAUDE.md「URL 生成禁止 (programming help 例外)」原則遵守のため、信頼度の高い順に推奨形式を以下に整理。記憶や推測で URL を作らない。確信がない場合は author/year/title だけ書いて URL は空欄にし、注記する。
2.1 信頼度: 高 (canonical / 永続識別子)
| タイプ | 推奨形式 | 例 |
|---|---|---|
| 公式 canonical site | [名称](https://公式ドメイン/) | [arc42](https://arc42.org/) / [MADR](https://adr.github.io/madr/) |
| arXiv 論文 | Author et al. (Year) — "Title". arXiv: [NNNN.NNNNN](https://arxiv.org/abs/NNNN.NNNNN) | Zheng et al. (2023) — "Judging LLM-as-a-Judge with MT-Bench...". arXiv: [2306.05685](https://arxiv.org/abs/2306.05685) |
| 論文 DOI | Author et al. (Year) — "Title". DOI: [10.xxxx/yyyy](https://doi.org/10.xxxx/yyyy) | Kruchten et al. (2006) — "Building Up and Reasoning About Architectural Knowledge". 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) |
2.2 信頼度: 中 (canonical だが永続性は劣る)
| タイプ | 推奨形式 | 注意 |
|---|---|---|
| 公式 blog (canonical author) | Author (Year) — [Title](URL) | URL 移転リスクあり、Wayback Machine snapshot 併記推奨 |
| GitHub Issue/PR | [repo#NNN](URL) または gh repo view ... | private repo は API URL 不可 |
| Wikipedia (well-established 概念) | [Title](https://en.wikipedia.org/wiki/Title) | 編集される可能性、判断軸の説明用に限定 |
2.3 信頼度: 低 (生成・推測したら NG)
| タイプ | 対応 |
|---|---|
| author/title は知っているが URL 不明 | URL 空欄で author/year/title だけ書く、注記 (URL 未確認、起案者要追加) |
| 内部メモ / Slack DM | 引用しない、引用先を ADR / how-to に formalize してから引用 |
| 記憶ベースの「あの論文」 | 引用しない、WebFetch / WebSearch で verify してから引用 |
重要: 確信がない URL を「ぽい URL」で書かない。Lint で検出されない false reference は最悪のドキュメント負債。空欄 + 注記が常に正解。
3. Mode 別の網羅性ガイドライン
ADR Mode (Light / Standard / Critical) と Pipeline Score 10 項目 #10 (長期的影響の言及) に応じた設計根拠の網羅レベル:
| Mode | 設計根拠の網羅レベル | 例 |
|---|---|---|
| Light | 省略可 (1 行の関連 ADR 参照で OK) | Refines ADR-NNNN のみ |
| Standard | 最低 1 件、判断軸の出典または採用 FW の canonical URL | arc42 / MADR / Nygard のいずれか |
| Critical | 最低 3 件 (判断 FW + 採用論文 + 撤退判断の根拠) | arc42 + Suhr 1999 + Zheng 2023 等 |
Pipeline の Gate 4 Scoring #10 (長期的影響の言及) で「Review After 日が設定されているか」と並んで「設計根拠の verifiable 性」が判定されると 1〜2 点上乗せ。Critical Mode で根拠ゼロは 0/5 になりやすい。
4. References セクションの位置と粒度
4.1 ADR 本文中の §7 References (起案時)
ADR テンプレ §7 References (docs/adr/templates/template.md 参照) で:
- §7.1 プロジェクト内参照 (関連 ADR / PR / Issue / RQ)
- §7.2 設計根拠 (Theoretical Foundation) — Standard/Critical 推奨
の 2 構造で書く。本文中で「Q42 9 タグを採用」「Suhr CBA を踏襲」などと言及した時点で §7.2 に出典を追加。
4.2 主要 README の「設計根拠」章 (分散根拠を集約)
複数 ADR で同じ FW を引用している場合、主要 README に独立した ## 設計根拠 (Theoretical Foundation) 章を作って集約推奨。例:
docs/_internal/03_decisions/decision_pipeline/README.md§設計根拠 — Pipeline 全体の grounding を 1 箇所に集約 (ADR-0019 / 0023 / 0030 / 0050 で個別引用されていた論文・FW を統合)
集約の判断基準:
- 同じ canonical site / 論文を 3 ADR 以上で引用 → 主要 README に集約
- ADR 1-2 件しか引用しない → ADR §7 References に個別記載のみ
4.3 1 出典 = 1 行 = 1 URL 原則
各エントリは 1 行で完結させ、複雑な説明が必要な場合は別 doc (docs/_internal/04_specs/<topic>.md 等) に切り出す。本セクションは「探せる」「verify できる」が目的、解説ではない。
5. Quick Checklist (起案前)
ADR / 主要 README に設計根拠を追加する前に:
- 各 URL は canonical / arXiv / DOI / ISBN か? (記憶推測 URL でないか)
- author/year/title が正確か? (WebFetch で 1 件は verify 済)
- Mode に応じた網羅レベルか? (Light: 省略可 / Standard: 1+ / Critical: 3+)
- 主要 README に集約済の出典を再度個別 ADR で長々と書いていないか? (1 行参照 + main README link で OK)
- CLAUDE.md「URL 生成禁止」原則に違反していないか?
- §7.2 に書いた根拠が本文 §決定・§判断基準で実際に参照されているか? (孤立 reference は削除)
6. アンチパターン
| パターン | 何が問題か | 対処 |
|---|---|---|
| 「あの論文」記憶ベース | 著者・年・タイトルが曖昧、URL もない | 引用を諦めるか、WebFetch / WebSearch で verify |
| 「ぽい URL」生成 | リンク先が存在しない / 別物に変わる | URL 空欄 + 注記、CLAUDE.md 原則違反 |
| References 肥大化 | 引用したフリで主張に紐づかない出典が並ぶ | 本文で実際に依拠した出典だけに絞る |
| 同一 FW の重複記載 | 3 ADR で同じ arc42 を引用、毎回別の URL | 主要 README に集約、ADR は 1 行参照のみ |
| publisher / 年欠落 | Suhr CBA だけで誰の何年版か不明 | 完全な citation 形式で書く |
| Wayback なし URL | blog 移転で dead link | canonical でも長命でない URL は WebArchive snapshot 併記 |
7. 関連ドキュメント
- ADR テンプレ §7 References: 本 doc の citation 形式が組み込まれた起案テンプレ
- Decision Pipeline README §設計根拠: 集約型「設計根拠」章の参考実装 (4 カテゴリ 11 件)
- ADR-0023: ADR フォーマット標準化 + Nygard / MADR 引用
- ADR-0050: Synthesis 標準テンプレート + Suhr 1999 CBA + arc42 Q42 引用
- ADR-0030: Kruchten 3 分類採用 + 原典 DOI 引用
- CLAUDE.md「URL 生成禁止」原則 (Session Guidance 参照)