• Status: Accepted
  • Mode: Standard
  • Kruchten Type: Existence/Property
  • Scope: platform
  • Implementation Status: Not Started
  • 起案者: t_saitoh
  • 起案日時 (JST): 2026-06-04 21:35
  • 承認日時 (JST): 2026-06-04 (PR #1438 merge = 受理)
  • Deciders: t_saitoh (単独)

決定の早わかり(Y-statement)

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

  • 文脈: DRP(意思決定 審査パイプライン)の説明書は 749 行の単一 README に概要・設計原則・アーキテクチャ図・ゲート表・運用情報が混在している。RQ-095(3 モデル Deep Research)で層別ドキュメント体系のベストプラクティスを調査済み。
  • 問題: 改修時に「ビジネス要件まで変わる改修か、内部設計のみか」を事前判定できない。仕様の一覧性がなく改善点の把握が属人的で、変更影響範囲の特定が困難。
  • 問題点と課題(直せる原因 → 発生を止めるためにやること):
    • 要求定義〜内部設計の層が分離されておらず、更新すべき文書層を判定できない → 9 層カタログ + L1〜L4 変更影響分類で再編し、PR テンプレートで影響層を宣言する。
    • 層別文書が独立して存在せず、変更影響範囲の特定が困難 → ID 体系 8 種と Covers: / Verified-by: の一方向参照でトレーサビリティを持たせる。
    • 手書きトレーサビリティマトリクスは matrix rot を起こす → マトリクスは CI 生成とし、手書き・コミットを禁止する。
  • 前提(解決を課題に立てない与件):
    • ADR-0039 の arc42 骨格・feature-folder 構造は不変(本起案は Refine)。既存 ADR 本文は追記のみで書き換えない。
    • 本体系の維持作業は Claude Code エージェントが実行し、人間の役割は PR レビューでの最終承認のみとする。
    • ADR インデックス自動生成は既存計画 MAS-367/368 に合流させる(重複起案しない)。
  • 決定(対応策): 一括ビッグバン・README 分割のみ・重量 RM ツール・RDRA 2.0 全面採用(案 a〜d)でなく、9 層カタログ + 8 種 ID 体系 + L1〜L4 変更影響分類で再編する。適用範囲は decision_pipeline ドキュメントに限定し、移行は strangler-fig の 3 Phase(合計 7.5 人日)で進める。
  • 目的: 改修時の更新範囲を事前判定可能にし、CI lint でトレーサビリティを機械保証できる体系へ移行する。仕様一覧性とエージェントのコンテキスト取得効率も上げる。
  • 代償: 初期導入 7.5 人日 + 維持 1.0 人日/年(5 年 TCO 12.5 人日)。移行の中間状態でリンク網の分断リスクがあり、lint green でも内容陳腐化を見逃す構造的リスクが残る。
  • 詳細は本文の影響・撤退条件セクションを参照のこと

コンテキスト

§1.1 背景

DRP(意思決定 審査パイプライン)の説明書は 749 行の単一 README に概要・設計原則・アーキテクチャ図・ゲート表・運用情報が混在しており、要求定義 / ビジネス要件 / システム要件 / 外部設計 / 内部設計の層が分離されていない。RQ-095(3 モデル Deep Research、synthesis: docs/research/rq-095-drp-layered-docs-architecture.md、結果 PR #1404・synthesis PR #1408)で層別ドキュメント体系のベストプラクティスを調査済み。

3 モデル一致点:

  1. 単一標準でなくハイブリッド(ISO/IEC/IEEE 29148 の層名 + 日本流の外部/内部設計 + arc42 骨格 + 既存 ADR 維持)
  2. 外部/内部の境界は「外から観測可能な契約か」
  3. ID + 上方向 Covers: 参照のみ・トレーサビリティマトリクスは手書き禁止で CI 生成
  4. ADR は「なぜ」の層で要件・設計を再記述しない
  5. 移行は strangler-fig(抽出と同一コミットで旧 README から本文削除)

§1.2 現状 (As-Is)

DRP ドキュメントは 749 行の単一 README に概要・設計原則・アーキテクチャ図・ゲート表・運用情報が混在。データ定義書・API 仕様書・プロンプト仕様書・テスト設計書は独立文書として存在しない。

§1.3 課題

(1) 改修時に「ビジネス要件まで変わる改修か、内部設計のみか」を事前判定できない、(2) 現在の仕様の一覧性がなく改善点の把握が属人的、(3) 層別文書が独立して存在しないため変更影響範囲の特定が困難。

§1.4 制約・要件

関連 ADR と整合性

  • ADR-0039(arc42 + C4 + MADR + feature-folder 文書構造): 本起案は arc42 骨格を維持したまま decision_pipeline 配下を層別カタログに再編する Refine。feature-folder 構造・C4 ビューの採用は不変。Supersede ではない。
  • ADR-0045(docs/_internal 文書管理ポリシー): 再編は 03_decisions 配下のステージ区分内で行い、人間手順書 = 05_how-to の区分も維持(整合)。
  • ADR-0023(ADR 構造の標準化 Nygard+MADR minimal): ADR frontmatter に Covers: / Constrains: フィールドを追加する Refine。Nygard 形の本文構造・既存 ADR 本文は不変(追記のみ・書き換えなし)。
  • ADR-0102(審査深度の Tier 化): DRP Triage(Light/Standard/Critical)は「審査の厳しさ」、本起案の L1〜L4 は「更新すべき文書層」で直交(Conflict なし・相互補完)。
  • ADR-0114(docs 概要ページ冒頭規約・受理済 2026-06-04): 本体系の §0 入口層の冒頭書式を規定。ADR-0115(AI エージェント知識レイヤ規約・受理済 2026-06-04): 知識の置き場所のメタ規約で、本起案の運用主体前提(エージェントが維持する)と同一の前提に立つ。エージェント向け入口ドキュメントは §0 入口層に置き ADR-0115 の層構造と統合する。いずれも本起案と矛盾せず補完関係。
  • MAS-367/368(ADR 抽出器 + adr-index.json 計画): 本起案の「ADR インデックス自動生成」はこの既存計画に合流させる(重複起案しない)。

Jr オンボーディング手順(2026-10 入社予定への引き継ぎ要件・Policy Alignment 必須対応)

Jr(または初見のエージェントセッション)は 用語集 → ID 規約 → L1〜L4 分類ガイド → 9 層カタログ索引 の順で読む。この導線を §0 入口層に明記し、読解所要は 0.5〜1.0 人日と見積もる(数値の根拠と Phase 完了条件への組込みは §コスト試算 参照)。「1 人 + AI」前提が崩れた場合(エージェント基盤変更・長期障害)の人間運用切替手順は §撤退条件 に定義する。

運用主体の前提(認知負荷の帰属 — 本体系は人間の作業記憶で運用しない)

本体系の維持作業(L1〜L4 分類判断・Covers/Verified-by 付与・ID 採番・カタログ棚卸し・トレーサビリティ確認・strangler-fig 抽出)は Claude Code エージェント(main/sub ワークスペース)が実行する。人間(代表取締役)の役割は PR レビューでの最終承認のみで、毎 PR の分類・参照付与を人手で行う運用は最初から想定しない。エージェントはセッションごとに ID 規約・カタログ定義を読み込んで機械的に適用するため、「単一開発者の作業記憶 7±2 チャンク」の制約は本体系には適用されない。9 層・8 種 ID はむしろエージェントのコンテキスト取得効率を上げるための分割であり(必要な層のファイルだけを読み込める)、DRP ドキュメントの主たる読者・運用者は人間でなく LLM エージェントである(ADR-0115 知識レイヤ規約と同じ前提。エージェント向け入口は §0 入口層に集約し ADR-0115 の層構造と統合する)。

人間の認知負荷はこの再編で削減される(一覧性向上・更新範囲の事前判定・レビュー対象の限定)。残るリスクは「エージェントが規約を形だけ適用し、意味のない Covers 参照が lint green のまま増殖する」形骸化であり、これは認知負荷でなく検知の問題として以下で対策する:

  1. 形骸化検知指標: 四半期ごとに Covers 参照 10 件を無作為抽出し、参照先の意味的整合(現役 ID か・カテゴリ適合か)をエージェント監査 + 人間レビューで確認。不整合 2 件以上で棚卸し前倒し
  2. 「L3 宣言のうち実際に ADR が作成された比率」を計測し、宣言だけの形式記入を検出
  3. L1〜L4 一致率の測定は Phase 3 後の 5 件でなく Phase 1 完了直後から全 PR を対象に収集し、最低 20 件のサンプルで評価する

§1.5 目標 (To-Be)

DRP ドキュメントを 9 層カタログ + 8 種 ID 体系 + L1〜L4 変更影響分類で再編し、改修時の更新範囲を事前判定可能・CI lint でトレーサビリティ機械保証可能な体系へ移行する。Non-Goals: GAS 会計本体 docs への展開(成功評価後の別 ADR)・DRP 実装コード変更・他コンポーネントへの ID 体系流用。

決定

DRP ドキュメントを 9 層カタログ + 8 種 ID 体系 + L1〜L4 変更影響分類 で再編する。適用範囲は decision_pipeline ドキュメントに限定し、ADR frontmatter への Covers:/Constrains: 追加のみ ADR 全体に横展開する。トレーサビリティマトリクスは CI 生成(手書き禁止・YAML/Markdown パーサーベース lint)、移行は strangler-fig の 3 Phase(合計 7.5 人日)で進める。維持作業は Claude Code エージェントが実行し、人間はレビュー承認のみを担う。

決定の構成要素:

  1. 9 層カタログへの再編(synthesis §5 の 41 文書カタログを正典): 入口・概要 / ビジネス要求 / システム要件 / 外部設計 / 内部設計 / アーキテクチャビュー(図はここに集約し各層から参照のみ)/ 決定(ADR)/ 検証(テスト)/ 品質・リスク・運用。

    • 横断要素 3 点の適用範囲: ①ADR frontmatter の Covers:/Constrains: フィールド追加は ADR 全体に適用(既存 ADR は追記のみ)②PR テンプレートの L1〜L4 チェックは decision_pipeline 配下の docs 変更を含む PR のみ必須(それ以外の PR は記入不要と明記)③CI lint のスキャン対象は docs/_internal/03_decisions/decision_pipeline/ に限定し、ID 体系の他コンポーネントへの非公式流用は本 ADR 違反とする(将来の全社展開時はスコープ修飾子 DRP-BR-001 形式を別 ADR で導入)。
  2. ID 体系 8 種を導入: BR- / SR- / NFR- / UC-(既存採番を流用)/ EDD- / IDD- / TC- / ADR-(既存)。参照は下層→上層の Covers: と テスト→対象の Verified-by: の一方向のみ。

  3. トレーサビリティマトリクスは CI 生成: 手書き・コミット禁止。lint は grep でなく YAML/Markdown パーサーベースで実装し(コードブロック内 ID・複数行 YAML・全角文字の境界値をユニットテストに含める)、orphan ID・リンク切れを検出。lint が保証するのは構文的存在確認のみ(参照先が現役で適切かの意味的整合は保証しない = 必要条件であって十分条件でない)と明記し、意味的整合は四半期サンプリング監査と半年毎棚卸しで担保する。既存 ADR の orphan は warning(別ファイル出力)・新規 ADR は error と severity を段階化し、警告慣れによる見逃しを防ぐ。

    • lint 検出対象パターンの明示: ID 参照は frontmatter の Covers/Verified-by フィールド限定で検出。散文中の ID 文字列は検出対象外であることを ADR・エージェントプロンプト・lint ユニットテストに明記し、「ID 参照は必ず frontmatter に記載し散文中への記載を禁止する」をエージェント指示に追加。
  4. L1〜L4 変更影響分類を PR テンプレートに導入: L1=ビジネス要件 / L2=システム要件 / L3=外部設計(ADR 必須)/ L4=内部設計のみ。迷ったら L3 扱い。L4 自動判定の除外リスト*.test.ts のみの変更・docs 誤字修正・コメント行のみ)を定め、該当 PR は記入をスキップ可能にする(分類はエージェントが diff から自動提案し人間は承認のみ)。各レベルに再実行テスト層(受入=Confirmation / システム=TC 系 / 契約=golden eval / 単体=vitest)を対応付ける。

  5. 検証層(TC-)を一級レイヤとする: テスト計画書・層別テスト設計書を新設し、既存資産(test_cases.md・golden eval・vitest・Web UI e2e)を層に写像する。

  6. 移行は strangler-fig の 3 Phase:

    • Phase 1 = must-have 8 項目(用語集 / ID 規約 / BR≥3 / ゲート別 SR / ADR テンプレ Covers 対応 / README ハブ化 / CI lint / PR テンプレ L1-L4)
    • Phase 2 = 外部設計 4 分冊 + OpenAPI + テスト計画
    • Phase 3 = 内部設計移行 + 被参照上位 20 ADR への Covers 後付け
    • 抽出したら同一コミットで旧 README から本文を削除しリンク化する。
    • 移行コミットは docs: [strangler-fig phase N] extract <doc> プレフィックス + 移行元行番号範囲をメッセージに記録し、移行前 README は docs/_internal/archive/ にスナップショット保存(blame/bisect の文脈喪失対策)。
    • マージ直後のリンク切れ検出 CI ジョブ: 各 Phase のマージ直後に全 Markdown 内リンクの到達確認を行う CI ジョブ(lychee または markdown-link-check)を GitHub Actions に追加し、リンク切れが 1 件でも存在する状態では次フェーズの PR をマージ不可にするブランチ保護ルールを設定。
  7. 完了条件を定量化: README ≤150 行(80% 以上がリンク/見出し)・README 内の正典コンテンツ残存 0・BR/SR/NFR の Covers 解決率 100%・新規 ADR の Covers 付与 100%・外部契約の OpenAPI/JSON スキーマ化 100%。

判断基準 (Decision Drivers)

3.1 評価軸

#重要度 (係数)案件特有の解釈
1#maintainable[Must] (×2.0)改修時に更新すべき文書層を事前判定可能か。手書きマトリクスでは matrix rot が発生するため CI 生成が必須
2#operable[Must] (×2.0)エージェントが機械的に維持できるか。lint で形式整合が機械保証され、形骸化検知が運用フローに組込まれているか
3#suitable[High] (×1.0)ソロ開発 docs-as-code に適した粒度か(重量 RM ツールでなく plain Markdown + CI lint)
4#flexible[High] (×1.0)strangler-fig による段階的移行が可能か。各 Phase 単独で価値を出せるか
5#reliable[Medium] (×0.5)リンク切れ・orphan ID・内容陳腐化の検知メカニズムが多層化されているか

K.O. criterion: Must 軸 (#maintainable, #operable) の score < 3 は不採用。

3.2 評価軸 × 案スコア表

係数採択案 (9 層 + 8 種 ID + L1-L4)案 a (一括ビッグバン)案 b (README 分割のみ)案 c (重量 RM ツール)案 d (RDRA 2.0 全面)
#maintainable (Must ×2.0)2.052242
#operable (Must ×2.0)2.041321
#suitable (High ×1.0)1.052412
#flexible (High ×1.0)1.051322
#reliable (Medium ×0.5)0.542243
加重和 (正規化)0.9240.3140.5710.5240.343
K.O. 通過 (Must ≥3)❌ (Must 1 件 =2)❌ (operable =2)

採択案のみ K.O. 通過し、加重和 0.924 で最高評価。

検討した代替案 (Alternatives Considered)

  • 案 a: 一括ビッグバン再編 — 不採用。新旧併存期間が長くなり drift が発生(移行失敗の最頻原因として 3 モデル一致)。レビュー単位も巨大化する。#flexible #operable で K.O.
  • 案 b: README 分割のみ(層・ID なし) — 不採用。ページは小さくなるが「この改修はどの層まで影響するか」の判定が依然できず、本起案の主目的を達成しない。#maintainable で K.O.
  • 案 c: 重量 RM ツール導入(Sphinx-Needs / DOORS 等) — 不採用。ソロ開発 docs-as-code には過剰で、調査でも plain Markdown + CI lint で十分と結論(RQ-095 Q2)。#suitable #operable で K.O.
  • 案 d: RDRA 2.0 の全面採用 — 不採用。図中心の方法論で Markdown/Git のテキスト差分管理に不向き(claude/openai の 2 モデルが否定。考え方のみ部分採用)。#operable で K.O.

影響 (Consequences)

§5.1 正の影響 (Good)

  • 改修時に L1〜L4 で更新範囲を事前判定可能(チェックリスト疲れはエージェント自動提案 + 人間承認で構造的回避)。
  • CI lint によりトレーサビリティが機械保証され、手書きマトリクスの matrix rot(経験則 年 2〜3 人日の修復コスト)を回避。
  • 9 層分割によりエージェントが必要層のみ読み込み可能となり、コンテキスト取得効率が向上(ADR-0115 と整合)。
  • データ定義書・API 仕様書・プロンプト仕様書・テスト設計書が独立文書として明示され、仕様一覧性が向上。

§5.2 負の影響 (Bad)

  • 初期導入 7.5 人日 + 維持 1.0 人日/年(5 年 TCO 12.5 人日)のコストが発生。
  • strangler-fig 中間状態でリンク網の分断リスクあり(マージ直後のリンク切れ検出 CI ジョブと旧 README スナップショット保存で対策)。
  • 構造的整合(lint green)が達成されても内容陳腐化(DRP 実装コードとの乖離)が見逃される構造的リスクあり。Phase 2 完了判定に内容整合指標を最低 2 件追加(OpenAPI スキーマと API レスポンス型 diff・プロンプト仕様書と nodes/*.ts の使用プロンプト一致)して対策。
  • ADR テンプレートの Covers フィールドが全 ADR に適用されるため、decision_pipeline 以外の開発者が DRP 固有 ID を非公式流用するリスクあり。ADR テンプレートに「DRP スコープの ID のみ記入可」と明記し、CI lint で対象外 ADR の DRP 固有 ID パターンを warning 出力して対策。
  • 散文中 ID 参照は lint をすり抜ける(エージェントへのプロンプト指示と lint ユニットテストの境界値ケースで対策)。

§5.3 中立・トレードオフ (Neutral / Trade-offs)

  • 適用範囲を decision_pipeline 限定とすることで先行検証は可能だが、GAS 会計本体への展開は別 ADR が必要(成功評価後)。
  • CI lint は構文的存在確認のみで意味的整合は保証しない(必要条件であって十分条件でない)。意味的整合は四半期サンプリング監査と半年毎棚卸しに依存。
  • GAS 会計コード・データモデル・業務フローへの変更なし。DRP 実装コード変更なし(ドキュメントと CI のみ)。CI lint スクリプトと PR テンプレートはコード領分のため main と分担。
  • LLM コスト: 本 ADR の審査 約 $0.5/run。CI lint は GitHub Actions 既存枠で追加費用 0 円/月。

撤退条件 (Rollback Plan)

  • Phase 1 完了後 2 ヶ月(2026-09 月末目安)の判定: 以下のいずれかに該当する場合、Phase 2 以降を中止し README ナビハブ + 既存構造の維持に切り替える(Phase 1 成果物の用語集・ID 規約は単体でも有用なため残す)。
    • (a) Covers の orphan 率が 20% 超のまま改善しない
    • (b) PR の L1〜L4 分類記入率が 50% 未満
    • (c) L1〜L4 宣言と実際の更新文書層の一致率が 60% 未満(20 件以上のサンプルで評価)
  • 段階的縮退オプション: Phase 3 完了後 6 ヶ月で四半期計測の分類精度 80% 未満かつ文書更新時間が増加している場合、または Jr 引き継ぎ困難の判定(オンボーディング所要が見積りの 2 倍超)が出た場合、9 層→5 層・8 種 ID→4 種への縮退を検討する(体系維持の目的化を防ぐ)。縮退時の最小構成案: 層 = 入口/要件/外部設計/ADR/検証の 5 層・ID = BR/SR/EDD/TC の 4 種(ADR- は既存体系として継続)。
  • エージェント不在時の人間運用切替(Policy Alignment 必須対応): Claude Code エージェント基盤の変更・長期障害・API 制限で維持作業をエージェントに委任できなくなった場合、(i) L1〜L4 分類と Covers 付与を「人間は L3 以上のみ記入・L4 は記入免除」に縮退し、(ii) 四半期サンプリング監査を半年毎に間引き、(iii) 3 ヶ月以内に復旧しない場合は上記の段階的縮退(5 層・4 種 ID)を発動する。本体系は特定エージェント製品に依存しない plain Markdown + CI lint で構成されているため、文書自体の可読性は失われない。
  • Phase 1 レトロスペクティブ: 「RQ-095 の推奨のうち実運用で有効でなかった点」を明示的に問い、実運用データが 3 モデル一致と矛盾した場合は実運用データを優先する。
  • revert 手順: Phase 単位の PR revert + nav 復元で 1 人日以内。既存 ADR への変更は追記のみのため revert 不要。
  • Review After(固定日付): 2027-06-04 — Phase 進行状況・撤退条件のマイルストーン到達如何にかかわらず、本体系の継続 / 縮退 / GAS 会計本体への展開判断を定期レビューする(タイムライン依存の補完・スコアリング講評対応)。

コスト試算

初期導入(3 Phase 合計 7.5 人日、週次刻みで 6〜8 週間):

Phase内容工数
Phase 1must-have 8 項目(ID 規約・用語集・BR/SR 抽出・README ハブ化・CI lint・PR テンプレ)2.5 人日
Phase 2外部設計 4 分冊(API+OpenAPI / データ定義 / プロンプト仕様 / 状態遷移)+ テスト計画3.0 人日
Phase 3内部設計移行(nodes/*.md 写像)+ 被参照上位 20 ADR への Covers 後付け2.0 人日

維持コスト(年間 1.0 人日 / 5 年で 5.0 人日):

項目工数
改修時の層別文書更新(L1〜L4 チェックリストで更新対象を限定・月平均 0.5 時間)0.75 人日/年
カタログ棚卸し(半年毎 0.125 人日 × 2)0.25 人日/年

5 年 TCO = 初期 7.5 + 維持 5.0 = 12.5 人日。Phase 1 完了後の最初の L2 以上の実改修をパイロットとして文書更新・整合確認の実工数を計測し、本試算を補正する。

現状の痛みの粗推計(ベースライン・起案時点・スコアリング講評対応): 文書更新漏れ起因の後追い修正は直近 1 ヶ月(2026-05〜06-04)で実例 2 件以上(test-tc*.mjs 転写プロンプト陳腐化 → PR #1399 / DRP README とプロンプト SSoT の文言乖離の同期修正)。1 件あたり調査 + 修正 + レビューで 0.1〜0.25 人日と置くと年 2.4〜6 人日規模の手戻り(粗推計)。層判定の所要時間は現状 749 行 README の通読を要し PR あたり 10〜15 分(人間レビュー時)。いずれも Phase 1 着手前に直近 PR の実測で補正し、導入後 1 ヶ月の効果測定(Confirmation)と同一指標で比較する。

Jr オンボーディングコスト(Policy Alignment 必須対応): 用語集 + ID 規約 + 分類ガイド(L1〜L4)+ 9 層カタログ索引の読解で 0.5〜1.0 人日と見積もる(2026-10 入社予定 Jr の引き継ぎ要件)。Phase 1 完了判定に「Jr 相当の初見読者(または初見エージェントセッション)が用語集 + ID 規約のみで L1〜L4 分類を 8 割再現できる」を確認項目として含め、オンボーディング所要 ≤1 人日を Phase 3 完了条件に追加する。

Confirmation

  • Phase 1 完了判定(マージ後 1 ヶ月):

    • 検証手段: チェックリスト + CI lint green 確認 — ID 規約文書 1 件・BR 3 件以上・SR 7 件以上(ゲート毎 1)・ADR テンプレに Covers フィールド・CI lint が orphan 0 で green・PR テンプレに L1〜L4 チェックボックス・初見読者(Jr 相当または初見エージェントセッション)が用語集 + ID 規約のみで L1〜L4 分類を 8 割再現できる、の 7 項目全充足。
    • 実行頻度: Phase 1 マージ後 1 ヶ月時点で 1 回
    • 違反時対応: 撤退条件 (a)(b)(c) に該当する場合、Phase 2 以降を中止
  • 最終完了判定(Phase 3 後):

    • 検証手段: CI またはチェックリスト — 完了条件表の 5 指標(README ≤150 行 / 正典残存 0 / Covers 解決率 100% / 新規 ADR Covers 100% / 外部契約スキーマ化 100%)
    • 実行頻度: Phase 3 完了時点で 1 回 + 以降は月次の CI 計測
    • 違反時対応: 段階的縮退オプション(9 層→5 層・8 種 ID→4 種)を検討
  • 効果測定(L1〜L4 一致率):

    • 検証手段: 改修前に L1〜L4 を宣言し、宣言と実際の更新文書層の一致率を測定(80% 以上目標)
    • 実行頻度: Phase 1 完了直後から全 PR 対象・最低 20 件のサンプル
    • 違反時対応: 判定基準(L3 デフォルト則)を改訂。Phase 1 着手前に現状の「文書更新漏れ起因の手戻り」をベースライン記録し、導入前後で比較可能にする
  • 形骸化検知:

    • 検証手段: Covers 参照 10 件の無作為サンプリング監査(意味的整合 = 現役 ID か・カテゴリ適合か、エージェント監査 + 人間レビュー)+「L3 宣言のうち実際に ADR が作成された比率」の計測
    • 実行頻度: 四半期ごと
    • 違反時対応: 不整合 2 件以上または比率の急落で半年毎棚卸しを前倒し実施
  • 内容整合指標(Phase 2 完了判定追加・盲点検出 #2 対応):

    • 検証手段: OpenAPI スキーマと実際の API レスポンス型の diff チェック・プロンプト仕様書と nodes/*.ts の使用プロンプトの一致確認、の最低 2 件
    • 実行頻度: Phase 2 完了時点 + 以降は月次 CI
    • 違反時対応: 不整合検出時は次フェーズ進行をブロックし、文書内容を実装に合わせて更新
  • リンク切れ検出(盲点検出 #1 対応):

    • 検証手段: lychee または markdown-link-check による全 Markdown リンク到達確認
    • 実行頻度: 各 Phase マージ直後 + 通常 PR の CI
    • 違反時対応: リンク切れ 1 件以上で次フェーズ PR のマージ不可(ブランチ保護ルール)

参照 (References)

  • 関連 ADR: ADR-0023 (Refine), ADR-0039 (Refine), ADR-0045 (整合), ADR-0102 (直交), ADR-0114 (補完), ADR-0115 (補完)
  • 関連 PR/Issue: PR #1404 (RQ-095 結果), PR #1408 (RQ-095 synthesis), MAS-367/368 (ADR 抽出器 + adr-index.json 計画)
  • 外部資料: docs/research/rq-095-drp-layered-docs-architecture.md, ISO/IEC/IEEE 29148, arc42, MADR, Lethbridge et al. 2003 (ソフトウェア文書管理研究)