# 機能設計書 2-Plan エージェント

## 概要

本ドキュメントは、OpenCodeシステムにおけるPlan エージェントの機能設計を記述する。Plan エージェントは、読み取り専用のエージェントであり、ファイル編集を拒否し、bashコマンド実行前に許可を求める。コードベース探索や変更計画の立案に適している。

### 本機能の処理概要

Plan エージェントは、OpenCodeにおける計画立案専用のエージェントとして、コードベースの調査・分析を行い、実装前の設計や変更計画を策定する。ファイル編集操作は原則禁止され、読み取り専用の操作に限定されることで、安全にコードベースを探索できる。

**業務上の目的・背景**：大規模な変更や複雑な機能実装を行う前に、コードベースを十分に調査し、影響範囲を把握した上で計画を立てることは、開発品質の向上とリスク低減に不可欠である。Plan エージェントは、この計画立案フェーズを支援し、無計画な変更による問題を防止する。

**機能の利用シーン**：新機能の実装計画策定、リファクタリング方針の検討、バグの原因調査、アーキテクチャ変更の影響分析など、実際のコード変更前の調査・計画段階で利用される。ユーザーは「このモジュールの構造を調査して」「変更の影響範囲を教えて」などの指示を与え、エージェントがコードを読み取って分析結果を報告する。

