# 機能設計書 4-Explore サブエージェント

## 概要

本ドキュメントは、OpenCodeシステムにおけるExplore サブエージェントの機能設計を記述する。Explore サブエージェントは、コードベース探索に特化した高速エージェントであり、ファイルパターン検索やコードキーワード検索に特化している。

### 本機能の処理概要

Explore サブエージェントは、Task ツールを通じてメインエージェントから呼び出され、コードベースの効率的な探索を行う。読み取り専用のツール（Glob、Grep、Read、Bash、WebFetch、WebSearch、CodeSearch）のみが許可され、ファイル編集やその他の変更操作は禁止されている。

**業務上の目的・背景**：大規模なコードベースにおいて、特定のファイルやコードパターンを素早く見つけ出すことは開発効率に直結する。Explore サブエージェントは、この探索作業に特化することで、メインエージェントのコンテキストを保持しながら高速な検索を実現する。

**機能の利用シーン**：ファイルパターンの検索（例："src/components/**/*.tsx"）、コードキーワードの検索（例："API endpoints"）、コードベースに関する質問への回答（例："APIエンドポイントの実装方法"）。探索の徹底度は"quick"（基本的な検索）、"medium"（中程度の探索）、"very thorough"（複数箇所の包括的分析）から指定可能。

**主要な処理内容**：
1. 探索タスクの受信と徹底度レベルの解釈
2. Globツールでファイルパターン検索
3. Grepツールでコード内キーワード検索
4. Readツールで特定ファイルの内容読み取り
5. 検索結果の整理と報告

**関連システム・外部連携**：LSPのCodeSearch機能との連携でシンボル検索も可能。Web検索（WebSearch、WebFetch）にも対応し、外部情報の取得も可能。

**権限による制御**：Explore サブエージェントは、デフォルトで全ツールがdenyに設定され、明示的に許可されたツール（grep、glob、list、bash、webfetch、websearch、codesearch、read）のみが利用可能。編集操作は完全に禁止。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | セッション | 補助画面 | Taskコンポーネントによるサブエージェントタスク表示 |

## 機能種別

読み取り専用検索 / コードベース探索

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | エージェント名（"explore"固定） | 文字列型 |
| description | string | Yes | エージェントの説明（徹底度レベル含む） | 任意の文字列 |
| mode | "subagent" \| "primary" \| "all" | Yes | エージェントのモード（"subagent"） | enum値 |
| native | boolean | No | ネイティブエージェントかどうか（true） | boolean型 |
| prompt | string | Yes | カスタムシステムプロンプト（PROMPT_EXPLORE） | 任意の文字列 |
| permission | PermissionNext.Ruleset | Yes | 権限ルールセット（読み取りツールのみ許可） | 有効なルールセット配列 |
| options | Record<string, any> | No | 追加オプション | オブジェクト型 |

### 入力データソース

- Task ツールからの検索タスク指示
- 徹底度レベル（quick/medium/very thorough）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| output | string | 検索結果のテキスト（絶対パス形式） |
| files | string[] | 発見したファイルパスのリスト |
| metadata | object | 検索メタデータ |

### 出力先

- 親セッションへの結果返却
- 子セッションデータベース

## 処理フロー

### 処理シーケンス

```
1. Task ツールからの呼び出し
   └─ 検索タスクと徹底度レベルの受信
2. 検索戦略の決定
   └─ 徹底度に応じたツール選択
3. ファイルパターン検索
   └─ Globツールでファイル一覧を取得
4. コード内検索
   └─ Grepツールでキーワード検索
5. ファイル読み取り
   └─ Readツールで詳細内容を確認
6. 結果整理
   └─ 絶対パス形式で結果をまとめる
```

### フローチャート

