brainstorm

ブレインストーミング - 要件の洗い出し（AI コーディング強化版）

実装前に、AI と共同で要件を洗い出すためのガイドです。AI コーディングのワークフローに最適化されています。

• タスク優先（アイデアをすぐに記録）
• 質問より先に行動（価値の低い質問を減らす）
• 技術的な選択では調査を優先（ユーザーに選択肢を考えさせない）
• 発散 → 収束（考えを広げてから、MVP を確定）

---

使用するタイミング

ユーザーが開発タスクを説明したとき、$start から開始します。特に次の場合に使用してください。

• 要件が不明確、または変化している
• 有効な実装方法が複数ある
• トレードオフが重要（UX、信頼性、保守性、コスト、パフォーマンス）
• ユーザーが最適な選択肢をすぐには把握できない可能性がある

---

基本原則（必須）

1. タスク優先（早めに記録） ユーザーのアイデアをすぐに記録できるよう、最初に必ずタスクが存在する状態にします。

2. 質問より先に行動 リポジトリのコード、ドキュメント、設定、規約、簡単な調査から答えを導き出せる場合は、まずそれを行います。

3. メッセージごとに質問は1つ 質問を列挙してユーザーに負担をかけないでください。1つ質問し、PRD を更新してから、次の質問をします。

4. 具体的な選択肢を優先 好みや意思決定について尋ねる場合は、トレードオフを添えて、実現可能で具体的な方法を2～3個提示します。

5. 技術的な選択では調査を優先 意思決定が業界の慣習、類似ツール、確立されたパターンに左右される場合は、まず調査してから選択肢を提示します。

6. 発散 → 収束 初期の理解を得た後、将来の拡張、関連するシナリオ、障害やエッジケースを積極的に検討し、その後、対象外の範囲を明示して MVP に収束させます。

7. メタ質問をしない 「検索しますか？」や「続けるためにコードを貼ってもらえますか？」とは尋ねないでください。 情報が必要な場合は、検索・確認します。作業が進められない場合は、進行を妨げている最小限の質問をします。

---

ステップ 0：タスクが存在することを確認（必ず実施）

質疑応答の前に、タスクが存在することを確認します。タスクがなければ、すぐに作成します。

• ユーザーのメッセージから仮の作業タイトルを付けます。
• タイトルが完璧でなくても問題ありません。後で PRD で調整します。

TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)

わかっていることを使って、prd.md をすぐに作成・初期化します。

# brainstorm: <short goal>

## Goal

<one paragraph: what + why>

## What I already know

* <facts from user message>
* <facts discovered from repo/docs>

## Assumptions (temporary)

* <assumptions to validate>

## Open Questions

* <ONLY Blocking / Preference questions; keep list short>

## Requirements (evolving)

* <start with what is known>

## Acceptance Criteria (evolving)

* [ ] <testable criterion>

## Definition of Done (team quality bar)

* Tests added/updated (unit/integration where appropriate)
* Lint / typecheck / CI green
* Docs/notes updated if behavior changes
* Rollout/rollback considered if risky

## Out of Scope (explicit)

* <what we will not do in this task>

## Technical Notes

* <files inspected, constraints, links, references>
* <research notes summary if applicable>

---

ステップ 1：コンテキストの自動収集（質問する前に必ず実施）

「コードはどのようになっていますか？」のような質問をする前に、自分でコンテキストを収集します。

リポジトリの確認項目

• 影響を受ける可能性が高いモジュールやファイルを特定する
• 既存のパターン（類似機能、規約、エラー処理のスタイル）を確認する
• 設定、スクリプト、既存のコマンド定義を確認する
• 制約（ランタイム、依存関係の方針、ビルドツール）を把握する

ドキュメントの確認項目

• 既存の PRD／仕様書／テンプレートを探す
• コマンドの使用例、README、ADR があれば確認する

調査結果を PRD に記録します。

• What I already know に追加する
• 制約やリンクを Technical Notes に追加する

---

ステップ 2：複雑さを分類（タスク作成の妨げにはならないが、有用）

