opencode

OpenCode サブエージェントプロトコル

OpenCode エージェントに作業を委任するための実行可能なプロトコルです。正確に従ってください。

前提条件

• opencode CLI がインストールされ、PATH に設定されていること（確認：opencode --version）
• 少なくとも 1 つのプロバイダーで認証済みであること（opencode providers list）
• 利用可能なモデルが opencode models で一覧表示されること

基本コマンド

OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json --model <provider/model> --agent <build|plan> --dir "<working-dir>" --dangerously-skip-permissions [options] "<prompt>" 2>/dev/null

主なフラグ：

• --format json -- 機械で解析可能な ndjson 出力（必ず使用してください）
• --model provider/model -- 例：openai/gpt-5.4、openai/gpt-5.3-codex
• --variant <level> -- 推論の強度：minimal、medium、high、xhigh（プロバイダー固有）
• --dir <path> -- タスクの作業ディレクトリ
• --dangerously-skip-permissions -- ツール呼び出しを自動承認します（ヘッドレス実行では必須）
• -f/--file <path> -- プロンプトにファイルを添付します
• --agent <name> -- 実装には build（ファイルシステム＋bash）、分析には plan（読み取り専用）を指定します
• -c/--continue -- 前回のセッションを続行します
• -s/--session <id> -- 特定のセッションを続行します

出力の解析

--format json フラグは ndjson（1 行に JSON オブジェクト 1 つ）を出力します。

種類	内容
text	.part.text -- モデルのテキスト応答
tool_call	.part.name、.part.input -- ツール呼び出し
tool_result	.part.output -- ツール実行結果
step_start	セッション／メッセージ ID
step_finish	.part.tokens（使用量）、.part.cost、.part.reason

ヘルパースクリプトで解析します（必ず stderr をリダイレクトしてください）。

opencode run --format json ... 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py [--mode text|full|tools|cost|session|diff|summary]

解析モード：

• text -- モデルのテキスト応答（デフォルト）
• full -- テキスト＋ツール呼び出し＋ツールの結果
• tools -- ツール呼び出しと結果のみ
• cost -- トークン使用量とコストの内訳
• session -- 続行用のセッション ID を抽出
• diff -- ツール呼び出しからファイルの変更内容を抽出
• summary -- 1 行の要約（ステータス、トークン数、コスト、所要時間）

---

タスクプロトコル

ユーザーの依頼からタスクの種類を判断し、該当するプロトコルに従ってください。

プロトコル 1：実装

ユーザーが OpenCode にコードの作成または変更を求めている場合に使用します。

手順：

1. 範囲 -- 作成または変更するファイルを正確に特定します。ファイルを明示的に列挙してください。
2. コンテキスト -- エージェントが確認する必要のあるファイルを収集します。-f で添付してください。
3. 制約 -- 制約ブロックを作成します（下記のプロンプトエンジニアリングを参照）。
4. 実行 -- --agent build を指定して実行します。

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4 --agent build \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     -f <file1> -f <file2> \
     "<prompt>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py --mode full
   

5. 検証 -- 変更したファイルをすべて読みます。正確性、規約、コンパイルを確認してください。
6. 報告 -- 変更内容を要約し、疑わしい点があれば指摘します。

デフォルトモデル： openai/gpt-5.4 | タイムアウト： timeout: 300000

プロトコル 2：レビュー

ユーザーがコードの品質、バグ、または正確性についてセカンドオピニオンを求めている場合に使用します。

手順：

1. 対象 -- レビューするファイルを特定します。
2. 実行 -- --agent plan（読み取り専用）を指定して実行します。

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4 --variant high --agent plan \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     -f <file1> "<review prompt>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py
   

3. 提示 -- ファイル名と行番号を添えて、調査結果をユーザーに伝えます。

デフォルトモデル： openai/gpt-5.4 ＋ --variant high | タイムアウト： timeout: 300000

プロトコル 3：デバッグ

ユーザーが OpenCode にバグやエラーの調査を求めている場合に使用します。

手順：

1. 証拠 -- エラーメッセージ、スタックトレース、関連コードを収集します。
2. GAS のコンテキスト -- GAS のバグの場合、エージェントに次の点を確認するよう指示します：タグのブロック／要件、エフェクトの適用／解除の順序、MMC の依存関係、ASC の初期化タイミング。
3. 実行 -- --agent plan を指定して実行します。

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.3-codex --variant high --agent plan \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     "<diagnostic prompt>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py
   

4. 分析 -- 結果を提示する前に、調査結果を実際のコードと照合します。

デフォルトモデル： openai/gpt-5.3-codex ＋ --variant high | タイムアウト： timeout: 300000

プロトコル 4：調査

ユーザーが OpenCode にコードベースの調査と分析を求めている場合に使用します。

手順：

