3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
217 lines
8.6 KiB
Markdown
217 lines
8.6 KiB
Markdown
# フェーズのプランニング方法
|
||
|
||
**目的:** フェーズの決定事項とリサーチを、実行可能なアトミックかつ検証可能なタスクプランに変換します。
|
||
|
||
**前提条件:** `.planning/ROADMAP.md` が存在すること。`/gsd-discuss-phase` で生成した `{phase}-CONTEXT.md` を強く推奨しますが、必須ではありません。
|
||
|
||
---
|
||
|
||
## 標準的なプランニングフローを実行する
|
||
|
||
```bash
|
||
/gsd-plan-phase 2
|
||
```
|
||
|
||
これにより 3 つのステージが順番に実行されます:
|
||
|
||
1. **リサーチ** — `gsd-phase-researcher` サブエージェントがドメインを調査し、`{phase}-RESEARCH.md` を書き込みます。
|
||
2. **プラン** — `gsd-planner` サブエージェントがコンテキスト、リサーチ、要件を読み込み、1 つ以上の `{phase}-{N}-PLAN.md` ファイルを書き込みます。
|
||
3. **検証** — `gsd-plan-checker` サブエージェントが 8 つの次元でプランの品質を検証し、品質ゲートが通過するまでリビジョンループ（最大 3 回）を実行します。
|
||
|
||
フェーズ番号を指定しない場合、GSD Core はロードマップから次の未プランフェーズを対象にします。
|
||
|
||
---
|
||
|
||
## リサーチをスキップまたは強制する
|
||
|
||
**ドメインに習熟しており新規リサーチが不要な場合:**
|
||
|
||
```bash
|
||
/gsd-plan-phase 3 --skip-research
|
||
```
|
||
|
||
**RESEARCH.md がすでに存在するが強制的に更新したい場合:**
|
||
|
||
```bash
|
||
/gsd-plan-phase 3 --research
|
||
```
|
||
|
||
**リサーチのみ実行したい場合** — RESEARCH.md を書き込んでプランニング前に終了:
|
||
|
||
```bash
|
||
/gsd-plan-phase --research-phase 4
|
||
```
|
||
|
||
RESEARCH.md がすでに存在する場合、更新・表示・スキップのプロンプトが表示されます。プロンプトなしに強制更新するには:
|
||
|
||
```bash
|
||
/gsd-plan-phase --research-phase 4 --research
|
||
```
|
||
|
||
既存の RESEARCH.md をリサーチャーを起動せずに標準出力に表示するには:
|
||
|
||
```bash
|
||
/gsd-plan-phase --research-phase 4 --view
|
||
```
|
||
|
||
注意: `--research-phase <N>` は `/gsd-plan-phase` のフラグです。独立したリサーチフェーズコマンドは存在しません。以前の独立したリサーチコマンドはこのフラグに移行されました。
|
||
|
||
---
|
||
|
||
## 水平レイヤーではなく垂直フィーチャースライスでプランする
|
||
|
||
**技術レイヤー別ではなく、薄いエンドツーエンドスライス**（フィーチャーごとに UI → API → DB）でタスクを整理したい場合:
|
||
|
||
```bash
|
||
/gsd-plan-phase 1 --mvp
|
||
```
|
||
|
||
以前のフェーズサマリーがない新規プロジェクトのフェーズ 1 では、`--mvp` は `SKELETON.md` も生成します。これはプロジェクトの骨格、ルーティング、実際の DB 読み書き 1 件、実際の UI インタラクション 1 件、開発用デプロイをカバーするウォーキングスケルトンです。
|
||
|
||
フラグなしでフェーズを MVP モードに設定するには、ROADMAP.md のそのフェーズのエントリに `**Mode:** mvp` を追加します。
|
||
|
||
---
|
||
|
||
## 振る舞いを追加するタスクごとに失敗するテストを要求する
|
||
|
||
**TDD 強制**が必要な場合 — 振る舞いを追加する各タスクは実装前に失敗するテストから始まります:
|
||
|
||
```bash
|
||
/gsd-plan-phase 1 --tdd
|
||
```
|
||
|
||
`--mvp` との組み合わせ:
|
||
|
||
```bash
|
||
/gsd-plan-phase 1 --mvp --tdd
|
||
```
|
||
|
||
これにより、振る舞いを追加するすべてのタスクが RED → GREEN → REFACTOR に従う垂直スライスが生成されます。プランナーは対象タスク（ビジネスロジック、API エンドポイント、データ変換）に `type: tdd` を適用し、UI、設定、グルーコードには標準の `type: execute` を使用します。
|
||
|
||
TDD モードは設定でも永続化できます:
|
||
|
||
```bash
|
||
node gsd-tools.cjs config-set workflow.tdd_mode true
|
||
```
|
||
|
||
---
|
||
|
||
## クロス AI レビューのフィードバックを使ってリプランする
|
||
|
||
**`/gsd-review --phase N` を実行済みで `REVIEWS.md` が存在する場合:**
|
||
|
||
```bash
|
||
/gsd-plan-phase 3 --reviews
|
||
```
|
||
|
||
プランナーは `REVIEWS.md` を読み込み、フィードバックに対応するようプランを修正します。`--gaps` との組み合わせはできません。
|
||
|
||
**自動ループが必要な場合** — HIGH 懸念がなくなるまでリプランと再レビューを繰り返す:
|
||
|
||
```bash
|
||
/gsd-plan-review-convergence 3
|
||
```
|
||
|
||
コンバージェンスループは plan → review → replan → re-review サイクルを（デフォルト最大 3 回）実行します。上限を変更するには `--max-cycles N` を使用します。
|
||
|
||
---
|
||
|
||
## 検証失敗後にギャップを埋める
|
||
|
||
**`VERIFICATION.md` に未解決のギャップが存在し、そのギャップのみを対象にリプランしたい場合:**
|
||
|
||
```bash
|
||
/gsd-plan-phase 3 --gaps
|
||
```
|
||
|
||
リサーチはスキップされ、プランナーは検証ギャップを直接読み込みます。
|
||
|
||
---
|
||
|
||
## プランニング開始前にプロジェクト状態を検証する
|
||
|
||
```bash
|
||
/gsd-plan-phase 2 --validate
|
||
```
|
||
|
||
リサーチャーを起動する前に状態検証を実行します。ROADMAP.md や STATE.md がずれている可能性がある場合に使用してください。
|
||
|
||
---
|
||
|
||
## プランニング後に外部バウンス検証を実行する
|
||
|
||
**`workflow.plan_bounce_script` が設定されており、完成したプランに対して外部検証を行いたい場合:**
|
||
|
||
```bash
|
||
/gsd-plan-phase 1 --bounce
|
||
```
|
||
|
||
設定でバウンスが有効でも実行をスキップするには:
|
||
|
||
```bash
|
||
/gsd-plan-phase 1 --skip-bounce
|
||
```
|
||
|
||
---
|
||
|
||
## インタラクティブな確認を抑制する
|
||
|
||
```bash
|
||
/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 スキーマ](../reference/plan-md.md) を参照してください。
|
||
|
||
### プラン品質の次元
|
||
|
||
`gsd-plan-checker` は実行を許可する前に 8 つの次元でプランを検証します:
|
||
|
||
1. タスクのアトミック性 — 各タスクは単一の関心事
|
||
2. 依存関係の正確性 — ウェーブの順序が一貫している
|
||
3. 受け入れ基準の検証可能性 — 主観的な基準がない
|
||
4. `<read_first>` の完全性 — 変更対象のファイルが常にリストされている
|
||
5. 具体的な `<action>` 値 — 「〜と合わせる」のような曖昧な指示がない
|
||
6. フェーズ目標から導出された `must_haves`
|
||
7. 要件 ID のカバレッジ — すべてのフェーズ要件 ID が少なくとも 1 つのプランに存在する
|
||
8. Nyquist テストマッピング — プランが VALIDATION.md の検証戦略に対応している
|
||
|
||
リビジョンループは最大 3 回実行されます。3 回の反復後も品質ゲートが通過しない場合、チェッカーは残りの問題を手動レビュー用に提示します。
|
||
|
||
---
|
||
|
||
## クローズ済みフェーズのリプランニング
|
||
|
||
フェーズに `status: passed` の `VERIFICATION.md` がある場合、そのフェーズはクローズ済みと見なされます。リプランを試みるとエラーで停止します。クローズが誤っていた場合は `--force` で上書きします:
|
||
|
||
```bash
|
||
/gsd-plan-phase 2 --force
|
||
```
|
||
|
||
トランスクリプトおよびコミット済みのプランドキュメントに警告が出力されます。
|
||
|
||
---
|
||
|
||
## Related
|
||
|
||
- [フェーズの検討](discuss-a-phase.md)
|
||
- [フェーズの実行](execute-a-phase.md)
|
||
- [PLAN.md スキーマ](../reference/plan-md.md)
|
||
- [コマンド](../COMMANDS.md)
|