← ADR 一覧へ残タスク一覧へ 最終更新: 2026/06/22 20:19
commonid: adr-0041type: adrstatus: accepted
pagemode: Standardkruchten: Property/Executivescope: platformimplementation_status: Done (docs/research/ 4 RQ doc + AGENTS…proposed_at: 2026-05-14 23:44approved_at: 2026-05-26 (Pipeline Web UI Standard 4…deciders: [email protected] (単独)business: meta
型付き辺: 出 9 / 入 0
関連: ADR-0033 ADR-0036 ADR-0038 ADR-0050 ADR-0052 ADR-0054 ADR-0058 ADR-0123 ADR-0039全体は INDEX →

ADR-0041: ドキュメント作成に型ファーストプロセスを義務化する

  • Status: Accepted
  • Mode: Standard
  • Scope: platform
  • Kruchten Type: Property/Executive
  • Implementation Status: Done (docs/research/ 4 RQ doc + AGENTS.md 改訂: PR #985、--check-template-exists: PR #997)
  • 起案者: [email protected]
  • 起案日時 (JST): 2026-05-14 23:44
  • 承認日時 (JST): 2026-05-26 (Pipeline Web UI Standard 48/50 通過、Gate 2 CONFLICT は retroactive 偽陽性として対応案 1 採択)
  • Review After: 2026-08-26 (3 ヶ月), 2026-11-15 (Phase 2 着手前), 2027-05-15 (1 年)
  • Deciders: [email protected] (単独)

1. コンテキスト

1.1 背景 (Background)

ADR-0039(docs構造をarc42+C4+MADR+feature-folderに刷新)Phase 1実装中(2026-05-14)、writing-guideとtemplatesをベストプラクティス調査なしで作成した。完成直後に2件の修正コミット(計6ファイル・+182/-34行)が発生し、「型を後から変えると遡及修正コストが高い」という問題が顕在化した。

1.2 現状 (Current State / As-Is)

  • templates初回作成(c4fe6dc)→修正完了(b17cb78)まで: 2コミット・6ファイル変更・約75分の手戻り
    • fix(docs-build): frontmatter stripping追加(SSGがYAML frontmatterをHTMLにそのまま出力するバグ)
    • feat: writing-guide.md新設・テンプレート3種に項番付与
  • _meta/templates/ に current-spec / research / itgc / spec の4種が存在するが、いずれも外部標準調査なしで作成
  • AGENTS.md の記載事項に根拠となる外部標準(Anthropic公式ガイド等)がない
  • 型(テンプレート)のない文書種別を作成しようとした場合の判断プロセスが未定義
  • adr-lint.mjs は現在161行。新規サブコマンドの追加実績(ADR-0038で6ルール追加)から実装工数を推定可能

1.3 課題 (Problem)

Phase 2では150+ファイルを新ディレクトリへ再配置する。型の定義が不安定な状態で進むと、移行完了後にwriting-guideの改訂→全移行済みファイルへの遡及修正という連鎖が発生する。Phase 1実測(6ファイル・75分)をPhase 2(150+ファイル)にスケールすると、最悪ケースで約31時間・期待値ベースで約17時間の手戻りリスクがある。

1.4 制約・要件 (Constraints & Requirements)

  • ソロ開発・業務並行のため調査フローは1型あたり最大2時間に収まること
  • 調査結果は docs/research/ に格納し再利用可能にすること
  • Claude Code・人間の両方が同じルールに従えること
  • 型の有無をCIで機械的に検証できること（対象: docs/ 配下の全.mdファイルのfrontmatter type フィールド）
  • 3者AIの月額API費用が既存予算(SaaS経費規程)の範囲内であること

1.5 目標 (Goals / To-Be)

「型なきドキュメントを作らない」状態を実現する: (1) すべての文書種別に _meta/templates/<type>.md が存在する (2) 新しい型を定義する前にGemini/Claude/GPT 3者リサーチを必須化する (3) 型の有無を adr-lint.mjs --check-template-exists でCI事後検証する

Non-goal: 既存の dev_mas-NNN.md（B2/B3/B5パイプライン管轄）の作成プロセスは変更しない

2. 決定

ドキュメント作成において「型ファーストプロセス」を義務化する。具体的には、(a) すべての文書種別は _meta/templates/<type>.md の存在を前提とする、(b) 新しい型を定義する前にGemini/Claude/GPT 3者によるベストプラクティスリサーチを行い結果を docs/research/rq-NNN-<topic>.md に格納する、(c) 型の有無を adr-lint.mjs --check-template-exists サブコマンドでCI事後検証する、の3点をAGENTS.mdおよびCIに組み込む。Phase 2着手前に既存4種テンプレートの遡及リサーチを完了させる。

3. 判断基準 (Decision Drivers)

ADR-0050 / ADR-0054 / ADR-0058 と同 Q42 5 軸 + WSM + K.O. criterion (Suhr 1999 CBA 準拠)。

3.1 評価軸

#軸重要度 (係数)案件特有の解釈
1#maintainable[Must] (×2.0)型 SSoT 一元化により Phase 2 で 17h 遡及修正回避、規約改訂時の伝播コスト最小化
2#suitable[Must] (×2.0)3 者 AI 月額 $1.4〜2.7、調査フロー ≤2h/型、SaaS 経費規程内
3#operable[High] (×1.0)Claude Code + 人間が同一 rule で動ける、属人化排除
4#reliable[High] (×1.0)adr-lint.mjs --check-template-exists で CI 機械検証
5#usable[Medium] (×0.5)起案者の負担 (初期遡及リサーチ 4-7h)、experimental 型 4 週間猶予で緊急時運用

K.O. criterion: Must 軸 (#maintainable / #suitable) score < 3 は不採用。

3.2 評価軸 × 案スコア表 + 加重和 (正規化分母 32.5)

加重和分子 = Σ (score × weight)、分母 = Σ (5 × weight) = (5×2 + 5×2 + 5×1 + 5×1 + 5×0.5) = 32.5

軸係数案A 現状維持案B 型ファースト(採用)案C 外部標準丸ごと案D 都度判断
#maintainable [Must]×2.01531
#suitable [Must]×2.01522
#operable High×1.01431
#reliable High×1.01431
#usable Medium×0.55443
加重和 (raw)8.530189.5
加重和算式 (採択 = 案B)(2+2+1+1+2.5)(10+10+4+4+2)(6+4+3+3+2)(2+4+1+1+1.5)
加重和 (正規化)0.2620.9230.5540.292
K.O. 通過 (Must ≥3)❌ #maint=1✓❌ #suit=2❌ #maint=1

採択首位 = 案B (加重和 0.923)。

4. 検討した代替案 (Alternatives Considered)

  • 採用案 (案B 型ファースト義務化): 月$1.4〜2.7 の API 費用で手戻りリスク排除、機械的 rule で Claude Code + 人間が同基準で動作、緊急時 experimental 型で 4 週間猶予確保 (加重和 0.923)
  • 案A: 現状維持 — K.O. (#maintainable=1、Phase 2 手戻り期待値 17h/最悪 31h を回避できない)
  • 案C: 外部標準丸ごと採用 (Diátaxis 等) — K.O. (#suitable=2、ADR-0039 §検討案B で「本プロジェクトの設計成果物に合わない」として却下済み)
  • 案D: 都度判断 — K.O. (#maintainable=1、プロセス属人化、Claude Code が一貫した rule で動けない)

5. コスト試算

3者AI選定理由: ADR-0039 Gate 3のGemini/Claude/GPT-4o構成を踏襲(ADR-0033で採用。3モデルが異なる学習データ・設計思想を持ち盲点を相互補完)。

5.1 1 RQ あたり想定 in/out トークン (×1.25 バッファの起点)

項目想定値根拠
Input tokens4,000リサーチプロンプト本体 (2,500) + 過去 ADR / 既存テンプレ参照 context (1,500)
Output tokens7,000詳細リサーチ回答 (6,000) + 3 ベストプラクティス比較サマリー (1,000)
安全バッファ×1.25想定超過時の許容率 (実測 1 RQ あたり 7,500-10,000 out 観測例あり)

5.2 モデル別 1 RQ コスト計算

モデルInput単価Output単価基本費用 = 4×単価 + 7×単価×1.25 バッファ
Gemini 1.5 Pro$0.00125/1K$0.005/1K4×$0.00125 + 7×$0.005 = $0.040~$0.050 (表記 $0.048 は丸め)
Claude Sonnet$0.003/1K$0.015/1K4×$0.003 + 7×$0.015 = $0.117~$0.146 (表記 $0.131 は基本ベース)
GPT-4o$0.005/1K$0.015/1K4×$0.005 + 7×$0.015 = $0.125~$0.156
合計/RQ (×1.25 込)~$0.34-0.40

5.3 月額・実装工数試算

月4〜8回想定: 月額 $1.4〜3.2（既存 AI 予算 SaaS 経費規程枠内）

実装工数:

  • 遡及リサーチ 4〜7h (既存 4 テンプレ × 1-1.75h/型)
  • --check-template-exists 実装 1.5〜2.5h
  • 合計 6〜10h

平均ケース: 約3h（既存テンプレートと外部標準の差異が軽微な場合） 期待値ベース手戻りリスク: 約17h → 投資対効果 ○ (回収期間 < 1 ヶ月)

6. 影響 (Consequences)

Good: Phase 2の遡及修正リスク排除 / CI自動検証 / RQドキュメントの再利用蓄積 Bad: 遡及リサーチ4〜7h + 実装1.5〜2.5hの初期投資 / 3者AI意見割れ時の裁定負荷 Neutral: dev_mas-NNN.md(B2/B3/B5管轄)は対象外 / 型上限20種で統廃合レビュー

6.1 長期影響シナリオ

  • experimental型滞留: 4週間以内に正規リサーチを完了できず滞留が複数発生した場合、Review After 2026-11-15で滞留件数を確認し2件超なら experimental 型を廃止してPhase 2着手要件に昇格修正
  • RQ陳腐化: Claude 4系等の世代更新タイミングを契機に主要RQドキュメントの再調査要否を判断。RQドキュメントに「3者の主要な意見差異」セクションを必須化し、形骸化を構造的に防止

6.2 frontmatter移行方針

CI導入時点でfrontmatter未設定の既存ファイルは warning扱い（PRをブロックしない）。移行期間最大4週間。期間中にfrontmatter付与または _meta/lint-ignore.txt 除外リスト登録を完了。4週後はerror化してPRブロック。docs/dev/ ディレクトリは除外リスト登録。

6.3 運用上の罠

  • 3者意見割れ時の裁定: 2者以上一致 → 多数決。全不一致 → 起案者裁定。裁定根拠をRQドキュメントの§1.サマリーに明記（レビュー時チェック）
  • experimental型の運用: _meta/templates/experimental.md（空テンプレート）を常設。使用後4週間以内に正規リサーチして昇格または廃止
  • 破壊的変更時: 変更前に git grep type: <type> で影響ファイル数確認。10ファイル超なら移行スクリプトを別PR
  • API障害時: 3者AIが利用不能な場合はarc42公式・Anthropic公式を直接参照して手動リサーチ（手順をAGENTS.mdに記載）

7. 撤退条件 (Rollback Plan)

  • Phase 2着手前撤退: 遡及リサーチ完了後、3者調査結果と現行テンプレートの差異が5項目未満 → 案Aに移行
  • CI撤退: 誤検知率PRあたり3件超×3週連続かつPR総数6件以上（週2件稼働前提）→ ルール縮退
  • ロールバック手順: (1)--check-template-exists 削除PR (2)CI workflow該当ステップ削除 (3)AGENTS.md記載削除 (4)research/*.md・templates/更新は保持

8. Confirmation (準拠確認 / Fitness Function)

  • 検証手段: adr-lint.mjs --check-template-exists。docs/ 配下全.mdのfrontmatter type フィールドと _meta/templates/<type>.md の存在を照合（warning/error二段階、.claude/worktrees/ および docs/dev/ は除外）
  • 実行頻度: PRごと（GitHub Actions、ADR-0038のworkflow設定を流用）
  • 完了判定: docs/ 配下で検出ゼロ（除外リスト適用後）
  • 3者意見一致率の記録: 月次で _nav/traceability.md に追記。判定式: 一致率 = 多数決成立件数 / 全RQ件数 × 100。記録フォーマット: YYYY-MM: RQ N件 / 一致 N件（率XX%）/ 起案者裁定 N件。集計主体: 起案者（月次Confirmation実施時）
  • ADR-0036 Confirmation準拠: 本CI検証が「決定の遵守をfitness functionで自動検証」する機構として機能

9. 参照 (References)

  • ADR-0039（補完関係: ADR-0039=「何を作るか」、本ADR=「どうやって作るか」）
  • ADR-0038（adr-lint.mjs実装パターンの先行事例）
  • ADR-0036（Confirmationセクション設計の根拠）
  • ADR-0033（Gemini/Claude/GPT-4o 3者並列レビュー構成の採用根拠）
  • PR #727（ADR-0039 Phase 1 / 手戻り実測: c4fe6dc→b17cb78）
  • PR #721（ADR-0038 adr-lint 6ルール追加・約3時間実績）
  • 外部資料: arc42公式 / IEEE 1063 / 経産省システム管理基準 / Anthropic CLAUDE.md公式ガイド（遡及リサーチで参照予定）

10. 参照: Pipeline 審査履歴 (2026-05-26 Web UI 実行時)

本セクションは Decision Pipeline (LangGraph TS on Cloudflare Workers) で本 ADR 草案を Web UI 経由で審査した結果のログ。sub session の curl 経由 audit は Cloudflare 100s edge timeout で Gate 1-4 完走不可 (ADR-0066 async polling 未実装、/chat/start 180s でも timeout)。Web UI が long-running pipeline を browser polling で handle するため Web UI 経由で実行。Standard 閾値 40 + Critical 閾値 45 双方クリアの 48/50 で通過。ADR-0056 §8 / ADR-0058 §11 / ADR-0062 §8 / ADR-0063 §8 / ADR-0070 §9 で確立した §audit history パターンの 第十適用例。デフォルトでは折りたたまれており、▶ をクリックで展開する。

📋 Pipeline 審査履歴 全 Gate 結果 (合格 Score 48 / 50, Gate 2 CONFLICT は retroactive 偽陽性で対応案 1 採択) — クリックで展開

Gate 2 CONFLICT (retroactive validation 偽陽性) の経緯と対応

operator prompt (docs/_internal/03_decisions/decision_pipeline/adr_0041_type_first_process_kv_submission_prompt.md) で「ADR-0041 全文を copy & paste」と指示。Pipeline Gate 2 は中身が ADR-0041 と完全一致と検出し、「Supersedes 宣言なしの重複起案」と判定 (差し戻し)。

これは retroactive validation の既知の偽陽性。ADR-0052 で /chat/create-pr には 422 guard を入れたが Gate 2 自体には適用されていない。本ドラフトは「ADR-0041 の audit 用再投入」であり「新規 ADR」ではないため、Pipeline 提示の対応案 3 つから 対応案 1 (ADR-0041 を進める = 本ドラフト取り下げ) を採択。Supersedes 宣言不要、Status: Proposed → Accepted で本 ADR を完了。

Gate 0-4 結果

  • Gate 0 Triage: needsAdr=true / triageMode=Standard (curl では Light、UI full audit で reclassify、ADR-0070 と同パターン)
  • Gate 1 Socratic: pass=true (追加質問 0 件)
  • Gate 2 Consistency: CONFLICT (ADR-0041 と重複検出、retroactive 偽陽性として対応案 1 採択)
  • Gate 3 Parallel Review: 3 vendor 出力は §改善余地 に要約
  • Gate 4 Scoring: 48 / 50
#採点項目点数コメント
1問題定義5起案日(2026-05-14)・コミット(c4fe6dc→b17cb78)・行数(+182/-34)・75分実測まで具体的。Phase 2の17h/31hも線形スケール仮定が明示されており追跡可能。
2代替案5A/B/C/Dの4案+却下理由+K.O.判定が揃う。ただし案Cの却下根拠がADR-0039 §検討案Bへの外部参照に依存し自己完結性はやや弱い。
3判断基準4加重和算式・K.O.基準・正規化分母は明示。ただし案Bは(10+10+4+4+2)/32.5=0.923が正しく、表中「0.918」と不整合。再現時に検算が止まる (本 PR で §3.2 加重和算式 0.923 + 計算過程明示で修正)。
4過去ADR整合性5ADR-0039(補完)/0038(先行事例)/0036(Confirmation根拠)/0033(3者AI根拠)を役割別に分類して参照。
5影響範囲5対象(docs/全.md)・除外(dev_mas/docs/dev/worktrees)・移行方針(warning→error 4週猶予)が網羅。ステークホルダー(ソロ+Claude Code)も明示。
6運用上の罠5意見割れ(2者一致→多数決)/experimental滞留(4週)/破壊的変更(10ファイル超で別PR)/API障害(手動手順)の4観点が具体的閾値付き。
7ロールバック5撤退条件(差異5件未満/誤検知3件×3週×PR6件以上)と4段階手順、研究成果物の保持方針まで明示。
8コスト試算4モデル単価・1RQ費用($0.34)・月額($1.4〜2.7)・実装工数(6〜10h)は提示。ただし1RQあたり想定入出力トークン数が未記載で「×1.25バッファ」の起点が不明。検算不可 (本 PR で §5.1 にトークン内訳 4k in/7k out + §5.2 計算式 + ×1.25 適用明示で修正)。
9完了条件5CI工具・PR毎実行・warning/error二段階・docs/配下検出ゼロ・3者一致率の月次測定式(多数決成立件数/全RQ件数)まで定義。
10長期影響5Review After 2026-11-15、experimental滞留2件超で廃止、型上限20種、Claude世代更新トリガでRQ再調査と複数の自己破綻防止策。

合計: 48 / 50 (Standard 閾値 40 → PASS, Critical 閾値 45 → PASS)

改善余地 (本 PR で全 2 件反映済)

#指摘反映先効果
1案B加重和が表「0.918」だが正しくは (10+10+4+4+2)/32.5=0.923§3.2 加重和算式明示 + 正規化分母 32.5 計算式追加判断基準 4/5 → 5/5 見込
21RQ 想定 in/out トークン未記載で ×1.25 バッファ起点不明§5.1 にトークン内訳 (4k in / 7k out + バッファ根拠) + §5.2 計算式コスト試算 4/5 → 5/5 見込

改善効果見込: 48/50 → 50/50 達成可能性。Gate 2 CONFLICT は retroactive 偽陽性につき対応案 1 採択で確定 (再投入不要)。

Status 遷移

  • v1 起案 (2026-05-14 23:44) → Proposed として PR 起案、本文確定
  • (2026-05-26 sub session) curl /chat/start audit → 180s timeout で Gate 1-4 未完走、Cloudflare 100s edge timeout
  • triageOnly curl → 13.5s で needsAdr=true / triageMode=Light 部分確認
  • operator prompt 作成 → user が Web UI 経由で full audit 実行
  • Web UI full audit → Standard 48/50 PASS、Gate 2 CONFLICT (retroactive 偽陽性、対応案 1 採択)
  • Status: Proposed → Accepted (本 PR で改善 2 件反映 + §10 audit history 追加)