OpenCodeの設定 - サブエージェントのソースを表示

== 概要 ==
OpenCodeのエージェント機能は、特定のタスクや作業モードに特化したAIアシスタントを定義し、用途に応じて使い分けることにより、効率的な開発ワークフローを構築する機能である。<br>
<br>
OpenCodeのエージェントは、以下に示す2つの役割に分類される。<br>
* プライマリエージェント
*: ユーザと直接対話するエージェント
*: Tabキーで切り替えることができる
* サブエージェント
*: プライマリエージェントから内部的に呼び出される特化アシスタント
<br>
エージェントを活用することにより、以下に示すメリットが得られる。<br>
* 作業の専門化
*: コードレビュー、ドキュメント生成等、特定の目的に最適化されたエージェントを定義できる
* モデルの使い分け
*: タスクの性質に応じて適切なモデルを割り当て、コストとパフォーマンスを最適化できる
*: OpenCodeは75以上のプロバイダをサポートしており、さまざまなモデルを指定できる
* 権限の制御
*: エージェントごとにツールアクセスを制限し、安全性を向上できる
* ワークフローの標準化
*: プロジェクト全体で一貫したエージェント設定を共有できる
<br><br>

== エージェントの種類 ==
OpenCodeには、ビルトインのプライマリエージェントとユーザ定義のサブエージェントが存在する。<br>
<br>
==== プライマリエージェント ====
プライマリエージェントは、ユーザと直接対話するエージェントである。<br>
Tabキーを押すことで、利用可能なプライマリエージェント間を切り替えることができる。<br>
<br>
===== Build エージェント =====
Buildエージェントは、OpenCodeのデフォルトエージェントである。<br>
<br>
Build エージェントの特徴を以下に示す。<br>
* 全てのツールが有効化された標準的な開発エージェント
* コードの編集、ファイルの読み書き、シェルコマンドの実行等、あらゆる操作が可能
* 日常的なコーディング作業に最適
<br>
===== Plan エージェント =====
Planエージェントは、変更を加えずに分析と計画を行うための制限されたエージェントである。<br>
<br>
Planエージェントの特徴を以下に示す。<br>
* ファイルの書き込みやシェルコマンドの実行を伴うツールへのアクセスが制限されている。
* コードベースの分析、設計の検討、実装計画の立案に特化
* 誤ってコードを変更するリスクなく、安全に探索・分析できる。
<br>
==== サブエージェント ====
サブエージェントは、プライマリエージェントから呼び出される特化アシスタントである。<br>
独立したコンテキストで作業を実行し、結果をプライマリエージェントに返す。<br>
<br>
===== Generalサブエージェント =====
Generalサブエージェントは、汎用的な目的で使用されるビルトインのサブエージェントである。<br>
<br>
* 汎用的なタスクに対応
* プライマリエージェントがタスクを委譲する際のデフォルトの委譲先
<br>
===== Exploreサブエージェント =====
Exploreサブエージェントは、コードベースの探索と分析に特化したビルトインのサブエージェントである。<br>
<br>
* ファイルの検索、コードの読み取りに特化
* 大規模なコードベースの調査や、既存実装の把握に適している。
<br><br>

== ディレクトリ構造 ==
エージェント定義ファイルは、以下に示すディレクトリに配置する。<br>
<br>
 .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         # 計画モード
<br>
配置場所の使い分けを以下に示す。<br>
* プロジェクト固有
*: <u>.opencode/agents/</u> に配置
*: チーム全体で共有し、バージョン管理に含める
*: <br>
* グローバル
*: <u>~/.config/opencode/agents/</u> に配置
*: 全てのプロジェクトで利用可能な共通エージェント
<br>
<u>ディレクトリ名について、<u>agents</u> (複数形) を推奨する。</u><br>
<u>後方互換性のため、<u>agent</u> (単数形) も認識される。</u><br>
<br><br>

== エージェントの作成方法 ==
エージェントの作成方法は3種類存在する。<br>
<br>
==== opencode agent createコマンド ====
CLIコマンドを使用して、対話的にエージェントを作成する方法である。<br>
<br>
 opencode agent create
