OpenCode × AGENTS.md 完全ガイド 2026 — オープンソースAIターミナルエージェントのセットアップ

OpenCodeはGitHub Stars 160,000超えのオープンソースAIコーディングエージェントだ。そのAGENTS.mdサポートには、Claude Codeからの移行者がもっとも驚く事実がある――すでに持っているファイルが、無修正でそのまま動く。

この互換性は意図的な設計だが、細部が重要になる。OpenCodeのディスカバリー順序、opencode.jsonのinstructionsフィールド、そして/initによる自動生成コマンドは、AGENTS.md単体よりも広い設定の余地を提供する。このガイドでは、ファイルの最初の配置からglobパターンの上級設定、BuildモードとPlanモードの違いまで、すべてを解説する。

OpenCodeとはなにか、なぜAGENTS.mdが重要なのか

OpenCodeはターミナルベースのオープンソースAIコーディングエージェントだ。単一モデルに縛られる閉鎖的なツールと異なり、一つのインストールで複数のLLMバックエンドをサポートする――Claude（Anthropic API）、GPT-4（OpenAI）、Gemini（Google）、そしてOllamaや互換エンドポイント経由のローカルモデル。

160K+のスター数はその訴求力を反映している。Claudeレベルの出力品質を求めながら、プロバイダーを切り替えられる柔軟性やプライバシーのためにローカルモデルで実行したい開発者が、OpenCodeを主要ツールとして採用している。

AGENTS.mdが重要な理由は二つある。

クロスツール互換性。 リポジトリにすでにAGENTS.md（またはCLAUDE.md）があれば、OpenCodeは追加設定なしで読み込む。Claude CodeとOpenCodeを混用するチームは、単一の指示ファイルを共有できる。

バックエンド非依存のルール。 OpenCodeが複数のLLMにルーティングするため、AGENTS.mdはバックエンドをまたいだ安定したコントラクトになる。Claudeセッション向けに書いたルールは、同じプロジェクトでGPT-4に切り替えた場合にも適用される。

OpenCodeのAGENTS.md読み込み順序

OpenCodeは指示ファイルを読み込む際、定義された優先順位チェーンに従う。

1. プロジェクトルートのAGENTS.md

OpenCodeはまずGitリポジトリルートのAGENTS.mdを探す。これがプライマリなプロジェクトレベル設定だ。AGENTS.mdが一つだけなら、ここに置く。

2. ~/.config/opencode/AGENTS.md（グローバル）

すべてのプロジェクトに適用される個人的な設定――好みのコードスタイル、コミットメッセージフォーマット、使いたくないツール――には、~/.config/opencode/AGENTS.mdにグローバルAGENTS.mdを作成する。OpenCodeはこれをプロジェクトレベルのファイルとマージし、競合する場合はプロジェクトレベルのルールが優先される。

3. CLAUDE.mdへのフォールバック

プロジェクトルートにAGENTS.mdが見つからない場合、OpenCodeはCLAUDE.mdにフォールバックする。このフォールバックはClaude Code移行者向けに明示的に設計されている――既存のCLAUDE.mdはファイル名を変更せずにOpenCodeで動作する。両方のファイルが存在する場合、AGENTS.mdが優先される。

opencode.json: instructionsフィールドによるディスカバリーの拡張

プロジェクトルートのopencode.json設定ファイルは、どの指示ファイルを読み込むかを制御する。instructionsフィールドはパスとglobパターンの配列を受け付ける。

{
  "instructions": [
    "AGENTS.md",
    "packages/*/AGENTS.md",
    "docs/agent-rules.md"
  ]
}

各エントリには以下が使える。

• 直接ファイルパス（"AGENTS.md"、"docs/rules.md"）
• globパターン（"packages/*/AGENTS.md"はpackages/の直接サブディレクトリそれぞれからAGENTS.mdを読み込む）
• リモートURL（"https://your-org.example.com/shared-rules.md"――セッション開始時にフェッチされる）

instructionsフィールドが存在する場合、OpenCodeはマッチしたすべてのファイルを読み込み、順番に連結する。プロジェクトルートのAGENTS.mdとグローバルの~/.config/opencode/AGENTS.mdは引き続き読み込まれる。opencode.jsonはスタックに追加するのであって、置き換えではない。

/initによるAGENTS.mdの自動生成

