Brainstorming

Brainstorming Skill

本プロジェクトの開発ワークフロー (docs/workflow.md) における起点ステージです。ユーザーの曖昧な要望を質問の往復で深掘りし、次の Spec ステージで仕様を書ける状態まで解像度を上げることが役割です。

用語: 「Project Phase」「Workflow Stage (ステージ)」「Release Phase」「Spec」の定義は docs/glossary.md を参照してください。本 skill 内では Workflow Stage を「ステージ」、ユーザープロジェクトのリリース段階 (MVP / Phase 2 等) を「Release Phase」と表記します。

1. 役割と位置づけ

本 skill はワークフローの最上流に位置します。後続のすべてのステージ (Spec → Spec Review → Isolate → Plan → Implement → Verify → Code Review → ship → Learn) は、本ステージの出力である Brainstorming ノートを起点として進みます。

設計原則: ヒアリングを飛ばして Spec ステージに直接進むことは禁止です。曖昧な要件のまま Spec を書くと、Plan / Implement / Code Review すべてが手戻りするため、本 skill を起点として固定化します (docs/workflow.md 設計原則 6 参照)。

2. 起動トリガー

以下のような自然言語のフレーズで自動的に起動してください。

• 「要件をまとめたい」
• 「Spec を書きたい」
• 「機能を追加したい」
• 「新しい仕事を始めたい」
• 「やりたいことがある」
• 「〜について相談したい」
• 「〜を作りたい」

ユーザーが上記のような着手意図を示した時点で、本 skill を起動し、ヒアリングを開始します。すでに Spec ファイル (specs/<spec-name>.md) が存在する場合は本 skill をスキップし、Spec Review ステージに進んでください。

3. 禁則事項 (Anti-Pattern)

本 skill 起動中に以下を行ってはいけません。

• ❌ ヒアリングを省略していきなり Spec ファイルを作成する
• ❌ ユーザーの最初の発話だけで Spec の解像度が十分と判断する
• ❌ 質問なしに実装提案を始める
• ❌ ユーザーの承認なしに次の Spec ステージへ自動遷移する
• ❌ Brainstorming ノートを worktree 内に作成する (worktree はまだ存在しない)

特に「これは簡単だから設計不要」という判断は、後続ステージで必ず手戻りを起こすため明確に禁止します。

4. ヒアリング手順 (チェックリスト)

以下の順序でユーザーと対話してください。各項目で十分な解像度が得られるまで、追加質問を続けます。

• 目的の確認: なぜこの作業をしたいのか、解決したい問題は何か
• 利用者の特定: 誰がこの成果物を使うのか (自分のみ / チーム / 外部ユーザー等)
• 成功条件の明確化: どうなれば完了と判断できるのか (受け入れ基準)
• 制約の洗い出し: 既存システムへの影響、技術的制約、時間的制約
• スコープの確定: 何を含み、何を含まないか
• 代替案の検討: 他のアプローチはないか、なぜこのアプローチを選ぶのか
• リスクの予測: 何がうまくいかない可能性があるか
• 次ステージへの移行確認: ユーザーが Spec ステージへ進む準備ができたか明示的に承認

各項目を機械的に質問するのではなく、ユーザーの発話から明らかになった項目はスキップし、未解明の項目を優先的に質問してください。

5. 質問カテゴリ

ヒアリングの軸として以下のカテゴリを参照してください。

カテゴリ	代表的な質問例
目的	「この機能で何を実現したいですか」「現状の何が不便ですか」
利用者	「誰が使いますか」「使う頻度はどれくらいですか」
成功条件	「完成したと判断する基準は何ですか」「動作確認はどう行いますか」
制約	「既存のどの部分に影響しますか」「期日はありますか」「使える技術スタックの制限はありますか」
スコープ	「今回含めない機能はありますか」「将来的に拡張予定の機能は何ですか」
代替案	「他に思いついたアプローチはありますか」「既存ライブラリで代替できませんか」
リスク	「何が起きると困りますか」「失敗パターンを想定していますか」

