概要
brainstorming スキルでできること
brainstorming スキルは、明確なルールを徹底します: 「デザインと仕様が先、実装は後」。このスキルを有効にすると、コードを書いたり、プロジェクトを scaffold したり、実装系スキルを呼び出す 前に、ユーザーの意図や要件、ハイレベルな設計をきちんと整理するよう促されます。
このスキルは、対話に基づく協働プロセスとして設計されています。まず大まかなアイデアからスタートし、絞り込まれた質問を通じてコンテキストや制約を明確にしていき、最後にユーザーがレビュー・承認できる具体的なデザインと仕様に収束させます。その「承認」という厳格なゲートを通過して初めて、実装やリファクタリングの作業に進むことが適切になります。
brainstorming の対象ユーザー
次のような場合に brainstorming スキルの利用がおすすめです:
- Claude や類似エージェントと一緒に、プロダクト機能・コンポーネント・UI フロー・アーキテクチャ変更などの検討を行う
- 「これくらいなら設計はいらないだろう」というアンチパターンを避けたい
- コード変更の前に、再現性があり監査可能な設計ディスカッションを残したい
- フロントエンド、UI/UX、ワークフロー中心のシステムを頻繁に構築・調整している
個人開発者、プロダクトエンジニア、デザイナーはもちろん、「軽量でも一貫した design-first なワークフロー」を求めているチームにフィットします。
このスキルが解決する課題
brainstorming スキルは、次のような問題を防ぐために設計されています:
- 目的が曖昧なまま、いきなりコードを書き始めてしまう
- 実装の終盤になってから、隠れた前提や齟齬が露呈する
- ユーザージャーニーやビジュアル方針が不明瞭なまま UI/UX を変更してしまう
- 計画やタスク委譲に十分使えない、曖昧すぎる仕様書
設計のチェックポイントを強制することで、手戻りや実装のミスマッチ、デザイン負債の発生を減らします。
brainstorming が向いている場合 / 向いていない場合
向いているケース:
- 新機能の計画、挙動の変更、UI/UX フローの設計を行う
- アイデア出し・コンテキスト整理・デザイン承認のための構造化されたテンプレートが欲しい
- 選択肢を検討する際、モックアップや図などのビジュアルがあると考えやすい
あまり向いていないケース:
- タイポ修正、変数名の変更、挙動に影響しない定数値の更新といった純粋な機械的編集だけを行う場合
- すでに詳細で最新・承認済みの仕様があり、それをただ実行する段階にある場合（その場合は実装特化のスキルを使う方が適しています）
一見ささいに見える設定変更や 1 関数だけのユーティリティでも、短い設計パスを通すことでメリットが得られます。その場合でも、brainstorming のプロセス自体は簡潔な形で回せます。
使い方
インストールとセットアップ
1. brainstorming スキルをインストールする
skills CLI を使って、obra/superpowers リポジトリから brainstorming スキルを追加します:
npx skills add https://github.com/obra/superpowers --skill brainstorming
これにより、スキル定義に加えて関連プロンプトやオプションのヘルパースクリプトが skills/brainstorming ディレクトリ以下に取り込まれます。
2. 主要ファイルを確認する
インストール後、ワークフローや利用可能なヘルパーを理解するために、次のファイルを確認しておきましょう:
SKILL.md– brainstorming プロセスの中核的な説明。コード前提の設計ゲートと、必須ステップのチェックリストが含まれます。spec-document-reviewer-prompt.md– 仕様レビュー用サブエージェントのテンプレートプロンプト。仕様の網羅性・整合性・明瞭性をチェックします。visual-companion.md– モックアップや図表などを表示するブラウザベースの visual companion の使い方ガイド。scripts/frame-template.html– visual companion が利用する HTML フレームテンプレート。UI にフォーカスしたレイアウトを一貫して表示するために使われます。scripts/helper.js– visual companion における選択イベントの処理やライブリロードを担当するクライアントサイドヘルパー。scripts/server.cjs,scripts/start-server.sh,scripts/stop-server.sh– visual companion サーバーの起動・管理用スクリプト。
brainstorming ワークフローを使い始めるために、これらのファイルを編集する必要はありませんが、中身を把握しておくと自分の環境への統合がスムーズになります。
brainstorming の基本ワークフロー
1. プロジェクトコンテキストから始める
brainstorming セッションを始めるときは、まず現在のプロジェクトの状況を整理することから着手します。SKILL.md のチェックリストでは、次の点が重視されています:
- 関連するファイルやドキュメントを確認する
- 直近のコミットをざっと眺めてコンテキストを掴む
- どの部分のシステムが今回の対象かを特定する
Claude や他のエージェントを使う際も、いきなりコード変更を依頼するのではなく、まずプロジェクトコンテキストを探索するよう促す プロンプトにしましょう。
2. ビジュアルが関わるテーマでは visual companion を提案する
タスクに UI/UX などのビジュアル要素が含まれる場合は、別ステップとして visual companion の利用を提案します。visual-companion.md にあるルールは次の通りです:
セッション単位ではなく、質問単位で判断すること。「読むより見たほうがユーザーは理解しやすいか？」を自問する。
ブラウザベースの companion は、次のような用途に使います:
- UI モックアップやレイアウト案の提示
- アーキテクチャ図やフローダイアグラム
- デザイン方針のサイドバイサイド比較
- 余白・階層構造・ビジュアルの洗練度についての議論
一方、ターミナル（テキストのみ）で進めるべき内容は次の通りです:
- スコープ・要件・用語定義
- 抽象的なトレードオフや API / データモデリングの検討
- 回答がビジュアルではなく言葉で十分な確認質問
3. 確認質問は 1 つずつ行う
brainstorming スキルは、1 回の巨大プロンプトではなく、整理された対話を前提としています。次のように、フォーカスを絞った質問を順番にしていきます:
- "Who are the primary users of this feature?"
- "What constraints do we have on performance or deployment?"
- "Which platforms and screen sizes matter most?"
質問は 1 つずつ投げ、回答を待ってから理解を少しずつ深めていきます。
4. 具体的なデザインと仕様を作成する
十分なコンテキストが揃ったら、ユーザーが本当に「承認」できる形のデザインにまとめます。タスクのタイプに応じて、次のような内容が含まれます:
- ハイレベルな目標と成功指標
- ユーザーストーリーや代表的なフロー
- UI レイアウトの説明やビジュアル方針（必要に応じて visual companion を併用）
- データ構造・インターフェース・連携ポイント
- 実装に影響する非機能要件
これらを構造化された仕様ドキュメントとして記述し、好みの場所に保存します（たとえば、リポジトリの慣例に従うなら docs/superpowers/specs/ 配下など）。
5. 「設計のハードゲート」を必ず守る
SKILL.md で最重要ルールとされているのが、次のハードゲートです:
デザインを提示してユーザーの承認を得るまで、実装系スキルの呼び出し、コードの記述、プロジェクトの scaffold、その他いかなる実装行為も行ってはならない。
これは、作業が 簡単そうに見える 場合にも適用されます。些細な変更であれば、デザインは数行の説明で済むかもしれませんが、それでも必ず存在し、明示的に確認されていなければなりません。
仕様ドキュメントレビュー用テンプレートの使い方
1. 仕様書を下書きする
brainstorming を終えたら、プロジェクトに適したフォーマットで仕様書を下書きします。次のように、後から参照しやすいパスに保存します:
docs/superpowers/specs/my-feature-spec.md
2. 仕様レビュー用サブエージェントを起動する
仕様が検証可能な状態になったら、spec-document-reviewer-prompt.md をテンプレートとして、仕様レビュー用サブエージェントを立ち上げます。プロンプト内の [SPEC_FILE_PATH] を、実際の仕様ファイルのパスに置き換えます。
このレビュアーは次のような観点でチェックを行います:
- 欠落しているセクション、TODO、"TBD" プレースホルダーの有無
- 矛盾や要件の不整合
- 誤実装を招きかねないあいまいな要件
- 1 つの一貫した計画として実行可能なレベルまでスコープが絞れているか
出力には Approved | Issues Found のステータスと、各問題が「なぜ実装計画上重要なのか」と紐づけられた課題リストが含まれます。
3. 承認されるまで繰り返す
レビュアーが問題を指摘したら、仕様を更新して再レビューを行います。仕様が承認されれば、実装系スキルや計画ツールにとって堅牢なベースが整ったことになります。
visual brainstorming companion の使い方
1. visual companion サーバーを起動する
scripts ディレクトリから、次のコマンドで brainstorm サーバーを起動できます:
./start-server.sh --project-dir /path/to/your/project
主なオプションは次の通りです:
--project-dir <path>– セッションファイルを/tmpではなく<path>/.superpowers/brainstorm/配下に保存し、永続化します。--host <bind-host>– 特定のインターフェースにバインドします（コンテナやリモート環境では0.0.0.0など）。--url-host <display-host>– 返却される URL JSON に表示するホスト名を制御します。--foregroundまたは--background– 現在のターミナルで動かすか、バックグラウンドプロセスとして動かすかを選択します。
起動時、スクリプトはセッション URL を含む JSON を出力します。ブラウザでその URL を開くと、visual brainstorming 用フレームにアクセスできます。
2. ビジュアル案をレンダリングする
サーバーは特定ディレクトリを監視し、常に最新の HTML ファイルを配信します。典型的なパターンは次の通りです:
- Claude（またはあなたのエージェント）が、
frame-template.htmlをベースに設定されたscreen_dirに HTML ファイルを書き出す。 - 新しいファイルが作成されると、
helper.jsによってブラウザが自動でリロードされる。 - ユーザーは UI 上のオプションやカードをクリックでき、そのイベントが WebSocket 経由でエージェントに送信される。
これにより、次のような内容を簡単に提示できます:
- クリックできるカードとしての複数レイアウト案
- フローダイアグラムやステートマシン
- 色・余白・コンポーネントバリエーションのビジュアル比較
3. セッション終了後にサーバーを停止する
セッションが終わったら、次のコマンドで brainstorm サーバーを安全に停止します:
./stop-server.sh <session_dir>
/tmp 配下のセッションであれば、生成ファイルも同時にクリーンアップされます。.superpowers/ 配下などの永続ディレクトリは保持されるため、後からモックアップや図を再確認することもできます。
brainstorming を自分のワークフローに組み込む
- 標準的な pre-commit ステップとして: フィーチャーブランチをマージする前に、brainstorming と仕様承認を必須フローとして組み込む。
- 他のスキルとの連携: まず brainstorming を実行して仕様を固めたうえで、実装・リファクタリング・テスト用スキルへ引き継ぐ。
- UI/UX 作業向けに: 対話型 brainstorming と visual companion を組み合わせ、CSS やコンポーネントコードを書く前に、レイアウトやインタラクション案を検証する。
フォルダ構成やファイル名、仕様フォーマットは既存リポジトリに合わせて調整しつつ、次のコアパターンは維持します: コンテキスト → 質問 → デザイン/仕様 → レビュー → 実装。
FAQ
brainstorming スキルは大規模・複雑なプロジェクト専用ですか？
いいえ。brainstorming スキルは、「この程度なら設計はいらない」というアンチパターンを避けるためにこそ設計されています。小さな設定変更や単発ユーティリティでも、思い込みや前提が隠れていることがあります。ごく小さなタスクであれば、設計は短く簡潔な説明で十分ですが、それでも実装前に明文化し、確認するべきです。
すでに仕様書がある場合は brainstorming を省略しても良いですか？
すでに詳細で最新、かつ承認済みの仕様がある場合は、フルな brainstorming セッションは不要かもしれません。ただし、実装前に spec-document-reviewer-prompt.md の仕様レビュー用テンプレートでその仕様を検証することはおすすめです。レビューでギャップや曖昧さが見つかった場合は、それを解消するために短めの brainstorming を追加で実施すると良いでしょう。
brainstorming は実装系スキルとどう連携しますか？
brainstorming スキルは、あらゆる実装系スキルの前段 として使うことを想定しています。このスキルが出力するのは:
- ユーザー承認済みの明確なデザイン
- レビューと改訂が可能な仕様ドキュメント
この承認ゲートを通過して初めて、コーディングやリファクタリング系スキルを呼び出すべきです。この分離により、設計意図が明示され、実装フェーズでの往復や食い違いを減らせます。
visual companion を使わなくても brainstorming の恩恵は得られますか？
はい。visual companion はオプションです。
- 作業内容が主にバックエンドロジック・API・インフラであれば、テキストベースのワークフローだけで brainstorming を十分活用できます。
- UI/UX、プロダクトデザイン、フロントエンド開発を行う場合は、
visual-companion.mdとscripts/ディレクトリに含まれる visual companion を併用することで、案の比較やフィードバック収集が格段にやりやすくなります。
ビジュアルが本当に議論を明確にするかどうかを基準に、利用有無を選んでください。
ハードゲートを無視して、先にコードを書き始めたらどうなりますか？
設計のハードゲートを無視すると、brainstorming スキルの主な利点である「早期の認識合わせ」が失われます。その結果、次のようなリスクが高まります:
- ユーザーの期待と噛み合わない機能が出来上がる
- フィードバック後に作り直しが必要な UI 実装になる
- 仕様がコードに追いつかず、ドキュメント負債が蓄積する
このゲートはプロセス上のルールとして扱い、「設計が書かれ、レビューされ、明示的に承認されるまでコードを書かない／書くよう依頼しない」ことを徹底してください。
仕様レビューの観点はカスタマイズできますか？
はい。spec-document-reviewer-prompt.md には、completeness・consistency・clarity・scope・YAGNI といった観点が定義されています。このテンプレートをベースに、自分たちのドメインに合わせて（たとえば security・performance・compliance チェックを追加するなど）拡張しても構いません。同じレビューの流れを維持しつつ、評価項目を増やすことができます。
brainstorming は特定のフレームワークや技術スタックに依存していますか？
いいえ。brainstorming スキルはスタック非依存です。フレームワーク固有のコードではなく、コンテキスト収集・要件整理・設計の言語化・ビジュアル検討に焦点を当てています。フロントエンドアプリ、バックエンドサービス、外部サービス連携、ハイブリッドなシステムなど、どのような構成でも利用できます。
brainstorming スキルのアンインストールや無効化はどう行いますか？
このスキルは obra/superpowers スキルセットの一部に過ぎません。利用をやめたい場合は、次のような対応で十分です:
- エージェントや skills loader 内の設定から、本スキルの定義を削除またはコメントアウトする
- ワークフローやパイプライン内で、本スキルを呼び出さないようにする
brainstorming スキル自体がシステム全体に変更を加えることはないため、削除は設定と運用を見直すだけで完了します。