# AGENTS.mdはOpenCodeにルールを教える。Maguyvaはコードを見せる。

Canonical source: https://maguyva.ai/ja/for-opencode

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

OpenCodeは作業の仕方をAGENTS.mdから読み、それ以外はすべてMCPサーバーを呼び出します。MaguyvaはリモートMCPサーバーとして、ファイルパスと行番号付きで照会できるリポジトリの地図をOpenCodeに与えます。

> mcpの下にリモートのエントリを1つ。ローカルでは何も動きません。

## OpenCodeについて知っておくこと

OpenCode特有の4つの事実。

### opencode.json

プロジェクトの`opencode.json`の`mcp`の下にサーバーを追加します。すべてのプロジェクトで使うなら`~/.config/opencode/opencode.json`に追加します。

### type: remote

OpenCodeはMaguyvaのエンドポイントにHTTPで接続します。ローカルでは何も動かず、Node.jsも不要です。

### 環境変数の参照

OpenCodeは設定内の環境変数を展開するので、ヘッダーは`Bearer {env:MAGUYVA_API_KEY}`となり、キーはコミットするファイルに入りません。

### エージェントごとに範囲を絞る

MCPサーバーを追加するたびに、ツール定義がコンテキストに加わります。OpenCodeでは`"maguyva*": false`のようなglobでサーバーのツールを全体でオフにし、必要なエージェントだけでオンに戻せます。

## AGENTS.mdは作業上の取り決めです。使いましょう。

```text
> /init
# リポジトリをスキャンしてAGENTS.mdを書く
```

OpenCodeはプロジェクトルートの`AGENTS.md`と、個人ルール用の`~/.config/opencode/AGENTS.md`を読みます。`AGENTS.md`がなければ`CLAUDE.md`にフォールバックします。用途は次のとおり:

- ビルド、テスト、lintのコマンド。
- エージェントが守るべき規約と境界。
- 重要なドキュメントへのポインタ。

`/init`時点のスキャンは要約であって、インデックスではありません。昨日追加された関数を誰が呼んでいるかは、OpenCodeに教えてくれません。

## AGENTS.mdの限界

OpenCodeがgrepと忍耐で埋めている3つの穴。

### // 要約はインデックスではない

AGENTS.mdは重要なパッケージの名前を挙げられます。すべてのシンボルと呼び出し箇所を列挙することはできませんし、そうすべきでもありません。

### // grepは呼び出し元ではなく文字列を見つける

テキストの一致では、本当の呼び出しと、コメントやモックや別クラスの同名メソッドとを区別できません。

### // ファイルはずれていく

AGENTS.mdは書かれた日には正しい。コードは動き続け、ファイルが更新されるのは誰かが思い出したときだけです。

## OpenCodeのリモートMCPサーバーとしてのMaguyva

mcpの下のエントリ1つで、OpenCodeが得られるもの:

- **インデックス済みリポジトリに対する11個のツール**: セマンティック、構造（AST）、グラフ、テキスト検索に加え、シンボル検索、依存元、ファイル取得。
- **ファイルパスと行番号付きの回答**: 285以上の言語に対応。
- **どのモデルにも同じ答え**: OpenCodeは多くのモデルプロバイダーで動きます。どのモデルが尋ねても、Maguyvaは同じ地図を返します。

> AGENTS.mdは、OpenCodeに*作業の仕方*を教える。
> Maguyvaは、OpenCodeに*作業の拠り所*を与える。

## 2つのワークフロー

同じターミナルから地図に聞く。

### 01. パッケージをまたいで共有の型をリネームする

```text
opencode> OrderStatusをFulfillmentStatusにリネームして

dependency_search("OrderStatus", dependents)
  8パッケージにまたがる23件の参照
structural_search(switch_statement, "OrderStatus")
  網羅的なswitchが4つ

→ OpenCodeはswitchも含めてリスト全体を編集します。
[exit 0]
```

網羅的なswitchこそ、テキスト検索が見逃し、コンパイラが遅れて捕まえる箇所です。

### 02. コードとドキュメントを見分ける

```text
opencode> FEATURE_BULK_EXPORTはどこで読まれている?

text_pattern_search("FEATURE_BULK_EXPORT")
  src/config/flags.ts:17
  src/export/bulk.ts:5
  docs/flags.md:40   ← ドキュメントのみ

→ コードパスが2つ、古いドキュメントが1つ。
[exit 0]
```

完全一致がパス付きで返ってくるので、OpenCodeはどちらかを編集する前にコードとドキュメントを見分けられます。

## OpenCodeでのセットアップ

3ステップ。Freeプラン:リポジトリ3個, インデックス済みリポジトリ行数、最大5万行、カード不要。

### 01. maguyva.aiでリポジトリをインデックス化

回答を評価できるよう、すでによく知っているリポジトリを選びましょう。

### 02. opencode.jsonのmcpの下にMaguyvaを追加

`opencode.json`

```json
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. キーをexportして接続を確認する

OpenCodeを起動するシェルで`MAGUYVA_API_KEY`を設定します。`opencode mcp list`で設定済みのサーバーが一覧できます。その後、答えをすでに知っている質問を1つしてみましょう。

OpenCodeの[MCPドキュメント](https://opencode.ai/docs/mcp-servers/)に、タイムアウト、OAuth、エージェントごとのツールアクセスの説明があります。

## すでに知っているリポジトリを1つインデックス化。

MCP経由でOpenCodeを接続し、確認できる質問を1つしてみましょう。