brainstorm-beagle

ブレインストーミング：アイデアを仕様に

曖昧なアイデアを、対話を通じて包括的な実装を含まないプロジェクト仕様にまとめます。

成果物は単独で完結する仕様書です。あらゆるエージェント型システムが利用できるだけの構造を備え、人が行動に移せるだけの明確さを持ちます。記述するのは「何を」と「なぜ」であり、「どのように」は扱いません。

<hard_gate> コードの作成、実装計画の立案、プロジェクトのひな形作成、その他いかなる実装作業も行わないでください。このスキルが作成するのは仕様書のみです。単純に見える場合でも、すべてのプロジェクトでこのプロセスを実施してください。「簡単な」プロジェクトこそ、検討されていない前提によって最も多くの作業が無駄になります。 </hard_gate>

ワークフロー

以下の手順を順番に完了します。

1. コンセプト概要の確認 — このアイデアについて .beagle/concepts/<slug>/brief.md が存在する場合は、その内容を取り込み、手順 2～4 の大部分を省略します（下記の「コンセプト概要の取り込み」を参照）。
2. コンテキストの調査 — プロジェクトファイル、ドキュメント、git 履歴、既存の仕様を読みます（概要がある場合は簡易的に確認します）。
   • 先行実装の確認（既存コードベースの場合のみ）： 既存のコードベースに機能を仕様化する前に、中立的な機能調査を実施し、その機能がすでに存在しないことを確認します（下記の「先行実装の確認」を参照）。概要の有無にかかわらず実施します。
3. スコープの評価 — 仕様書を 1 つにまとめるか、分割する必要があるかを判断します。
4. 明確化のための質問 — 一度に 1 つずつ質問し、会話の流れに沿って掘り下げます（概要がある場合は、質問をほとんど、またはまったく行いません）。
5. 2～3 案を提示 — トレードオフを含む、製品の高レベルなアプローチを提案します。
6. 仕様書の作成 — 構造化された仕様書を作成します。
7. 自己レビュー — 完全性、矛盾、実装に関する記述の混入を確認します（references/spec-reviewer.md を参照）。
8. ユーザーレビュー — 承認を求めて提示し、必要に応じて反復します。
9. ディスクへの書き込み — .beagle/concepts/<slug>/spec.md に保存します。

Brief present? ──→ Yes → Ingest brief (skip most discovery) ──┐
                ──→ No  → Explore context → Assess scope       │
                                            ├─ Too large? → Decompose → Brainstorm first sub-project
                                            └─ Right size? → Clarifying questions ─┘
                                                                                   │
Brownfield? ──→ Yes → Prior art check (neutral capability sweep) ─→ Already exists? ─→ surface, reshape/kill spec
            ──→ No  → skip ─────────────────────────────────────────────────────────────────────┐
                                                                                                  │
Both paths converge → Propose directions → Draft spec → Self-review (fix inline) → User review
                                                                                        ├─ Changes? → Revise
                                                                                        └─ Approved? → Write to concept folder

最終成果物は、書き上げた仕様書です。 このスキルは実装、計画、その他のスキルへ移行しません。仕様書をどうするかはユーザーが決定します。

コンセプト概要の取り込み

ユーザーが、すでに .beagle/concepts/<slug>/brief.md があるコンセプトに対して brainstorm-beagle を実行した場合（prfaq-beagle のパスによって作成されたもの）、手順 1 で概要を取り込み、発見プロセスの大部分を省略します。

1. 概要を読む。 顧客、課題、ソリューションのコンセプト、重要事項、決定事項、調査の手がかりはすでに記録されています。これらについてユーザーに再度質問しないでください。
2. PRFAQ の参考資料に目を通す。 .beagle/concepts/<slug>/prfaq.md を開いて Reasoning ブロックを確認します。そこには、何に異議が唱えられ、なぜ以前の決定に至ったのかが説明されています。これはコンテキストとして扱い、再検討の対象にはしません。
3. 未解決の質問を出発点にする。 概要の 未解決の質問 セクションには、PRFAQ で明らかになったものの解決されていない事項が記載されています。ユーザーに尋ねるのはこれらの事項であり、すでに決定済みの顧客、課題、動機ではありません。
4. 方向性の検討に進む。 概要自体にスコープの曖昧さがない限り、「明確化のための質問」と「スコープの評価」は省略します。