OpenCodeの/initコマンドは現在のリポジトリをスキャンし、プロジェクトに適したAGENTS.mdを生成する。スキャン対象は以下の通りだ。

• パッケージマネージャーファイル（package.json、pyproject.toml、Cargo.toml、go.mod）
• 既存のテストランナー設定（jest.config.*、pytest.ini、.mocharc.*）
• リンター・フォーマッター設定（.eslintrc、biome.json、.prettierrc）
• CIファイル（.github/workflows/、.gitlab-ci.yml）
• 既存のCLAUDE.mdまたはAGENTS.md（コンテンツ移行用）

生成されるファイルには、検出されたビルド・テスト・リント・型チェックコマンドを含むCommandsセクションが含まれる――これがエージェントの動作に最も大きな影響を与えるセクションだ。

/init実行後、動作するベースラインが得られる。カスタマイズは簡単だ――生成されたファイルを開き、プロジェクト固有のセクション（アーキテクチャメモ、変更禁止ファイル、命名規則）を追加する。自動生成されたコンテンツがスキャフォールディングを提供し、手動追記が具体性を与える。

生成されたAGENTS.mdはすぐにコミットする。バージョン管理に属するファイルだ。チームメンバーやCI環境が恩恵を受け、プロジェクトの実際のツールチェーンとのズレを防ぐ。

OpenCodeで効果的なAGENTS.mdセクション

すべてのAGENTS.mdセクションがOpenCodeで同等に効果を発揮するわけではない。サポートするバックエンド全体での観測された動作を踏まえると、以下の通りだ。

Commandsセクション（最高の信頼性）

Commandsセクションは、OpenCodeがサポートするすべてのバックエンドで確実に処理される。正確なターミナルコマンドは曖昧さが低く、モデルは指定されたものを実行する。

## Commands

Build: `npm run build`
Test: `npm test`
Test（単一ファイル）: `npm test -- path/to/file.test.ts`
Lint: `npm run lint`
型チェック: `npx tsc --noEmit`
Format: `npm run format`

単一ファイルのテストコマンドを必ず含めること。変更のたびにテストスイート全体を実行するエージェントは遅い。単一ファイルの実行方法を指定することで、エージェントが対象を絞ったテストを実行するようになる。

コードスタイルルール

具体的なスタイルルールは効果的だが、曖昧な好みは効果がない。

## Code Style

- TypeScript strict mode。`any`禁止。
- named exportのみ。default export禁止。
- 非同期関数: async/awaitを使う。`.then()`チェーン禁止。
- エラーメッセージ: 小文字、末尾ピリオドなし。
- 変数名: 説明的な名詞。ループカウンター以外の1文字変数禁止。

「クリーンなコードを書く」や「ベストプラクティスに従う」といったルールでは動作の変化は測定できない。「default export禁止」のようなルールは守られる。

各セクションの効果テンプレート（Node.js/TypeScript）

# AGENTS.md

## Commands

Build: `npm run build`
Test: `npm test`
Test（単一ファイル）: `npx jest path/to/file.test.ts`
Lint: `npm run lint`
型チェック: `npx tsc --noEmit`
Format: `npx prettier --write .`

## Code Style

- TypeScript strict modeを使う。
- `any`型禁止。`unknown`を使って型を絞る。
- named exportのみ。
- オブジェクト形状にはtype aliasよりinterfaceを使う。
- デフォルトは`const`。再代入が必要な場合のみ`let`。

## Architecture

- `src/` — アプリケーションソース
- `src/api/` — HTTPハンドラー（ビジネスロジックなし）
- `src/services/` — ビジネスロジック層
- `src/db/` — データベースアクセス（このディレクトリ外にraw SQLを書かない）
- `tests/` — src/のディレクトリ構造をミラー

## Rules

- 作業完了前に`npm test`と`npm run lint`を実行する。
- `src/db/migrations/`は変更しない。マイグレーションはappend-only。
- `.env`ファイルをコミットしない。`.env.example`をテンプレートとして使う。
- PRタイトルはConventional Commitsに従う: `feat:`、`fix:`、`chore:`など。

opencode.json: 高度な設定

AGENTS.mdに関連するopencode.jsonの完全な設定オプション。

{
  "instructions": [
    "AGENTS.md",
    "packages/*/AGENTS.md",
    "https://raw.githubusercontent.com/your-org/shared-rules/main/AGENTS.md"
  ],
  "model": "claude-opus-4",
  "temperature": 0
}