<br>
コマンドを実行すると、以下の手順で進む。<br>
# 保存場所の選択 (プロジェクト固有またはグローバル)
# エージェントの目的を説明する入力プロンプト
# OpenCodeが自動的にエージェント定義を生成
# 使用するツールの選択と確認
<br>
==== Markdownファイルによる定義 ====
Markdownファイルを手動で作成してエージェントを定義する方法である。<br>
ファイル名がエージェント名となる。<br>
<br>
ファイルは以下の2つのセクションで構成される。<br>
* YAMLフロントマター
*: エージェントのメタデータを定義
* Markdown本文
*: エージェントへの指示を記述
<br>
 <syntaxhighlight lang="md">
 ---
 name: エージェント名
 description: エージェントの説明
 mode: primary / subagent / all (デフォルト: all)
 model: モデル指定 (任意)
 prompt: カスタムシステムプロンプトファイルへのパス (任意)
 ---
 
 ## エージェントへの指示
 
 このエージェントは、[目的] を担当します。
 
 ## 実行手順
 
 1. ステップ1
 2. ステップ2
 </syntaxhighlight>
<br>
==== opencode.jsonによる定義 ====
プロジェクトルートまたはホームディレクトリの <u>opencode.json</u> にエージェントを定義する方法である。<br>
<br>
複数のエージェントを1つのファイルで集中管理できる。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "agents": {
       "review": {
          "description": "コード審査専用エージェント",
          "mode": "subagent",
          "model": "モデル名 (任意)",
          "permissions": {
             "read": "allow",
             "write": "deny"
          }
       }
    }
 }
 </syntaxhighlight>
<br><br>

== エージェント定義の設定オプション ==
エージェント定義で使用できる設定オプションを以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ エージェント定義の設定オプション
! オプション !! 説明 !! 必須
|-
| name || エージェントの一意な識別子<br>kebab-caseを推奨 || 任意 (ファイル名から自動設定)
|-
| description || エージェントの目的と機能の説明<br>プライマリエージェントがこれを読んで呼び出しを判断する。 || 推奨
|-
| mode || <u>all</u> (デフォルト)<br><u>primary</u><br><u>subagent</u> の3種類 || 任意
|-
| model || タスクに最適化されたモデルを指定<br>プロバイダ / モデル名の形式で記述する。 || 任意
|-
| prompt || エージェント固有のシステムプロンプトファイルへのパス || 任意
|-
| temperature || 応答のランダム性を制御する値 (0.0〜1.0) || 任意
|-
| permissions || ツール別アクセス制御<br>allow / deny / ask を設定 || 任意
|}
</center>
<br>
下表に、modeオプションの詳細を示す。<br>
<br>
<center>
{| class="wikitable"
|+ modeオプションの詳細
! 値 !! 説明
|-
| <code>all</code> || プライマリエージェントとしてもサブエージェントとしても使用可能 (デフォルト)
|-
| <code>primary</code> || Tabキーで切り替え可能なプライマリエージェントとしてのみ使用
|-
| <code>subagent</code> || プライマリエージェントから呼び出されるサブエージェントとしてのみ使用
|}
</center>
<br><br>

== エージェントの定義例 ==
==== コードレビュー専門エージェント ====
コードの品質とセキュリティをチェックするエージェントの定義例を以下に示す。<br>
<br>
* ファイル名の例
*: .opencode/agents/code-reviewer.md
<br>
 <syntaxhighlight lang="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キーが露出していないか
 - 入力検証が実装されているか
 - 適切なテストカバレッジがあるか
 
 ## フィードバックの優先順位
 
 - 重要な問題 (必ず修正すべき)
 - 警告 (修正すべき)
 - 提案 (改善を検討)
 </syntaxhighlight>
<br>
==== ドキュメント生成エージェント ====
プロジェクトのドキュメントを自動生成するエージェントの定義例を以下に示す。<br>
<br>
* ファイル名の例
*: .opencode/agents/doc-writer.md
<br>
 <syntaxhighlight lang="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リファレンス
 - 使用例
 </syntaxhighlight>
<br><br>

== エージェントの呼び出し方法 ==
==== Tabキーによる切り替え ====
プライマリエージェント (<code>mode: primary</code> または <code>mode: all</code>) は、[Tab]キーで切り替えることができる。<br>
<br>
* [Tab]キーを押下するたびに、次のプライマリエージェントへ切り替わる。
* ビルトインのBuildエージェント、Planエージェント、ユーザ定義のプライマリエージェントが切り替え対象
* 現在使用中のエージェント名が画面に表示される。
<br>
==== @メンションによる呼び出し ====
プロンプト内でエージェント名を @メンション形式で指定することにより、特定のサブエージェントを明示的に呼び出すことができる。<br>
<br>
 @security-auditor このコードのセキュリティ上の問題を確認してください