1. 質問 -- 明確で範囲を限定した調査の質問を作成します。
2. 実行 -- --agent plan を指定して実行します。

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4-mini-fast --agent plan \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     "<research question>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py
   

3. 検証 -- 参照されているファイルを自分で読み、主張を抜き取り確認します。

デフォルトモデル： openai/gpt-5.4-mini-fast | タイムアウト： timeout: 300000

---

オーケストレーションパターン

これらのパターンは、上記の基本プロトコルを組み合わせ、より強力なワークフローを実現します。 複数ステップでの検証や並列実行が有効なタスクで使用してください。

パターン A：実装してからレビューするパイプライン

使用する場面： 品質が重要な実装タスク。複雑な実装では、これをデフォルトとして使用します。

プロトコル：

1. --agent build を指定して プロトコル 1（実装） を実行します
2. 変更内容を自分で読み、検証します（簡単な健全性チェック）
3. 変更したファイルを対象に、異なるモデルを使って プロトコル 2（レビュー） を実行します。
   • 実装に openai/gpt-5.4 を使用した場合は、openai/gpt-5.3-codex でレビューします
   • 異なるモデルでレビューすると、モデル固有の見落としを発見できます
4. 品質ゲート： レビューで重大な問題が見つかった場合は、修正します（自分で修正するか、修正指示を付けて実装を再実行します）
5. 実装とレビューの両方の結果をユーザーに報告します

パターン B：複数モデルによる並列レビュー

使用する場面： ユーザーが徹底的な検証を求めている場合、または「複数の意見を聞いて」と依頼した場合。

プロトコル：

1. レビュープロンプトを一度作成します
2. Bash コマンドを並列で起動します（run_in_background または & を使用）：

   # Run in parallel -- each to a temp file
   PROMPT="<review prompt>"
   DIR="C:/UnrealEngine/VHS"
   
   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4 --variant high --agent plan \
     --dir "$DIR" --dangerously-skip-permissions "$PROMPT" \
     2>/dev/null > /tmp/review_gpt54.txt &
   
   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.3-codex --variant high --agent plan \
     --dir "$DIR" --dangerously-skip-permissions "$PROMPT" \
     2>/dev/null > /tmp/review_codex.txt &
   
   wait
   

3. それぞれの結果を個別に解析します：

   cat /tmp/review_gpt54.txt | python .claude/skills/opencode/scripts/parse_output.py
   cat /tmp/review_codex.txt | python .claude/skills/opencode/scripts/parse_output.py
   

4. 統合 -- 複数のモデルが指摘した問題（確信度が高い）と、単一のモデルだけが指摘した問題（確信度が低い）を特定します。統合したレポートを提示します。

パターン C：自律的な改善ループ

使用する場面： ユーザーが反復的なコード改善を求めている場合、または「これを改善し続けて」「最適化して」「仕上げて」と依頼した場合。

autoresearch の反復実験ループを参考にしています。エージェントが変更を加えて検証し、改善は維持し、失敗した変更は元に戻します。

プロトコル：

LOOP (max N iterations, default 3):
  1. Identify the current quality baseline (read code, note issues)
  2. Construct an improvement prompt targeting the worst issue
  3. Run Protocol 1 (Implement) with --agent build
  4. Validate: read changed files, check for regressions
  5. Run Protocol 2 (Review) on changed files with a different model
  6. QUALITY GATE:
     - If review passes (no critical issues) → keep changes, report improvement
     - If review fails (critical issues found) → revert changes (git checkout the files), report why
  7. If no more meaningful improvements found → STOP
  8. Continue to next iteration

重要な制約：

• 常に最大反復回数を設定します（デフォルトは 3 回です。ユーザーはそれ以上を指定できます）
• 各反復では、具体的かつ測定可能な改善を目標にする必要があります
• 失敗した場合は元に戻します -- 問題のある変更を決して積み重ねないでください
• 改善がわずかになった場合は、早めに停止します
• ユーザーが進捗を把握できるよう、各反復の結果を報告します

パターン D：バックグラウンドエージェント

使用する場面： OpenCode の実行中に Claude Code が別の作業を続けたい場合。会話を止めない、時間のかかるタスクに使用します。

プロトコル：

1. Bash で run_in_background: true を指定して OpenCode コマンドを実行します：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4 --agent plan \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     "<prompt>" 2>/dev/null > /tmp/opencode_result.txt
   

2. 通知を待つ間、別の作業を続けます
3. 通知を受け取ったら、結果を解析します：

   cat /tmp/opencode_result.txt | python .claude/skills/opencode/scripts/parse_output.py
   

4. 調査結果をユーザーに提示します

パターン E：セッションの継続（複数ステップのワークフロー）

使用する場面： 複数回のやり取りを通じてコンテキストを積み上げると効果的な、複雑なタスク。

プロトコル：

