最終更新: 2026/06/22 18:56
RQ-042 ADR コンテキスト・サブセクション構造化 (Synthesis: 両回答突合 + bizlp 採択方針 / ADR-0024 起案準備)
調査日: 2026-05-12 方式: Claude Research + Gemini Deep Research 並列、本ドキュメントで突合 問い: ADR テンプレートの §1 コンテキストをサブ見出しに分解する事例・ベストプラクティス・bizlp 文脈での実用テンプレートは?
1. 両エンジンの結論サマリ
| 観点 | Claude | Gemini | 一致度 |
|---|---|---|---|
| 5項目分解の正当性 | Tyree & Akerman / MADR / arc42 / Cloud Posse / Azure WAF から正当化可能 | Nygard 単一節の限界 (歴史/現状/要件の混在) を3時間軸で分析 | ✅ 完全一致 |
| 推奨サブ項目名 | 背景 / 現状(As-Is) / 課題 / 制約・要件 / 目標(To-Be) | 背景 / 現状 / 課題 / 要求 / 目標 | ✅ 完全一致 (語彙差のみ) |
| 過剰構造化リスク | Olaf Zimmermann のアンチパターン (Mega-ADR / Blueprint in Disguise) を警告 | 「巨大な文書は更新されない」Nygard 警告を強調 | ✅ 完全一致 |
| 小規模プロジェクト対応 | Mini-ADR と Full-ADR の使い分け、項目削除許容 | 必須項目と任意項目の柔軟運用、「―」デフォルト | ✅ 完全一致 (アプローチ差) |
| 不変性原則 | Accepted 後は誤字修正のみ、Supersede で更新 | Append-only ログ、Superseded/Deprecated リンク | ✅ 完全一致 |
| AI 連携の機械可読性 | 言及なし | LLM による ADR ライター、構造化が精度向上 | △ Gemini 独自 |
| 適合度関数 (Fitness Functions) | 言及なし | 目標・要求を将来の客観的再評価トリガーとして再利用 | △ Gemini 独自 |
| 境界オブジェクト概念 | 言及なし | 非技術系ステークホルダーとのアライメント手段として明示 | △ Gemini 独自 |
| Tyree & Akerman 14項目フル版 | 「個人開発には重すぎる」と明確に却下 | 言及なし | △ Claude 独自 |
| 日本国内事例 | Wantedly / kawasima / NIFTY / CAMPFIRE / sgrokym / laiso 等 6 事例列挙 | 言及なし | △ Claude 独自 |
| Mini-ADR / Full-ADR 切替基準 | 5項目チェックリスト ("6-12 ヶ月後に再議論しそうか" 等) | 影響範囲の大小で柔軟運用 (粒度は明示せず) | ✓ 部分一致 (Claude が具体的) |
両エンジン完全一致: コンテキスト 5 項目分解の構造、アンチパターン警告、不変性原則、柔軟運用。 bizlp 文脈で採用: 完全一致部分 + Claude の「項目削除許容」「Mini/Full 切替基準」+ Gemini の「機械可読性 / 適合度関数」観点を併用。
2. bizlp-gas-accounting への適用方針
2.1 採用する 5 項目構造
現行テンプレート (docs/adr/templates/template.md) の §1 コンテキストには既に "詳細起案では §1.1〜§1.5 (現状 / 課題 / 要求 / 前提条件 / 制約条件) に分割可" とコメントがあるが、これを 明示的なサブ見出しとして正式採用 する:
## 1. コンテキスト
### 1.1 背景 (Background)
<経緯・きっかけ 1〜2文>
### 1.2 現状 (Current State / As-Is)
<今どうなっているか 1〜2文>
### 1.3 課題 (Problem)
<痛みポイント・具体的数値 1〜2文>
### 1.4 制約・要件 (Constraints & Requirements)
- <箇条書き 2〜5項目>
### 1.5 目標 (Goals / To-Be)
<To-Be 像 1〜2文 + Non-Goals>
2.2 §5 影響 (Consequences) サブ構造の整理
現行テンプレートの §5 にも「詳細起案の場合のみ §5.1〜§5.6 に分割可」のコメントがある。これも明示的に標準化:
## 5. 影響 (Consequences)
### 5.1 正の影響 (Good)
- ...
### 5.2 負の影響 (Bad) ← 必ず 1 行以上
- ...
### 5.3 中立 / トレードオフ (Neutral / Trade-offs)
- ...
2.3 Mode 別の適用粒度
両エンジン共通の「過剰構造化リスク」を踏まえ、現行 Mode 区分と整合させる:
| Mode | コンテキストサブ見出し | 影響サブ見出し |
|---|---|---|
| Light | §1 単一節のまま (30-80 行 ADR で5分割は重い) | §5 単一節のまま |
| Standard | §1.1〜§1.5 を採用 (推奨) | §5.1〜§5.3 を採用 (推奨) |
| Critical | §1.1〜§1.5 を採用 (必須) | §5.1〜§5.3 を採用 (必須) |
| Initial Master | §1.1〜§1.5 + α (§1.6 判断基準等の独自拡張可) | §5.1〜§5.6 (フル分解) |
2.4 「該当なし」項目の扱い
Claude が推奨する「不要なサブ見出しは消す派」 + Gemini が言及する「デフォルト『―』派」の折衷:
- 空欄のまま見出しだけ残すのは禁止 (Blueprint in Disguise 化)
- 該当なしの項目はサブ見出しごと削除 (Claude 派)
- ただし、削除した場合は §1.6 等の番号は前詰めにしない (§1.1, §1.3, §1.5 等の歯抜けを許容、判断したことの記録として)
2.5 既存 ADR への適用
- ADR-0001〜0023 は不変 (イミュータブル原則)。サブ見出し追加目的の編集は禁止
- 新規 ADR-0024 以降 に本決定を適用
- ADR-0021 (UC スライス) は既に §1.1〜§1.6 構造を採用済 → 本決定の先行事例として位置付け、テンプレート設計のリファレンスとする
3. 影響範囲
3.1 改修対象
| ファイル | 改修内容 |
|---|---|
docs/adr/templates/template.md | §1 / §5 のコメント記述を正式なサブ見出し例に昇格 |
docs/adr/README.md | §運用ガイドの「Mode 別の構造」に粒度表を追加 |
3.2 不変対象
- ADR-0001〜0023 の本文 (イミュータブル原則)
- Decision Pipeline (
drp/) の Triage / Socratic / Consistency 等のノード (構造変更は Mode 判定に直結する可能性あり要確認)
3.3 オプション (追加検討)
- Decision Pipeline の
socratic.ts等で、Critical Mode 時に「§1.1〜§1.5 の各項目が埋まっているか」を Gate チェック項目に追加 → 本 ADR スコープ外、別途 Pipeline 改修 ADR で
4. 採用に伴うトレードオフ
| 捨てるもの | 理由 |
|---|---|
| ADR 起案の自由度 | サブ見出しが Standard 以上で必須化 → Light Mode を温存することで柔軟性確保 |
| 1〜2 文ルール違反時の運用負荷 | サブ見出しが増えると各項目を埋めたくなる衝動 → README に「1〜2 文制限」を明文化 |
| 既存 ADR との見た目の不統一 | ADR-0001〜0020 は単一節、ADR-0021 以降は分割 → イミュータブル原則優先 |
5. 完了条件
- ADR-0024 (本 ADR) が Accepted 化
docs/adr/templates/template.mdの §1 / §5 が正式サブ見出し構造に更新docs/adr/README.mdに Mode 別の構造粒度表が追加- 次回の Standard Mode 以上 ADR 起案で、新サブ見出し構造が実用されることの動作確認
6. 撤退条件 / 再評価トリガー
| トリガー | 対応 |
|---|---|
| サブ見出し導入後、ADR 起案が手間で月次起案数が半減 (現状ベース) | サブ見出しを必須から推奨に格下げ |
| 「該当なし」サブ見出しが新規 ADR の 50% 以上で発生 | 5項目分解を Critical 専用に縮退、Standard はオプション化 |
| 削除サブ見出しの歯抜け番号 (§1.1, §1.3 等) が読みにくいフィードバック発生 | 番号は前詰めし直す方針に変更 |
| Decision Pipeline Triage / Socratic が新構造で誤動作 | Pipeline 側の改修 ADR で対応 (本 ADR の決定は撤退不要) |
7. 参照
docs/_internal/research_prompts/RQ-042_adr_context_subsection_structuring_result_claude.mddocs/_internal/research_prompts/RQ-042_adr_context_subsection_structuring_result_gemini.md- 関連 ADR: ADR-0023 (ADR 構造業界標準化 / 本 ADR の前提)、ADR-0021 (UC スライス / §1.1〜§1.6 構造の先行事例)
- 外部資料:
- MADR 4.0.0: https://adr.github.io/madr/
- Tyree & Akerman (IEEE Software 2005): DOI 10.1109/MS.2005.27
- Y-Statement (Zdun et al., IEEE Software 2013): DOI 10.1109/MS.2013.97
- Olaf Zimmermann ADR Anti-patterns: ozimmer.ch (practices archive, "How to create ADRs — and how not to" 2023-04-03; 正確な URL は ozimmer.ch/practices で検索)