OpenCodeの設定 - サブエージェント

概要

OpenCodeのエージェント機能は、特定のタスクや作業モードに特化したAIアシスタントを定義し、用途に応じて使い分けることにより、効率的な開発ワークフローを構築する機能である。

OpenCodeのエージェントは、以下に示す2つの役割に分類される。

• プライマリエージェント

  ユーザと直接対話するエージェント

  Tabキーで切り替えることができる

• サブエージェント

  プライマリエージェントから内部的に呼び出される特化アシスタント

エージェントを活用することにより、以下に示すメリットが得られる。

• 作業の専門化

  コードレビュー、ドキュメント生成等、特定の目的に最適化されたエージェントを定義できる

• モデルの使い分け

  タスクの性質に応じて適切なモデルを割り当て、コストとパフォーマンスを最適化できる

  OpenCodeは75以上のプロバイダをサポートしており、さまざまなモデルを指定できる

• 権限の制御

  エージェントごとにツールアクセスを制限し、安全性を向上できる

• ワークフローの標準化

  プロジェクト全体で一貫したエージェント設定を共有できる

エージェントの種類

OpenCodeには、ビルトインのプライマリエージェントとユーザ定義のサブエージェントが存在する。

プライマリエージェント

プライマリエージェントは、ユーザと直接対話するエージェントである。
Tabキーを押すことで、利用可能なプライマリエージェント間を切り替えることができる。

Build エージェント

Buildエージェントは、OpenCodeのデフォルトエージェントである。

Build エージェントの特徴を以下に示す。

• 全てのツールが有効化された標準的な開発エージェント
• コードの編集、ファイルの読み書き、シェルコマンドの実行等、あらゆる操作が可能
• 日常的なコーディング作業に最適

Plan エージェント

Planエージェントは、変更を加えずに分析と計画を行うための制限されたエージェントである。

Planエージェントの特徴を以下に示す。

• ファイルの書き込みやシェルコマンドの実行を伴うツールへのアクセスが制限されている。
• コードベースの分析、設計の検討、実装計画の立案に特化
• 誤ってコードを変更するリスクなく、安全に探索・分析できる。

サブエージェント

サブエージェントは、プライマリエージェントから呼び出される特化アシスタントである。
独立したコンテキストで作業を実行し、結果をプライマリエージェントに返す。

Generalサブエージェント

Generalサブエージェントは、汎用的な目的で使用されるビルトインのサブエージェントである。

• 汎用的なタスクに対応
• プライマリエージェントがタスクを委譲する際のデフォルトの委譲先

Exploreサブエージェント

Exploreサブエージェントは、コードベースの探索と分析に特化したビルトインのサブエージェントである。

• ファイルの検索、コードの読み取りに特化
• 大規模なコードベースの調査や、既存実装の把握に適している。

ディレクトリ構造

エージェント定義ファイルは、以下に示すディレクトリに配置する。

.opencode/
├── agents/                  (プロジェクト固有のエージェント定義)
│   ├── qml-frontend.md      # QMLフロントエンド開発エージェント
│   ├── cpp-backend.md       # C++バックエンド開発エージェント
│   ├── qml-reviewer.md      # QMLコードレビューエージェント
│   └── cpp-debugger.md      # C++デバッグ専門エージェント
└── modes/                   (プロジェクト固有のモード定義)
    ├── qml-design-mode.md   QML UI設計モード
    ├── debug-mode.md        # C++デバッグモード
    └── review-mode.md       # コードレビューモード

~/.config/opencode/
├── agents/                  (グローバルエージェント定義、全プロジェクトで使用可能)
│   └── translator.md        # 翻訳エージェント
└── modes/                   (グローバルモード定義)
    └── plan-mode.md         # 計画モード

配置場所の使い分けを以下に示す。

• プロジェクト固有

  .opencode/agents/ に配置

  チーム全体で共有し、バージョン管理に含める

  
  

