brainstorming

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

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

まず、依頼にどの程度のプロセスが必要かを分類し、その後、状況を把握し、アイデアを練り上げ、デザインを提示して、人間のパートナーの承認を得るという手順で進めます。

人間のパートナーに意図を伝え、その承認を得るまでは、実装スキルを呼び出したり、コードを書いたり、プロジェクトのひな形を作成したり、実装に関する操作を行ったりしてはいけません。これは、以下のすべての手順における、すべてのタスクに適用されます。手順の規模はタスクに応じて変わりますが、承認という関門は変わりません。

このスキルの実行中に EnterPlanMode や ExitPlanMode を呼び出してはいけません。 このスキルは通常モードで動作します。プランモードでは Write/Edit ツールが制限され、正常に終了できません。構造化された計画には、代わりに writing-plans スキルを使用してください。

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

3 つの進め方

最初の質問をする前に、依頼を分類し、その分類を声に出して伝えてください。「これは範囲が限定されているようなので、仕様書を書くのではなく、ここで簡単なデザインを提示します」のように伝え、人間のパートナーが異議を唱えられるようにします。

• スパイク — 実現可能性に関する質問（「〜できますか」「〜は可能ですか」「ざっくりで構いません」など）で、成果物がコードではなく回答であるもの。質問と、試す内容を 2〜3 文で提示し、了承を得てから、正確さを保てる範囲で最も低コストな方法で調べます。デザイン文書も仕様ファイルも作成しません。調査結果は推奨事項として報告し、作成したものがあれば使い捨てであることを明記します。
• 範囲限定 — このリポジトリにすでに存在するコードに対する、適用範囲が明確な変更です。新しいフラグ、小さなエンドポイント、1 ファイルの修正などが該当します。どのようなアプリかを把握しているだけでは、範囲限定とは言えません。変更対象のフローをすでに読めることが条件です。変更対象となる既存のフローがない場合、そのタスクは範囲限定ではありません。重要な確認事項を質問し、チャット内で簡単なデザイン（数文から短い段落数個）を提示して、そこで停止します。人間のパートナーがデザインに同意して初めて実装を開始できます。範囲限定のタスクでも、承認はアーキテクチャ上のタスクと同様に厳格な関門です。仕様ファイルも実装計画書も作成しません。
• アーキテクチャ — 新規プロジェクト、新しいサブシステム、コンポーネント間の連携方法を再構成する変更、または他のコンポーネントが依存するインターフェースを変更するもの。完全なプロセスに従います。質問、アプローチの検討、セクションに分けたデザイン、仕様書の作成を経てから、writing-plans スキルを使用します。

2 つの進め方で迷った場合は、より重い方を選んでください。段階を上げることはあっても、下げることはできません。タスクの途中で隠れた複雑さが見つかった場合は、進め方を引き上げます。作業を止めて、その旨を伝え、次の段階に進んでください。タスクの途中で段階を下げることはありません。

アンチパターン：「承認が必要なほどではない」

どの進め方でも、実装前に人間のパートナーから意図の承認を得る必要があります。ToDo リスト、単一関数のユーティリティ、設定変更など、チャット内で 2 文のデザインを提示すれば済む場合でも、必ず提示して承認を得てください。「簡単な」タスクほど、確認されていない前提が無駄な作業を招きます。簡単さに応じて変わるのは成果物の規模であり、承認の必要性ではありません。

注意すべき兆候

考え	実際
「シンプルすぎて設計は必要ない」	シンプルなら設計が短くなるだけで、設計が不要になるわけではありません。チャットで2文伝え、その後承認を得ます。
「範囲が限定されていると呼べば、仕様を省略できる」	作業を省略するためにラベルを持ち出すこと自体が疑念の表れです。より慎重な手順を選びます。
「範囲は限定され、設計も明白だから、読んでもらっている間に着手しよう」	ゲートとなるのは設計の長さではなく、承認です。提示したら、承認の返事があるまで待ちます。
「この種のアプリは理解しているから、範囲は限定されている」	範囲の限定性は、あなたの経験ではなくリポジトリを基準に判断します。新しいプロジェクトには既存のフローがないため、アーキテクチャに関わる作業です。
「スパイクがうまくいったから、コードを残そう」	スパイクの成果は答えです。コードを残すのは新たな依頼なので、分類してください。
「作業が大きくなったけれど、もうすぐ終わるから再分類は不要」	隠れていた複雑さによって、作業の途中でも手順を切り替える必要が生じます。中断して、その旨を伝えてください。
「スパイクの承認を得たから、後続の変更も承認済みだ」	タスクごとに、それぞれ分類と承認が必要です。

