155c08facf
* docs(#2197): drop --validate docs for /gsd-plan-phase and /gsd-execute-phase These two commands never parse --validate (silent no-op); the flag is real only for /gsd-quick. Remove the false flag-table rows and CLI examples across COMMANDS.md and the how-to guides (en + ja-JP/zh-CN/ ko-KR/pt-BR mirrors), and correct the manager.flags.execute example from --validate to --cross-ai (a flag execute-phase actually parses). /gsd-quick's real --validate docs are left untouched. Ref #2197 * docs(#2197): add changeset for --validate docs removal --------- Co-authored-by: CI Rebase Check <ci@gsd-redux>
8.4 KiB
フェーズのプランニング方法
目的: フェーズの決定事項とリサーチを、実行可能なアトミックかつ検証可能なタスクプランに変換します。
前提条件: .planning/ROADMAP.md が存在すること。/gsd-discuss-phase で生成した {phase}-CONTEXT.md を強く推奨しますが、必須ではありません。
標準的なプランニングフローを実行する
/gsd-plan-phase 2
これにより 3 つのステージが順番に実行されます:
- リサーチ —
gsd-phase-researcherサブエージェントがドメインを調査し、{phase}-RESEARCH.mdを書き込みます。 - プラン —
gsd-plannerサブエージェントがコンテキスト、リサーチ、要件を読み込み、1 つ以上の{phase}-{N}-PLAN.mdファイルを書き込みます。 - 検証 —
gsd-plan-checkerサブエージェントが 8 つの次元でプランの品質を検証し、品質ゲートが通過するまでリビジョンループ（最大 3 回）を実行します。
フェーズ番号を指定しない場合、GSD Core はロードマップから次の未プランフェーズを対象にします。
リサーチをスキップまたは強制する
ドメインに習熟しており新規リサーチが不要な場合:
/gsd-plan-phase 3 --skip-research
RESEARCH.md がすでに存在するが強制的に更新したい場合:
/gsd-plan-phase 3 --research
リサーチのみ実行したい場合 — RESEARCH.md を書き込んでプランニング前に終了:
/gsd-plan-phase --research-phase 4
RESEARCH.md がすでに存在する場合、更新・表示・スキップのプロンプトが表示されます。プロンプトなしに強制更新するには:
/gsd-plan-phase --research-phase 4 --research
既存の RESEARCH.md をリサーチャーを起動せずに標準出力に表示するには:
/gsd-plan-phase --research-phase 4 --view
注意: --research-phase <N> は /gsd-plan-phase のフラグです。独立したリサーチフェーズコマンドは存在しません。以前の独立したリサーチコマンドはこのフラグに移行されました。
水平レイヤーではなく垂直フィーチャースライスでプランする
技術レイヤー別ではなく、薄いエンドツーエンドスライス（フィーチャーごとに UI → API → DB）でタスクを整理したい場合:
/gsd-plan-phase 1 --mvp
以前のフェーズサマリーがない新規プロジェクトのフェーズ 1 では、--mvp は SKELETON.md も生成します。これはプロジェクトの骨格、ルーティング、実際の DB 読み書き 1 件、実際の UI インタラクション 1 件、開発用デプロイをカバーするウォーキングスケルトンです。
フラグなしでフェーズを MVP モードに設定するには、ROADMAP.md のそのフェーズのエントリに **Mode:** mvp を追加します。
振る舞いを追加するタスクごとに失敗するテストを要求する
TDD 強制が必要な場合 — 振る舞いを追加する各タスクは実装前に失敗するテストから始まります:
/gsd-plan-phase 1 --tdd
--mvp との組み合わせ:
/gsd-plan-phase 1 --mvp --tdd
これにより、振る舞いを追加するすべてのタスクが RED → GREEN → REFACTOR に従う垂直スライスが生成されます。プランナーは対象タスク（ビジネスロジック、API エンドポイント、データ変換）に type: tdd を適用し、UI、設定、グルーコードには標準の type: execute を使用します。
TDD モードは設定でも永続化できます:
node gsd-tools.cjs config-set workflow.tdd_mode true
クロス AI レビューのフィードバックを使ってリプランする
/gsd-review --phase N を実行済みで REVIEWS.md が存在する場合:
/gsd-plan-phase 3 --reviews
プランナーは REVIEWS.md を読み込み、フィードバックに対応するようプランを修正します。--gaps との組み合わせはできません。
自動ループが必要な場合 — HIGH 懸念がなくなるまでリプランと再レビューを繰り返す:
/gsd-plan-review-convergence 3
コンバージェンスループは plan → review → replan → re-review サイクルを（デフォルト最大 3 回）実行します。上限を変更するには --max-cycles N を使用します。
検証失敗後にギャップを埋める
VERIFICATION.md に未解決のギャップが存在し、そのギャップのみを対象にリプランしたい場合:
/gsd-plan-phase 3 --gaps
リサーチはスキップされ、プランナーは検証ギャップを直接読み込みます。
プランニング後に外部バウンス検証を実行する
workflow.plan_bounce_script が設定されており、完成したプランに対して外部検証を行いたい場合:
/gsd-plan-phase 1 --bounce
設定でバウンスが有効でも実行をスキップするには:
/gsd-plan-phase 1 --skip-bounce
インタラクティブな確認を抑制する
/gsd-plan-phase --auto
すべてのプロンプトをスキップします。自動化パイプラインで役立ちます。設定で research_enabled が false の場合、リサーチはスキップされます。
プランが生成するもの
成功した実行では以下が書き込まれます:
| ファイル | 目的 |
|---|---|
{phase}-RESEARCH.md |
ドメインリサーチ、パッケージ正当性監査、検証アーキテクチャ |
{phase}-VALIDATION.md |
Nyquist テストマッピング — プランが満たすべきテストケース（次元 8） |
{phase}-{N}-PLAN.md |
フロントマター、ウェーブ割り当て、受け入れ基準を含む実行可能タスクプラン |
{phase}/SKELETON.md |
ウォーキングスケルトン（MVP モード、新規プロジェクトのフェーズ 1 のみ） |
各 PLAN.md には必須の <read_first> と <acceptance_criteria> フィールドを持つタスクが含まれます。すべての <acceptance_criteria> エントリは、ソースアサーション、振る舞いアサーション、テストコマンド、または CLI 出力として検証可能です。主観的な表現は使用しません。
完全なフィールドリファレンスは PLAN.md スキーマ を参照してください。
プラン品質の次元
gsd-plan-checker は実行を許可する前に 8 つの次元でプランを検証します:
- タスクのアトミック性 — 各タスクは単一の関心事
- 依存関係の正確性 — ウェーブの順序が一貫している
- 受け入れ基準の検証可能性 — 主観的な基準がない
<read_first>の完全性 — 変更対象のファイルが常にリストされている- 具体的な
<action>値 — 「〜と合わせる」のような曖昧な指示がない - フェーズ目標から導出された
must_haves - 要件 ID のカバレッジ — すべてのフェーズ要件 ID が少なくとも 1 つのプランに存在する
- Nyquist テストマッピング — プランが VALIDATION.md の検証戦略に対応している
リビジョンループは最大 3 回実行されます。3 回の反復後も品質ゲートが通過しない場合、チェッカーは残りの問題を手動レビュー用に提示します。
クローズ済みフェーズのリプランニング
フェーズに status: passed の VERIFICATION.md がある場合、そのフェーズはクローズ済みと見なされます。リプランを試みるとエラーで停止します。クローズが誤っていた場合は --force で上書きします:
/gsd-plan-phase 2 --force
トランスクリプトおよびコミット済みのプランドキュメントに警告が出力されます。