OpenCodeの設定ファイル一覧とカスタマイズ方法まとめ（json / agents / skills / commands）

ローカルAIコーディングエージェント環境を構築できる「OpenCode」。しばらく使い込んでいくうちに、各設定ファイルの役割や記述ルールが徐々に分かってきました。

今回は、OpenCodeの挙動を制御する各種設定ファイル（.json や .md）の具体的な書き方と役割をまとめました。「エージェントのペルソナを固定したい」「独自の / コマンドを作りたい」という方は、ぜひ参考にしてください。

はじめに

ローカル環境で自律的に動くAIコーディングエージェントとして、非常に強力な選択肢である「OpenCode」。他の記事では基本的な導入方法をご紹介しましたが、デフォルトのままだと「生成されるコードの型が理想と違う」「毎回同じような前提指示を入力するのが面倒」といった壁にぶつかることがあります。

あわせて読みたい

OpenCode+DS4で、ローカルAIコーディングエージェント環境を試してみた

OpenCodeの利点は、プロジェクトごとのカスタマイズ性にあります。しばらく使い込んでいくうちに、各種設定ファイルやフォルダ構造を適切に配置することで、エージェントのペルソナ（役割）や使用ツールを厳密にコントロールできることが分かってきました。

本記事では、開発をさらに効率化するために押さえておきたい設定ファイル（opencode.json）の優先順位から、独自のサブエージェントやカスタムコマンド（/コマンド）の具体的な書き方まで、実際に検証して得られたノウハウを備忘録としてまとめました。

設定ファイル

opencode.json

OpenCodeの設定を行うJSONファイルです。モデルやツール、エージェントなど様々な設定をここで行うことができます。作成していない場合はグローバル設定が優先されます。

同じ項目が設定されている場合、以下の優先順位で後ろの設定が前の設定を上書き（オーバーライド）します。

AGENTS.md

プロジェクト内で稼働させる複数のエージェント（オーケストレーターやサブエージェント）の役割分担や、全体の連携フローを定義するファイルです。

# 開発チームの構成と連携フロー

本プロジェクトでは、以下のエージェントが連携して開発を進めます。

## エージェント一覧

- **Orchestrator（主導）**: ユーザーからの指示を解釈し、タスクを分解して各サブエージェントに割り振ります。全体の進捗管理と最終成果物の確認を担当します。
- **Coder（実装担当）**: 設計書や指示に基づき、クリーンで再利用性の高いコードを実装します。
- **Tester（テスト担当）**: 実装されたコードに対するテストコードの作成および実行を担当し、品質を担保します。

## 連携フロー

1. **Orchestrator** が要件を定義し、仕様書を作成。
2. **Coder** が仕様書を基にソースコードを実装。
3. **Tester** が実装されたコードのテストを行い、バグがあれば **Coder** へ修正をフィードバック。
4. すべてのテストが通過した後、**Orchestrator** がユーザーに成果物を報告。

.opencode/agents/xxx.md

各サブエージェントの具体的なペルソナ（役割）、使用可能なツール、および振る舞いのルールを個別のマークダウンファイルとして定義します。フロントマター（文頭の --- で囲まれた部分）を使用して、ツールの権限や実行モードを指定します。

---
description: コードの実装を担当するプログラマー
mode: subagent
tools:
  write: true
  edit: true
  bash: true
---

あなたは優秀なPythonエンジニアです。
Orchestratorから渡された仕様書に基づき、要件を完全に満たす実装コードを作成してください。

【ルール】
1. テストコードは書かないこと（Testerエージェントの担当です）。
2. 指定がない限り、コードは `.py` ファイルとして保存すること。
3. Pythonの標準的な命名規則（PEP 8）や、エラーハンドリングのベストプラクティスに従うこと。
4. 実装が完了したら、速やかにOrchestratorに完了報告を行うこと。

注意点 サブエージェントに与える役割（例：Pythonエンジニア）と、出力させるファイルの拡張子（例：.py）などの前提条件は、矛盾がないように厳密に指定してください。指示が競合するとエージェントの挙動が不安定になります。

.opencode/skills/xxx/

エージェントが実行できる特定の「スキル（機能）」を定義するフォルダです。"xxx" には任意のスキル名が入ります。このフォルダ内に SKILL.md と、関連するスクリプトファイルを配置します。

ここで定義されたスキルは、ユーザーがチャットで "/" コマンドとして明示的に呼び出すことも、エージェントが必要に応じて自律的に自動で使用することも可能です。

フォルダ構成の例

.opencode/skills/web-query/
├── SKILL.md          # スキルの概要と手順を記述
└── getWebData.py       # 実際の処理を行うスクリプト

# Webから情報を取得するスキル 

## 概要 
Webから情報を取得するスキル 

## 実行手順 
1. `getWebData.py <URL>` を実行して、URLからWebページを取得する 
2. 結果はhtml形式で返される

.opencode/commands/xxx.md

ユーザーがチャット欄で "/" を入力して呼び出すカスタムコマンドを定義できます。実行したい定型処理の手順をマークダウンで記述しておくことで、そのフローに沿った処理を直接実行させることができます。

---
description: 関数（Python）を作成する
agent: build
---

# 指示に従ってコードを作成します。

1. **仕様定義**
   - 与えられた指示から関数の仕様書を作成します。
   - ユーザーに仕様の確認を求めます。問題があれば仕様を再整理し、ステップ1を繰り返します。
2. **実装**
   - 承認された仕様に沿った関数を作成します。
   - 対応する `pytest` 用のテストコードを作成します。
3. **テスト実行**
   - 作成したテストを実行（`pytest`）し、すべてのテストが通過することを確認します。

その他

これまでのセッションの履歴を表示する

opencode session list

セッションをまとめて削除する

opencode session list | grep ses | awk '{print $1}' | xargs -I {} opencode session delete {}

ある/Aru

IT＆機械学習エンジニア/ファイナンシャルプランナー（CFP®)

XContact

専門分野は並列処理・画像処理・機械学習・ディープラーニング。プログラミング言語はC, C++, Go, Pythonを中心として色々利用。現在は、Kaggle, 競プロなどをしながら悠々自適に活動中 保有資格：CFP, マンション管理士、管理業務主任、宅建士など