複雑さ	基準	対応
簡単	1行の修正、誤字、明白な変更	ブレインストーミングを省略し、直接実装する
シンプル	目標が明確で、対象ファイルが1～2個、範囲が明確	確認の質問を1つしてから実装する
中程度	複数のファイルに関わり、ある程度の曖昧さがある	簡易的なブレインストーミング（価値の高い質問を2～3個）
複雑	目標が曖昧、アーキテクチャ上の選択が必要、方法が複数ある	十分なブレインストーミングを行う

注：ステップ 0 の時点でタスクは作成済みです。分類によって変わるのはブレインストーミングの深さだけです。

---

ステップ 3：質問の判断基準（価値の高い質問のみ行う）

質問をする前に、必ず以下の判断基準を確認します。

Gate A — ユーザーに尋ねずに導き出せますか？

次の方法で答えが得られる場合：

• リポジトリの調査（コード／設定）
• ドキュメント／仕様／慣例
• 簡単な市場／OSS 調査

→ 質問しないでください。 情報を取得して要約し、PRD を更新します。

Gate B — これはメタな質問、または怠慢な質問ですか？

例：

• 「検索したほうがいいですか？」
• 「作業を進められるよう、コードを貼ってもらえますか？」
• 「コードはどのような見た目ですか？」（リポジトリを参照できる場合）

→ 質問しないでください。 自分で行動してください。

Gate C — 質問の種類は何ですか？

• 作業を妨げる質問：ユーザーの入力なしでは先に進められない
• 好みに関する質問：複数の妥当な選択肢があり、プロダクト／UX／リスクに関する好みによって異なる
• 調査で導き出せる質問：調査や確認によって答えられる

→ 作業を妨げる質問または好みに関する質問だけを尋ねてください。

---

ステップ 4：調査優先モード（技術的な選択では必須）

発動条件（いずれかに該当すれば調査優先）

• タスクに、アプローチ、ライブラリ、プロトコル、フレームワーク、テンプレートシステム、プラグイン機構、または CLI の UX 慣例の選定が含まれる
• ユーザーが「ベストプラクティス」「他の人がどうしているか」「推奨案」を尋ねている
• ユーザーが現実的に選択肢を列挙できない

調査手順

1. 比較対象となるツール／パターンを 2～4 個特定する
2. 共通する慣例と、その理由を要約する
3. 慣例をリポジトリの制約に照らし合わせる
4. プロジェクトで実現可能な2～3 個のアプローチを提示する

調査結果の出力形式（PRD）

PRD にセクションを追加します（Technical Notes 内、または独立したセクションとして）。

## Research Notes

### What similar tools do

* ...
* ...

### Constraints from our repo/project

* ...

### Feasible approaches here

**Approach A: <name>** (Recommended)

* How it works:
* Pros:
* Cons:

**Approach B: <name>**

* How it works:
* Pros:
* Cons:

**Approach C: <name>** (optional)

* ...

その後、好みに関する質問を1 つ尋ねます。

• 「どのアプローチを希望しますか：A／B／C（またはその他）？」

---

ステップ 5：範囲拡張の検討（DIVERGE）— 初期理解の後に必須

目標を要約できる段階になったら、収束に入る前に、積極的に視野を広げて検討します。

拡張カテゴリ（各 1～2 項目にとどめる）

1. 将来的な進化

   • この機能は 1～3 か月後にどう発展する可能性がありますか？
   • 今のうちに維持しておく価値のある拡張ポイントは何ですか？

2. 関連するシナリオ

   • 隣接するコマンド／フローとの一貫性を保つべき点は何ですか？
   • 同等性への期待（作成と更新、インポートとエクスポートなど）はありますか？

3. 障害とエッジケース

   • 競合、オフライン／ネットワーク障害、再試行、冪等性、互換性、ロールバック
   • 入力検証、セキュリティ境界、権限チェック

ユーザーへの拡張メッセージのテンプレート

I understand you want to implement: <current goal>.

Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):

1. Future evolution: <1–2 bullets>
2. Related scenarios: <1–2 bullets>
3. Failure/edge cases: <1–2 bullets>

For this MVP, which would you like to include (or none)?

1. Current requirement only (minimal viable)
2. Add <X> (reserve for future extension)
3. Add <Y> (improve robustness/consistency)
4. Other: describe your preference

その後、PRD を更新します。

• MVP に含めるもの → Requirements
• 対象外とするもの → Out of Scope

---

ステップ 6：Q&A ループ（CONVERGE）

