# コミットする前にスパイクとスケッチを行う方法

**目標:** フェーズを特定のアプローチに確定する前に、集中的な実現可能性実験（スパイク）と使い捨ての HTML モックアップによるビジュアル方向探索（スケッチ）を通じて、実装のリスクを軽減する。

**前提条件:** なし。`/gsd-spike` と `/gsd-sketch` は独自のストレージディレクトリを作成し、初期化済みの GSD プロジェクトは必要ありません。

---

## スパイク、スケッチ、またはその両方を選ぶ

| 答えたい問い | 使用するもの |
|---|---|
| 「この技術的アプローチは実際に機能するか？」 | `/gsd-spike` |
| 「このレイアウト / インタラクション / ビジュアル処理は適切か？」 | `/gsd-sketch` |
| 「適切な技術的アプローチは何で、どのように見えるべきか？」 | 両方、順番に：スパイク先行、次にスケッチ |

スパイクは実行可能なコードと VALIDATED / INVALIDATED / PARTIAL の判定で、二項対立の実現可能性問題に答えます。スケッチはブラウザで比較可能な 2〜3 種類の HTML バリアントで、ビジュアルの問いに答えます。両者は補完的です。スパイクはアプローチの構築可能性を証明し、スケッチはデザインの構築する価値を証明します。

---

## スパイクを実行する

### インタラクティブな受付（デフォルト）

```bash
/gsd-spike
```

GSD は技術的な問いについて質問し、それを **Given / When / Then** 形式の仮説として 2〜5 個の独立した実験に分解し、構築前に確認を求めます。

### アイデアを直接指定する

```bash
/gsd-spike "can we stream LLM tokens through SSE"
```

### 受付をスキップしてすぐに実行する

```bash
/gsd-spike --quick "websocket vs SSE latency"
```

`--quick` は分解の会話をスキップし、引数を単一のスパイク質問として扱います。問いがすでに精度が高く、絞り込みなしに実行できる場合に使用してください。

### 各実験が生成するもの

`.planning/spikes/NNN-descriptive-name/` 内の各スパイクには以下が含まれます。

- 動作するコード（擬似コードではない）
- コードの前に書かれた **Given / When / Then** 仮説
- エッジケース、方向転換、驚きを記録した調査トレイル
- 証拠付きの **VALIDATED**、**INVALIDATED**、または **PARTIAL** 判定
- フロントマター、実行方法の説明、結果を含む `README.md`

すべてのスパイクは `.planning/spikes/MANIFEST.md` にインデックスされます。

### 知見をパッケージ化する

シグナルが得られたら、今後のセッションで自動的に読み込まれるプロジェクトローカルスキルとして知見をまとめます。

```bash
/gsd-spike --wrap-up
```

これにより `.claude/skills/spike-findings-[project]/` が書き込まれます。このスキルは自動的に検出され、後続の `/gsd-sketch`、`/gsd-ui-phase`、`/gsd-plan-phase` の実行時に読み込まれます。明示的に参照する必要はありません。

---

## スケッチを実行する

### ムードの受付（デフォルト）

```bash
/gsd-sketch
```

GSD は、コードを書く前に、雰囲気、ビジュアルリファレンス、コアユーザーアクションを探る短い会話を開きます。一度に 1 つの質問をして、「実行してください」と言った時点でのみ構築を開始します。

### デザイン方向を直接指定する

```bash
/gsd-sketch "dashboard layout"
```

### ムードの受付をスキップしてすぐに実行する

```bash
/gsd-sketch --quick "sidebar navigation"
```

`--quick` は受付の会話を完全にスキップし、引数をデザイン方向として使用します。

### Claude 以外のランタイム（Codex、Gemini CLI など）

```bash
/gsd-sketch --text "onboarding flow"
```

`--text` はインタラクティブなプロンプトをプレーンテキストの番号付きリストに置き換えます。ランタイムが `AskUserQuestion` をサポートしていない場合に使用してください。

### 各スケッチが生成するもの

`.planning/sketches/NNN-descriptive-name/` 内の各スケッチには以下が含まれます。

- タブナビゲーションで 2〜3 種類のバリアントにアクセスできる `index.html`（ビルドステップなし、直接ブラウザで開ける）
- 機能的なインタラクティブ要素（ホバー、クリック、トランジション）
- 事前のスパイク知見からのフィールド名とデータ形状を使ったリアルなコンテンツ
- `.planning/sketches/themes/default.css` からの共有 CSS 変数
- デザインの問い、バリアント、注目ポイントを含む `README.md`

すべてのスケッチは `.planning/sketches/MANIFEST.md` にインデックスされます。

### 採用したデザイン決定をパッケージ化する

バリアントを選択したら、ビジュアル決定をプロジェクトローカルスキルとして記録します。

```bash
/gsd-sketch --wrap-up
```

これにより `.claude/skills/sketch-findings-[project]/` が書き込まれます。このスキルは `/gsd-ui-phase` によって自動的に読み込まれ、事前に検証された決定（レイアウト、カラーパレット、タイポグラフィ、スペーシング）はロック済みとして扱われ、再確認されません。

---

## 統合フロー：スパイク → スケッチ → フェーズ

技術的な実現可能性とビジュアル方向の両方が不確かな場合、以下の順序が推奨されます。

```bash
/gsd-spike "SSE vs WebSocket for real-time feed"
/gsd-spike --wrap-up

/gsd-sketch "real-time feed UI"
/gsd-sketch --wrap-up

/gsd-discuss-phase N
/gsd-plan-phase N
```

スパイク知見はスケッチに反映されます（実際のデータ形状、実際のインタラクション状態、現実的な制約）。両方の wrap-up は決定を永続化し、プランナーと UI リサーチャーが自動的に読み込みます。そのため、`/gsd-discuss-phase` や `/gsd-ui-phase` 中に選択内容を再説明する必要はありません。

---

## スパイクまたはスケッチがフェーズにどう組み込まれるか

スパイクとスケッチの成果物は手動で参照する必要はありません。GSD は 2 つのタイミングで自動的に読み込みます。

1. **`/gsd-sketch`** — モックアップ構築前に `.claude/skills/spike-findings-*/` を読み込み、バリアントが証明済みの制約（ストリーミング状態、実際のフィールド名など）を反映するようにする
2. **`/gsd-ui-phase N`** — UI デザインコントラクト生成前に `.claude/skills/sketch-findings-*/` を読み込み、事前検証済みのデザイン決定をロック済みとして扱う

プランナーも `spike-findings-*` スキルが存在する場合はスパイク知見を読み込むため、検証済みの技術的選択（ライブラリ、プロトコル、データ形式）が繰り返しの説明なしに直接タスクプランに反映されます。

---

## Related

- [UI フェーズをデザインする](design-a-ui-phase.md)
- [フェーズを計画する](plan-a-phase.md)
- [コマンドリファレンス](../COMMANDS.md)
- [ドキュメント一覧](../README.md)