spec-brainstorm

仕様のブレインストーミング

大規模な作業に向けて、焦点を絞りレビュー済みの仕様を作成する対話型デザインワークショップです。

質問は一度に1つずつ行います。複数のアプローチを検討します。デザインはセクションごとに承認を得ます。スコープを厳格に管理します。デザインが承認されるまで実装は行いません。

このスキルは、atelier-orchestrator が仕様に基づく Plan を選択した場合、または人間が明示的に仕様を求めた場合にのみ実行してください。範囲が限定された作業は、Inline Plan のために直接 spec-plan に進めてください。ここで計画モードを再分類しないでください。

成果物

docs/specs/YYYY-MM-DD-<feature>/
└── design.md  ← This skill's output

要件はインラインで記述するため、別途 requirements.json を用意する必要はありません。

出力限定の契約

このスキルで作成または更新できるのは、上記の design.md のみです。リポジトリを調査したり、会話の中でドラフトについて話し合ったりすることはできますが、ほかのファイルを変更したり、plan.json を作成したり、トラッカーのエントリーを作成したり、別のワークフロースキルを呼び出したり、実装コードを記述したりしてはいけません。人間がブレインストーミング、計画、実装を1つのリクエストで求めた場合も、この制約は適用されます。design.md を完成させて報告し、そこで終了してください。

---

教訓

これらの原則は、あらゆる仕様に常に適用されます。

仕様にはコストに見合う価値が必要です

保存する仕様は、調査、アーキテクチャ、依存関係、または調整の必要性が、永続的な成果物を作成する価値に見合う作業に使用します。複数のファイルに触れる、あるいは時間がかかるという理由だけで、範囲が限定された作業をこのワークフローに持ち込んではいけません。そのような作業には Inline Plan を使用します。

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

システムを、それぞれ明確な目的を1つ持つ単位に分割します。単位間のインターフェースを明確に定義します。各単位は、それぞれ独立して理解でき、テストできる必要があります。単位の役割を一文で説明できないなら、責務を抱えすぎています。oracle-codebase-design を適用し、深いモジュールを設計し、振る舞いが変化する箇所にシームを置き、インターフェースをテスト対象とします。

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

まず現在の構成を調査します。既存のパターンに従います。改善は対象を絞って行います。無関係なリファクタリングはしません。変更を提案する前に、なぜ現状の形になっているのかを理解します。読み込まれたスキルは関連する指針として扱い、含まれるすべてのパターンを適用する要件とはみなしません。

分割

リクエストに複数の独立したサブシステムが記述されている場合は、すぐにその点を伝えます。詳細に踏み込む前に、サブプロジェクトに分割します。大規模な各サブプロジェクトには、それぞれ独自の仕様と計画を用意します。範囲が限定されたサブプロジェクトには Inline Plan を使用できます。3つのサブシステムを扱う仕様は、誰の役にも立ちません。

移行は、認可、プロダクトの振る舞い、インフラストラクチャ、スキーマ、テストプラットフォームのプロジェクトとは分けてください。移行を、隣接するシステムを再設計する許可として扱ってはいけません。

YAGNIを徹底する

すべてのデザインから不要な機能を取り除きます。最初のユーザーストーリーで必要ない機能は、仕様に含めません。すべての機能には、構築、テスト、保守、将来の理解にコストがかかります。調査中のスコープ拡大には異議を唱えてください。

将来の利用者がいるというだけでは、共有インフラストラクチャを正当化できません。「再利用可能な基盤」はアーキテクチャ上の品質を表すことはあっても、ユーザーストーリーでも現在の要件でもありません。

---

ステップ1：状況を把握する

作業に取りかかる前に、現在の状況を把握します。

1. プロジェクトのコンテキストを読む — AGENTS.md、README、既存のアーキテクチャ文書を確認します
2. 既存の仕様を確認する — docs/specs/ を調べ、過去の作業を確認します。どのようなドメインモデルが存在しますか？どのようなパターンが確立されていますか？これまでに何が構築されていますか？
3. 最近の仕様を読む — 直近で構築されたものは何ですか？この機能は既存の作業を基盤にしていますか、それを拡張していますか、それとも新規開発ですか？