チェックリスト

まず分類し、手順を伝えます。その後、その手順に含まれる各項目のタスクを作成し、順番に完了してください。

スパイク：

1. プロジェクトの背景を調べる — 調査の枠組みを定めるのに十分な範囲で
2. 疑問点と調査計画を提示する — 2～3文で
3. 承認を得る — うなずきだけでも十分です
4. 調査する — 正確さを保てる範囲で、最も低コストな方法を使います
5. 調査結果を報告する — 推奨案を示し、作成したものはすべて使い捨てであると明記します

範囲が限定された作業：

1. プロジェクトの背景を調べる — ファイル、ドキュメント、最近のコミットを確認します
2. 不明点を確認する — 重要な点について、一度に1つずつ質問します
3. チャットで簡潔な設計を提示する — アプローチ、変更するファイル、テストについて説明します
4. 承認を得る — 明示的な承認があるまで中断して待ちます。設計の提示と着手を一息で行うのは、ゲートの省略にあたります
5. 実装する — 通常の開発ワークフローに従って進めます（TDDを適用）。計画ドキュメントは作成しません

アーキテクチャに関わる作業：

1. プロジェクトの背景を調べる — ファイル、ドキュメント、最近のコミットを確認します
2. 必要になった時点でビジュアルコンパニオンを提案する — 最初から提案してはいけません。質問を説明するより実際に見せたほうが明らかに分かりやすくなる最初の時点で、その都度提案します（提案は独立したメッセージで行います）。承認されると、ブラウザータブが開きます。視覚的に示す必要のある質問がなければ、提案しません。下記の「ビジュアルコンパニオン」セクションを参照してください。
3. 不明点を確認する — 目的、制約、成功基準を理解できるよう、一度に1つずつ質問します
4. 2～3通りのアプローチを提案する — トレードオフと推奨案を示します
5. 設計を提示する — 複雑さに応じたセクションに分け、各セクションの後にユーザーの承認を得ます
6. 設計ドキュメントを作成する — docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md に保存し、コミットします
7. 仕様を自己レビューする — プレースホルダー、矛盾、曖昧さ、スコープについて、簡単にその場で確認します（下記を参照）
8. ユーザーが記述済みの仕様をレビューする — 作業を進める前に、仕様ファイルを確認するようユーザーに依頼します
9. 実装へ移行する — writing-plans スキルを呼び出して実装計画を作成します

プロセスフロー