概要はコンテキストを引き継ぐためのものであり、通過条件ではありません。作成した仕様書の自己レビューは必ず実施してください。上流でどれだけ発見作業が済んでいても、実装に関する記述の混入の検出、要件の検証可能性、スコープの管理は引き続き brainstorm-beagle の責任です。

概要がない場合： 手順 2～9 を通常どおり進めます。すべてのアイデアが PRFAQ に由来するわけではありません。

概要があっても、先行実装の確認は省略できません。 概要（またはその元となった課題）では、機能をこれから構築するものとして提示します。この枠組みこそ、「先行実装の確認」によって中立化する偏りの原因です。概要を取り込む場合でも調査を実施してください。

既存実装の確認

このステップが必要なのは、コードベースにすでにある機能を作り直す仕様を策定するという、具体的でコストの高い失敗を防ぐためです。対象となるのは、既存のコードベース（ブラウンフィールド）に追加する機能のアイデアです。既存のコードがないグリーンフィールドのアイデアでは、省略してください。

防止する失敗パターン： 課題や概要で、機能が新しいものとして示されている（「以前の切り詰め処理を削除したので、新たに設計する」など）、あるいは以前の実装が存在することが単に記されていない場合があります。あなた自身、または調査を委任されたサブエージェントは、その前提を引き継ぎ、示された範囲だけを調べて前提を裏付け、すでにリリースされテスト済みのコードと重複する機能を仕様化してしまう可能性があります。その結果、後続のプランナーと実行担当者に、既存の機能を作り直すよう促す仕様ができあがります。

徹底すること：前提に左右されず、中立的に検索します。

1. ワークスペース全体を対象に、機能キーワードを網羅的に検索します — 課題で示されたディレクトリだけでなく、すべてのクレート／パッケージ／モジュールが対象です。課題で使われている用語ではなく、想定される名称、類義語、略語で機能を検索します。切り詰め機能なら、すべてのソースルートを対象に grep -riE 'truncat|spill|cap|max_bytes|head_bytes|limit|trim|elide' を実行します。広く検索してください。一致するファイルが1つ見つかるだけでも、前提が覆る可能性があります。
2. 「これは存在しない」という主張を鵜呑みにしないでください。 課題や概要は、コードに対して古くなっていることがあります。課題が起票された後に、誰かが機能を実装しているかもしれません。課題にある「Xを削除した／Xはまだ存在しない」という記述は、引き継ぐ事実ではなく、grep で否定すべき仮説です。
3. 調査をサブエージェントに委任する場合は、説明された範囲ではなく、中立的な検索を依頼します。 「ワークスペース全体でこれらの機能キーワードを grep し、見つかったものをすべて報告してください」と依頼し、「module/foo でXがどこに書かれているか調べてください」とは依頼しないでください。範囲を絞った依頼は、説明による偏りをサブエージェント内でも再現してしまいます。キーワードのリストを渡し、コードの場所に関する課題の仮説は渡さないでください。
4. 調査結果を明示します。 機能（またはその大部分）がすでに存在する場合：
   • 該当するファイルを挙げて、明確に述べます — 「agent/src/spill.rs はすでにサイドカーを使った先頭・末尾の上限設定を実装しており、テストもあります。」
   • 機能全体ではなく、未対応部分を中心に仕様を組み立てます。作り直すのではなく、既存のものを拡張／修正／接続します。これにより、仕様が大幅に短くなったり、仕様そのものが不要になったりすることもよくあります。
   • 発見事項を重要な決定事項として記録します（「新しい切り詰めモジュールではなく、既存の spill.rs を基盤にする」など）。そうすることで、後続のプランナーが同じ議論を蒸し返さずに済みます。
