brainstorming

アイデアを設計にまとめる

自然な対話を通じて、アイデアを完成度の高い設計と仕様にまとめるのを支援します。

まず現在のプロジェクトの状況を把握してから、アイデアを磨くために質問を一度に1つずつ尋ねます。何を作るのか理解できたら、設計を提示してユーザーの承認を得ます。

設計を提示し、ユーザーが承認するまでは、実装スキルを呼び出したり、コードを書いたり、プロジェクトのひな形を作成したり、実装に関する作業を行ったりしてはいけません。これは、簡単に見えるかどうかにかかわらず、すべてのプロジェクトに適用されます。

アンチパターン：「設計するほどのことではない」

すべてのプロジェクトでこのプロセスを実施します。ToDoリスト、単一機能のユーティリティ、設定の変更も例外ではありません。確認していない前提が最も大きな手戻りを招くのは、「簡単な」プロジェクトです。設計は短くてもかまいません（本当に簡単なプロジェクトなら数文程度です）が、必ず提示して承認を得てください。

チェックリスト

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

1. プロジェクトの状況を調べる — ファイル、ドキュメント、最近のコミットを確認する
2. ビジュアルコンパニオンを提案する（話題に視覚的な質問が含まれる場合）— これは確認質問とまとめず、独立したメッセージで送ります。以下の「ビジュアルコンパニオン」セクションを参照してください。
3. 確認質問をする — 目的、制約、成功基準を理解するために、一度に1つずつ質問する
4. 2～3つのアプローチを提案する — トレードオフと推奨案を示す
5. 設計を提示する — 複雑さに応じたセクションに分け、各セクションの後でユーザーの承認を得る
6. 設計ドキュメントを作成する — docs/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 です。 designing-frontend-interfaces、building-mcp-servers、またはその他の実装スキルを呼び出してはいけません。ブレインストーミングの後に呼び出すスキルは、writing-plans だけです。

プロセス

アイデアを理解する：

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

アプローチを検討する：

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

設計を提示する：

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

プロジェクトにユーザーインターフェースがある場合：

仕様に含めるべき重要な点が2つあります。どちらも構造に関わるため、記載を忘れやすく、後から追加するのは高くつきます。

• 美的方向性。 「クリーンでモダン」ではなく、実世界の具体的な事例を伴う、明確な方向性を定めます。designing-frontend-interfaces/references/aesthetic-directions.md には選択できる一覧があります。実装時に決めると、デフォルト設定に任せることになります。
• 状態の網羅性。 各画面について、データがない初回ユーザーには何が表示されるか、失敗時にどう見えるか、接続が遅い場合にどうなるかを定めます。完全なマトリックスは designing-user-experience にあります。これらは仕上げではなく要件です。記載を省いた仕様では、実装でも省かれてしまいます。

明確化の質問をする際に、この2点についても尋ねます。実装スキルは呼び出さないでください。一覧を確認するために参考ファイルを読むのは問題ありませんが、最終状態は引き続き writing-plans です。

分離と明瞭さを考慮して設計する：

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

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

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

設計後

ドキュメント：

• 検証済みの設計（仕様）を docs/specs/YYYY-MM-DD-<topic>-design.md に記述します
  • （仕様書の保存場所についてユーザーの希望がある場合は、この既定の保存場所より優先します）

仕様書のセルフレビュー： 仕様書を作成したら、あらためて新鮮な視点で確認します。

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

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

ユーザーレビューの確認： 仕様書のレビューループが完了したら、先に進む前に、作成した仕様書をユーザーに確認してもらいます。

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

ユーザーの返答を待ちます。変更の依頼があった場合は修正し、仕様書のレビューループを再実行します。ユーザーの承認を得てから先に進みます。

実装：

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

重要な原則

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

ビジュアルコンパニオン

ブレインストーミング中にモックアップ、図、ビジュアル案を見せるためのブラウザベースのコンパニオンです。モードではなく、ツールとして利用できます。コンパニオンを利用すると、視覚的な説明が役立つ質問で使えるようになりますが、すべての質問をブラウザ経由にするという意味ではありません。

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

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

この提案は必ず単独のメッセージにしてください。 確認の質問、背景の要約、その他の内容と組み合わせてはいけません。メッセージには上記の提案のみを含め、それ以外は何も含めないでください。先に進む前にユーザーの返答を待ちます。断られた場合は、テキストのみでブレインストーミングを続けます。

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

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

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

コンパニオンの利用に同意した場合は、先に進む前に詳細なガイドを読みます。 skills/brainstorming/visual-companion.md