6. 出力フォーマット

ヒアリングが完了したら、以下のフォーマットで specs/<spec-name>.brainstorm.md を作成してください。<spec-name> はユーザーと相談して決定したケバブケースの名前 (例: add-user-login, fix-payment-bug) を使います。

---
name: <spec-name>
created: YYYY-MM-DD
status: brainstorming-complete
---

# Brainstorming: <spec-name>

## 目的
<なぜこの作業をするのか、解決する問題>

## 利用者
<誰が使うのか>

## 成功条件 (受け入れ基準)
- <条件 1>
- <条件 2>

## 制約
- <技術的制約>
- <時間的制約>
- <既存システムへの影響>

## スコープ
### 含むもの
- <項目 1>

### 含まないもの (明示的に除外)
- <項目 1>

## 代替案の検討
- <検討した代替案 1 と却下理由>
- <検討した代替案 2 と却下理由>

## リスク
- <想定されるリスク 1 と対策方針>

## 未解決事項
- <Spec ステージで決定する事項>

## ヒアリングログ (任意)
<重要なやり取りの抜粋>

ファイル配置先は specs/<spec-name>.brainstorm.md です。specs/ ディレクトリが存在しない場合は新規作成してください。worktree 内ではなく、main ブランチ側に配置します。

7. 完了判定基準

以下を すべて 満たした時点で本 skill を完了とします。

1. 上記チェックリストの「次ステージへの移行確認」を除く全項目に十分な情報が得られている
2. Brainstorming ノートが上記フォーマットで作成され、specs/<spec-name>.brainstorm.md に保存されている
3. ユーザーが Spec ステージへの移行を 明示的に 承認している (例: 「これで Spec 書いて良いです」「次に進んで」)

ユーザー承認なしに自動で次のステージへ遷移してはいけません。承認を得るための問いかけは「以上の内容で Spec ステージに進めますがよろしいですか」のように明確に行ってください。

8. 次ステージへの引き継ぎ

完了判定を満たしたら、以下の引き継ぎを行います。

1. ユーザーに writing-spec skill (Phase 3 で実装予定) を起動する旨を伝える
2. 引き継ぎ情報として、作成した Brainstorming ノートのパスを明示する
3. 未解決事項として残した項目を Spec ステージで議論することを伝える

writing-spec skill 未実装の Phase 3 着手段階では、引き継ぎは口頭での合意で代替し、Brainstorming ノートのパスをユーザーに提示するに留めます。

9. 失敗時の対応

ヒアリング中にユーザーが要件を確定できない、あるいは前提条件を見直す必要が生じた場合、無理に Brainstorming ノートを作成せず、以下のいずれかを提案してください。

• 一時保留 (要件が固まるまでセッションを終了する)
• スコープ縮小 (確定済みの部分のみで Spec ステージへ進む)
• 前提調査 (技術検証や類似事例の調査を別 Spec として切り出す)

ユーザーの判断を待ち、無断で進行しないでください。

10. Spec 分割提案 (スコープ肥大時)

ヒアリングを進めるうちに、要件が単一 Spec として扱うには大きすぎると判明する場合があります。そのまま 1 つの Spec として進めると Plan / Implement ステージで破綻するため、分割を積極的に提案 してください。

10.1 分割推奨の判定基準

以下のうち 2 つ以上 に該当した時点で、ユーザーに分割を提案してください。

• 成功条件 (受け入れ基準) が 5 個以上 挙がっている
• 独立性の高い機能領域が 2 つ以上 含まれる (例: 認証 + 決済 + 管理画面)
• スコープの「含むもの」が 5 項目以上 ある
• ユーザーが述べた「目的」が 複数 存在する
• 実装期間の見積もりが数週間以上に及ぶ
• 既存モジュール/テーブル/サービスの変更箇所が 3 箇所以上 ある

