spike

スパイク

ユーザーが本格的な開発に着手する前にアイデアを試してみたい場合に、このスキルを使います。実現可能性の検証、アプローチの比較、調査だけでは解消できない未知の要素の洗い出しに役立ちます。スパイクは使い捨てを前提としています。目的を果たしたら破棄してください。

「試してみたい」「X がうまくいくか確認したい」「これをスパイクしたい」「Y に取りかかる前に」「Z の簡単なプロトタイプ」「そもそも実現可能？」「A と B を比較して」などとユーザーが言った場合に、このスキルを読み込みます。

使用しない場合

• ドキュメントやコードを読めば答えがわかる場合は、作成せずに調査します
• 本番環境向けの作業には、代わりに plan スキルを使います
• アイデアの検証がすでに済んでいる場合は、そのまま実装に進みます

ユーザーが GSD システム一式をインストールしている場合

gsd-spike が兄弟スキルとして見つかった場合（npx get-shit-done-cc --hermes でインストール）、ユーザーが GSD のワークフロー一式を希望しているなら、gsd-spike を優先してください。こちらは、状態を保持する .planning/spikes/、セッションをまたいだ MANIFEST の追跡、Given/When/Then 形式の判定、GSD のほかの機能と連携するコミットパターンに対応しています。このスキルは、システム一式を使っていない（または使いたくない）ユーザー向けの、軽量で単独利用できるバージョンです。

基本的な手法

規模にかかわらず、すべてのスパイクで次のサイクルに従います。

decompose  →  research  →  build  →  verdict
   ↑__________________________________________↓
                  iterate on findings

1. 分解

ユーザーのアイデアを、2～5 個の独立した実現可能性に関する質問に分解します。各質問を 1 つのスパイクとし、Given/When/Then の形式で表にまとめます。

#	スパイク	検証内容（Given/When/Then）	リスク
001	websocket-streaming	Given a WS connection, when LLM streams tokens, then client receives chunks < 100ms	高
002a	pdf-parse-pdfjs	Given a multi-page PDF, when parsed with pdfjs, then structured text is extractable	中
002b	pdf-parse-camelot	Given a multi-page PDF, when parsed with camelot, then structured text is extractable	中

スパイクの種類：

• 標準 — 1 つの質問に答える 1 つのアプローチ
• 比較 — 同じ質問に対する複数のアプローチ（同じ番号を使い、a／b／c の文字を付けます）

良いスパイクの質問： 観察可能な結果が得られる、具体的な実現可能性に関する質問です。
悪いスパイクの質問： 範囲が広すぎる、観察可能な結果がない、または単に「X についてドキュメントを読む」だけの質問です。

リスクの高い順に並べます。 アイデアを頓挫させる可能性が最も高いスパイクを最初に実施します。難しい部分がうまくいかないのなら、簡単な部分を先にプロトタイプする意味はありません。

ユーザーがスパイクしたいものをすでに明確に把握し、それを伝えている場合に限り、分解を省略します。その場合は、ユーザーのアイデアを 1 つのスパイクとして扱います。

2. 調整（複数のスパイクがある場合）

スパイクの表を提示します。「この順序ですべて作成しますか、それとも調整しますか？」と尋ねます。コードを書く前に、ユーザーがスパイクの削除、順序の変更、枠組みの見直しをできるようにします。

3. 調査（各スパイクの実装前）

スパイクでも調査は必要です。適切なアプローチを選ぶのに必要なだけ調査してから、実装します。スパイクごとに、次の手順を実行します。

1. 概要をまとめます。 このスパイクの内容、重要な理由、主なリスクを 2～3 文で説明します。

2. 現実的な選択肢がある場合は、競合するアプローチを提示します。

   アプローチ	ツール／ライブラリ	メリット	デメリット	状態
   ...	...	...	...	メンテナンス中／放棄済み／ベータ

3. 1 つ選びます。 選んだ理由を説明します。信頼できる選択肢が 2 つ以上ある場合は、スパイクの中で簡単なバリエーションを作成します。

4. 外部依存関係のない純粋なロジックの場合は、調査を省略します。

調査には Hermes ツールを使います。

• web_search("python websocket streaming libraries 2025") — 候補を探します
• web_extract(urls=["https://websockets.readthedocs.io/..."]) — 実際のドキュメントを読みます（マークダウンが返されます）
• terminal("pip show websockets | grep Version") — プロジェクトの仮想環境にインストールされているものを確認します

ドキュメントページがないライブラリについては、read_file を使ってリポジトリをクローンし、README.md／examples/ を読みます。Context7 MCP（ユーザーが設定している場合）も情報源として適しています。mcp_*_resolve-library-id の後に mcp_*_query-docs を使います。

4. ビルド

スパイクごとにディレクトリを1つ作成します。単独で動作する状態に保ちます。