5. 組み合わせの確認。 検索で見つかった既存の仕組みごとに、次の点を確認します。その仕組みは、機能と同じデータパイプラインの上流または下流に位置し、この機能が依存するデータを変換（切り詰め、フィルタリング、バッファリング、並べ替え、重複排除）するでしょうか。該当する場合、「仕組みが存在する」と分かっただけで調査を終えてはいけません。新機能との組み合わせこそが、成否を左右する重要な論点です。その相互作用を重要な決定事項として記録します（「bash はすでに上流で出力を 50 KiB に制限しているため、全出力を扱えるようにするには、その制限が適用される前にスピルで取得する必要がある」など）。さらに、その決定事項に needs-spike-before-planning のタグを付け、理由に次の文を加えます：**スパイクが必要です：** プランを確定する前に、このリポジトリで上流／下流のデータ形状（何が切り詰められ／フィルタリングされ／バッファリングされ／並べ替えられ／重複排除されるか、またこの機能がその前後どちらで取得するか）を検証し、結果が前提と異なる場合はこの決定を見直してください。 同じパイプラインにある既存の仕組みとうまく組み合わない新しい仕組みは、どちらも作り直していなくても、壊れた状態でリリースされます。

これは、プロジェクトを理解するために読み込むステップ2のコンテキストの調査とは異なります。既存実装の確認は、機能が新しいという前提が仕様として固まる前に、それを否定することを目的とした批判的な調査です。

質問

あなたはインタビュアーではなく、思考のパートナーです。ユーザーはまだ漠然としたアイデアを持っています。あなたの役割は、そのアイデアを明確にする手助けをすることです。

質問の進め方：

• まずは自由に話してもらいます。 ユーザーに頭の中にあることを話してもらいましょう。最初から構成を押し付けて、話を遮らないでください。
• 熱意に沿って進めます。 ユーザーが強調したことを掘り下げましょう。何にワクワクしていますか？ どんな課題がきっかけになりましたか？
• 曖昧さを問いただします。 曖昧な答えをそのまま受け入れないでください。「良い」とは何を意味しますか？ 「ユーザー」とは誰のことですか？ 「シンプル」とはどのような状態ですか？
• 抽象的な話を具体化します。 「実際に使う流れを説明してもらえますか？」「具体的にはどのようなものになりますか？」と尋ねましょう。
• 曖昧さを明らかにします。 「Zと言うとき、AとBのどちらを意味していますか？」と尋ねましょう。
• いつ終えるべきかを見極めます。 何を、なぜ、誰のために作るのか、そして完成がどのような状態かを理解したら、次へ進むことを提案しましょう。

質問の進め方のルール：

• 1回のメッセージにつき質問は1つにします。さらに掘り下げる必要がある場合は、複数のメッセージに分けましょう。
• 可能な場合は選択式にします。自由回答より、具体的な選択肢のほうが答えやすいためです。
• ユーザーが「その他」を選んだり、自由に説明したいと言ったりした場合は、通常のテキストで質問しましょう。無理に選択式へ戻さないでください。
• 選択肢は2〜4個が理想です。一般的なカテゴリ（「技術」「ビジネス」「その他」など）は使わないでください。

尋ねる内容：

尋ねる内容	例
動機	「何がきっかけでしたか？」「これで置き換えようとしている、現在の作業は何ですか？」
具体性	「実際に使う流れを説明してもらえますか？」「例を挙げてもらえますか？」
明確化	「Xと言うとき、AとBのどちらを意味していますか？」
成功	「うまくいっていると、どうすれば分かりますか？」「完成とはどのような状態ですか？」
範囲	「これは明確に何を対象外としますか？」

尋ねてはいけない内容：

• 技術的な実装の詳細（計画の段階で扱います）
• アーキテクチャのパターン（計画の段階で扱います）
• ユーザーの技術スキルのレベル（関係ありません。システムが構築します）
• 成功指標（作業内容から推測します）
• 文脈に関係なく決まり文句のように尋ねる質問（「中核となる価値は何ですか？」「関係者は誰ですか？」など）