<br>
 @doc-writer src/api/ のドキュメントを生成してください
<br>
<u>プライマリエージェントは、サブエージェントの <code>description</code> フィールドを参照し、</u><br>
<u>タスクの内容に応じて適切なサブエージェントを自動的に選択・呼び出す場合もある。</u><br>
<br><br>

== エージェントのカスタマイズ ==
==== ツールの制限 ====
エージェントに対して使用できるツールを制限することで、安全性を向上できる。<br>
<br>
opencode.jsonでの権限設定例を以下に示す。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "agents": {
       "read-only-analyzer": {
          "description": "コードを読み取り専用で分析するエージェント",
          "mode": "subagent",
          "permissions": {
             "read": "allow",
             "write": "deny",
             "bash": "deny"
          }
       }
    }
 }
 </syntaxhighlight>
<br>
permissionsの値を以下に示す。<br>
<br>
<center>
{| class="wikitable"
|+ permissionsの値
! 値 !! 説明
|-
| <code>allow</code> || 操作を許可
|-
| <code>deny</code> || 操作を拒否
|-
| <code>ask</code> || 実行前にユーザに確認を求める。<br>確認時の選択肢は、once、always、rejectの3種類
|}
</center>
<br>
<u>※権限のマージルール</u><br>
<u>エージェント固有の権限設定はグローバル権限設定よりも優先される。</u><br>
<br>
==== モデルの指定 ====
エージェントごとに異なるモデルを指定することで、コストとパフォーマンスのバランスを最適化できる。<br>
<br>
OpenCodeは75以上のプロバイダをサポートしており、様々なモデルをエージェントに割り当てることができる。<br>
<br>
Markdownファイルでのモデル指定例を以下に示す。<br>
<br>
 <syntaxhighlight lang="md">
 ---
 name: quick-fixer
 description: Quick bug fixes and simple code changes
 mode: subagent
 model: anthropic/claude-haiku-4-5
 ---
 </syntaxhighlight>
<br>
 <syntaxhighlight lang="md">
 ---
 name: architect-reviewer
 description: Architecture and design review specialist
 mode: subagent
 model: openai/gpt-4o
 ---
 </syntaxhighlight>
<br>
==== 権限設定 ====
エージェントのシステムプロンプトには、プロジェクト固有のルール、コーディング規約、技術スタックの情報等を含めることができる。<br>
<br>
また、<code>prompt</code> オプションで外部のシステムプロンプトファイルを指定することもできる。<br>
<br>
 <syntaxhighlight lang="md">
 ---
 name: react-reviewer
 description: React component code review specialist
 mode: subagent
 prompt: .opencode/prompts/react-rules.md
 ---
 </syntaxhighlight>
<br><br>

== モード (Modes) との連携 ==
OpenCodeでは、エージェントとは別に <u>"モード"</u> を定義することもできる。<br>
<br>
<u>モードは、特定の作業スタイルや制約を定義する仕組みである。</u><br>
<br>
==== ビルトインモード ====
OpenCodeにはビルトインモードが2種類存在する。<br>
<br>
<center>
{| class="wikitable"
|+ ビルトインモード
! モード名 !! 説明 !! 特徴
|-
| build || 完全な開発機能を有効化した標準モード || ファイル編集、コマンド実行等全操作が可能
|-
| plan || 変更提案のみを行う分析モード || 読み取り専用、コードを変更せずに計画を立案
|}
</center>
<br>
==== カスタムモードの作成 ====
カスタムモードは、Markdownファイルまたは <u>opencode.json</u> で定義できる。<br>
<br>
モード定義ファイルは以下のディレクトリに配置する。<br>
<br>
* プロジェクト固有
*: <u>.opencode/modes/</u>
* グローバル
*: <u>~/.config/opencode/modes/</u>
<br>
カスタムモードの定義例を以下に示す。<br>
<br>
 <syntaxhighlight lang="md">
 ---
 name: review-only
 description: コードレビューのみを行うモード
 model: anthropic/claude-sonnet-4-5
 temperature: 0.2
 permissions:
   write: deny
   bash: deny
 ---
 
 ## モードの動作
 
 このモードでは、コードの変更を行わずにレビューと提案のみを行います。
 </syntaxhighlight>