**主要な処理内容**：
1. コードベースの読み取りと構造分析
2. ファイルパターン検索（Glob）とコード検索（Grep）
3. コードの依存関係調査
4. 変更計画の立案とドキュメント作成
5. 計画ファイル（.opencode/plans/*.md）への出力

**関連システム・外部連携**：Language Server Protocol（LSP）との連携によりコードナビゲーション（定義ジャンプ、参照検索）を活用。外部ディレクトリへのアクセスは計画保存用ディレクトリに限定。

**権限による制御**：Plan エージェントは、編集操作（edit権限）がデフォルトで拒否され、`.opencode/plans/*.md`とグローバルデータディレクトリ内の計画ファイルのみ編集可能。`question`権限と`plan_exit`権限が許可されており、質問機能とBuildモードへの復帰が可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | セッション | 主画面 | 読み取り専用エージェントによるコード探索・計画 |

## 機能種別

読み取り専用分析 / 計画立案

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | エージェント名（"plan"固定） | 文字列型 |
| description | string | No | エージェントの説明 | 任意の文字列 |
| mode | "subagent" \| "primary" \| "all" | Yes | エージェントのモード（"primary"） | enum値 |
| native | boolean | No | ネイティブエージェントかどうか（true） | boolean型 |
| hidden | boolean | No | 非表示フラグ | boolean型 |
| permission | PermissionNext.Ruleset | Yes | 権限ルールセット（edit: deny） | 有効なルールセット配列 |
| model | {modelID, providerID} | No | 使用するモデル指定 | 有効なモデル/プロバイダーID |
| options | Record<string, any> | No | 追加オプション | オブジェクト型 |

### 入力データソース

- ユーザーからのセッションメッセージ
- コードベースのファイルシステム
- LSPによるコード情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| assistantMessage | MessageV2.Assistant | エージェントの分析・計画応答 |
| planFile | string | 計画ファイル（.opencode/plans/*.md） |
| analysis | string | コード分析結果テキスト |

### 出力先

- セッションデータベース（SQLite）
- 計画ファイル（.opencode/plans/または Global.Path.data/plans/）
- UIへのリアルタイムストリーミング

## 処理フロー

### 処理シーケンス

```
1. Planモードへの遷移
   └─ plan_enter権限でBuildからPlanモードへ切り替え
2. コードベース調査
   └─ Glob、Grep、Readツールでファイル検索・読み取り
3. 構造分析
   └─ LSP機能で定義・参照関係を調査
4. 計画立案
   └─ 調査結果に基づき変更計画を策定
5. 計画ファイル出力
   └─ .opencode/plans/*.mdに計画を保存
6. Buildモードへの復帰
   └─ plan_exit権限で実装フェーズへ移行
```

### フローチャート

```mermaid
flowchart TD
    A[Buildモード] --> B{plan_enter許可?}
    B -->|Yes| C[Planモード開始]
    B -->|No| A
    C --> D[コードベース調査]
    D --> E[Glob/Grep検索]
    E --> F[ファイル読み取り]
    F --> G[LSP分析]
    G --> H[計画立案]
    H --> I{計画ファイル保存?}
    I -->|Yes| J[.opencode/plans/*.md出力]
    I -->|No| K[テキスト応答のみ]
    J --> L{plan_exit要求?}
    K --> L
    L -->|Yes| M[Buildモード復帰]
    L -->|No| D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 編集禁止 | edit権限がデフォルトでdenyに設定され、一般ファイルの編集不可 | 常時 |
| BR-02 | 計画ファイル編集許可 | .opencode/plans/*.mdとGlobal.Path.data/plans/*.mdのみ編集可能 | 計画保存時 |
| BR-03 | 外部ディレクトリ制限 | Global.Path.data/plans/*へのアクセスのみ許可 | 外部アクセス時 |
| BR-04 | 質問許可 | questionパーミッションがallowでユーザーへの質問可能 | エージェント実行中 |
| BR-05 | Buildモード復帰 | plan_exitパーミッションがallowでBuildモードへ戻ることが可能 | エージェント実行中 |

### 計算ロジック

特になし（読み取り専用のため）

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| メッセージ保存 | message | INSERT/UPDATE | 分析結果メッセージの保存 |
| パーツ保存 | message_part | INSERT/UPDATE | テキスト・ツール結果パーツの保存 |

### テーブル別操作詳細

#### message

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | role | "assistant" | 固定値 |
| INSERT | agent | "plan" | Planエージェント |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DeniedError | 許可されていないファイルの編集試行 | 編集操作を拒否しエラーメッセージ表示 |
| - | DeniedError | 許可されていない外部ディレクトリアクセス | アクセスを拒否しエラーメッセージ表示 |

### リトライ仕様

読み取り専用操作のため、エラー時のリトライは基本的にBuildエージェントと同様。

## トランザクション仕様

計画ファイルの保存は通常のファイル書き込み操作として実行。

## パフォーマンス要件

- 大規模コードベースでも効率的に検索可能（Glob/Grepの最適化）
- LSP応答のキャッシュ活用

## セキュリティ考慮事項

- 編集操作の制限によりコードベースの安全性を確保
- 計画ファイルの出力先を限定的に許可

## 備考

Plan エージェントは、BuildエージェントからのモードN切り替えにより起動され、十分な調査・計画後にBuildエージェントへ戻って実装を行う、段階的な開発ワークフローを実現する。

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

Planエージェントの権限設定を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | agent.ts | `packages/opencode/src/agent/agent.ts` | planエージェント定義（93-114行目）で権限設定を理解 |
| 1-2 | next.ts | `packages/opencode/src/permission/next.ts` | PermissionNext.fromConfig()で権限マージの仕組みを理解 |

**読解のコツ**: planエージェントはbuildエージェントとの対比で理解すると分かりやすい。edit権限がdenyになっている点が最大の違い。

#### Step 2: エントリーポイントを理解する

Planエージェントの定義と権限設定を把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | agent.ts | `packages/opencode/src/agent/agent.ts` | planエージェント定義（93-114行目） |

**主要処理フロー**:
1. **93行目**: name: "plan"でエージェント名定義
2. **94行目**: description: "Plan mode. Disallows all edit tools."
3. **96-111行目**: 権限設定（question: allow, plan_exit: allow, edit: deny）
4. **104-108行目**: 計画ファイルへの編集のみ許可（.opencode/plans/*.md）

#### Step 3: 権限評価の流れを理解する

編集操作が拒否される仕組みを把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | next.ts | `packages/opencode/src/permission/next.ts` | evaluate()関数（236-243行目）で権限評価 |

**主要処理フロー**:
- **236-243行目**: 権限とパターンのマッチングでアクションを決定
- **239-241行目**: findLast()で最後にマッチしたルールを適用

### プログラム呼び出し階層図

```
Session.chat() [index.ts]
    │
    ├─ Agent.get("plan") [agent.ts]
    │      └─ state() → Planエージェント設定取得
    │
    ├─ SessionProcessor.create() [processor.ts]
    │
    └─ processor.process() [processor.ts]
           │
           ├─ LLM.stream() [llm.ts]
           │
           └─ ツール実行時
                  └─ PermissionNext.ask()
                         │
                         ├─ evaluate("edit", pattern)
                         │      └─ "deny" → DeniedError
                         │
                         └─ evaluate("edit", ".opencode/plans/*.md")
                                └─ "allow" → 計画ファイル編集許可
```

### データフロー図

```
[入力]                    [処理]                         [出力]

ユーザー調査依頼 ───▶ Planエージェント
                              │
                              ├──▶ Glob/Grep検索 ───▶ ファイルリスト
                              │
                              ├──▶ Read ───▶ ファイル内容
                              │
                              ├──▶ LSP ───▶ コード構造情報
                              │
                              └──▶ 計画立案
                                        │
                              ┌─────────┴─────────┐
                              ▼                   ▼
                        テキスト応答         計画ファイル
                              │                   │
                              ▼                   ▼
                        セッションDB      .opencode/plans/*.md
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| agent.ts | `packages/opencode/src/agent/agent.ts` | ソース | Planエージェント定義（93-114行目） |
| next.ts | `packages/opencode/src/permission/next.ts` | ソース | 権限評価とedit: deny制御 |
| llm.ts | `packages/opencode/src/session/llm.ts` | ソース | LLMストリーミング処理 |
| processor.ts | `packages/opencode/src/session/processor.ts` | ソース | ストリームイベント処理 |
| read.ts | `packages/opencode/src/tool/read.ts` | ソース | ファイル読み取りツール |
| grep.ts | `packages/opencode/src/tool/grep.ts` | ソース | コード検索ツール |
| glob.ts | `packages/opencode/src/tool/glob.ts` | ソース | ファイルパターン検索ツール |