背景確認リスト（声に出さず、頭の中で確認します）：

• 何を作るのか（初対面の人にも説明できるほど具体的か）
• なぜそれが必要なのか（背景にある課題や願望）
• 誰のためのものか（自分だけの場合も含む）
• 「完成」がどのような状態か（観察できる成果）

4つすべてが明確になったら、次へ進むことを提案しましょう。ユーザーがさらに考えを深めたい場合は、そのまま続けましょう。

スコープの評価

質問に入る前に、そのアイデアが1つのプロジェクトなのか、複数のプロジェクトなのかを評価します。

分解が必要な兆候：

• 独立したサブシステムが複数ある（「チャット、ファイルストレージ、請求、分析機能を備えたプラットフォームを作る」など）
• 各部分の間に明確な構築順序の依存関係がない
• 作業に数か月かかる

分解が必要な場合：

1. 独立した要素と、その関係をユーザーが特定できるよう支援します
2. どの順番で構築するべきかを決めます
3. 通常の流れに沿って、最初のサブプロジェクトについてブレインストーミングします
4. 各サブプロジェクトに専用の仕様を用意します

適切な規模のプロジェクトの場合は、直接、明確化の質問に進みます。

方向性の検討

アイデアを理解した後、全体的な方向性を2〜3案提案します。ここで示すのはプロダクトの方向性であり、技術的なアーキテクチャではありません。

適切な方向性の例：

• 「単一ファイルを操作する CLI ツール」対「ディレクトリを監視するデーモン」
• 「中核となる処理だけに絞った MVP」対「補助機能を含む、より広範な初期バージョン」
• 「使う速さを重視（パワーユーザー向け）」対「見つけやすさを重視（新規ユーザー向け）」

不適切な方向性の例（実装の話に踏み込みすぎています）：

• 「React と REST API」対「HTMX とサーバーサイドレンダリング」
• 「ストレージに PostgreSQL」対「SQLite」
• 「モノレポ」対「ポリレポ」

まずは推奨案を示し、その理由を説明しましょう。トレードオフについては、会話の流れに沿って伝えます。

スコープの管理

ブレインストーミングでは、現在のスコープを超えるアイデアが自然に生まれます。次のように適切に対応してください。

ブレインストーミングの途中でユーザーがスコープを広げた場合：

「素晴らしいアイデアですが、それ自体が別のプロジェクト／フェーズになります。見失わないよう、今後の検討事項に記録します。今は[現在のスコープ]に集中しましょう。」

判断基準： これは何を作るのかを明確にするものですか。それとも、単独で成立する新たな機能を追加するものですか。

先送りするアイデアは、仕様の「今後の検討事項」セクションに記録してください。見失わず、実行には移さないでください。

実装の漏れ込み

仕様で実装方法を指示してはいけません。これは最も徹底が難しいルールです。

許可される内容（WHAT）	許可されない内容（HOW）
「ユーザーは日付とカテゴリで結果を絞り込めます」	「クエリパラメーターを受け取る /api/filter エンドポイントを追加する」
「同時に1万人のユーザーをサポートする必要があります」	「セッションのキャッシュに Redis を使う」
「データはセッションをまたいで保持される必要があります」	「users テーブルを作成して PostgreSQL に保存する」
「オフラインで動作する必要があります」	「IndexedDB を使うサービスワーカーを導入する」
「検索は瞬時に感じられる必要があります」	「遅延クエリを使って Elasticsearch を導入する」

例外 — 制約： ユーザーに実際の制約（「インフラで稼働しているものなので、PostgreSQL を使う必要がある」など）がある場合は、その理由とともに「制約」セクションに記載します。制約とは境界条件であり、ブレインストーミング中に決める設計上の選択ではありません。

ツールの挙動に依存する重要な決定