これは内部で行います。状況を説明してはいけません。コンテキストを踏まえて、注力する箇所を決めてください。

---

ステップ2：要件の確認

何を構築すべきかを理解するために質問します。コンテキスト（既存の仕様、人間から提供された詳細など）から要件がすでに明確な場合は、このステップを省略してください。

インタビュー形式

一度に質問は1つにしてください。可能であれば選択式を優先し、自由回答形式の質問ではなく、具体的な選択肢を2～4個示してください。会話の流れを保ちます。

良い例：「リアルタイム処理とバッチ処理のどちらにしますか？（a）WebSocket によるリアルタイム処理、（b）30秒ごとの定期ポーリング、（c）ユーザーのリクエストに応じたオンデマンド処理」

悪い例：「データの同期はどのように行うべきですか？」

要件の掘り下げを省略する場合

• 人間が明確で詳細な要件を提示している
• 機能の対象範囲が明確に定まっている既存の作業を拡張する
• 人間が「Xの仕様をまとめて」と依頼しており、Xが十分具体的である

分解の確認

詳細を質問する前に、対象範囲を確認します。依頼に複数の独立したサブシステム（例：「メール、SMS、プッシュ通知、管理ダッシュボードを備えた通知システムを構築する」）が含まれている場合：

1. すぐに指摘します：「これは複数の独立したプロジェクトに見えます。分解案を提案します。」
2. **分解します：**サブシステムとその依存関係を特定します。
3. 合意を得ます：「まず、どの項目の仕様をまとめますか？」

1つのドキュメントですべての仕様をまとめようとしないでください。

YAGNI の確認

要件の掘り下げ中に、対象範囲について再考を促します：

• 「これは最初のバージョンから必要ですか、それともあると便利なだけですか？」
• 「これがなくてもリリースし、必要になったら後から追加できますか？」
• 「この機能を追加すると複雑さが大幅に増します。ユースケースは実際にありますか、それとも仮定上のものですか？」

人間が必要だと主張する場合は含めます。ただし、仕様書にはトレードオフを明記してください。

要件の掘り下げに関する質問

状況に応じて調整してください。毎回すべてを尋ねる必要はありません。

1. どのような問題を解決しますか？ — 解決策の説明ではなく、具体的な問題の説明
2. 誰がその問題を抱えていますか？ — ユーザーの役割
3. 現在はどのように解決していますか？ — 現在のワークフローと課題
4. 成功とはどのような状態ですか？ — 測定可能な成果
5. 何と連携しますか？ — 既存のシステム、API
6. どのような制約がありますか？ — 技術、ビジネス、規制上の制約

事前調査ですでに回答が分かっている場合は、質問するのではなく確認してください。

人間に伝えます：「調査に基づいて、構築するものについて次のように理解しています。この内容で合っていますか？」

停止します。人間の確認を待ちます。

---

ステップ 3：調査

関連するコードベースを深く読みます。シグネチャだけでなく、実装、エッジケース、エラー処理、データフローを確認します。呼び出し元と呼び出し先をたどります。テストを読んで、想定される動作を把握します。

調査対象が数ファイルを超える場合は、分野ごとに読み取り専用のサブエージェントに委任し（atelier-orchestrator の「委任」を参照）、引用付きの調査結果をもとに調査表をまとめます。

仕様書の土台となる調査結果を収集します。ステップ 4c で承認済みの設計セクションがそろうまで、design.md を作成しないでください。

調査セクションでは、関連する懸念事項ごとに、その処理をすでに担っているコードと、その判断の根拠となる現在の要件を対応付ける必要があります。

懸念事項	既存の解決策	判断	現在の要件
ID	共有パーサーと ID 型	再利用	ルートパラメーターを解析する

判断列では reuse、modify、delete、new のみを使用してください。new の概念はすべて、現在存在する要件に対応付ける必要があります。将来または仮定上の利用者は該当しません。

人間に伝えます：「仕様書の調査セクションを作成しました。設計に進む前にレビューしていただけますか？」

