brainstorming

アイデアをデザインにまとめる

自然な対話を通じて、アイデアを具体的なデザインや仕様に仕上げるお手伝いをします。

まず現在のプロジェクトの状況を把握し、次に質問を一つずつ行ってアイデアを練り上げます。何を作るのかを理解したら、デザインを提示してユーザーの承認を得ます。

デザインを提示し、ユーザーの承認を得るまで、実装スキルの呼び出し、コードの記述、プロジェクトのひな形作成、その他の実装作業を行ってはいけません。これは、どれほど簡単に見えるプロジェクトであっても例外ではありません。

アンチパターン：「デザインは不要なほど簡単」

すべてのプロジェクトで、このプロセスを実施します。ToDoリスト、単機能のユーティリティ、設定の変更も、すべて対象です。「簡単な」プロジェクトほど、検討されていない前提によって無駄な作業が最も多く発生します。デザインは短くてもかまいません（本当に簡単なプロジェクトなら数文程度で十分です）が、必ず提示して承認を得てください。

チェックリスト

以下の各項目について必ずタスクを作成し、順番に完了してください。

1. プロジェクトの状況を調べる — ファイル、ドキュメント、最近のコミットを確認します
2. ビジュアル資料を提案する（ビジュアルに関する質問が含まれる場合） — これは確認質問とは別のメッセージにします。以下の「ビジュアル資料」セクションを参照してください。
3. 確認質問をする — 目的、制約、成功基準を理解するため、一度に一つずつ質問します
4. 2〜3つのアプローチを提案する — トレードオフと推奨案を示します
5. デザインを提示する — 複雑さに応じたセクションに分け、各セクションについてユーザーの承認を得ます
6. デザインドキュメントを作成する — docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md に保存してコミットします
7. 仕様を自己レビューする — プレースホルダー、矛盾、曖昧さ、範囲を簡潔に確認します（以下を参照）
8. ユーザーが作成した仕様をレビューする — 次に進む前に、仕様ファイルのレビューをユーザーに依頼します
9. 実装へ移行する — writing-plans スキルを呼び出して実装計画を作成します

プロセスの流れ

digraph brainstorming {
    "Explore project context" [shape=box];
    "Visual questions ahead?" [shape=diamond];
    "Offer Visual Companion\n(own message, no other content)" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "Present design sections" [shape=box];
    "User approves design?" [shape=diamond];
    "Write design doc" [shape=box];
    "Spec self-review\n(fix inline)" [shape=box];
    "User reviews spec?" [shape=diamond];
    "Invoke writing-plans skill" [shape=doublecircle];

    "Explore project context" -> "Visual questions ahead?";
    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "Present design sections";
    "Present design sections" -> "User approves design?";
    "User approves design?" -> "Present design sections" [label="no, revise"];
    "User approves design?" -> "Write design doc" [label="yes"];
    "Write design doc" -> "Spec self-review\n(fix inline)";
    "Spec self-review\n(fix inline)" -> "User reviews spec?";
    "User reviews spec?" -> "Write design doc" [label="changes requested"];
    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
}

最終段階で呼び出すのは writing-plans です。 frontend-design、mcp-builder、その他の実装スキルを呼び出してはいけません。ブレインストーミングの後に呼び出すスキルは、writing-plans だけです。

プロセス

アイデアを理解する：

• まず、現在のプロジェクトの状態（ファイル、ドキュメント、最近のコミット）を確認します
• 詳細な質問をする前に、範囲を評価します。依頼に複数の独立したサブシステム（例：「チャット、ファイルストレージ、請求、分析機能を備えたプラットフォームを構築する」）が記載されている場合は、すぐにその点を伝えます。まず分割が必要なプロジェクトについて、詳細を詰める質問に時間をかけないでください。
• プロジェクトが単一の仕様に収まらないほど大きい場合は、サブプロジェクトへの分解を支援します。独立した部分は何か、それらはどう関連しているか、どの順序で構築すべきかを整理します。その後、通常の設計フローに沿って最初のサブプロジェクトを検討します。各サブプロジェクトで、仕様 → 計画 → 実装のサイクルを個別に進めます。
• 適切な範囲のプロジェクトでは、アイデアを具体化するために、質問を一度に1つずつします
• 可能であれば選択式の質問を優先しますが、自由回答でもかまいません
• 1つのメッセージにつき質問は1つだけにします。あるトピックをさらに掘り下げる必要がある場合は、質問を複数に分けます
• 目的、制約、成功基準の理解に重点を置きます

アプローチを検討する：

• トレードオフの異なるアプローチを2～3案提示します
• 推奨案とその理由を説明しながら、会話形式で選択肢を提示します
• 推奨する選択肢を最初に示し、その理由を説明します

設計を提示する：

• 何を構築するのか理解できたと考えたら、設計を提示します
• 各セクションの詳しさは複雑さに応じて調整します。単純な内容なら数文、複雑な内容なら200～300語まで説明します
• 各セクションの後に、ここまでの内容で問題ないかを確認します
• アーキテクチャ、コンポーネント、データフロー、エラー処理、テストを扱います
• 不明点があれば、戻って確認する準備をしておきます

分離と明確さを重視して設計する：