ルール

• 1 回のメッセージにつき質問は 1 つ

• 可能であれば選択式にする

• ユーザーの回答ごとに：

  • すぐに PRD を更新する
  • 回答済みの項目を Open Questions から Requirements に移す
  • テスト可能なチェックボックスを使って Acceptance Criteria を更新する
  • Out of Scope を明確にする

質問の優先順位（推奨）

1. MVP の範囲（含めるもの／除外するもの）
2. 好みに関する選択（具体的な選択肢を提示した後）
3. 障害時／エッジケースの動作（MVP に不可欠な経路に限る）
4. 成功指標と受け入れ基準（動作の証明方法）

推奨する質問形式（選択式）

For <topic>, which approach do you prefer?

1. **Option A** — <what it means + trade-off>
2. **Option B** — <what it means + trade-off>
3. **Option C** — <what it means + trade-off>
4. **Other** — describe your preference

---

ステップ 7：アプローチの提案と決定の記録（複雑なタスク）

要件が十分に明確になったら、（調査優先の過程でまだ行っていない場合は）2～3 個のアプローチを提案します。

Based on current information, here are 2–3 feasible approaches:

**Approach A: <name>** (Recommended)

* How:
* Pros:
* Cons:

**Approach B: <name>**

* How:
* Pros:
* Cons:

Which direction do you prefer?

結果を ADR-lite セクションとして PRD に記録します。

## Decision (ADR-lite)

**Context**: Why this decision was needed
**Decision**: Which approach was chosen
**Consequences**: Trade-offs, risks, potential future improvements

---

ステップ 8：最終確認と実装計画

未解決の質問がなくなったら、構成化した要約で要件全体を確認します。

最終確認の形式

Here's my understanding of the complete requirements:

**Goal**: <one sentence>

**Requirements**:

* ...
* ...

**Acceptance Criteria**:

* [ ] ...
* [ ] ...

**Definition of Done**:

* ...

**Out of Scope**:

* ...

**Technical Approach**:
<brief summary + key decisions>

**Implementation Plan (small PRs)**:

* PR1: <scaffolding + tests + minimal plumbing>
* PR2: <core behavior>
* PR3: <edge cases + docs + cleanup>

Does this look correct? If yes, I'll proceed with implementation.

サブタスクへの分割（複雑なタスク）

複数の独立した作業項目を含む複雑なタスクでは、サブタスクを作成します。

# Create child tasks
CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")

# Or link existing tasks
python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"

---

PRD の最終構成

最終的に prd.md は次の構成にまとめます。

# <Task Title>

## Goal

<why + what>

## Requirements

* ...

## Acceptance Criteria

* [ ] ...

## Definition of Done

* ...

## Technical Approach

<key design + decisions>

## Decision (ADR-lite)

Context / Decision / Consequences

## Out of Scope

* ...

## Technical Notes

<constraints, references, files, research notes>

---

アンチパターン（厳禁）

• リポジトリから導き出せるコード／コンテキストをユーザーに求める
• 具体的な選択肢を提示する前に、アプローチを選ぶようユーザーに求める
• 調査するかどうかについてのメタな質問
• 初期の依頼に狭くとどまり、将来の進化やエッジケースを考慮しない
• PRD を更新しないまま、ブレインストーミングを続ける

Start Workflow との統合

ブレインストーミングの完了後（ステップ 8 の確認が承認された後）、フローは Task Workflow の フェーズ 2：実装の準備 に進みます。

Brainstorm
  Step 0: Create task directory + seed PRD
  Step 1–7: Discover requirements, research, converge
  Step 8: Final confirmation → user approves
  ↓
Task Workflow Phase 2 (Prepare for Implementation)
  Code-Spec Depth Check (if applicable)
  → Research codebase (based on confirmed PRD)
  → Configure code-spec context (jsonl files)
  → Activate task
  ↓
Task Workflow Phase 3 (Execute)
  Implement → Check → Complete

タスクディレクトリと PRD はブレインストーミングですでに作成されているため、Task Workflow のフェーズ 1 は完全にスキップされます。

---

関連コマンド

コマンド	使用するタイミング
$start	ブレインストーミングを開始するエントリーポイント
$finish-work	実装が完了した後
$update-spec	作業中に新しいパターンが見つかった場合