停止します。人間のレビューを待ちます。

---

ステップ 4：設計

設計は3つのフェーズで進めます。アプローチを検討し、設計をセクションごとに提示してから、仕様書ファイルを作成します。

4a. アプローチを検討する

設計を決める前に、トレードオフを含めて2～3 個のアプローチを提示します。

最初のアプローチでは既存のアーキテクチャを維持し、正しい変更を最小限に抑えます。 より広範なアプローチは、現在の要件によって追加コストが妥当になる場合にのみ提示します。 アプローチの違いが主にインターフェースの形状にある場合は、 oracle-codebase-design の「2 回設計する」リファレンスを使用します。

各アプローチについて、次の点を説明します。

1. 概要 — アーキテクチャの簡潔な説明
2. 長所 — このアプローチの利点
3. 短所 — 難しい点、コストがかかる点、リスク
4. 複雑さの見積もり — 実装に必要な作業量の概算

推奨する選択肢を最初に示し、なぜそれが最適なのかを説明します。

人間にアプローチまたは設計のバッチの承認を求める前に、網羅性、一貫性、または仮定上の再利用だけを理由とするものを取り除きます。

例：

アプローチ A：JSON 列を含む単一テーブル

• スキーマがシンプルで、実装が速い
• JSON 内のクエリには制限があり、後で移行に手間がかかる
• 複雑さ：低

アプローチ B：正規化されたリレーショナルテーブル

• クエリが明確で、スキーマを簡単に発展させられる
• 結合が増え、移行ファイルやコードも増える
• 複雑さ：中

推奨： アプローチ B — ここでは実装速度よりもクエリの柔軟性が重要です。

設計を提示する前に、選択したアプローチについて明確な承認を得ます。

人間に伝える：「どのアプローチで進めましょうか？それとも、別の方向性を検討しましょうか？」

停止します。人間がアプローチを選ぶまで待ちます。

4b. 設計をセクションごとに提示する

設計を複数のバッチに分けて提示します。続行する前に、各バッチの承認を得ます。

前のステップですでに確認されたセクション（問題、スコープ、制約、コンテキスト）は、その確認内容に基づいて仕様書に記載します。再度提示してはいけません。

バッチ A：ユーザーストーリー — 設計の基準となる契約です。受け入れ基準と優先度を含む正式なストーリーを提示します。却下された場合は修正します。却下によってスコープの誤解が明らかになった場合は、ディスカバリー（ステップ 2）に戻ります。

バッチ B：アーキテクチャ — コンポーネント設計、ドメインモデリング、レイヤーの境界です。oracle-codebase-design と、スタックに関連する導入済みの言語固有のアーキテクチャまたは API 設計スキルを使用します。そのうえで、コンポーネント構成、ドメインモデル、ビジネスロジックの配置場所、IO の配置場所、信頼できない入力を解析する場所（外部との境界）、各モジュールのテストで使用する境界を提示します。却下された場合は修正します。却下によって選択したアプローチの妥当性が損なわれる場合は、アプローチの検討（4a）に戻ることを提案します。根本的な不足が明らかになった場合は、リサーチ（ステップ 3）に戻ります。詳細を検討した結果、作業が見積もりより大幅に複雑だと判明した場合は、その旨を伝え、アプローチを再検討することを提案します。

バッチ C：API 設計 + データモデル — 承認済みのアーキテクチャから導かれる契約です。該当しないセクションは省略して構いませんが、その旨を明示します（「API の変更はありません — トレードオフに進みます」）。黙って省略してはいけません。却下された場合は修正します。却下がアーキテクチャに関わる場合は、バッチ B に戻ります。

バッチ D：トレードオフ + 未解決の質問 — 検討した代替案、このアプローチを選ぶ理由、既知の制限、未解決の事項を提示します。通常はその場で修正できます。

各バッチの最後に、次のように尋ねます。

人間に伝える：「この内容でよさそうですか？」

停止します。続行する前に承認を待ちます。

同じバッチを 2 回繰り返した場合は、停止して次のように尋ねます。

「[batch] を 2 回繰り返しました。アプローチを再検討しますか？」

