req-driven-dev

# Requirements-Driven Development 要件ファイルを起点に、条件確定→検証→実装→記録を行うワークフロー。 ## 状態管理 全ての状態は CLI ツール (`req_tool.py`) 経由でのみ操作する。 状態ファイルを直接読み書きしてはならない。 ## CLI ツール リファレンス 以下のコマンド例は、skill root からの相対パスで記載する。 ```bash # 状態確認（最初に必ず実行） uv run scripts/req_tool.py status [req_file] # 受け入れ条件の管理 uv run scripts/req_tool.py criteria add <req_file> <req_no> <criterion> uv run scripts/req_tool.py criteria list [req_file] [--req-no N] # 検証結果の記録（受け入れ条件が存在する req_no のみ） uv run scripts/req_tool.py verify <criteria_id> <status> [--detail TEXT] [--limitation TEXT] # リグレッション記録 uv run scripts/req_tool.py regress <req_file> <req_no> --detail TEXT [--criteria-id ID] # 承認（ユーザーが実行。エージェントは実行しない） uv run scripts/req_tool.py approve <verification_id> <decision> [--comment TEXT] # 要件の追加 uv run scripts/req_tool.py req add <file> <text> uv run scripts/req_tool.py req list [file] # 仕様メモの追加 uv run scripts/req_tool.py spec add <requirement> <title> --body TEXT [--commits ...] [--files ...] # マイグレーション（レガシー .md → 現行形式） uv run scripts/req_tool.py migrate [req_file] ``` status の値: `passed`, `failed`, `conditional` decision の値: `approved`, `rejected` ## Web UI ダッシュボード ブラウザベースのダッシュボード (NiceGUI)。検証状態の俯瞰、承認操作、要件追加が可能。 この skill には WebUI 起動機能がある。 現在の指示が `webui`, `web ui`, `dashboard`, `open dashboard`, `start webui` のような内容であれば、次のスクリプトを実行する。 ```bash uv run scripts/webui.py [--port PORT] # デフォルト: http://localhost:9421 ``` **Dashboard タブ:** - サマリーバー (approved / pending / failed / regression / stale) - フィルター (All / Pending / Problems / Approved) - 要件カード: 検証詳細の展開、承認・却下ボタン - 要件・受入条件の追加ダイアログ - 60秒自動リフレッシュ **Dependencies タブ:** - Mermaid ダイアグラムで要件→受入条件→検証→承認の依存関係を可視化 - ノード色: 承認=緑, 保留=黄, 失敗=赤, 古い=オレンジ ## When to Use - ユーザーが「要件 XXXX を実装して」「検証して」と言ったとき - 実装タスクを始めるとき（AGENTS.md ポリシー: 常に要件ファイルから始める） - 検証状態の確認・更新が必要なとき - 仕様メモを作成・更新するとき ## Procedure ### Phase 1: 要件読解 + 現状把握 1. `uv run scripts/req_tool.py req list XXXX` で要件一覧を確認 2. `uv run scripts/req_tool.py status XXXX` を実行して現在の検証状態を確認 3. 関連する仕様メモがあれば `commits` と `files` の git log を比較し、乖離があればコードと照合 4. フォーマットが不明なら [要件フォーマット](./references/requirements-format.md) を確認 ### Phase 2: 意図解釈 + 受け入れ条件確定 要件の意味を解釈し、検証可能な受け入れ条件を確定する。 **条件確定の判断基準:** | 要件の性質 | アクション | |-----------|-----------| | 明確で一意な解釈 | 要件テキストをそのまま条件として `criteria add` で登録 | | 複数の解釈が可能 | ユーザーに解釈を提案し、対話で確定してから登録 | | 曖昧・不完全 | ユーザーに明確化を求める。推測で条件を作らない | | 既に条件が存在 | `criteria list` で確認。stale 警告があれば再確認 | ```bash # 条件登録例 uv run scripts/req_tool.py criteria add 0001 10 "BitBlt API で画面全体のスクリーンショットが取得できること" ``` **暗黙の要件を発見した場合:** 本文に追記するのではなく、ユーザーに「この暗黙の要件も追加すべきでは？」と提案する。 ユーザーが同意すれば、ユーザー自身が要件ファイルに追記する。 ### Phase 3: 影響度分析 + 計画 1. 未対応の要件・条件を特定 2. コードベースの影響範囲を調査 3. 変更ファイル・手順の計画を立てる 4. 非自明なタスクでは rubber-duck サブエージェントで計画をレビュー ### Phase 4: 実装 1. コード変更を実施 2. ビルド・テストで動作確認 3. 各段階で検証可能な状態を維持 ### Phase 5: 検証 各受け入れ条件に対して検証を実施し、結果を記録する。 | 要件タイプ | 検証方法 | |-----------|---------| | コードの存在・構造 | grep / ファイル確認 | | 動作・出力 | ビルド + 実行 | | 既に verified のもの | コード現状と照合して妥当性を再確認 | ```bash # 検証結果の記録 uv run scripts/req_tool.py verify ac-1 passed --detail "cargo test で全テスト通過" uv run scripts/req_tool.py verify ac-3 conditional --detail "背後ウィンドウOK" --limitation "最小化ウィンドウは不可" uv run scripts/req_tool.py verify ac-5 failed --detail "コンパイルエラー: xxx" ``` **注意:** `approve` コマンドはエージェントが実行するものではない。ユーザーが検証結果を確認して承認する。 ### Phase 6: 報告 + 記録 1. `uv run scripts/req_tool.py spec add` で仕様メモを追記 2. 他の仕様に影響する変更をした場合、該当仕様も更新 3. `uv run scripts/req_tool.py status XXXX` で最終状態を表示 ### リグレッション検出時 既存の検証結果は残したまま、新しいリグレッション記録を追加する: ```bash uv run scripts/req_tool.py regress 0003 10 --detail "Aggregator状態マシン欠陥で連続変化中にイベント不発行" ``` ## Decision Points - 要件が曖昧なとき → ユーザーに確認。推測で実装しない - 検証と実装どちらが先か → 全要件を先に検証し、未対応リストを作ってから実装に入る - specs が古い（commits 乖離）→ コードと照合してから利用。更新も行う - stale 警告が出たとき → 要件テキストが変更されている。条件を再確認 ## 禁止事項 - 要件ファイルの本文を勝手に編集しない（ユーザー所有） - `approve` コマンドを実行しない（ユーザー操作） - CLI ツールを経由せずに状態を変更しない（状態ファイルを直接読み書きしない）