brainstorming

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

自然な対話を通じて、アイデアを具体的なデザインや仕様にまとめるのを支援します。

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

デザインを提示し、ユーザーの承認を得るまでは、実装スキルを呼び出したり、コードを書いたり、プロジェクトのひな形を作成したり、実装に向けた操作を行ったりしてはいけません。これは、どれほど簡単に思えるプロジェクトにも例外なく適用されます。

アンチパターン：「デザインが必要なほど複雑ではない」

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

チェックリスト

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

1. プロジェクトの状況を調べる — ファイル、ドキュメント、最近のコミットを確認します
2. ビジュアル資料を提案する（トピックに視覚的な質問が含まれる場合） — 確認質問とは別のメッセージで提示します。以下の「ビジュアル資料」セクションを参照してください。
3. 確認質問をする — 目的、制約、成功基準を理解するため、一度に一つずつ質問します
4. 2～3種類のアプローチを提案する — トレードオフと推奨案を示します
5. デザインを提示する — 複雑さに応じたセクションに分け、各セクションの後にユーザーの承認を得ます
6. デザイン文書を書く — プロジェクトの仕様／デザイン用ディレクトリ（例：ai-workspace/plans/YYYY-MM-DD-<topic>-design.md）に保存します。仕様の保存先についてユーザーの希望を尊重してください。
7. 仕様を自己レビューする — プレースホルダー、矛盾、曖昧さ、範囲について簡単にその場で確認します（以下を参照）
8. ユーザーに作成した仕様をレビューしてもらう — 次に進む前に、仕様ファイルをレビューするようユーザーに依頼します
9. 実装に移行する — /blueprint を呼び出して実装計画を作成します

プロセスの流れ

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 /blueprint" [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 /blueprint" [label="approved"];
}

最終状態は /blueprint の呼び出しです。 frontend-design、mcp-builder、またはその他の実装スキルを呼び出してはいけません。ブレインストーミングの後に呼び出すスキルは、/blueprint のみです。

プロセス

アイデアを理解する：

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

アプローチを検討する：

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

設計を提示する：

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

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

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

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

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

設計の完了後

ドキュメント：

• 検証済みの設計（仕様）を、プロジェクトの spec/design ディレクトリに書き込みます（例：ai-workspace/plans/YYYY-MM-DD-<topic>-design.md）。仕様の保存場所に関するユーザーの希望を尊重してください。
• 利用可能であれば、elements-of-style:writing-clearly-and-concisely スキルを使用します。
• 設計ドキュメントを git にコミットします。

仕様のセルフレビュー： 仕様ドキュメントを書いた後、改めて内容を確認します。

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

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

ユーザーレビューのゲート： 仕様のレビューループを通過したら、先に進む前に、作成した仕様をレビューするようユーザーに依頼します。

「仕様を <path> に書き込み、コミットしました。レビューしていただき、実装計画の作成を始める前に変更したい点があればお知らせください。」

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

実装：

• 詳細な実装計画を作成するため、/blueprint を呼び出します。
• 他のスキルは呼び出さないでください。次のステップは /blueprint です。

主な原則

• 一度に一つの質問 - 複数の質問で圧倒しないでください。
• 選択式を優先 - 可能であれば、自由回答より答えやすい形式にします。
• YAGNI を徹底 - すべての設計から不要な機能を取り除きます。
• 代替案を検討 - 決定する前に、常に 2～3 案を提示します。
• 段階的に検証 - 設計を提示し、次に進む前に承認を得ます。
• 柔軟に対応 - 納得できない点があれば、戻って確認します。

ビジュアルコンパニオン

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

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

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

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

**質問ごとの判断：**ユーザーが同意した後も、質問ごとにブラウザーとターミナルのどちらを使うか判断します。基準は、読んで理解するより、見たほうが理解しやすいかです。

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

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

コンパニオンの利用に同意された場合は、続行する前に詳細ガイドを読みます。スキルのディレクトリにビジュアルコンパニオンのガイドがある場合は、それを読みます。