用語の徹底： バッチの作成中は、用語を CONTEXT.md と照合して検討し、確定した用語を design.md に記録します。このスキルから CONTEXT.md を更新してはいけません。ドメインの混乱が深刻な場合は、続行する前にoracle-grill-meで一時停止することを提案します。

4c. 仕様書を作成する

すべてのバッチが承認されたら、仕様書全体を作成します。

仕様書に含める内容

# Feature Name

## Problem
- What problem are we solving
- Who has this problem
- How they solve it today

## Scope
- **In scope:** [specific capabilities]
- **Out of scope:** [explicitly deferred]

## User Stories
- US-1: As a [role], I want [action], so that [benefit]
  - Given X, when Y, then Z
- Priority: must/should/could

## Constraints
- [Technical or business constraints]

## Context
- What exists today, how it works end-to-end
- Existing patterns and conventions
- Dependencies and integration points
- Gotchas, assumptions, technical debt

## Architecture
- Component structure (functional core / effectful edge)
- Domain model: entities, value objects, aggregates
- Where business logic lives, where IO lives

## API Design
- Endpoints, request/response contracts
- Error handling approach
- Event contracts (published/consumed)

## Data Model
- Schema design, access patterns
- Migrations needed

## Trade-offs
- Alternatives considered
- Why this approach wins
- Known limitations

## Open Questions
- Anything unresolved needing human input

複雑さに合わせて各セクションの詳しさを調整します。単純な内容なら数文、複雑な内容なら詳細に記述します。

リファレンス実装

人間がリファレンスコード（オープンソースのものや、コードベース内の別の場所にあるもの）を提示した場合は、具体的な指針として使用してください。リファレンスに基づいて作業すると、設計の質が大幅に向上します。

セルフレビュー

ファイルを書き終えたら、新鮮な視点で確認してください。

1. プレースホルダーの確認 — TBD、TODO、FIXME、または未完成のセクションはありませんか？各セクションには実際の内容を記述するか、削除してください。
2. 内部整合性 — セクション同士が矛盾していませんか？たとえば、アーキテクチャのセクションに「ステートレス」とあるのに、データモデルにセッション状態が含まれている場合は、矛盾を解消してください。
3. スコープの確認 — 単一の実装計画として、十分に焦点が絞られていますか？仕様が複数の独立したサブシステムを対象としている場合は、ステップ 2 で分割しておくべきでした。それでも範囲が広すぎる場合は、ここで指摘してください。
4. 曖昧さの確認 — 要件に複数の解釈ができる部分はありませんか？ある場合は、解釈を 1 つ選んで明記し、人間が修正できるようにしてください。
5. 必要性の確認 — 完全性、一貫性、または仮定上の再利用だけを理由に正当化されている概念は削除してください。残す新しい概念がすべて、現在の要件に対応していることを確認してください。

内容に関するルール： 修正によって承認済みセクションの内容が変わる場合は、そのセクションを再提示して承認を得てください。文言や整合性の修正はそのまま反映し、引き継ぎ時に伝えてください。

---

ステップ 5：引き継ぎ

人間に次のように伝えてください。

「ブレインストーミングが完了しました。設計書を docs/specs/<path>/design.md に作成しました。このドキュメントの承認後、別途 spec-plan を実行すると plan.json を作成できます。」

人間から会話中またはファイルへの注釈で変更を求められた場合は、すべての指摘に対応し、仕様を更新してセルフレビューを再実行してください。変更によって承認済みセクションの内容が変わる場合は、続行する前にそのセクションを再提示して承認を得てください。スコープ、アーキテクチャ、契約、データ、セキュリティ、またはタスクの順序に関わる質問は、引き継ぎ前に解決してください。

完成した design.md を報告したら終了してください。spec-plan を実行したり、自動的に続行すると申し出たり、plan.json を作成したり、コードを書いたりしないでください。人間が別途リクエストして、次のフェーズを開始する必要があります。

計画中に設計上の欠陥が見つかった場合は、調査に戻ってください。反復のパターンについては、atelier-orchestrator を参照してください。