1. 最初のタスクを実行し、セッション ID を記録します：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4 --agent plan \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     "<first task>" 2>/dev/null | tee /tmp/oc_step1.txt | python .claude/skills/opencode/scripts/parse_output.py --mode session
   

2. 後続タスクでセッション ID を使用します：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --session "<session-id>" --dangerously-skip-permissions \
     "<follow-up task>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py
   

   または、最後のセッションに対して --continue を使用します：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --continue --dangerously-skip-permissions \
     "<follow-up task>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py
   

パターン F：Git チェックポイントを使った実装

使用する場面： ロールバック時の安全性が重要な、リスクの高い実装。

autoresearch の「git を状態機械として使う」パターンを参考にしています。

プロトコル：

1. チェックポイント -- 現在の git の状態を記録します：

   git stash  # or commit current work
   

2. --agent build を指定して プロトコル 1（実装） を実行します
3. 検証 -- 変更したファイルをすべて読み、該当する場合はビルド／テストを実行します
4. ゲート：
   • 変更が正しい場合 → 維持し、成功を報告します
   • 変更が誤っている場合 → 元に戻します：

     git checkout -- <modified-files>
     

   • 問題の内容と、元に戻した理由を報告します
5. 問題のある変更を残さないでください -- 検証に失敗した場合は、報告する前に必ず元に戻します

---

プロンプトエンジニアリング

OpenCode は、この会話のコンテキストにアクセスできません。すべてのプロンプトは完全に自己完結している必要があります。

OpenCode を使って Claude／Anthropic モデルや Google／Gemini モデルを呼び出さないでください。これらのプロバイダーは OpenCode では利用できません。OpenAI、GitHub Copilot、ローカルモデル、および OpenCode 独自のモデルのみを使用してください。

プロンプトの構成（必須）

OpenCode に送信するすべてのプロンプトは、次の構成に従う必要があります。

[CONTEXT BLOCK]
<project type, conventions, key constraints>

[TASK]
<imperative description of what to do>

[SCOPE]
<explicit boundaries: which files/dirs to touch, which to ignore>

[CONSTRAINTS]
<naming conventions, patterns to follow, things to avoid>

[OUTPUT FORMAT]
<what form the response should take>

UE5／VHS コンテキストブロック（プロジェクトタスクでは必ず含める）

This is an Unreal Engine 5.7 C++ project (VHS - first-person horror game).
Source: Source/VHS/  |  Module: VHS  |  No Public/Private split (side-by-side .h/.cpp)

Naming conventions:
- UE prefixes: A (actors), U (UObjects), F (structs), E (enums), I (interfaces)
- GAS: GA_ (abilities), GC_ (cues), MMC_ (magnitude calcs), GE_ (effects)
- Booleans: b prefix (bIsRecovering)
- #pragma once, CoreMinimal.h first, .generated.h last

Key systems: GAS (AbilitySystem/), Enhanced Input, StateTree (AI)
Dependencies: GameplayAbilities, GameplayTags, GameplayTasks, EnhancedInput, StateTreeModule

スコープの制約（タイムアウトを避けるために重要）

必ず明示的なスコープの境界を設定してください。範囲の広いプロンプトを指定すると、エージェントがファイルシステム全体を探索してタイムアウトすることがあります。

適切な例：

Search ONLY in Source/VHS/AbilitySystem/. Do NOT explore other directories.
Modify ONLY HorrorCharacter.h and HorrorCharacter.cpp. Do NOT touch other files.

不適切な例：

Look through the project and find issues.  (too broad -- will timeout)

実装プロンプトのテンプレート

[CONTEXT]
This is an Unreal Engine 5.7 C++ project (VHS). <conventions block>

[TASK]
Implement <feature> in <file(s)>.
<detailed requirements>

[SCOPE]
- Create/modify ONLY: <explicit file list>
- Reference (read-only): <files to read for context>
- Do NOT touch: <exclusions>

[CONSTRAINTS]
- Follow existing patterns in <reference file>
- Use UPROPERTY(EditDefaultsOnly, Category = "<Category>") for configurable values
- All new UObject classes need UCLASS(ClassGroup=(VHS)) macro
- Header: #pragma once, CoreMinimal.h first, .generated.h last

[OUTPUT]
Write the implementation directly. No explanations needed.

レビュープロンプトのテンプレート

[CONTEXT]
This is an Unreal Engine 5.7 C++ project using GAS. <conventions block>

[TASK]
Review the following files for: correctness, bugs, performance, security, UE5 best practices.
Be specific: cite file paths and line numbers. Suggest concrete fixes.

[SCOPE]
Review ONLY: <file list>
Do NOT explore other directories.

[OUTPUT FORMAT]
For each issue found:
- **[SEVERITY]** (critical/warning/info)
- **File:Line** -- specific location
- **Issue** -- what's wrong
- **Fix** -- concrete solution

