OpenCodeの設定 - AGENTS.md
概要
AGENTS.mdは、OpenCodeのカスタム指示ファイルである。
Claude CodeにおけるCLAUDE.mdに相当する機能を提供し、プロジェクトのコンテキストをAIエージェントに永続的に伝達する役割を担う。
AGENTS.mdを活用することにより、以下に示すメリットが得られる。
- プロジェクト固有のルールや規約の永続化
- セッションをまたいでプロジェクトの知識を保持する
- チーム全体での知識共有
- バージョン管理システムを通じて、チーム全員が同じルールを共有できる
- AIエージェントへの一貫したコンテキスト提供
- セッション開始時にAGENTS.mdの内容が自動的に読み込まれる
- グローバルとローカルの階層管理
- 個人設定とプロジェクト設定を分離して管理できる
なお、OpenCodeはClaude CodeのCLAUDE.mdとの後方互換性を持つ。
既存のCLAUDE.mdファイルも自動的に検出・利用されるため、Claude Codeから移行した場合でも設定を引き継ぐことができる。
AGENTS.mdの優先度と読み込み順序
OpenCodeは、AGENTS.mdをローカルカテゴリとグローバルカテゴリの2つのカテゴリに分けて管理する。
両カテゴリのファイルは改行で連結され、システムプロンプトに含まれる。
優先度1 : プロジェクトレベル
プロジェクトレベルのファイルは、カレントディレクトリから上位ディレクトリへとトラバース探索される。
探索で最初に見つかったファイルのみが使用される。
優先順位は以下の通りである。
- AGENTS.md (最高優先度)
- CLAUDE.md
- CONTEXT.md
例えば、カレントディレクトリ内に AGENTS.md が存在する場合、上位ディレクトリの CLAUDE.md よりも優先される。
探索対象の配置例を以下に示す。
- AGENTS.md
- プロジェクトルートに配置する。(推奨)
- .opencode/AGENTS.md
- .opencodeディレクトリ内に配置する。
- .claude/CLAUDE.md
- Claude Code互換のパスも探索対象となる。
優先度2 : グローバルレベル
グローバルレベルのファイルは、全プロジェクト共通のルールを定義するために使用する。
以下に示す優先順位でファイルが適用される。
- ~/.config/opencode/AGENTS.md (公式パス、最高優先度)
- ~/.claude/CLAUDE.md (Claude Code互換フォールバック)
グローバルレベルのファイルとプロジェクトレベルのファイルは排他的ではなく、両方が存在する場合は改行で連結されてシステムプロンプトに含まれる。
優先度3 : レガシー互換 (CLAUDE.md)
OpenCodeは、Claude CodeのCLAUDE.mdとの後方互換性を保持している。
互換性の詳細は以下の通りである。
- ~/.claude/CLAUDE.md
- グローバルレベルのフォールバックとして自動検出される。
- ./.claude/CLAUDE.md
- プロジェクトレベルのトラバース探索対象に含まれる。
- AGENTS.md > CLAUDE.md
- 同じディレクトリに両方存在する場合は、AGENTS.mdが優先される。
Claude Codeから移行する際は、既存のCLAUDE.mdをそのまま使用し続けることができる。
段階的にAGENTS.mdへ移行する方法も選択可能である。
ディレクトリ構造
OpenCodeは、プロジェクトレベルとグローバルレベルの2つのディレクトリ構造を持つ。
プロジェクトレベルのディレクトリ構造を以下に示す。
# 例 : QML/C++プロジェクト .opencode/ ├── AGENTS.md # プロジェクト固有のルール ├── agents/ # カスタムエージェント定義 │ ├── qml-frontend.md # QMLフロントエンド開発エージェント │ ├── cpp-backend.md # C++バックエンド開発エージェント │ ├── qml-reviewer.md # QMLコードレビューエージェント │ └── cpp-debugger.md # C++デバッグ専門エージェント ├── commands/ # カスタムコマンド定義 │ ├── build.md # /build CMakeビルドコマンド │ ├── qml-lint.md # /qml-lint QMLリントコマンド │ └── ctest.md # /ctest ユニットテスト実行コマンド ├── skills/ # カスタムスキル │ ├── qt-api/ # Qt APIリファレンス調査スキル │ │ └── SKILL.md # スキル定義ファイル │ ├── qml-design/ # QML UI設計ガイドスキル │ │ └── SKILL.md # スキル定義ファイル │ └── cpp-optimization/ # C++パフォーマンス最適化スキル │ └── SKILL.md # スキル定義ファイル ├── tools/ # カスタムツール定義 │ ├── qml-analyzer.ts # QMLコード静的解析ツール │ └── cmake-helper.ts # CMake設定補助ツール ├── modes/ # モード設定 │ ├── qml-design-mode.md # QML UI設計モード │ ├── debug-mode.md # C++デバッグモード │ └── review-mode.md # コードレビューモード ├── plugins/ # プラグイン定義 │ ├── build-notify.ts # CMakeビルド結果通知プラグイン │ └── qml-hot-reload.ts # QMLホットリロード検知プラグイン ├── themes/ # テーマ設定 │ └── qt-creator.json # Qt Creator風カスタムテーマ └── package.json # プラグイン依存関係
グローバルレベルのディレクトリ構造を以下に示す。
~/.config/opencode/
├── AGENTS.md # グローバルルール
├── opencode.json # グローバル設定ファイル
├── agents/ # グローバルエージェント
│ └── translator.md # 翻訳エージェント
├── commands/ # グローバルコマンド
│ ├── commit-msg.md # /commit-msg コミットメッセージ生成コマンド
│ └── translate.md # /translate 翻訳コマンド
├── skills/ # グローバルスキル
│ └── doc-gen/ # ドキュメント生成スキル
│ └── SKILL.md # スキル定義ファイル
├── tools/ # グローバルツール
│ └── format-checker.ts # コードフォーマットチェックツール
├── modes/ # グローバルモード
│ └── plan-mode.md # 計画モード
├── plugins/ # グローバルプラグイン
│ └── session-notify.ts # セッション通知プラグイン
└── themes/ # グローバルテーマ
└── monokai.json # Monokaiカスタムテーマ
プロジェクト固有の設定は .opencode/ ディレクトリに、個人の全プロジェクト共通設定は ~/.config/opencode/ ディレクトリに配置する。
AGENTS.mdに記述する内容
プロジェクト概要
プロジェクトの目的、技術スタック、主要な機能を簡潔に記述する。
記述例を以下に示す。
# プロジェクト概要
このプロジェクトは、RESTful APIを提供するバックエンドサービスです。
技術スタック:
- 言語: Go 1.22
- フレームワーク: Gin
- データベース: PostgreSQL 15
- コンテナ: Docker / Kubernetes
コーディング規約
プロジェクトで使用するコーディング規約、命名規則、スタイルガイドを記述する。
記述例を以下に示す。
# コーディング規約
- 関数名: camelCase
- 定数: UPPER_SNAKE_CASE
- ファイル名: snake_case
- インデント: タブ
- 行の最大文字数: 120文字
頻繁に使用するコマンド
プロジェクトで頻繁に使用するコマンドを記録する。
記述例を以下に示す。
# 頻繁に使用するコマンド
## 開発サーバの起動
go run ./cmd/server
## テストの実行
go test ./...
## ビルド
go build -o bin/server ./cmd/server
注意事項・制限事項
プロジェクトで避けるべきパターン、使用禁止のライブラリ、セキュリティ制約等を記述する。
記述例を以下に示す。
# 注意事項
- APIキーをソースコードにハードコードしないこと
- 直接SQLを記述せず、ORMを使用すること
- エラーはログに記録し、ユーザには汎用メッセージを返すこと
AGENTS.mdの作成方法
/initコマンドによる自動生成
OpenCodeには、プロジェクト構造を分析してAGENTS.mdを自動生成する /init コマンドが用意されている。
/init コマンドの使い方を以下に示す。
# OpenCodeセッション内で実行する /init
/init コマンドは以下の処理を自動的に実行する。
- プロジェクトの技術スタックの検出
- package.json、go.mod、Cargo.toml等の設定ファイルを解析する
- ディレクトリ構造の解析
- プロジェクトの構成を把握し、主要なディレクトリの役割を説明する
- 頻繁に使用するコマンドの推測
- ビルド、テスト、実行コマンドを自動的に識別する
自動生成後は内容を確認し、プロジェクト固有の情報を追記することを推奨する。
また、生成されたAGENTS.mdはGitにコミットしておくことを推奨する。
再実行することで、AGENTS.mdを再生成することもできる。
手動作成
/init コマンドを使用せず、手動でAGENTS.mdファイルを作成することもできる。
ステップ1: ファイルの作成
プロジェクトルート または .opencodeディレクトリにAGENTS.mdファイルを作成する。
# プロジェクトルートに作成する場合 touch AGENTS.md
# .opencodeディレクトリに作成する場合 mkdir -p .opencode touch .opencode/AGENTS.md
ステップ2: 基本情報の記述
プロジェクト概要、技術スタック、ディレクトリ構造等を記述する。
Markdown形式で記述する。
# プロジェクト概要
このプロジェクトは...
# 技術スタック
- フロントエンド: React
- バックエンド: Node.js
# ディレクトリ構造
```
src/
├── components/
└── api/
```
ステップ3: コーディング規約の追加
プロジェクト固有のコーディング規約を追加する。
# コーディング規約
- 関数名: camelCase
- インデント: 半角スペース2つ
- セミコロン: 必須
ステップ4: ファイルの保存と確認
ファイルを保存し、OpenCodeセッションを再起動して読み込みを確認する。
# OpenCodeセッションの終了 /exit
# OpenCodeセッションの再起動 opencode
セッション開始時に、AGENTS.mdの内容が自動的に読み込まれる。
基本的な記述例
シンプルな例
最小限の構成でAGENTS.mdを作成する例を以下に示す。
# MyProject
Node.js + TypeScript のWebアプリケーション
## 技術スタック
- Node.js 20
- TypeScript 5
- Express 4
## 開発サーバの起動
npm run dev
## テストの実行
npm test
詳細な例
包括的なAGENTS.mdファイルの例を以下に示す。
# Backend API Service
このプロジェクトは、マイクロサービスアーキテクチャを採用したREST APIサービスです。
## 技術スタック
- 言語: TypeScript 5.0
- ランタイム: Node.js 20
- フレームワーク: Fastify 4
- データベース: PostgreSQL 15 + Prisma ORM
- キャッシュ: Redis 7
- テスト: Vitest
## ディレクトリ構造
```
src/
├── routes/ # APIルート定義
├── services/ # ビジネスロジック
├── repositories/ # データアクセス層
├── models/ # Prismaモデル
└── utils/ # ユーティリティ関数
```
## コーディング規約
- 変数・関数名: camelCase
- クラス・型名: PascalCase
- 定数: UPPER_SNAKE_CASE
- インデント: 半角スペース2つ
- セミコロン: 必須
## 頻繁に使用するコマンド
```bash
# 開発サーバの起動
npm run dev
# テストの実行
npm test
# データベースマイグレーション
npx prisma migrate dev
# ビルド
npm run build
```
## 注意事項
- APIキーは.envファイルで管理すること
- any型の使用を避けること
- 全てのAPIエンドポイントにバリデーションを実装すること
高度な機能
opencode.jsonのinstructionsによる複数ファイル参照
opencode.json の instructions フィールドを使用することにより、複数のMarkdownファイルをAGENTS.mdに加えてロードできる。
instructions フィールドの基本形式を以下に示す。
{
"instructions": [
"CONTRIBUTING.md",
"docs/guidelines.md",
".opencode/rules/security.md"
]
}
instructions フィールドを使用することにより、以下に示すメリットが得られる。
- ファイルの分割管理
- AGENTS.mdをコンパクトに保ち、詳細は別ファイルで管理できる。
- チーム間での責任分担
- 各ドキュメントを担当者ごとに分割して管理できる。
- 既存ドキュメントの活用
- CONTRIBUTING.md や README等の既存ドキュメントをそのまま参照できる。
GLOBパターンによる参照
instructions フィールドでは、GLOBパターンを使用して複数のファイルを一括指定することができる。
GLOBパターンの使用例を以下に示す。
{
"instructions": [
"AGENTS.md",
"docs/**/*.md",
".opencode/rules/*.md"
]
}
対応しているグロブパターンの例を以下に示す。
- docs/**/*.md
- docsディレクトリ以下の全てのMarkdownファイル
- .opencode/rules/*.md
- .opencode/rulesディレクトリ直下のMarkdownファイル
- **/*.md
- プロジェクト全体の全てのMarkdownファイル
リモートURLの参照
instructions フィールドでは、HTTPSのURLを指定してリモートファイルを参照することができる。
組織共通のルールセットをリモートリポジトリで一元管理し、複数のプロジェクトから参照する場合に有用である。
リモートURLの使用例を以下に示す。
{
"instructions": [
"AGENTS.md",
"https://raw.githubusercontent.com/my-org/shared-rules/main/style.md",
"https://raw.githubusercontent.com/my-org/shared-rules/main/security.md"
]
}
リモートURLを使用する時の注意事項を以下に示す。
- HTTPSのURLのみ対応している
- リモートファイルの取得には5秒のタイムアウトが設定されている
- 信頼できるURLのみを指定する
- 悪意のあるコンテンツがシステムプロンプトに混入するリスクがある
- ネットワーク接続が必要である
- オフライン環境ではリモートファイルの読み込みに失敗する可能性がある
推奨される方法
簡潔性を保つ
AGENTS.mdファイルは、必要な情報のみを記述して簡潔に保つことを推奨する。
ファイルサイズの目安を以下に示す。
- 最小構成: 60行程度
- プロジェクト概要、技術スタック、よく使うコマンドのみ
- 標準構成: 150行程度
- 概要、技術スタック、ディレクトリ構造、コーディング規約、よく使うコマンド
- 詳細構成: 300行程度
- 概要、技術スタック、ディレクトリ構造、コーディング規約、よく使うコマンド、アーキテクチャパターン、注意事項
300行を超える場合は、opencode.json の instructions フィールドを使用してファイルを分割することを推奨する。
具体性を重視する
抽象的な説明ではなく、具体的な指示を記述する。
| 抽象的な表現 | 具体的な表現 |
|---|---|
| コードは読みやすく書くこと | 関数は50行以内に抑え、変数名はcamelCaseを使用すること |
| テストを書くこと | 全ての新機能にはVitestでユニットテストを追加し、カバレッジ80%以上を維持すること |
| セキュリティに注意すること | APIキーは.envファイルに記載し、ユーザ入力は必ずバリデーションを実施すること |
定期的な更新
AGENTS.mdファイルは、プロジェクトの進行に合わせて定期的に更新する。
更新のタイミングの例を以下に示す。
- 新しい技術スタックを導入した時
- コーディング規約を変更した時
- 新しいディレクトリを追加した時
- 新しいワークフローを導入した時
月に1回程度、AGENTS.mdファイルを見直すことを推奨する。
バージョン管理に含める
プロジェクトレベルのAGENTS.mdファイルは、バージョン管理システムに含めることを推奨する。
これにより、チーム全体でプロジェクトのルールとパターンを共有できる。
バージョン管理に含めるファイルの例を以下に示す。
- ./AGENTS.md
- プロジェクトルートのAGENTS.md
- .opencode/AGENTS.md
- .opencodeディレクトリ内のAGENTS.md
機密情報はAGENTS.mdに記載せず、環境変数や別途管理する設定ファイルで管理する。
トラブルシューティング
AGENTS.mdが読み込まれない場合
ファイルの配置場所を確認
AGENTS.mdファイルが正しい場所に配置されているか確認する。
OpenCodeのトラバース探索は、カレントディレクトリから上位ディレクトリへと実行される。
プロジェクトのルートディレクトリにAGENTS.mdが配置されているか確認する。
# ファイルの存在確認 ls -la AGENTS.md ls -la .opencode/AGENTS.md
ファイルの権限を確認
AGENTS.mdファイルが読み取り可能であるか確認する。
# 権限の確認 ls -l AGENTS.md
読み取り権限がない場合は、権限を変更する。
# 読み取り権限の付与 chmod u+r AGENTS.md
OpenCodeセッションを再起動
AGENTS.mdファイルを作成または変更した後、OpenCodeセッションを再起動する。
セッション開始時に、AGENTS.mdの内容が自動的に読み込まれる。
# OpenCodeセッションの終了 /exit
# OpenCodeセッションの再起動 opencode
CLAUDE.mdとAGENTS.mdの競合
同じディレクトリにCLAUDE.mdとAGENTS.mdの両方が存在する場合、AGENTS.mdが優先される。
移行期間中に両方のファイルが存在する場合は、以下に示す点を確認する。
- どちらのファイルが優先されているか
- OpenCodeはAGENTS.mdを優先して読み込む。
- 両方のファイルに矛盾するルールがないか
- 矛盾がある場合は、AGENTS.mdの内容が適用される。
- 統合が完了したらCLAUDE.mdを削除
- 移行後はCLAUDE.mdを削除してAGENTS.mdに一本化することを推奨する。
リモートURLの読み込みに失敗する場合
instructions フィールドで指定したリモートURLの読み込みに失敗する場合は、以下を確認する。
- ネットワーク接続を確認する
- URLが正しいか確認する
- HTTPSのURLであることを確認する (HTTPは非対応)
- タイムアウト (5秒) が発生していないか確認する
- 応答が遅いサーバの場合は、ローカルファイルへのミラーリングを検討する
関連機能
opencode.jsonとの関係
opencode.json は、AGENTS.mdとは別に、OpenCodeの動作設定を管理する設定ファイルである。
opencode.json の配置場所を以下に示す。
- グローバル設定
- ~/.config/opencode/opencode.json
- プロジェクト設定
- ./opencode.json
下表に、opencode.json と AGENTS.mdの使い分けを示す。
| ファイル | 用途 | 記述内容 |
|---|---|---|
| opencode.json | OpenCodeの動作設定 | モデル、プロバイダ、LSP設定、instructions参照等 |
| AGENTS.md | プロジェクトの知識とルール | コーディング規約、技術スタック、アーキテクチャ等 |
opencode.json の例を以下に示す。
{
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5",
"instructions": [
"AGENTS.md",
"docs/guidelines.md"
]
}
.opencodeディレクトリとの関係
.opencode/ ディレクトリは、プロジェクト固有のOpenCode設定を格納するディレクトリである。
AGENTS.mdはこのディレクトリ内に配置することもできる。
.opencode/ ディレクトリ内には、AGENTS.md以外にも以下に示すファイルを配置できる。
| ファイル | 説明 |
|---|---|
| agents/ディレクトリ | カスタムエージェントの定義ファイル |
| commands/ディレクトリ | カスタムコマンドの定義ファイル |
| skills/ディレクトリ | カスタムスキルの定義ファイル |
| tools/ディレクトリ | カスタムツールの定義ファイル |
参考リンク