• システムを、それぞれ明確な目的を持ち、定義されたインターフェースを通じて連携し、個別に理解・テストできる小さな単位に分割します
• 各単位について、何をするのか、どう使うのか、何に依存するのかを説明できるようにします
• 内部の実装を読まなくても、その単位の役割を理解できますか？内部実装を変更しても、利用側に影響はありませんか？そうでない場合は、境界を見直す必要があります。
• 適切に境界を定めた小さな単位は、作業もしやすくなります。一度にコンテキストに収められるコードのほうが推論しやすく、焦点の定まったファイルなら変更の信頼性も高まります。ファイルが大きくなっている場合は、役割を抱え込みすぎている兆候であることがよくあります。

既存のコードベースで作業する：

• 変更を提案する前に、現在の構成を調べます。既存のパターンに従います。
• 既存コードの問題が作業に影響する場合（例：ファイルが大きくなりすぎている、境界が不明確、責務が複雑に絡み合っている）は、優れた開発者が作業中のコードを改善するように、対象を絞った改善を設計に含めます。
• 無関係なリファクタリングは提案しません。現在の目標に役立つことに集中します。

デザインの後

ドキュメント：

• 検証済みのデザイン（仕様書）を docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md に記述します
  • （仕様書の保存場所についてユーザーの希望がある場合は、この既定の場所より優先します）
• 利用できる場合は、elements-of-style:writing-clearly-and-concisely スキルを使用します
• デザインドキュメントを git にコミットします

仕様書のセルフレビュー： 仕様書を作成したら、改めて内容を確認します。

1. プレースホルダーの確認： 「TBD」「TODO」、未完成のセクション、曖昧な要件はありませんか？あれば修正します。
2. 内部整合性： セクション間に矛盾はありませんか？アーキテクチャは機能の説明と一致していますか？
3. スコープの確認： 単一の実装計画として十分に絞り込まれていますか？それとも、分割する必要がありますか？
4. 曖昧さの確認： 要件が複数の意味に解釈される可能性はありませんか？ある場合は、解釈を一つに決めて明記します。

問題があれば、その場で修正します。再レビューは不要です。修正したら次に進みます。

ユーザーレビューのゲート： 仕様書のレビューを終えたら、先に進む前に、作成した仕様書をユーザーにレビューしてもらいます。

"仕様書を作成し、<path> にコミットしました。実装計画の作成を始める前に内容をご確認ください。変更したい点があればお知らせください。"

ユーザーの返答を待ちます。変更の依頼があれば修正し、仕様書のレビューをやり直します。ユーザーの承認を得てから先に進みます。

実装：

• writing-plans スキルを呼び出して、詳細な実装計画を作成します
• ほかのスキルは呼び出さないでください。次のステップで呼び出すのは writing-plans です。

重要な原則

• 質問は一度に一つ — 複数の質問でユーザーを圧倒しないでください
• 選択式を優先 — 可能な場合は、自由回答よりも回答しやすい形式にします
• YAGNIを徹底する — すべてのデザインから不要な機能を取り除きます
• 代替案を検討する — 決定する前に、必ず2～3つのアプローチを提案します
• 段階的に検証する — デザインを提示し、次に進む前に承認を得ます
• 柔軟に対応する — 筋が通らない点があれば、戻って確認します

ビジュアルコンパニオン

ブレインストーミング中にモックアップ、図、視覚的な選択肢を表示するための、ブラウザー上で動作するコンパニオンです。モードではなく、ツールとして利用できます。コンパニオンを利用すると、視覚的な表現が役立つ質問で使えるようになりますが、すべての質問をブラウザーで扱うという意味ではありません。

コンパニオンの提案： これからの質問に視覚的な内容（モックアップ、レイアウト、図など）が含まれそうな場合は、同意を得るために一度だけ提案します。

"取り組んでいる内容の一部は、ウェブブラウザーで図を見せながら説明すると、より分かりやすいかもしれません。作業を進めながら、モックアップ、図、比較資料などを用意できます。この機能はまだ新しく、トークンを多く消費することがあります。試してみますか？（ローカルURLを開く必要があります）"

この提案は、必ず単独のメッセージにしてください。 確認の質問、状況の要約、その他の内容と一緒にしてはいけません。メッセージには上記の提案だけを含め、ほかの内容は一切含めないでください。続行する前にユーザーの返答を待ちます。断られた場合は、テキストのみでブレインストーミングを進めます。

質問ごとの判断： ユーザーがコンパニオンの利用に同意した後も、質問ごとにブラウザーとターミナルのどちらを使うか判断します。判断基準は、読むよりも見たほうがユーザーに伝わりやすいかです。

• ブラウザーを使う場合： 視覚的な内容そのものを扱う場合（モックアップ、ワイヤーフレーム、レイアウトの比較、アーキテクチャ図、デザインの並列比較）
• ターミナルを使う場合： テキストを扱う場合（要件の質問、概念的な選択肢、トレードオフの一覧、A/B/C/D形式のテキスト選択肢、スコープの決定）

UIに関する質問だからといって、必ずしも視覚的な質問とは限りません。「この文脈でパーソナリティとは何を意味しますか？」は概念に関する質問なので、ターミナルを使います。「どのウィザードのレイアウトがよいですか？」は視覚に関する質問なので、ブラウザーを使います。

コンパニオンを使うことに同意した場合は、続行する前に詳細ガイドを読んでください。 skills/brainstorming/visual-companion.md