• グローバル

  ~/.config/opencode/agents/ に配置

  全てのプロジェクトで利用可能な共通エージェント

ディレクトリ名について、agents (複数形) を推奨する。
後方互換性のため、agent (単数形) も認識される。

エージェントの作成方法

エージェントの作成方法は3種類存在する。

opencode agent createコマンド

CLIコマンドを使用して、対話的にエージェントを作成する方法である。

opencode agent create

コマンドを実行すると、以下の手順で進む。

1. 保存場所の選択 (プロジェクト固有またはグローバル)
2. エージェントの目的を説明する入力プロンプト
3. OpenCodeが自動的にエージェント定義を生成
4. 使用するツールの選択と確認

Markdownファイルによる定義

Markdownファイルを手動で作成してエージェントを定義する方法である。
ファイル名がエージェント名となる。

ファイルは以下の2つのセクションで構成される。

• YAMLフロントマター

  エージェントのメタデータを定義

• Markdown本文

  エージェントへの指示を記述

 ---
 name: エージェント名
 description: エージェントの説明
 mode: primary / subagent / all (デフォルト: all)
 model: モデル指定 (任意)
 prompt: カスタムシステムプロンプトファイルへのパス (任意)
 ---
 
 ## エージェントへの指示
 
 このエージェントは、[目的] を担当します。
 
 ## 実行手順
 
 1. ステップ1
 2. ステップ2

opencode.jsonによる定義

プロジェクトルートまたはホームディレクトリの opencode.json にエージェントを定義する方法である。

複数のエージェントを1つのファイルで集中管理できる。

 {
    "agents": {
       "review": {
          "description": "コード審査専用エージェント",
          "mode": "subagent",
          "model": "モデル名 (任意)",
          "permissions": {
             "read": "allow",
             "write": "deny"
          }
       }
    }
 }

エージェント定義の設定オプション

エージェント定義で使用できる設定オプションを以下に示す。

エージェント定義の設定オプション

オプション	説明	必須
name	エージェントの一意な識別子 kebab-caseを推奨	任意 (ファイル名から自動設定)
description	エージェントの目的と機能の説明 プライマリエージェントがこれを読んで呼び出しを判断する。	推奨
mode	all (デフォルト) primary subagent の3種類	任意
model	タスクに最適化されたモデルを指定 プロバイダ / モデル名の形式で記述する。	任意
prompt	エージェント固有のシステムプロンプトファイルへのパス	任意
temperature	応答のランダム性を制御する値 (0.0〜1.0)	任意
permissions	ツール別アクセス制御 allow / deny / ask を設定	任意

下表に、modeオプションの詳細を示す。

modeオプションの詳細

値	説明
all	プライマリエージェントとしてもサブエージェントとしても使用可能 (デフォルト)
primary	Tabキーで切り替え可能なプライマリエージェントとしてのみ使用
subagent	プライマリエージェントから呼び出されるサブエージェントとしてのみ使用

エージェントの定義例

コードレビュー専門エージェント

コードの品質とセキュリティをチェックするエージェントの定義例を以下に示す。

• ファイル名の例

  .opencode/agents/code-reviewer.md

 ---
 name: code-reviewer
 description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use after writing or modifying code.
 mode: subagent
 ---
 
 ## 役割
 
 あなたはコード品質とセキュリティの高い基準を保証するシニアコードレビューアーです。
 
 ## 実行手順
 
 1. 変更されたファイルを確認する
 2. コーディング規約への準拠を検証する
 3. セキュリティ上の問題を検出する
 4. パフォーマンスの問題を指摘する
 
 ## レビューチェックリスト
 
 - コードが明確で読みやすいか
 - 適切なエラーハンドリングがあるか
 - シークレットやAPIキーが露出していないか
 - 入力検証が実装されているか
 - 適切なテストカバレッジがあるか
 
 ## フィードバックの優先順位
 
 - 重要な問題 (必ず修正すべき)
 - 警告 (修正すべき)
 - 提案 (改善を検討)