globパターンは標準glob構文を使う。packages/*/AGENTS.mdは直接サブディレクトリのみにマッチ。packages/**/AGENTS.mdはすべてのネストされたレベルにマッチする。

リモートURLはセッション開始時にフェッチされる。組織全体のルールを一元管理するのに便利だ――一つのURLで、すべての開発者が自動的に更新を受け取る。フェッチされたコンテンツはローカルのAGENTS.mdと同様に扱われる。

複数の指示ファイルの組み合わせは配列の順番でコンテンツを連結する。直接競合する場合は配列の最後のファイルが勝つため、最も具体的な（パッケージレベルの）ルールを最後に置く。

BuildモードとPlanモードとAGENTS.md

OpenCodeは主に二つのモードで動作する。

Buildモード（デフォルト）は自律実行だ。エージェントはAGENTS.mdを読み込み、ファイルを書き、ターミナルコマンドを実行し、ステップごとの確認なしにイテレーションする。このモードでは、Commandsセクションが最もインパクトの大きいAGENTS.mdの部分になる――エージェントがnpm test（または指定したコマンド）を自律的に実行して作業を検証する。

Planモードは読み取り専用のプレビューだ。エージェントはAGENTS.mdを読み込み、何をするかのステップバイステップな計画を生成するが、ファイルを書いたりコマンドを実行したりしない。

OpenCode初心者のチームには、複雑なタスクでまずPlanモードを実行し、Buildモードに切り替える前にエージェントのAGENTS.md解釈を確認することを推奨する。

OpenCode vs Claude Code: AGENTS.mdサポート比較

FAQ

OpenCodeはAGENTS.mdを読み込むか？

読み込む。OpenCodeはセッション開始時にプロジェクトルートからAGENTS.mdを自動的に読み込む。追加設定は不要だ。グローバルな個人ルールには~/.config/opencode/AGENTS.mdを使う。

OpenCode用のAGENTS.mdはどこに置けばよいか？

プロジェクトレベルのファイルはGitリポジトリルート――package.jsonやCargo.tomlと同じディレクトリ――に置く。個人的なクロスプロジェクトのルールには~/.config/opencode/AGENTS.mdを使う。モノレポの場合は、パッケージごとにAGENTS.mdを追加し、opencode.jsonでglobパターンを使って参照する。

AGENTS.mdとopencode.jsonのinstructionsは何が違うか？

AGENTS.mdはエージェントが従う指示のコンテンツだ。opencode.jsonは、どの指示ファイルをどの順番で読み込むかを制御する設定レイヤーだ。ほとんどのプロジェクトはAGENTS.mdだけで十分だ。opencode.jsonのinstructionsフィールドは、モノレポで複数の指示ソースがある場合や、一元管理するリモートURLルールがある場合に有用になる。

AGENTS.mdを使ってClaude CodeからOpenCodeに移行するには？

CLAUDE.mdがあってAGENTS.mdがない場合、OpenCodeはすぐにCLAUDE.mdを使う――何もする必要がない。今後の整合性のために、CLAUDE.mdをAGENTS.mdにコピーして両方をコミットする。マルチツール用にクリーンに保つために、AGENTS.mdコピーからClaude Code固有の構文（@importシステム、MCPツール参照）を削除する。Claude Code固有の機能にはCLAUDE.mdを残しておく。

OpenCodeはCLAUDE.mdを読み込むか？

フォールバックとして読み込む。OpenCodeがプロジェクトルートにAGENTS.mdを見つけない場合、代わりにCLAUDE.mdを読み込む。両方のファイルが存在する場合、AGENTS.mdが優先される。このフォールバックは、Claude Codeチームが既存の設定をリネームせずにOpenCodeを採用できるように設計されている。

関連記事

• AGENTS.md ベストプラクティス 2026：60,000以上のリポジトリが教えてくれること
• AGENTS.md for Gemini CLI：GoogleのエージェントはどうAGENTS.mdを読むか
• 効果的なAGENTS.mdの書き方：完全ガイド
• AGENTS.md for OpenAI Codex：完全セットアップガイド

OpenCodeのLLM APIキーを安全に管理する

OpenCodeはClaude・GPT-4・Gemini・ローカルモデルなど複数バックエンドに対応している。各プロバイダーのAPIキーをAGENTS.mdやopencode.jsonに書かずに管理するには、1Password CLIのop runでランタイム注入するのが確実だ。