<br>
opencode.jsonでのカスタムモード定義例を以下に示す。<br>
<br>
 <syntaxhighlight lang="json">
 {
    "modes": {
       "review-only": {
          "description": "コードレビューのみを行うモード",
          "model": "anthropic/claude-sonnet-4-5",
          "temperature": 0.2,
          "permissions": {
             "write": "deny",
             "bash": "deny"
          }
       }
    }
 }
 </syntaxhighlight>
<br><br>

== 推奨される事柄 ==
==== 明確なdescriptionの記述 ====
<code>description</code> フィールドは、エージェントの呼び出し判断に使用される最も重要な項目である。<br>
<br>
<u>アクション指向の表現で、いつ・なぜ使用すべきかを明確に記述する。</u><br>
<br>
<center>
{| class="wikitable"
|+ 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
|}
</center>
<br>
==== モードの適切な使い分け ====
エージェントの <code>mode</code> オプションを適切に設定することにより、誤った使用を防ぎ、意図した用途に限定できる。<br>
<br>
* 探索や分析のみを担当するエージェント
*: <code>mode: subagent</code> を設定し、プライマリエージェントとしての誤使用を防ぐ。
* ユーザが直接切り替えて使用するエージェント
*: <code>mode: primary</code> を設定する。
<br>
==== ツールスコープの最小化 ====
各エージェントには、必要なツールのみを付与する。<br>
<br>
* 読み取りと分析のみを行うエージェント
*: write / bash を deny に設定する。
* 実装を担当するエージェント
*: 必要な書き込み権限のみを allow に設定する。
<br>
==== バージョン管理への組み込み ====
プロジェクトレベルのエージェント定義はバージョン管理に含め、チーム全体で共有する。<br>
<br>
バージョン管理に含めることを推奨するファイル:<br>
* <u>.opencode/agents/*.md</u>
*: エージェント定義ファイル
*: <br>
* <u>.opencode/modes/*.md</u>
*: モード定義ファイル
*: <br>
* <u>opencode.json</u>
*: プロジェクト設定ファイル
<br><br>

== トラブルシューティング ==
==== エージェントが認識されない場合 ====
===== ディレクトリ構造の確認 =====
エージェント定義ファイルが正しいディレクトリに配置されているか確認する。<br>
<br>
* プロジェクト固有
*: <u>.opencode/agents/エージェント名.md</u>
* グローバル
*: <u>~/.config/opencode/agents/エージェント名.md</u>
<br>
===== YAMLフロントマターの確認 =====
YAMLフロントマターの構文が正しいか確認する。<br>
インデントや引用符の誤りによってエラーが発生する場合がある。<br>
<br>
 <syntaxhighlight lang="md">
 ---
 name: my-agent
 description: エージェントの説明
 mode: subagent
 ---
 </syntaxhighlight>
<br>
===== セッションの再起動 =====
エージェント定義を追加または変更した後は、OpenCodeのセッションを再起動する。<br>
エージェント定義は、セッション開始時に読み込まれる。<br>
<br>
==== エージェントが期待通りに動作しない場合 ====
===== descriptionフィールドの見直し =====
サブエージェントが自動選択されない場合、<code>description</code> が不明確である可能性がある。<br>
以下の内容が含まれているか確認する。<br>
<br>
* いつ使用すべきか (トリガーとなる状況)
* 何をするエージェントか (具体的な機能)
* どのような結果を返すか (出力の形式)
<br>
===== permissions 設定の確認 =====
エージェントが必要な操作を実行できるか、権限設定を確認する。<br>
<br>
* ファイルの書き込みが必要なエージェント
*: <code>write: allow</code> が設定されているか確認する。
* シェルコマンドの実行が必要なエージェント
*: <code>bash: allow</code> が設定されているか確認する。
<br>
===== モード設定の確認 =====
<code>mode: subagent</code> に設定したエージェントは、[Tab]キーでは切り替えられない。<br>
[Tab]キーで切り替えたい場合は、<code>mode: primary</code> または <code>mode: all</code> を設定する。<br>
<br><br>

== 参考リンク ==
* [https://opencode.ai/docs OpenCode公式ドキュメント]
* [https://github.com/sst/opencode OpenCode GitHubリポジトリ]
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,OpenCode,Agents,Subagents,AI,Development,Programming,SUSE,Linux
|description={{PAGENAME}} - OpenCodeのエージェント機能に関する設定ガイド
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]