brainstorming

アイデアをデザインに落とし込む

概要

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

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

デザインを先に行う理由

実装前にデザインを提示することで、コストのかかる次のような失敗を防げます。

• 前提のずれ — 間違った目標に向かってコーディングすると、軌道修正に多大なコストがかかります
• スコープの拡大 — デザインによって境界が明確になります。デザインなしで実装すると、機能が肥大化しやすくなります
• アーキテクチャの作り直し — 初期のコードは構造上の負債を生みやすく、それが後々積み重なります
• 専門スキルの無駄遣い — 実装スキルは強力ですが、明確な方向性がなければ無駄になります

これは、簡単なものも含めて、あらゆるプロジェクトに当てはまります。ToDo リスト、単一機能のユーティリティ、設定変更でも、意図と異なるものをリリースしてしまう可能性があります。簡単なプロジェクトならデザインは短くても構いません（数文程度）が、実装を始める前に作成し、承認を得る必要があります。

アンチパターン：「これは簡単すぎてデザインは不要」

詳しい失敗例と防止手順については、以下の「よくある落とし穴 1」を参照してください。

ワークフロー

次のフェーズを順番に進めます。各ステップは前のステップを土台とします。

1. プロジェクトの状況を調べる — ファイル、ドキュメント、最近のコミットを確認し、実情に基づいて対話します
2. 明確化のための質問をする — 目的、制約、成功基準を理解するため、一度に1つずつ質問します
3. 2～3つのアプローチを提案する — 代替案を検討したことが伝わるよう、トレードオフと推奨案を示します
4. デザインを提示する — 複雑さに応じたセクションに分けて提示し、各セクションの後にユーザーの承認を得ます
5. デザインドキュメントを作成する — docs/plans/YYYY-MM-DD-<topic>-design.md に保存し、決定事項を残すためコミットします
6. 実装に移る — writing-plans スキルを呼び出し、詳細な実装計画を作成します

プロセスの流れ

digraph brainstorming {
    "Explore project context" [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];
    "Invoke writing-plans skill" [shape=doublecircle];

    "Explore project context" -> "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" -> "Invoke writing-plans skill";
}

次のステップは writing-plans の呼び出しで、デザインから詳細な計画へと進みます。ほかの実装スキル（frontend-design、mcp-builder など）は、計画の作成後に使用します。この順序により、実装計画そのものが検証され、作業を効果的に導けるようになります。

プロセス

アイデアを理解する：

• まず現在のプロジェクトの状態を確認します（ファイル、ドキュメント、最近のコミット）
• アイデアを深めるため、一度に1つずつ質問します
• 可能であれば選択式の質問を優先しますが、自由回答式でも構いません
• 1つのメッセージにつき質問は1つだけにします。さらに掘り下げる必要がある場合は、複数の質問に分けます
• 目的、制約、成功基準の理解に重点を置きます

アプローチを検討する：

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

デザインを提示する：

• 何を作るのか理解できたら、デザインを提示します
• 各セクションの分量は複雑さに合わせます。単純な場合は数文、複雑な場合は200～300語程度にします
• 各セクションの後に、内容に問題がないか確認します
• アーキテクチャ、コンポーネント、データフロー、エラー処理、テストを扱います
• 不明点があれば、戻って確認できるようにします

デザインの後

ドキュメント作成：

• 承認されたデザインを docs/plans/YYYY-MM-DD-<topic>-design.md に書き込みます （docs/plans/ ディレクトリがない場合は、mkdir -p docs/plans で作成します）
• デザインドキュメントを Git にコミットします

実装：

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

主な原則

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

例

例1：新機能のリクエスト

ユーザー：「アプリにダークモードを追加しましょう」

ブレインストーミングのワークフロー：

1. 現在のテーマの実装を確認する
2. 質問する：「ダークモードは自動（システム設定に従う）、手動切り替え、それとも両方にしますか？」
3. 3つの案を提示する：CSS 変数、Tailwind の dark: クラス、テーマプロバイダー
4. 設計の各セクションを提示する：カラーパレット、コンポーネントの更新、保存方法
5. 各セクションについて承認を得る
6. docs/plans/YYYY-MM-DD-dark-mode-design.md に設計ドキュメントを書く
7. writing-plans スキルを呼び出す

期待される出力： 検証済みの設計ドキュメントと計画フェーズへの移行

例2：ユーティリティ関数

ユーザー：「電話番号を整形する関数が必要です」

ブレインストーミングのワークフロー：

1. 質問する：「どの形式に対応する必要がありますか？（米国のみ、国際形式など）」
2. 質問する：「検証も行いますか、それとも整形のみですか？」
3. 案を提示する：正規表現ベース、ライブラリ（libphonenumber）、シンプルなフォーマッター
4. 設計を提示する：関数シグネチャ、エッジケース、エラー処理
5. 承認を得る
6. 簡潔な設計ドキュメントを書く
7. writing-plans を呼び出す

期待される出力： 「シンプルな」ユーティリティであっても、まず設計を行います

例3：アーキテクチャの変更

ユーザー：「REST から GraphQL に移行すべきです」

ブレインストーミングのワークフロー：

1. 現在の API 構成とクライアントの利用状況を確認する
2. 質問する：「この変更のきっかけは何ですか？パフォーマンス、開発者体験、それとも特定の機能ですか？」
3. 質問する：「段階的な移行ですか、それとも一括での移行ですか？」
4. 3つの案を提示する：API の並行運用、REST をラップする GraphQL、全面的な書き換え
5. 設計を提示する：スキーマ設計、移行戦略、後方互換性
6. セクションを順次提示し、承認を得る
7. 包括的な設計ドキュメントを書く
8. writing-plans を呼び出す