判定は硬直的に行わず、上記基準を「分割すべきかの思考補助」として使ってください。ユーザーが「これは絶対に 1 Spec で進めたい」と主張する場合は理由を確認した上で尊重します。

10.2 分割軸の提示

分割を提案する際は、以下の軸から 2〜3 個の候補 を提示し、ユーザーと選定してください。

軸	分割例	向いているケース
機能単位	auth, payment, admin-dashboard	独立性の高い複数機能を同時に作るケース
Release Phase 単位	mvp, phase2-polish, phase3-scale	MVP → 拡張の段階的開発 (docs/glossary.md の Release Phase 定義参照)
データ単位	user-schema, product-schema, order-schema	データモデル中心の作業
層 (垂直/水平)	ui-layer, api-layer, data-layer	フルスタック機能で層ごとに責務を分けたいケース

複数軸を組み合わせる必要がある場合 (例: 機能単位 × Release Phase 単位) はその旨も提示してください。

10.3 分割承認フロー

以下の順序で必ずユーザー承認を得てから複数ノート生成に進んでください。

1. 分割推奨の理由を具体的に提示 (「成功条件が 7 個 / 機能領域が 3 つに跨っている」等、判定基準を明示)
2. 分割軸の候補を 2〜3 個提示
3. ユーザーが軸を選択 (または別の軸を逆提案)
4. 分割後の各 Spec 名と担う責務を一覧で提示
5. 依存関係の有無を確認 (Spec 間の前後関係 / 並行実行可否)
6. ユーザーが分割案を明示的に承認 (例: 「この分割で進めて」)
7. 複数の Brainstorming ノートを生成

ユーザーの明示的な承認なしに複数ノートの生成を開始してはいけません。

10.4 複数 Brainstorming ノートのファイル命名規則

分割後の Brainstorming ノートは、共通接頭辞を使って関連性を示します。

• 機能単位: specs/<project>-<feature>.brainstorm.md
  • 例: specs/ecsite-auth.brainstorm.md, specs/ecsite-payment.brainstorm.md, specs/ecsite-admin.brainstorm.md
• Release Phase 単位: specs/<project>-<release-phase>.brainstorm.md
  • 例: specs/ecsite-mvp.brainstorm.md, specs/ecsite-phase2.brainstorm.md
• 依存関係を明示したい場合: 各ノートの frontmatter に depends_on フィールドを追加
  • 例: depends_on: [ecsite-auth]

10.5 分割後の各ノートに含める追加項目

単一 Spec 時のテンプレート (セクション 6 参照) に加え、分割時は以下を必ず含めてください。

• 関連 Spec: 同時に分割された他の Spec の一覧と、この Spec との関係 (並行 / 前提 / 後続)
• 切り出した理由: この Spec を独立させた根拠 (「認証は決済より先に必要」等)
• Spec 間で共有する資産: 共通スキーマ / 共通ライブラリ / 環境変数等

10.6 Phase 5 (orchestrator) への橋渡し

本プロジェクトのワークフロー (docs/workflow.md) では、複数 Spec の並列実行は Phase 5 で実装される orchestrator skill が担当します。Phase 3 の時点では分割後の各 Spec を順次手動で進めることになりますが、Brainstorming ノート段階で依存関係 (depends_on) を明記しておくことで、Phase 5 の orchestrator がそのまま DAG 解決に利用できます。

未来の自動化を意識し、依存関係は必ず記述してください。

11. コードベース精査

ヒアリング項目の中には、ユーザーへの質問だけでは引き出せない情報や、ユーザーが忘れている / 知らない情報があります。AI が能動的にコードベースを読めば数秒で判明する事項を、何往復もして質問するのは非効率かつ不正確です。本 skill では コードベース精査を 2 段階で行う ことを必須とします。

11.1 段階 1: 起動直後の軽スキャン (必須)

skill 起動直後、ヒアリングを開始する前に、以下を必ず実施してください。