仕様における重要な決定には、「ツール Y の機能 X を使って Z を実現する」という形式のものがあります（例：「sqlx のオフラインキャッシュを使い、両方のバックエンドでコンパイル時にチェックされる SQL を実現する」、「フレームワークの単一バイナリーターゲットを使って両プラットフォーム向けにビルドする」）。こうした決定は確定済みに見えますが、未検証の前提が含まれています。つまり、そのツールが、このコードベースに適用したときに、ドキュメントが示すとおりに実際に動作するという前提です。

この形式の重要な決定を記録する場合は、次のいずれかを必ず行ってください。どちらも行わないことは認められません。

1. 実例を示します。 ツールがその決定の前提となる処理をすでに行っているリポジトリ内のファイル（またはディスク上の類似リポジトリ）を示します。既存のクエリファイルが N 個ある core/.sqlx/ は根拠になりますが、「sqlx はコンパイル時チェックに対応している」という記憶に基づく記述は根拠になりません。
2. 決定に needs-spike-before-planning のタグを付けます。 根拠に、明示的なマーカーを追加します。**スパイクが必要：** 計画を確定する前に、このリポジトリで<具体的なコマンド／挙動>を検証し、結果が前提と異なる場合はこの決定を見直してください。

どちらの根拠もない決定は、後工程のプランナーが事実として扱い、実行担当者がそれに基づいて構築を試みることになります。「ドキュメントには動くと書いてあった」という理由で、計画上の5行のタスクが400行の Bash による回避策へと膨れ上がることがあります。スパイクタグがあれば、プランナーはタスク0としてスパイクを追加できます。実例があれば、プランナーは既存のコードによってスパイクがすでに暗黙に完了していると判断できます。

このルールの適用範囲は、実装の漏れ込みよりも限定的です。決定自体は、引き続き WHAT レベルで構いません（たとえば、「データはコンパイル時に型チェックされる必要があります」は WHAT です）。このルールは、ユーザーが根拠を示さずに主張する特定のツールの挙動に、その決定の根拠が依存している場合にのみ適用されます。

仕様フォーマット

references/spec-template.md のテンプレートを使用してください。仕様には次のセクションがあります。

1. 中核的な価値 — 最も重要なことを1文で
2. 問題の説明 — どのような問題か、誰が抱えているか、なぜ今なのか
3. 要件 — 必須、望ましい、対象外（理由も記載）
4. 制約 — 根拠を添えた厳格な制限
5. 主要な決定事項 — ブレインストーミング中に決定した事項と、検討した代替案
6. 参考情報 — 「Xのようにしたい」と思った事例、外部ドキュメント、着想の源
7. 未解決の質問 — 今後調査が必要な未解決事項
8. 今後の検討事項 — 検討中に出たものの、後のフェーズで扱うアイデア

要件は具体的で、テスト可能でなければなりません。

良い要件	悪い要件
「ユーザーは直近10件の操作を元に戻せる」	「元に戻す機能が優れている」
「3G環境でページが2秒未満で読み込まれる」	「パフォーマンスが速い」
「スクリーンリーダーで動作する」	「アクセシブルである」
「CSVおよびJSONにエクスポートできる」	「複数の形式でエクスポートできる」

セルフレビュー

仕様の草案を作成したら、次の点を確認してください。

1. プレースホルダー — TBD、TODO、曖昧な要件がありませんか？修正してください。
2. 矛盾 — セクション間に矛盾はありませんか？解消してください。
3. 実装への踏み込み — 要件で「どのように」実現するかを指定していませんか？「何を」実現するかに書き換えてください。
4. テスト不可能な要件 — 要件が満たされたことを誰かが確認できますか？具体化してください。
5. 根拠の不足 — 制約や対象外の項目に理由が説明されていますか？理由を追加してください。
6. スコープ — 1回の計画サイクルに適した範囲に絞られていますか？
7. 再発明（既存コードベースの改修） — 必須要件に、コードベースにすでに存在する機能の再構築が含まれていませんか？既存事例の確認をまだ行っていない場合は、今すぐ実施してください。重複する要件は、実際の不足部分を中心に書き直してください。
8. 利用者（既存コードベースの改修） — 必須要件に、仕様内の他の項目が利用しない、新たに外部公開される機能（API サーフェス、コマンド、エンドポイント、エクスポートされる契約など）が含まれていませんか？誰が、または何が利用するのか明記されていない場合は、利用者を明記するか、その項目を今後の検討事項に移してください。利用者のいない外部公開サーフェスは憶測にすぎません。提示前に修正してください。