ドキュメント生成エージェント

プロジェクトのドキュメントを自動生成するエージェントの定義例を以下に示す。

• ファイル名の例

  .opencode/agents/doc-writer.md

 ---
 name: doc-writer
 description: Documentation generation specialist. Analyzes source code and generates comprehensive documentation. Use when creating or updating project documentation.
 mode: subagent
 permissions:
   read: allow
   write: allow
   bash: deny
 ---
 
 ## 役割
 
 あなたはソフトウェアドキュメンテーションの専門家です。
 
 ## 実行手順
 
 1. プロジェクト構造を分析する
 2. 各モジュール・関数の目的を把握する
 3. コードコメントとシグネチャから説明を生成する
 4. Markdown形式でドキュメントを出力する
 
 ## ドキュメント構成
 
 - 概要と目的
 - インストール・セットアップ手順
 - APIリファレンス
 - 使用例

エージェントの呼び出し方法

Tabキーによる切り替え

プライマリエージェント (mode: primary または mode: all) は、[Tab]キーで切り替えることができる。

• [Tab]キーを押下するたびに、次のプライマリエージェントへ切り替わる。
• ビルトインのBuildエージェント、Planエージェント、ユーザ定義のプライマリエージェントが切り替え対象
• 現在使用中のエージェント名が画面に表示される。

@メンションによる呼び出し

プロンプト内でエージェント名を @メンション形式で指定することにより、特定のサブエージェントを明示的に呼び出すことができる。

@security-auditor このコードのセキュリティ上の問題を確認してください

@doc-writer src/api/ のドキュメントを生成してください

プライマリエージェントは、サブエージェントの description フィールドを参照し、
タスクの内容に応じて適切なサブエージェントを自動的に選択・呼び出す場合もある。

エージェントのカスタマイズ

ツールの制限

エージェントに対して使用できるツールを制限することで、安全性を向上できる。

opencode.jsonでの権限設定例を以下に示す。

 {
    "agents": {
       "read-only-analyzer": {
          "description": "コードを読み取り専用で分析するエージェント",
          "mode": "subagent",
          "permissions": {
             "read": "allow",
             "write": "deny",
             "bash": "deny"
          }
       }
    }
 }

permissionsの値を以下に示す。

permissionsの値

値	説明
allow	操作を許可
deny	操作を拒否
ask	実行前にユーザに確認を求める。 確認時の選択肢は、once、always、rejectの3種類

※権限のマージルール
エージェント固有の権限設定はグローバル権限設定よりも優先される。

モデルの指定

エージェントごとに異なるモデルを指定することで、コストとパフォーマンスのバランスを最適化できる。

OpenCodeは75以上のプロバイダをサポートしており、様々なモデルをエージェントに割り当てることができる。

Markdownファイルでのモデル指定例を以下に示す。

 ---
 name: quick-fixer
 description: Quick bug fixes and simple code changes
 mode: subagent
 model: anthropic/claude-haiku-4-5
 ---

 ---
 name: architect-reviewer
 description: Architecture and design review specialist
 mode: subagent
 model: openai/gpt-4o
 ---

権限設定

エージェントのシステムプロンプトには、プロジェクト固有のルール、コーディング規約、技術スタックの情報等を含めることができる。

また、prompt オプションで外部のシステムプロンプトファイルを指定することもできる。

 ---
 name: react-reviewer
 description: React component code review specialist
 mode: subagent
 prompt: .opencode/prompts/react-rules.md
 ---

モード (Modes) との連携

OpenCodeでは、エージェントとは別に "モード" を定義することもできる。

モードは、特定の作業スタイルや制約を定義する仕組みである。

ビルトインモード

OpenCodeにはビルトインモードが2種類存在する。

ビルトインモード

モード名	説明	特徴
build	完全な開発機能を有効化した標準モード	ファイル編集、コマンド実行等全操作が可能
plan	変更提案のみを行う分析モード	読み取り専用、コードを変更せずに計画を立案