• ディレクトリ構造の把握 (ルート直下の ls または Glob でトップレベルのファイル / ディレクトリを取得)
• メタ情報の読み込み (存在する場合のみ)
  • CLAUDE.md (プロジェクトルール)
  • README.md
  • package.json / pyproject.toml / Cargo.toml / go.mod 等のマニフェスト
  • docs/ 配下の主要ドキュメント
• 既存の specs/ ディレクトリ確認 (関連する過去の Brainstorming ノート / Spec の存在確認)

これにより、技術スタック・プロジェクトの種類・既存のルール・関連する過去の作業を把握します。把握した情報はヒアリング質問の精度向上に使い、「Node.js プロジェクトと判明したので React か Vue かのみ確認」のように 質問を絞り込んでください。

11.2 段階 2: ヒアリング中の深スキャン (要件次第)

ヒアリングが進み、要件のキーワード (例: 「認証」「在庫」「メール送信」) が見えてきた段階で、関連コードを能動的に検索してください。

• 関連キーワードでコード検索 (Grep)
  • 例: 「認証」要件 → Grep で auth, login, session, JWT 等を検索
  • 例: 「在庫」要件 → Grep で inventory, stock, quantity 等を検索
• 関連ファイルの読み込み (Read)
  • 既存実装の有無
  • 関連モジュールの I/F
  • 命名規約・コードスタイル
  • データモデル / スキーマ定義
• 既存テストパターンの確認
  • テストフレームワーク
  • テストの粒度 (unit / integration / e2e)
  • 既存テストヘルパー / fixture
• 関連 commit 履歴 (git log)
  • 過去に同じ領域に変更があったか
  • 変更時の commit メッセージから設計意図を推測

精査結果を踏まえ、ヒアリング項目を更新します。コードから判明した事項は ユーザーに質問せず、推測内容を提示して確認を求める形にしてください (例: 「既存の MailSender クラスを再利用する想定で良いですか」)。

11.3 精査結果の Brainstorming ノートへの反映

精査結果は Brainstorming ノートの該当セクションに反映してください。

• 制約: 既存技術スタック / 既存命名規約 / 既存ライブラリ依存 を「制約」セクションに記述
• 既存システムへの影響: 関連モジュール / 関連テーブル / 関連エンドポイント を具体的に列挙
• 未解決事項からの除外: 精査で判明した事項は「未解決事項」から除外 (Spec ステージへ先送りしない)
• リスク: 既存実装のバグ / 古い設計 / テスト不足 等のリスクを「リスク」セクションに追加
• ヒアリングログ (任意): 精査結果のサマリと参照したファイルパスを記載

11.4 新規プロジェクト時の扱い

リポジトリが空、または README.md のみ存在する場合、深スキャンはスキップしてください。軽スキャンのみ実施し、Brainstorming ノートに「新規プロジェクトのため精査対象なし」と明記します。

11.5 大規模リポジトリでの注意

以下の場合は精査範囲を絞ってください。コンテキスト枯渇と精査時間の浪費を避けるためです。

• ファイル数が 1,000 を超える場合: ディレクトリ構造の概観のみで深掘りしない
• 関連キーワードでのヒット数が 50 を超える場合: ファイル名のみリストアップしてユーザーと相談 (どのファイルを読むかをユーザー判断に委ねる)
• 過去 commit が数百以上ある場合: 直近 1 ヶ月程度に範囲を限定

11.6 Phase 5 への橋渡し (investigator agent)

Phase 5 で investigator agent の役割を「Plan ステージ専用」から「Brainstorming + Plan 両ステージで使用」へ拡張する予定です。Phase 3 の時点では本 skill 内で精査を完結させますが、将来は重い精査を investigator agent に委譲することで、本 skill の責務を「ヒアリング進行」に集中させる設計に移行します。

そのため、Phase 3 の精査実装も「将来 investigator に委譲できる粒度」を意識してください。具体的には、精査ステップを「軽スキャン」「キーワード検索」「ファイル読み込み」「テストパターン確認」「commit 履歴確認」のように独立した手順として記述し、agent に切り出しやすい構造にします。