ynitto requirements-definer
曖昧度スコアリングで進捗を定量化しながら、インタビューを通じて要件を明確化し requirements.md に出力する。曖昧度が閾値（25%）以下になるか、上限ラウンド（15 ラウンド）に達したらドキュメントを出力して終了する。
このスキルの責務はここまで。 出力後の計画立案・タスク分解・実行は行わない。
曖昧度スコアリング
インタビューの進捗を定量化する。各次元を 0.0〜1.0 で評価し、以下の式で曖昧度を算出する。
Greenfield（新規プロジェクト）
明確度 = 目標明確度 × 0.35
+ スコープ明確度 × 0.25
+ 受け入れ条件明確度 × 0.25
+ 制約明確度 × 0.15
曖昧度 = 1 - 明確度
Brownfield（既存コードへの変更）
明確度 = 目標明確度 × 0.30
+ スコープ明確度 × 0.20
+ 受け入れ条件明確度 × 0.25
+ 制約明確度 × 0.10
+ コンテキスト明確度 × 0.15
曖昧度 = 1 - 明確度
次元の評価基準
| 次元 | 0.0 | 0.3 | 0.5 | 0.7 | 1.0 |
|---|---|---|---|---|---|
| 目標明確度 | 何を作るか不明 | 概念はあるが利用者不明 | ゴールはあるが成功指標が曖昧 | ゴール・利用者・価値が揃っている | ゴール・価値・数値成功指標が全て明確 |
| スコープ明確度 | In/Out が未定義 | 主要機能は思いついているが未整理 | 主要機能は列挙済み、境界が一部曖昧 | In/Out の大半が合意済み | In/Out の境界が全て合意済み |
| 受け入れ条件明確度 | 検証可能な条件がない | 一部機能に断片的な条件がある | 主要機能に条件あり、Given/When/Then が不完全 | 多くの機能に Given/When/Then あり | 全機能に Given/When/Then が定義済み |
| 制約明確度 | 制約が不明 | 主要制約を口頭で言及した程度 | 主要制約は把握済みだが数値がない | 主要制約に数値目標あり | 性能・セキュリティ・技術制約が全て数値で明記 |
| コンテキスト明確度（Brownfield のみ） | 既存コードを調査していない | ディレクトリ構造を確認した程度 | 一部ファイル・パターンを把握 | 変更対象の構造と主要依存を把握 | 変更対象の構造・依存関係・既存パターンを完全に把握 |
起動モードの判定
| 条件 | 動作 |
|---|---|
| 収集済みコンテキストが提供されている（対象ユーザー・スコープ・規模感が記載されている） | 非対話モード: Phase 0 → Phase 1（Greenfield/Brownfield 判定・初期スコア算出）を実施後、Phase 2 から開始 |
| 収集済みコンテキストがない / ユーザー直接起動 | 通常モード: Phase 0 から順に実行 |
フェーズ概要
| フェーズ | 名称 | 概要 |
|---|---|---|
| Phase 0 | スコーピング | 既存 requirements.md の確認・中断判断 |
| Phase 1 | 初期化 | Greenfield/Brownfield 判定、コードベース探索（Brownfield のみ）、初期スコア算出 |
| Phase 2 | インタビューループ | 1 ラウンド 1 質問、曖昧度スコアを毎回表示 |
| Phase 3 | チャレンジ | ラウンド 4・8 で視点を転換する特別質問（曖昧度が先に解消されれば発動しない） |
| Phase 4 | 要件結晶化 | スコープ確定・受け入れ条件完成・ペルソナ整理 |
| Phase 5 | Markdown 出力 | requirements.md を生成して終了 |
| Phase 6 | トレーサビリティ | 実装・テスト完了後に別途起動。コードと要件を双方向紐付け |
Phase 0: スコーピング
以下を確認し、該当しない場合は中断して適切なスキルを提案する。
- requirements.md が存在する場合 — 内容を確認し、「新規作成」か「更新」かをユーザーに確認する。更新の場合は既存の曖昧度スコアから再開する
- スコープが要件定義レベルであること — 既に詳細設計フェーズに入っている場合は
domain-modelerを提案する - 対象プロジェクトが明確であること — 何の要件を定義するのかが不明な場合はユーザーに確認する
Phase 1: 初期化
Step 1-1: Greenfield / Brownfield の判定
| 判定 | 条件 |
|---|---|
| Brownfield | 既存のソースファイル・テストファイルがある、または「既存システムに追加/変更したい」という記述がある |
| Greenfield | 何もない状態から新規に構築する |
Step 1-2: Brownfield の場合 — コードベースを先に探索する
方針: ユーザーが既に知っていることを聞かない。ファイルを読んで事実を把握してから質問する。
以下を自分で実行する（ファイルを直接読み込む）:
- プロジェクト構造・主要ファイルの確認
- 技術スタック・フレームワークの特定
- 既存の類似機能・パターンの確認
- 変更対象に関連する依存ファイルの確認
探索結果をコンテキスト明確度スコアに反映する。ファイルパスを証拠として引用しながら質問を構成する。
Step 1-3: 初期曖昧度スコアを算出して表示する
Greenfield の場合:
=== 初期曖昧度スコア（Greenfield）===
| 次元 | スコア | 重み | 貢献度 |
|------|-------|------|-------|
| 目標明確度 | 0.X | 0.35 | 0.XXX |
| スコープ明確度 | 0.X | 0.25 | 0.XXX |
| 受け入れ条件明確度 | 0.X | 0.25 | 0.XXX |
| 制約明確度 | 0.X | 0.15 | 0.XXX |
| **明確度合計** | | | **X.XXX** |
| **曖昧度** | | | **XX.X%** |
目標: 25% 以下 | 現在: XX.X% | 残り: XX.X%
===
Brownfield の場合:
=== 初期曖昧度スコア（Brownfield）===
| 次元 | スコア | 重み | 貢献度 |
|------|-------|------|-------|
| 目標明確度 | 0.X | 0.30 | 0.XXX |
| スコープ明確度 | 0.X | 0.20 | 0.XXX |
| 受け入れ条件明確度 | 0.X | 0.25 | 0.XXX |
| 制約明確度 | 0.X | 0.10 | 0.XXX |
| コンテキスト明確度 | 0.X | 0.15 | 0.XXX |
| **明確度合計** | | | **X.XXX** |
| **曖昧度** | | | **XX.X%** |
目標: 25% 以下 | 現在: XX.X% | 残り: XX.X%
===
Phase 2: インタビューループ
ルール
- 1 ラウンド 1 質問のみ
- 常に 最も曖昧度の高い次元 を狙って質問する
- 質問の前に「この質問が [次元名] を狙う理由」を 1 文で添える
- 回答後、全次元のスコアを更新して曖昧度を再計算・表示する
- ラウンド 3 以降は早期終了を提案できる（リスクを明示）
- 上限 15 ラウンド（超えたら強制的に Phase 4 へ進む）
ラウンド進行フォーマット
--- ラウンド N / 上限 15 ---
狙い: [次元名]（現在スコア: 0.X）
[質問文]
（ラウンド 3 以降のみ）
早期終了オプション: 「続ける」か「今の内容で要件定義する」か選べます
曖昧度 XX.X% のまま進めると [リスクの内容] が発生する可能性があります
回答後フォーマット
プロジェクトタイプに応じた行数で表示する（Greenfield: 4行、Brownfield: 5行）。
=== ラウンド N 完了 ===
| 次元 | スコア | 重み | 貢献度 |
|------|-------|------|-------|
| 目標明確度 | 0.X | 0.XX | 0.XXX |
| スコープ明確度 | 0.X | 0.XX | 0.XXX |
| 受け入れ条件明確度 | 0.X | 0.XX | 0.XXX |
| 制約明確度 | 0.X | 0.XX | 0.XXX |
| コンテキスト明確度（Brownfield のみ） | 0.X | 0.15 | 0.XXX |
| **明確度合計** | | | **X.XXX** |
| **曖昧度** | | | **XX.X%** ← [前回比 -X.X% / 変化なし / +X.X%]
目標: 25% 以下 | 現在: XX.X% | 残り: XX.X%
[曖昧度 ≤ 25% の場合] → Phase 4 へ進みます
[曖昧度 > 25% の場合] → 次の質問に進みます
===
規模に応じた手法の使い分け
ラウンド 1 完了後に規模を判定する。ラウンド 1 の回答をもとに規模を確定し、以降のインタビューで追加収集する内容を決める:
| 規模 | 判定基準 | 追加収集する情報 |
|---|---|---|
| 小規模 | 機能数3以下、単一ユーザー種別、明確なゴール | ユーザーストーリー + 受け入れ条件のみ |
| 中〜大規模 | 機能数4以上、複数ユーザー種別、スコープが広い | ストーリーマップ + MoSCoW + ペルソナ |
| BtoC | エンドユーザー向け、UX 重視 | カスタマージャーニーマップ（任意） |
Phase 3: チャレンジ
ラウンド 4 と 8 のタイミングで、通常の質問の代わりに視点を転換する特別質問を行う。
発動条件
- ラウンド 4 または 8 に到達した時点で 曖昧度がまだ 25% より高い 場合のみ発動する
- 曖昧度がすでに 25% 以下であれば Phase 4 へ進むためチャレンジは発動しない
- チャレンジをスキップしても ラウンドカウントは進む（スキップ = ラウンド N を消費した扱い）
| ラウンド | チャレンジ名 | 目的 |
|---|---|---|
| 4 | コントラリアン | 「逆に〇〇が起きたらどうするか」を問い、見落としたリスクを露出する |
| 8 | シンプリファイアー | 「この要件を半分の工数で実現するとしたら？」と問い、スコープ肥大化を防ぐ |
チャレンジフォーマット
--- [チャレンジ名] チャレンジ（ラウンド N / 上限 15）---
通常とは異なる視点からの質問です。
[チャレンジ質問]
回答は任意です。スキップする場合は「スキップ」と入力してください。
スキップしてもラウンド N は消費します（次はラウンド N+1）。
Phase 4: 要件結晶化
インタビューで収集した情報を整理し、最終確認を行う。
Step 4-1: スコープ確定
In/Out を明記してユーザーと合意する。中〜大規模で MoSCoW を使用した場合は Won't が自動的に Out になる。
スコープ確認:
In: [機能1], [機能2], ...
Out: [機能A]（理由: ...）, [機能B]（理由: ...）
変更がある場合はお知らせください。
Step 4-2: 受け入れ条件の補完
まだ Given/When/Then が定義されていない機能要件に対して、自動生成してユーザーに確認する。
Step 4-3: 非機能要件の数値化確認
非機能要件の内容に具体的な数値目標が欠けている場合は確認する:
非機能要件 [N-XX] の数値目標を確認します:
「API 応答が速いこと」→ 具体的な目標値は？（例: 95パーセンタイルで 500ms 以内）
Step 4-4: 中〜大規模の追加整理（該当する場合のみ）
- ペルソナ定義: 複数のユーザー種別が存在する場合に整理
- ストーリーマップ: MoSCoW 分類を確定
- カスタマージャーニー: BtoC プロダクトでユーザーが希望した場合に実施
Phase 5: Markdown 出力
作業ディレクトリのルートに requirements.md を保存する。フォーマットは references/requirements-schema.md を参照する。
出力後はユーザーに完了を通知して終了する。
要件定義が完了しました。requirements.md を出力しました。
曖昧度スコア: XX.X%（目標 25% 以下）
次のステップ:
- 計画立案: 「スクラムして」「計画を立てて」
- トレーサビリティ: 実装・テスト後に「トレーサビリティマトリクスを生成して」
Phase 6: トレーサビリティマトリクス（オプション・別途起動）
このフェーズは要件定義完了後、実装・テストが存在するタイミングで別途実行する。
「トレーサビリティマトリクスを生成して」「要件とコードを紐付けて」「ACのカバレッジを確認して」などのリクエストで発動する。
実行条件の確認
| 条件 | 動作 |
|---|---|
requirements.md が存在し、ソース/テストファイルがある |
通常実行 |
requirements.md が存在しない |
「まず要件定義を実行してください」と案内して中断 |
| ソース/テストファイルがない（要件定義直後） | not_covered のマトリクスを生成し、実装後の再実行を案内 |
トレーサビリティ追跡の仕組み
方法1: 要件IDによる直接参照（推奨・高精度）
// F-01: TODO作成
export function createTodo(title: string, deadline: Date): Todo { ... }
方法2: キーワードマッチ（IDなし時のフォールバック）
コードに要件IDがない場合、要件名・受け入れ条件のキーワードでファイルをマッチングする（精度は低下する）。
実行手順
# 基本実行（traceability-matrix.md を出力）
python scripts/generate_traceability.py
# 対象ディレクトリを指定
python scripts/generate_traceability.py --root path/to/project
マトリクスの読み方
カバレッジサマリー表（全要件のAC充足状況を一覧）:
| 要件ID | 要件名 | AC数 | ✅ 済 | ⚠️ 一部 | ❌ 未 |
|---|---|---|---|---|---|
| F-01 | TODO作成 | 2 | 2 | 0 | 0 |
| F-02 | ステータス管理 | 1 | 0 | 1 | 0 |
| 記号 | 意味 |
|---|---|
| ✅ カバー済み | 実装ファイルとテストの両方が見つかった |
| ⚠️ 一部カバー | 実装またはテストのどちらか一方のみ |
| ❌ 未カバー | 実装もテストも見つからない（要対応） |
補助スクリプト
- validate_requirements.py — 出力した
requirements.mdの構造バリデーション
python scripts/validate_requirements.py
python scripts/validate_requirements.py --file path/to/requirements.md
python scripts/validate_requirements.py --strict # 警告も表示
終了コード: 0 = 通過 / 1 = エラーあり / 2 = ファイル不在
- generate_traceability.py — 受け入れ条件と実装コード/テストの双方向トレーサビリティマトリクス生成
python scripts/generate_traceability.py
python scripts/generate_traceability.py --root path/to/project
python scripts/generate_traceability.py --requirements path/to/requirements.md
終了コード: 0 = 正常完了 / 1 = エラーあり / 2 = ファイル不在