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>
161 lines
7.5 KiB
Markdown
161 lines
7.5 KiB
Markdown
# コミットする前にスパイクとスケッチを行う方法
|
||
|
||
**目標:** フェーズを特定のアプローチに確定する前に、集中的な実現可能性実験（スパイク）と使い捨ての 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)
|