digraph brainstorming {
    "Classify: spike / bounded / architectural" [shape=diamond];
    "Present question + probe (2-3 sentences)" [shape=box];
    "Ask clarifying questions (bounded)" [shape=box];
    "Present short design in chat" [shape=box];
    "Human approves?" [shape=diamond];
    "Investigate; report recommendation" [shape=doublecircle];
    "Implement via normal workflow (no plan doc)" [shape=doublecircle];
    "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];
    "Spec self-review\n(fix inline)" [shape=box];
    "User reviews spec?" [shape=diamond];
    "Invoke writing-plans skill" [shape=doublecircle];
    "Hidden complexity? Upgrade path" [shape=box];

    "Classify: spike / bounded / architectural" -> "Present question + probe (2-3 sentences)" [label="spike"];
    "Classify: spike / bounded / architectural" -> "Ask clarifying questions (bounded)" [label="bounded"];
    "Classify: spike / bounded / architectural" -> "Explore project context" [label="architectural"];
    "Present question + probe (2-3 sentences)" -> "Human approves?";
    "Ask clarifying questions (bounded)" -> "Present short design in chat";
    "Present short design in chat" -> "Human approves?";
    "Human approves?" -> "Investigate; report recommendation" [label="spike: yes"];
    "Human approves?" -> "Implement via normal workflow (no plan doc)" [label="bounded: yes"];
    "Hidden complexity? Upgrade path" -> "Classify: spike / bounded / architectural";
    "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" -> "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、その他の実装スキルは呼び出しません。範囲が限定された作業：承認後、計画ドキュメントは作成せず、通常の開発ワークフローでそのまま実装を進めます。スパイク：終了状態は、推奨案を報告した時点です。

プロセス

以下のサブセクションは、範囲が限定された作業とアーキテクチャ設計を伴う作業を対象としています（スパイクは「調査内容を提示し、承認を得る」までで終了します）。 アプローチの検討以降のセクションは、アーキテクチャ設計を伴う作業向けの深さです。範囲が限定された作業では、背景情報といくつかの質問、そしてチャット内での簡単な設計だけでプロセス全体を網羅できます。

アイデアの理解：

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

アプローチの検討：

• トレードオフを含め、異なるアプローチを2～3案提示します
• 推奨案とその理由を示し、会話形式で選択肢を提示します
• 推奨案を最初に示し、その理由を説明します
• YAGNIを徹底し、すべてのアプローチと設計から不要な機能を取り除きます

設計の提示：

• 構築するものを理解できたと判断したら、設計を提示します
• 各セクションの長さは複雑さに合わせます。単純な内容なら数文、複雑な内容なら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 のみです。

ビジュアルコンパニオン

ブレインストーミング中にモックアップ、図、ビジュアル案を提示するための、ブラウザーを使ったコンパニオンです。モードではなく、ツールとして利用できます。コンパニオンを利用可能にしても、ブラウザーで対応するのは、ビジュアルでの提示が役立つ質問に限られます。すべての質問でブラウザーを使うわけではありません。

コンパニオンの提案（必要なタイミングで）： 最初から提案しないでください。説明するより表示するほうが本当にわかりやすい質問が出るまで待ちます。単なる UI トピック ではなく、実際のモックアップ、レイアウト、図に関する質問が対象です。そのような質問が初めて出た時点で、独立したメッセージとして提案します。

「次の部分は、実際にお見せしたほうがわかりやすいかもしれません。ブラウザーのタブで、モックアップ、図、比較を作成しながら進められます。まだ新しい機能で、トークンを多く消費する可能性があります。使ってみますか？こちらで開きます。」

この提案は必ず単独のメッセージにしてください。 提案だけを伝え、確認の質問、要約、その他の内容は含めないでください。ユーザーの返答を待ちます。承諾された場合は、--open を指定してサーバーを起動し、ブラウザーが最初の画面を自動的に開くようにします。断られた場合はテキストのみで続け、ユーザーから再度話題に出されない限り、もう提案しません。

質問ごとの判断： ユーザーがコンパニオンを承諾した後も、質問ごとにブラウザーを使うかターミナルを使うか判断します。基準は、読んでもらうより見てもらうほうが、ユーザーにとってわかりやすいかです。

• ブラウザーを使う： モックアップ、ワイヤーフレーム、レイアウトの比較、アーキテクチャ図、並べて比較するビジュアルデザインなど、内容自体がビジュアルの場合
• ターミナルを使う： 要件に関する質問、概念上の選択肢、トレードオフの一覧、A/B/C/D のテキスト案、スコープの判断など、内容がテキストの場合

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

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

---

ネイティブタスク統合

必須： 設計中に、Claude Code のネイティブタスクツールを使って、構造化されたタスクを作成します。

設計の検証中

設計の各セクションの検証が完了したら、構造化された説明を含むタスクを作成します。

TaskCreate:
  subject: "Implement [Component Name]"
  description: |
    **Goal:** [What this component produces]

    **Files:**
    - Create/Modify: [paths identified during design]

    **Acceptance Criteria:**
    - [ ] [Criterion from design validation]
    - [ ] [Criterion from design validation]

    **Verify:** [How to test this component works]

    ```json:metadata
    {"files": ["path/from/design"], "acceptanceCriteria": ["criterion 1", "criterion 2"], "modelTier": "mechanical|standard|frontier"}
    ```
  activeForm: "Implementing [Component Name]"

これらのタスクには、計画の作成時に手順と検証コマンドを追加します。形式の詳細については skills/shared/task-format-reference.md を参照してください。

依存関係の設定に備えて、すべてのタスク ID を記録します。

すべてのコンポーネントの検証後

依存関係を設定します。

TaskUpdate:
  taskId: [dependent-task-id]
  addBlockedBy: [prerequisite-task-ids]

引き継ぎ前

TaskList を実行して、依存関係を含むタスク構造全体を表示します。