spikes/
├── 001-websocket-streaming/
│   ├── README.md
│   └── main.py
├── 002a-pdf-parse-pdfjs/
│   ├── README.md
│   └── parse.js
└── 002b-pdf-parse-camelot/
    ├── README.md
    └── parse.py

ユーザーが操作できるものを優先します。 出力が「動作します」というログ行だけのスパイクは失敗です。ユーザーはスパイクが動作することを実感したいのです。優先順位の高い順に、次の選択肢を標準とします。

1. 入力を受け取り、確認可能な出力を表示する実行可能な CLI
2. 動作を実証する最小限の HTML ページ
3. エンドポイントが1つだけの小規模なウェブサーバー
4. 認識しやすいアサーションで問いを検証する単体テスト

速度より深さを重視します。 ハッピーパスを1回実行しただけで「動作します」と判断してはいけません。エッジケースをテストします。意外な発見を追究します。調査が誠実に行われたときにのみ、判定を信頼できます。

スパイクで特に必要でない限り、複雑なパッケージ管理、ビルドツール／バンドラー、Docker、環境ファイル、設定システムは避けます。すべてハードコードします。これはスパイクです。

1つのスパイクを構築する場合 — 一般的なツールの手順：

terminal("mkdir -p spikes/001-websocket-streaming")
write_file("spikes/001-websocket-streaming/README.md", "# 001: websocket-streaming\n\n...")
write_file("spikes/001-websocket-streaming/main.py", "...")
terminal("cd spikes/001-websocket-streaming && python main.py")
# Observe output, iterate.

比較用スパイクを並行して実施する場合（002a / 002b）— 委任します。 2つのアプローチを並行して進められ、どちらにも本格的なエンジニアリングが必要な場合（10行のプロトタイプでは済まない場合）は、delegate_taskで作業を振り分けます。

delegate_task(tasks=[
    {"goal": "Build 002a-pdf-parse-pdfjs: ...", "toolsets": ["terminal", "file", "web"]},
    {"goal": "Build 002b-pdf-parse-camelot: ...", "toolsets": ["terminal", "file", "web"]},
])

各サブエージェントがそれぞれ判定を出し、全体の直接比較はあなたが作成します。

5. 判定

各スパイクのREADME.mdの末尾には、次の内容を記載します。

## Verdict: VALIDATED | PARTIAL | INVALIDATED

### What worked
- ...

### What didn't
- ...

### Surprises
- ...

### Recommendation for the real build
- ...

VALIDATED = 中心となる問いに対し、証拠をもって「はい」と回答できました。 PARTIAL = X、Y、Zの制約下では動作します。それらを記録します。 INVALIDATED = 次の理由で動作しません。これはスパイクの成功です。

比較用スパイク

2つのアプローチが同じ問いに答える場合（002a / 002b）は、続けて構築し、最後に直接比較します。

## Head-to-head: pdfjs vs camelot

| Dimension | pdfjs (002a) | camelot (002b) |
|-----------|--------------|----------------|
| Extraction quality | 9/10 structured | 7/10 table-only |
| Setup complexity | npm install, 1 line | pip + ghostscript |
| Perf on 100-page PDF | 3s | 18s |
| Handles rotated text | no | yes |

**Winner:** pdfjs for our use case. Camelot if we need table-first extraction later.

フロンティアモード（次にスパイクする対象の選定）

スパイクがすでに存在し、ユーザーが「次は何をスパイクすべきですか？」と尋ねた場合は、既存のディレクトリを確認し、次の点を調べます。

• 統合リスク — 同じリソースに関連する2つの検証済みスパイクが、別々にテストされている
• データの受け渡し — スパイクAの出力がスパイクBの入力と互換性があると仮定されていたが、検証されていない
• ビジョンのギャップ — 前提とされているものの、実証されていない機能
• 代替アプローチ — PARTIALまたはINVALIDATEDのスパイクに対する別の切り口

Given/When/Then形式で候補を2～4件提案します。ユーザーに選んでもらいます。

出力

• リポジトリのルートにspikes/を作成します（ユーザーがGSDの規約を使用している場合は.planning/spikes/）
• スパイクごとに1つのディレクトリを作成します：NNN-descriptive-name/
• 各スパイクのREADME.mdに、問い、アプローチ、結果、判定を記録します
• コードは使い捨てにします。本番向けに「整える」ために2日かかるスパイクは、良いスパイクではありません

クレジット

GSD（Get Shit Done）プロジェクトの/gsd-spikeワークフローをベースにしています — MIT © 2025 Lex Christopherson（gsd-build/get-shit-done）。GSDの完全なシステムでは、スパイク状態の永続化、MANIFESTによる追跡、より広範な仕様駆動開発パイプラインとの統合が利用できます。npx get-shit-done-cc --hermes --globalでインストールしてください。