期待される出力： 移行戦略を含む複数フェーズの設計

トラブルシューティング

問題：ユーザーが「もう作って」と繰り返し求める

症状： ユーザーがブレインストーミングを省略し、すぐにコードを書くよう求める

原因： 「シンプルな」タスクに対して、設計フェーズを余計な手間だと感じている

解決策：

1. 急いでいることを受け止める：「すぐに進めたいということは理解しています」
2. リスクを説明する：「設計をしないと、間違ったものを作ってしまう可能性があります」
3. 時間を区切った設計を提案する：「方針を確認するため、簡単な質問を2つだけさせてください」
4. それでもユーザーが譲らない場合は、最小限の設計を提示する：「これを作る予定です……」
5. 続行する前に明示的な承認を得る

問題：設計が実装計画になってしまう

症状： 設計ドキュメントにコードスニペット、ファイル構成、手順が含まれている

原因： 設計（何を、なぜ）と計画（どのように、いつ）を混同している

解決策：

1. 設計ではアーキテクチャ、コンポーネント、データフロー、トレードオフに焦点を当てる
2. 実装の詳細は writing-plans スキルに委ねる
3. 「手順1：X というファイルを作成する」と書き始めたことに気づいたら、いったん止めて計画フェーズに移る

問題：実装の途中でユーザーの考えが変わる

症状： 作業開始後に、ユーザーが異なる動作や方針を求める

原因： 設計が具体的でなかった、または前提を検証していなかった

解決策：

1. 実装を直ちに止める
2. ブレインストーミングモードに戻る
3. 新しい要件について確認の質問をする
4. 修正した設計を提示する
5. 実装を再開する前に明示的な承認を得る
6. 新たな決定を設計ドキュメントに反映する

問題：デザインの検討が延々と続く

症状： ユーザーがさらに多くの選択肢を求め続ける、またはどのデザインにも満足しない

原因： 成功の基準が不明確であるか、ユーザー自身が何を求めているのかはっきりしていません

解決策：

1. いったん立ち止まり、こう尋ねます：「理想的な結果とは、どのようなものでしょうか？」
2. 実用最小限のバージョンを提案します：「役に立つものを作るために、最小限必要なものは何でしょうか？」
3. プロトタイプの作成を提案します：「これを検討するために、簡単なプロトタイプを作ってみませんか？」
4. それでも行き詰まる場合は、時間を区切ることを提案します：「まずはオプション A で進めて、うまくいかなければ見直しましょう」

よくある落とし穴

1. 「簡単な」タスクでブレインストーミングを省略する

何が起きるか： タスクは単純（単一コンポーネント、小さなユーティリティ、設定の変更）だと判断し、コーディング中に詳細を整理すればよいと考えて、そのまま実装に進みます。

なぜ裏目に出るのか： 「簡単な」タスクでは、明白に思えるため、思い込みが最も危険です。ある動作を実装したものの、ユーザーが期待していたのは別の動作で、そのことに気づいた頃には足場となる部分がすでにできており、手直しが必要になります。

回避方法： シンプルさは、ブレインストーミングを省略する理由ではなく、短時間で済ませる理由と捉えます。「これは X を行う単一ファイルのユーティリティですよね？」といった30秒のやり取りで、30分のリファクタリングを避けられます。明白に思える点について明確に合意しておくことにも価値があります。

2. ユーザーから明確な承認を得る前にコードに着手する

何が起きるか： デザインを提示したところ、ユーザーが確認の質問をします。それを軽い関心の表れと解釈し、「フィードバックについて考えながら」コードを書き始めます。

なぜ裏目に出るのか： ユーザーはまだ検討中です。承認前に書いたコードは、書き直しが必要になることがよくあります。デザインが確定していないのに、作業を進めているという印象を与えてしまいます。

回避方法： writing-plans を呼び出す前に、「いいですね」「それで進めましょう」「リリースしましょう」といった明確な承認の言葉があるまで待ちます。確認の質問が1つでもあるなら、デザインはまだ確定していません。修正して、再度提示しましょう。

3. プランを作成せずに実装スキルを直接呼び出す

何が起きるか： デザインの承認後、writing-plans を先に呼び出す代わりに、frontend-design、mcp-builder、その他の実装スキルへ直接進みたくなります。

なぜ裏目に出るのか： 実装スキルは強力ですが、構造化されていません。スコープ、受け入れ基準、技術上の決定を定めた詳細なプランがあると、最も効果を発揮します。プランを省略すると、スキルがその内容を一から考え直すことになり、作業が非効率になったり、スコープが膨らんだりする可能性があります。

回避方法： ブレインストーミングと実装をつなぐ役割として、必ず writing-plans を呼び出します。ブレインストーミングで決めたことを具体的なプランにまとめ、実装スキルがそれに沿って進められるようにします。

4. 抽象的すぎて実装できないデザイン

何が起きるか： 考え方としては筋が通っていても、具体的な詳細が欠けたデザインを提示します。「アイテムを表示するレスポンシブなグリッドを作ります」と説明するだけで、列数、ブレークポイント、フィルタリングの仕組みを示しません。

なぜ裏目に出るのか： デザインで疑問に答えられていないため、実装を始めると質問が出てきます。実装担当者が詳細を推測し、誤って実装し、それを修正するというループに陥ります。

回避方法： デザインドキュメントを開いて質問しなくても実装担当者が作業を始められる程度に、具体的な内容にします。例、具体的な数値、エッジケース、トレードオフに関する判断を含めます。自分でも曖昧だと感じる詳細は、実装時にも曖昧なままです。