spark

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

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

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

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

反アンチパターン：「これはデザインを考えるほど複雑ではない」

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

チェックリスト

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

1. プロジェクトの状況を調べる — ファイル、ドキュメント、最近のコミットを確認します
2. ビジュアルコンパニオンを提案する（トピックに視覚的な質問が含まれる場合）— これは確認質問と組み合わせず、独立したメッセージとして送ります。下記の「ビジュアルコンパニオン」セクションを参照してください。
3. 確認質問をする — 目的、制約、成功基準を理解するため、一度に1つずつ質問します
4. 2～3種類のアプローチを提案する — トレードオフと推奨案を示します
5. デザインを提示する — 複雑さに応じたセクションに分け、各セクションの後にユーザーの承認を得ます
6. デザインドキュメントを作成する — docs/spark/YYYY-MM-DD-<topic>-design.md に保存してコミットします
7. 仕様を自己レビューする — プレースホルダー、矛盾、曖昧さ、スコープについて、簡単にインラインで確認します（下記を参照）
8. ユーザーに作成した仕様をレビューしてもらう — 続行する前に、仕様ファイルのレビューを依頼します
9. 仕様をユーザーに渡して停止する — 仕様ファイルのパスを伝え、ほかの作業や実装は始めません

プロセスの流れ

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];
    "Deliver spec path to user and STOP" [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?" -> "Deliver spec path to user and STOP" [label="approved"];
}

最終段階は、仕様をユーザーに渡すことです。ここで停止してください。 ほかのスキルを呼び出したり、実装の計画を始めたり、コードを書いたりしてはいけません。仕様ファイルのパスを伝えて応答を終了してください。仕様をどうするかは、ユーザーが決めます。

プロセス

アイデアを理解する：

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

アプローチを検討する：

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

設計を提示する：

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

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

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

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

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

デザインの完了後

ドキュメント：

• 検証済みのデザイン（仕様書）を docs/spark/YYYY-MM-DD-<topic>-design.md に記述します
  • （仕様書の保存場所に関するユーザーの希望がある場合は、既定の場所より優先します）
• デザインドキュメントを git にコミットします

仕様書のセルフレビュー： 仕様書を作成したら、少し時間をおいて新鮮な目で読み返します。

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

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

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

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

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

完了 — ここで停止します：

• 仕様書のファイルパスをユーザーに伝え、応答を終了します。
• 他のスキルを呼び出してはいけません。
• 実装計画の作成を始めたり、コードを書いたりしてはいけません。
• 仕様書をどうするかは、ユーザーが決めます。

重要な原則

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

ビジュアルコンパニオン

ブレインストーミング中にモックアップ、図、ビジュアルの選択肢を表示するための、ブラウザー上で動作するコンパニオンです。モードではなく、ツールとして利用できます。コンパニオンを利用することに同意しても、ビジュアルな提示が有効な質問で使えるようになるだけであり、すべての質問をブラウザーで行うという意味ではありません。

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

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

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

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

• ブラウザーを使う： モックアップ、ワイヤーフレーム、レイアウトの比較、アーキテクチャ図、デザインの並列比較など、ビジュアルであることが本質の内容
• ターミナルを使う： 要件に関する質問、概念上の選択肢、トレードオフの一覧、A/B/C/D のテキスト形式の選択肢、スコープの決定など、テキストによる内容

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

コンパニオンの利用に同意した場合は、続行する前に詳細ガイドを読んでください。 skills/brainstorming/visual-companion.md