```mermaid
flowchart TD
    A[Task ツール呼び出し] --> B[Exploreサブエージェント選択]
    B --> C[徹底度レベル解釈]
    C --> D{検索タイプ}
    D -->|ファイルパターン| E[Glob検索]
    D -->|コードキーワード| F[Grep検索]
    D -->|両方| G[Glob + Grep]
    E --> H[結果収集]
    F --> H
    G --> H
    H --> I{詳細読み取り必要?}
    I -->|Yes| J[Read実行]
    I -->|No| K[結果整理]
    J --> K
    K --> L[絶対パス形式で返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 読み取り専用 | 編集・書き込み操作は全て禁止 | 常時 |
| BR-02 | 許可ツール限定 | grep、glob、list、bash、webfetch、websearch、codesearch、readのみ許可 | 常時 |
| BR-03 | 絶対パス返却 | 検索結果のファイルパスは絶対パス形式で返却 | 結果返却時 |
| BR-04 | 徹底度対応 | quick/medium/very thorough の3段階で検索範囲を調整 | 検索実行時 |
| BR-05 | 状態変更禁止 | ファイル作成やbashコマンドによるシステム状態変更禁止 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 子セッション作成 | session | INSERT | 子セッションレコードの作成 |
| 検索結果保存 | message | INSERT/UPDATE | 検索結果メッセージの保存 |

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

読み取り専用のため、データベースへの書き込みは子セッション管理のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DeniedError | 許可されていないツール呼び出し | 操作を拒否しエラーメッセージ返却 |
| - | 検索タイムアウト | 大規模検索での時間超過 | 部分結果を返却 |

### リトライ仕様

読み取り操作のため、一時的なエラーはリトライ可能。

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- 高速な検索レスポンス（サブエージェント特化による最適化）
- 大規模コードベースでも効率的に動作

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

- 読み取り専用制限によりシステム保護
- 外部ディレクトリアクセスは権限チェック対象

## 備考

Explore サブエージェントは、専用のシステムプロンプト（PROMPT_EXPLORE）を持ち、検索専門家としての振る舞いが定義されている。ファイル検索にはGlob、コンテンツ検索にはGrep、ファイル読み取りにはReadを使い分ける。

---

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

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

### 推奨読解順序

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

Exploreサブエージェントの設定と専用プロンプトを理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | agent.ts | `packages/opencode/src/agent/agent.ts` | exploreエージェント定義（130-156行目） |
| 1-2 | explore.txt | `packages/opencode/src/agent/prompt/explore.txt` | 専用システムプロンプトの内容 |

**読解のコツ**: 権限設定で*: denyの後に個別ツールをallowで上書きしている点に注目。これにより読み取りツールのみが有効化される。

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

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

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

**主要処理フロー**:
1. **130-131行目**: name: "explore"でエージェント名定義
2. **132-148行目**: 権限設定（*: deny → 個別ツールをallow）
3. **149-151行目**: description（徹底度レベルの説明を含む）
4. **152行目**: prompt: PROMPT_EXPLORE（専用システムプロンプト）

#### Step 3: システムプロンプトを理解する

Explore専用の振る舞い定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | explore.txt | `packages/opencode/src/agent/prompt/explore.txt` | ファイル検索スペシャリストとしての振る舞い定義 |

**主要処理フロー**:
- **1-2行目**: "You are a file search specialist"という役割定義
- **4-6行目**: Glob、Grep、Readの使い分けガイドライン
- **8-15行目**: 検索アプローチの調整、絶対パス返却、状態変更禁止のルール

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

```
Task ツール呼び出し [task.ts]
    │
    ├─ Agent.get("explore") [agent.ts]
    │      └─ Exploreサブエージェント設定取得
    │
    ├─ Session.create() [session/index.ts]
    │      └─ 子セッション作成
    │
    └─ Session.chat() [session/index.ts]
           │
           ├─ LLM.stream() [llm.ts]
           │      └─ PROMPT_EXPLORE適用
           │
           └─ processor.process() [processor.ts]
                  │
                  ├─ Glob実行 [glob.ts]
                  │
                  ├─ Grep実行 [grep.ts]
                  │
                  ├─ Read実行 [read.ts]
                  │
                  └─ 結果返却
```

### データフロー図

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

検索タスク ───▶ Exploreサブエージェント
    │                     │
    ├─ 徹底度レベル       ├──▶ Glob検索 ───▶ ファイルリスト
    │                     │
    └─ 検索パターン       ├──▶ Grep検索 ───▶ マッチ箇所
                          │
                          ├──▶ Read ───▶ ファイル内容
                          │
                          └──▶ 結果整理
                                    │
                                    └──▶ 絶対パス形式で返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| agent.ts | `packages/opencode/src/agent/agent.ts` | ソース | Exploreサブエージェント定義（130-156行目） |
| explore.txt | `packages/opencode/src/agent/prompt/explore.txt` | テンプレート | 専用システムプロンプト |
| task.ts | `packages/opencode/src/tool/task.ts` | ソース | Task ツール（サブエージェント呼び出し） |
| glob.ts | `packages/opencode/src/tool/glob.ts` | ソース | ファイルパターン検索ツール |
| grep.ts | `packages/opencode/src/tool/grep.ts` | ソース | コード検索ツール |
| read.ts | `packages/opencode/src/tool/read.ts` | ソース | ファイル読み取りツール |
| codesearch.ts | `packages/opencode/src/tool/codesearch.ts` | ソース | LSPシンボル検索ツール |
| websearch.ts | `packages/opencode/src/tool/websearch.ts` | ソース | Web検索ツール |
| webfetch.ts | `packages/opencode/src/tool/webfetch.ts` | ソース | URL取得ツール |