カスタムモードの作成

カスタムモードは、Markdownファイルまたは opencode.json で定義できる。

モード定義ファイルは以下のディレクトリに配置する。

• プロジェクト固有

  .opencode/modes/

• グローバル

  ~/.config/opencode/modes/

カスタムモードの定義例を以下に示す。

 ---
 name: review-only
 description: コードレビューのみを行うモード
 model: anthropic/claude-sonnet-4-5
 temperature: 0.2
 permissions:
   write: deny
   bash: deny
 ---
 
 ## モードの動作
 
 このモードでは、コードの変更を行わずにレビューと提案のみを行います。

opencode.jsonでのカスタムモード定義例を以下に示す。

 {
    "modes": {
       "review-only": {
          "description": "コードレビューのみを行うモード",
          "model": "anthropic/claude-sonnet-4-5",
          "temperature": 0.2,
          "permissions": {
             "write": "deny",
             "bash": "deny"
          }
       }
    }
 }

推奨される事柄

明確なdescriptionの記述

description フィールドは、エージェントの呼び出し判断に使用される最も重要な項目である。

アクション指向の表現で、いつ・なぜ使用すべきかを明確に記述する。

description 記述の比較

良い例	悪い例
Use after writing or modifying code to check quality	A code reviewer
Use proactively when encountering any errors or test failures	Helps with debugging
Use when designing new features or making structural changes	Architecture expert

モードの適切な使い分け

エージェントの mode オプションを適切に設定することにより、誤った使用を防ぎ、意図した用途に限定できる。

• 探索や分析のみを担当するエージェント

  mode: subagent を設定し、プライマリエージェントとしての誤使用を防ぐ。

• ユーザが直接切り替えて使用するエージェント

  mode: primary を設定する。

ツールスコープの最小化

各エージェントには、必要なツールのみを付与する。

• 読み取りと分析のみを行うエージェント

  write / bash を deny に設定する。

• 実装を担当するエージェント

  必要な書き込み権限のみを allow に設定する。

バージョン管理への組み込み

プロジェクトレベルのエージェント定義はバージョン管理に含め、チーム全体で共有する。

バージョン管理に含めることを推奨するファイル:

• .opencode/agents/*.md

  エージェント定義ファイル

  
  

• .opencode/modes/*.md

  モード定義ファイル

  
  

• opencode.json

  プロジェクト設定ファイル

トラブルシューティング

エージェントが認識されない場合

ディレクトリ構造の確認

エージェント定義ファイルが正しいディレクトリに配置されているか確認する。

• プロジェクト固有

  .opencode/agents/エージェント名.md

• グローバル

  ~/.config/opencode/agents/エージェント名.md

YAMLフロントマターの確認

YAMLフロントマターの構文が正しいか確認する。
インデントや引用符の誤りによってエラーが発生する場合がある。

 ---
 name: my-agent
 description: エージェントの説明
 mode: subagent
 ---

セッションの再起動

エージェント定義を追加または変更した後は、OpenCodeのセッションを再起動する。
エージェント定義は、セッション開始時に読み込まれる。

エージェントが期待通りに動作しない場合

descriptionフィールドの見直し

サブエージェントが自動選択されない場合、description が不明確である可能性がある。
以下の内容が含まれているか確認する。

• いつ使用すべきか (トリガーとなる状況)
• 何をするエージェントか (具体的な機能)
• どのような結果を返すか (出力の形式)

permissions 設定の確認

エージェントが必要な操作を実行できるか、権限設定を確認する。

• ファイルの書き込みが必要なエージェント

  write: allow が設定されているか確認する。

• シェルコマンドの実行が必要なエージェント

  bash: allow が設定されているか確認する。

モード設定の確認

mode: subagent に設定したエージェントは、[Tab]キーでは切り替えられない。
[Tab]キーで切り替えたい場合は、mode: primary または mode: all を設定する。

参考リンク

• OpenCode公式ドキュメント
• OpenCode GitHubリポジトリ