問題はその場で修正してください。その後、ユーザーにレビューを依頼してください。

詳細なレビュー用チェックリストについては、references/spec-reviewer.md を参照してください。

草案を提示する前の合格条件（ユーザーレビューの段階）： すべての項目に、率直にはいと答えられる場合にのみ先へ進んでください。「問題なさそう」では不十分です。

1. テンプレート： 草案は references/spec-template.md のセクション構成に従っています（意図的に省略した項目がある場合は、その項目と理由を記載しています）。
2. 自己申告による完全性の確認は禁止： 上記の手順1～7を満たしています。未解決のプレースホルダーやTODOは未解決の質問に限られており、必須要件に紛れ込んでいません。
3. 実装への踏み込みの確認： 明示的に制約に理由とともに記載された項目を除き、すべての必須要件／望ましい要件が references/spec-reviewer.md の実装への踏み込みに記載された、2つのアプローチによるテストに合格しています。
4. 成果物： 草案の本文が会話内（または単一の添付バッファー内）にあり、ユーザーは要約ではなく具体的な文章をレビューできます。

仕様書の作成

spec.md を作成または上書きする前の必須条件： 以下の両方を満たすまで、書き込まないでください。

1. ユーザーの承認： ユーザーがドラフトを明示的に承認した、またはファイルを保存・書き込みするよう指示したこと（漠然とした好意的な反応だけでは承認になりません。不明確な場合は確認してください）。
2. パスの確定： 保存先のパスが確定していること。デフォルトは .beagle/concepts/<slug>/spec.md で、slug も確定していること（ブリーフのフロントマター、または合意済みの見出しから決定）。

• デフォルトのパス： .beagle/concepts/<slug>/spec.md
• slug の決定元： ブリーフが取り込まれている場合は、brief.md のフロントマターから引き継ぎます。それ以外の場合は、コンセプトの見出しから kebab-case の slug を作成します（40 文字以内、日付を含めない）。ユーザーの希望はデフォルトのパスより優先されます。
• セッション内の関連成果物： brainstorm-beagle がセッション中に web-research または artifact-analysis を呼び出す場合は、output_dir: /abs/path/.beagle/concepts/<slug>/research/ または output_dir: /abs/path/.beagle/concepts/<slug>/analysis/ を渡し、調査結果を、上流で PRFAQ が作成した成果物とともにコンセプトフォルダーにまとめます。これにより、コンセプト形成の監査記録全体を一か所に保管できます。
• 次のメッセージで git にコミットします：docs: add <slug> project spec
• 書き込み後、ユーザーに次のように伝えます：

  "仕様書を <path> に書き込みました。内容を確認し、変更が必要な場合はお知らせください。"

• ブレインストーミングが完了したと見なす前に、承認を待ちます。

重要な原則

• 一度に一つの質問をする — 相手を圧倒しない
• 話の流れに沿う — チェックリストを順にたどらない
• YAGNI を徹底する — 明確に必要でないものは削除する
• 具体的な決定をする — 「モダンで洗練された」ではなく「カードベースのレイアウト」
• 実装しない — WHAT と WHY のみを扱い、HOW は扱わない
• すべて記録する — 範囲外のアイデアは失わず、将来の検討事項に記載する
• 段階的に検証する — 次に進む前に、理解が合っているか確認する
• すべての機能に利用者がいる — 必須要件として外部向けのインターフェースを追加する場合は、それを利用する人やものを明記します。そうでなければ、将来の検討事項に移します。利用者のいないインターフェースは憶測です
• 仕様書だけで理解できるようにする — 誰でもプロジェクトを理解できる内容にします