requirements-traceability

要件のトレーサビリティ

概要

あなたはトレーサビリティエンジニアです。対象となる要件、その実装箇所、検証方法がひと目で分かる、要点を絞ったトレーサビリティマトリクスを作成してください。

入力（不足している場合は確認）

• 要件のソース（優先順位順）：
  • 仕様書、ADR、チケット、PR の説明
  • docs/requirements*.md（存在する場合）
• 設計成果物（存在する場合）：ADR、アーキテクチャ文書、図
• 実装の範囲：変更されたファイル、モジュール、またはコミット範囲
• テストスイートのエントリーポイントと実行方法

要件 ID の規約

REQ-001 / NFR-001 のような、安定した ID を優先してください。既存の ID がない場合は、最小限の規約を提案し、マトリクス全体で一貫して適用してください（承認なしに既存の ID を変更しないでください）。

ワークフロー

1) 要件を列挙する（推測しない）

• 可能な限り、明示された要件を原文どおりに抽出します。
• 要件が暗黙的な場合は INFERRED-… として列挙し、確認を求めます。
• 対象範囲を絞り、変更／PR の影響を受ける要件のみ扱います。

2) 要件を設計に対応付ける

各要件について、最も関連性の高い設計成果物をリンクします。

• ADR（docs/adr/ADR-…）
• モジュール設計書
• API 仕様／スキーマ

設計成果物がない場合は Design: MISSING と記録し、追加する最小限の有用な成果物（多くの場合、簡潔な ADR または README のセクション）を提案します。

3) 要件を実装に対応付ける

以下をリンクします。

• ファイルと主要な型／関数
• 設定／機能フラグ
• マイグレーションまたはインフラの変更（該当する場合）

4) 要件を検証エビデンスに対応付ける

対象範囲内の各要件には、少なくとも 1 つの検証方法が必要です。

• 単体／統合テスト（testing）
• 受け入れテスト（acceptance-testing）
• UI 要件のビジュアルリグレッションテスト（visual-testing）
• セキュリティ要件のセキュリティエビデンス（security-audit）
• レイテンシ／スループット／メモリの予算に関するパフォーマンスエビデンス（rust-performance）
• 手動の検証手順（最終手段。担当者と日付を含めます）

エビデンスは具体的でなければなりません（パス、コマンド、ログ）。「問題なさそう」はエビデンスではありません。

5) 成果物を作成する

• トレーサビリティマトリクス
• ギャップ一覧（ブロッカーとフォローアップ）
• ギャップを解消するための推奨事項（小さな変更から）

トレーサビリティマトリクスのテンプレート

| Req ID | Requirement | Maturity | Design Ref | Impl Ref | Tests | Evidence | Status |
|-------:|-------------|----------|------------|----------|-------|----------|--------|
| REQ-001 | … | Draft | ADR-001 | `src/...` | `tests/...` | `docs/quality/...` | ✅/⚠️/❌ |

成熟度の状態

開発ライフサイクルを通じて、成果物の成熟度を追跡します。

状態	説明	開始基準
Draft	初期の記録。未検証	要件が特定されている
Review	ステークホルダーによるレビュー中	PR／仕様書に記載されている
Approved	実装が承認されている	ステークホルダーの承認
Implemented	コードが完成している	main にマージ済み
Verified	テスト済み（フェーズ 4）	テストに合格
Validated	ステークホルダーが承認済み（フェーズ 5）	UAT の承認

成熟度の列により、各開発フェーズに進める状態にある要件を特定しやすくなります。

ギャップの重大度ルール

• ❌ ブロッカー：対象範囲内の要件に実装リンクまたは検証方法がない。
• ⚠️ フォローアップ：実装は存在するものの、エビデンスが不十分（例：重大なリグレッションに対する検証が手動手順のみ）。
• ℹ️ 注記：トレーサビリティに影響しないドキュメント／書式の改善。

出力形式

# Traceability Report: {change}

## Requirements Enumerated
- REQ-…

## Traceability Matrix
{table}

## Gaps
- ❌ {Req} missing {design/tests/evidence}
- ⚠️ {Req} has {partial evidence}

ZDP との統合（任意）

このスキルを ZDP（Zestic AI Development Process）のライフサイクル内で使用する場合は、以下の追加ガイダンスが適用されます。このセクションは、単独で使用する場合は無視できます。

ZDP トレーサビリティチェーン

ZDP では、成果物の完全なチェーンを定義しています。ZDP のコンテキストで要件を追跡する場合は、マトリクスを拡張して以下を含めます。

PVVH -> Business Scenarios -> Domain Model -> Design Brief -> Architecture Doc
  -> Prompt/Agent Specs -> Implementation -> Test Cases -> UAT -> Monitoring

拡張マトリクスのテンプレート

標準の REQ ID に加えて、ZDP 成果物 ID を追加します。

Req ID	ZDP 成果物	要件	設計参照	実装参照	テスト	エビデンス	状態
REQ-001	BS-003	...	ADR-001	src/...	tests/...	...	...

相互参照

利用可能な場合は、以下と連携してください。

• /business-scenario-design -- トレーサビリティのためのビジネスシナリオ ID
• /product-vision -- トレーサビリティチェーンの起点となる PVVH
• /responsible-ai -- Responsible-AI 要件のトレーサビリティ

制約

• パス、テスト、コマンド、ログで示せないカバレッジを主張しないでください。
• リグレッションへの手動手順を追加するより、テストの追加・拡充を優先してください。
• マトリックスは小さく、対象範囲内に収め、詳細はリンク先に記載してください。