163 lines
5.7 KiB
Markdown
163 lines
5.7 KiB
Markdown
# Brainstorm 詳細ガイド
|
|
|
|
着手前または行き詰まり時に、複数アプローチを構造化された形で比較してから 1 つを採用する **思考の checkpoint** ツール。
|
|
|
|
LLM が「最初に思いついた方法でそのまま突き進む」「同じ tool が失敗してるのに同じ args で呼び直す」といったループに陥ることを防ぐ。
|
|
|
|
## 何を解決するか
|
|
|
|
問題のあるパターン:
|
|
|
|
```
|
|
失敗 → リトライ → 失敗 → リトライ → 失敗 → リトライ → ...
|
|
```
|
|
|
|
Brainstorm を挟むと:
|
|
|
|
```
|
|
失敗 → Brainstorm({ context: 失敗内容, approaches: [A, B, C], chosen: B }) → B を試す
|
|
```
|
|
|
|
## 必須フィールド
|
|
|
|
| フィールド | 説明 |
|
|
|---|---|
|
|
| `task` | 今解こうとしているサブ問題を **1 文** で。例: `"input/data.xlsx の中身を要約したい"` |
|
|
| `approaches` | 検討する解法の配列。**2 個以上**必要 (1 個だと比較にならない) |
|
|
| `chosen` | 採用する approach の `name`。`approaches[].name` のどれかと完全一致させる |
|
|
| `rationale` | 採用理由を 1-2 文で |
|
|
|
|
## 任意フィールド
|
|
|
|
| フィールド | 説明 |
|
|
|---|---|
|
|
| `context` | これまで試した手段・失敗内容など。行き詰まり時のリセット用途で記入する |
|
|
|
|
## approaches[] の各要素
|
|
|
|
| フィールド | 必須 | 説明 |
|
|
|---|---|---|
|
|
| `name` | ✓ | 短い名前 (例: `"ReadExcel 直接"`, `"CSV エクスポート経由"`) |
|
|
| `description` | ✓ | 1-2 文で具体的な手順 |
|
|
| `reliability` | - | `high` / `medium` / `low`。副作用無し・後戻り可能なら high |
|
|
| `speed` | - | `fast` / `medium` / `slow` |
|
|
| `prerequisites` | - | 前提条件・必要なもの |
|
|
| `risks` | - | 想定される失敗パターン |
|
|
|
|
## 使うべき場面
|
|
|
|
1. **複雑な依頼の着手前** — レポート生成・複数ファイル処理・多段階の調査など
|
|
2. **同じ tool が 2 回以上失敗した時** — エラー内容を `context` に書いて、別アプローチを 2-3 個並べる
|
|
3. **存在しないファイルを掴んだ時** — `output/foo.xlsx` が無いと分かった時点で「Glob で実在確認 / ユーザーに ASK / 別パスを試す」を比較
|
|
4. **方針が複数あって迷った時** — どっちでも動きそうな選択肢がある時に、確実性で選び直す
|
|
|
|
## 使わなくて良い場面
|
|
|
|
- 短い質問への即答
|
|
- 自明な単一 tool で済む依頼 (例: 「current time を教えて」)
|
|
- 1-2 ステップで完結する操作
|
|
|
|
## 使い方の例
|
|
|
|
### 例1: ファイル読み込みのアプローチ比較
|
|
|
|
```js
|
|
Brainstorm({
|
|
task: "input/data.xlsx の中身を要約したい",
|
|
approaches: [
|
|
{
|
|
name: "ReadExcel 直接",
|
|
description: "ReadExcel({ path: 'input/data.xlsx' }) で全シート読む",
|
|
reliability: "high",
|
|
speed: "fast",
|
|
},
|
|
{
|
|
name: "シート分割→個別 Read",
|
|
description: "SplitExcelSheets で .md に分割してから Read で 1 シートずつ",
|
|
reliability: "high",
|
|
speed: "medium",
|
|
prerequisites: "出力ディレクトリの書き込み許可",
|
|
},
|
|
{
|
|
name: "ヘッダーだけ先に確認",
|
|
description: "ReadExcel に range: 'A1:Z3' を渡して構造把握 → 範囲拡大",
|
|
reliability: "high",
|
|
speed: "fast",
|
|
risks: "範囲を間違えるとデータを取り逃がす",
|
|
},
|
|
],
|
|
chosen: "ReadExcel 直接",
|
|
rationale: "ファイルサイズが小さければ全件読みが最速で確実"
|
|
})
|
|
```
|
|
|
|
### 例2: エラー連発時のリセット
|
|
|
|
```js
|
|
Brainstorm({
|
|
task: "output/レポート.xlsx を読みたい",
|
|
context: "ReadExcel が JSZip エラー、ReadPdf も extension mismatch、Bash cat も file not found。\n直前のターンで Write が成功したという認識だが実際は失敗していた可能性",
|
|
approaches: [
|
|
{
|
|
name: "Glob で実在確認",
|
|
description: "Glob({ pattern: 'output/*' }) で実際に存在するファイル一覧を取る",
|
|
reliability: "high",
|
|
speed: "fast",
|
|
},
|
|
{
|
|
name: "Write をやり直す",
|
|
description: "前回の Write 失敗が原因なら、対象ファイルを改めて生成する",
|
|
reliability: "medium",
|
|
speed: "medium",
|
|
risks: "既存ファイルを上書きしてしまう可能性",
|
|
},
|
|
{
|
|
name: "ユーザーに ASK",
|
|
description: "complete({ status: 'needs_user_input', missing_info: 'ファイルパスを確認させて' })",
|
|
reliability: "high",
|
|
speed: "slow",
|
|
},
|
|
],
|
|
chosen: "Glob で実在確認",
|
|
rationale: "副作用なしで現状把握できる。実在しないなら次の手も決まる"
|
|
})
|
|
```
|
|
|
|
## 出力の形
|
|
|
|
Brainstorm は以下のような Markdown を返す:
|
|
|
|
```
|
|
# Brainstorm: <task>
|
|
|
|
## 背景 / これまでの試行
|
|
<context があれば>
|
|
|
|
## 検討した N 個のアプローチ
|
|
|
|
**A 案**
|
|
<description>
|
|
[確実性: high / 速度: fast]
|
|
|
|
✓ **B 案** (採用)
|
|
<description>
|
|
[確実性: medium / 速度: medium]
|
|
|
|
**C 案**
|
|
...
|
|
|
|
## 採用: B 案
|
|
理由: <rationale>
|
|
|
|
続けて、採用したアプローチで実装に進んでください。
|
|
```
|
|
|
|
このアウトプットが activity log / tool 履歴に残るので、後から「どのアプローチを比較したか」「なぜそれを選んだか」を追跡できる。
|
|
|
|
## 注意
|
|
|
|
- **Brainstorm は思考の checkpoint であって、独立した解答ではない**。Brainstorm 後は採用したアプローチで実際の tool を呼ぶ
|
|
- **2 個以上の approaches が必須**。1 個だと「比較」にならない
|
|
- `chosen` は `approaches[].name` と完全一致必要 (大小・空白も含めて)
|
|
- 短い質問・自明なタスクで Brainstorm を呼ぶ必要は無い (オーバーヘッドになる)
|