要件トレーサビリティマトリクス（RTM）運用ガイド¶

目的¶

本RTMは、要件（REQ）から設計・実装・受入基準（ACC）までの到達性を可視化し、実装漏れ候補を機械的に検知するための正本です。

判定方針（初版）は以下の通りです。

要対応（失敗）: in_scope 要件で design_refs または implementation_refs が未設定。
警告（失敗しない）: pending_decision 要件、in_scope / pending_decision 要件の acc_refs 未設定、ACC未知ID。
対象外: out_of_scope は exempt として扱う。

要件 vs 設計の分離原則¶

RTMに登録するREQは顧客と合意した要求のみとする。

層	記載場所	判断基準
要件（WHAT）	REQ台帳・RTM・ACC	顧客がACCとして確認できる振る舞いか
設計（HOW）	`docs/02-design/`・AGENTS.md・コード	開発者の実装判断か

REQ台帳に書いてよいもの：

顧客が操作・体験できる機能
業務上の制約・制御ルール
品質基準（性能・可用性・セキュリティ等）

REQ台帳に書いてはいけないもの：

具体的なフレームワーク名・ライブラリ名（Vite、TanStack Router、React Flow等）
プラグイン名・実装クラス名（CommercialRulesPlugin等）
実装手段・内部アーキテクチャの説明

判断テスト： 「顧客はこれをACCとして確認できるか？」→ Yes → 要件、No → 設計

実現方法カラムには技術名を記載してよい（実装方針の参照用）。詳細説明・要件項目名には技術名を含めない。

正本ファイル¶

RTM正本（CSV）: docs/01-requirements/09-requirements-traceability-matrix.csv
要件台帳: docs/01-requirements/08-ritsubi-requirements-registry.csv
受入基準: docs/01-requirements/07-acceptance-criteria-checklist.csv
検証CLI: scripts/quality/rtm-check.py

実装コメント規約¶

implementation_refs にコードファイルを記載した場合、そのファイル先頭に RTM Traceability: RTM-xxx 形式のコメントを置く
1つのファイルが複数RTMに対応する場合は、RTM-053, RTM-070 のように併記する
scripts/quality/rtm-check.py --strict は、implementation_refs に記載したコードファイル内に対象RTM番号が存在することを検証する

役割の違い¶

02-b2b-business-requirements-questionnaire.csv
新しい質問や背景確認が必要なときの質問票
要件本文の認識合わせの主画面にはしない
08-ritsubi-requirements-registry.csv
REQとして正規化した要件台帳
顧客と同じ見え方でレビューする主画面。顧客確認状況 / 顧客確認観点 / 顧客確認コメント を使って差分確認する
09-requirements-traceability-matrix.csv
08 の各REQが設計・実装・ACCへ到達しているかを追う表
質問票の代わりには使わない

CSVスキーマ（運用契約）¶

以下の15カラムを固定運用します。

rtm_id,req_id,req_status,scope_bucket,req_title,source_refs,design_refs,implementation_refs,acc_refs,coverage_result,gap_type,gap_reason,owner,last_verified_on,notes

値ルール¶

scope_bucket: in_scope | pending_decision | out_of_scope
coverage_result: covered | gap | warning | exempt
gap_type: missing_design | missing_implementation | missing_both | none
*_refs: ; 区切りで複数指定。基本は repo 相対パス（必要時 :line を付与可）。
acc_refs: ACC-xxx を優先。必要に応じてファイル参照も可。

実行方法¶

手動実行（推奨）¶

just rtm-check

直接実行¶

python3 scripts/quality/rtm-check.py \
  --req docs/01-requirements/08-ritsubi-requirements-registry.csv \
  --rtm docs/01-requirements/09-requirements-traceability-matrix.csv \
  --acc docs/01-requirements/07-acceptance-criteria-checklist.csv \
  --strict

更新タイミング¶

以下の変更が入ったらRTMを更新します。

要件台帳（REQ）更新
設計資料（docs/02-design）更新
実装仕様/コード（docs/03-implementation, apps/, packages/）更新
受入基準（ACC）更新

更新責任¶

RTM行の追加・更新: 要件変更を実施した担当者
判定ポリシーの変更: 開発リード / PM 合意後
CI連携の維持: CI管理担当

初版の既定¶

対象範囲: 要件台帳（08-ritsubi-requirements-registry.csv）に登録された全REQ。欠番はダミー行で埋めず、番号ギャップのまま扱う
設計リンク粒度: docs/02-design のドキュメント単位
ACC連携: 参考（警告）扱い
CI適用: PR -> develop のRTM検証ジョブ