デバッグプロンプトのテンプレート

[CONTEXT]
UE5.7 project (VHS) using GAS. <conventions block>

[BUG REPORT]
<symptom description>
<error messages / stack traces>
<reproduction steps if known>

[TASK]
Investigate root cause. Check:
- <specific things to check based on the bug>
- For GAS bugs: tag blocking, effect ordering, MMC deps, ASC init timing

[SCOPE]
Search ONLY in: <directory>

[OUTPUT FORMAT]
1. Root cause (most likely)
2. Evidence (file:line references)
3. Fix (concrete code changes)

---

モデルの選択

タスクに適したモデルを選んでください。詳しくは references/models.md をご覧ください。

クイック設定：

タスク	高速	デフォルト	高精度
実装	openai/gpt-5.4-mini-fast	openai/gpt-5.4	openai/gpt-5.3-codex
レビュー	openai/gpt-5.4-mini	openai/gpt-5.4 + --variant high	openai/gpt-5.3-codex + --variant high
デバッグ	openai/gpt-5.4-mini-fast	openai/gpt-5.3-codex + --variant high	openai/gpt-5.4 + --variant xhigh
調査	openai/gpt-5.4-mini-fast	openai/gpt-5.4-fast	openai/gpt-5.4

利用可能なモデルをすべて確認するには、opencode models を使用してください。サポートされているのは、OpenAI、GitHub Copilot、OpenCode 独自の無料モデル、およびローカルモデル（Ollama／LM Studio）のみです。

モデルをまたいだレビューペア（パイプラインパターン A 用）：

• openai/gpt-5.4 で実装 → openai/gpt-5.3-codex でレビュー
• openai/gpt-5.3-codex で実装 → openai/gpt-5.4 でレビュー
• レビューには、実装時とは必ず異なるモデルを使用してください

コストを抑えたい場合の代替案：

• github-copilot/gpt-5.4 -- Copilot サブスクリプションで無料
• github-copilot/gpt-5.3-codex -- Copilot サブスクリプションで無料
• opencode/big-pickle -- OpenCode 独自の無料プラン
• ローカル：ollama/qwen3-coder:latest -- API コストなし

---

エラー処理と復旧

エラーの検出

症状	原因	復旧方法
opencode が見つからない	インストールされていない	ユーザーに npm i -g opencode を伝える
プロバイダーが設定されていない	認証されていない	ユーザーに opencode providers login を伝える
モデルを利用できない	モデル ID が間違っている	opencode models を実行し、代替案を提案する
タイムアウト（3 分超）	スコープが広すぎる	スコープの制約を狭め、より高速なモデルを使用する
JSON の解析に失敗	出力が破損している	--format default を指定して再試行し、プレーンテキストを読む
終了コードがゼロ以外	実行時エラー	stderr を確認し（最大 500 文字）、一度だけ再試行する
空のテキスト応答	エージェントがツール呼び出しのみ実行した	--mode full を指定してツール呼び出しの結果を確認する

モデルの自動フォールバック

モデルが失敗するかタイムアウトした場合は、次の順番でフォールバックします：

1. openai/gpt-5.4（プライマリ）
2. openai/gpt-5.3-codex（コードに最適化）
3. openai/gpt-5.4-mini-fast（最速で、常に動作）
4. github-copilot/gpt-5.4（無料プラン）
5. opencode/big-pickle（OpenCode の無料プラン）

クラッシュからの復旧

実装の途中（--agent build）で OpenCode がクラッシュした場合：

1. 変更されたファイルを確認します：git diff --name-only
2. 変更された各ファイルを読み、完成度を評価します
3. 変更が不完全または壊れている場合は、git checkout -- <files> を実行します
4. スコープを狭めるか、別のモデルを使用して再試行します
5. クラッシュと復旧についてユーザーに報告します

---

判断のフレームワーク

OpenCode をいつ、どのように呼び出すかは、こちらを参考に判断してください：

User request received
  │
  ├─ "use opencode" / names a model → Use OpenCode (user explicit)
  │
  ├─ "second opinion" / "cross-validate" → Pattern B (Parallel Multi-Model)
  │
  ├─ "implement with X" → Protocol 1, optionally Pattern A (Implement-Then-Review)
  │
  ├─ "review with X" → Protocol 2
  │
  ├─ "keep improving" / "optimize" / "polish" → Pattern C (Autonomous Loop)
  │
  ├─ Complex implementation → Pattern A (Implement-Then-Review) by default
  │
  ├─ Risky changes → Pattern F (Git-Checkpoint)
  │
  └─ Long-running task, user wants to continue chatting → Pattern D (Background)

高度なパターン

references/advanced.md では、以下について説明しています：

• セッションを維持するためのサーバーモード
• 自動化のための環境変数
• セッションのエクスポート／インポート
• 統計情報とコストの追跡