# AGENTS.mdは、Codexにどう作業すべきかを教える。何があるかは教えない。

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

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).

AGENTS.mdは、作業上の合意事項を定めます。MCPは、Codexがツールに手を伸ばせるようにします。Maguyvaは、あなたのリポジトリの問い合わせ可能な地図をCodexに与えるMCPサーバーです。だから、最初の編集がファイル構造の当てずっぽうにならずに済みます。

> AGENTS.mdは合意事項。MCPはチャネル。Maguyvaは地図。

## レイヤー構造

4つの考え方。それぞれがひとつの役割を果たします。

### AGENTS.md

このリポジトリで、Codexがどう振る舞うべきか。

### MCP

Codexが、外部ツールやコンテキストにどう手を伸ばすか。

### Maguyva

根拠のあるリポジトリの事実を返す、MCPサーバー。

### 課金対象はワークスペース、シートではありません

エージェントはシート料金を払いません。[料金を見る](https://maguyva.ai/ja/pricing)

## AGENTS.mdは作業上の合意事項です。使いましょう。

永続的な指示は、[`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md)に置くべきものです。以下のことを書くのに適した場所です:

- Codexが実行すべき、ビルド、テスト、lintコマンド。
- ディレクトリ単位でスコープされた「常にXをする / 決してYをしない」というガードレール。
- 命名規則とリファクタリングの好み。
- 正式な意思決定ログやアーキテクチャノートへのポインタ。

簡潔にまとめてください。スコープを絞ってください。コミットしてください。

しかし、`AGENTS.md`は、リポジトリ内のすべてのシンボル、ファイル、呼び出し箇所を問い合わせ可能にするインデックスとして設計されたことは一度もありません。

## AGENTS.mdだけでは、規模が大きくなると静的になる場所

4つの失敗モード、カードひとつにつきひとつ。

### // 合意事項はインデックスではない

Codexに*どう作業するか*を教えても、*何が存在するか*は教えられません。見慣れないパッケージでの最初の編集は、ファイルパスや関数名についての当てずっぽうになります。AGENTS.mdは、すべてのシンボルを列挙することはできませんし、そうすべきでもありません。

### // ドキュメントはコードから乖離する

キューのトポロジーを説明するAGENTS.mdの記述は、誰かが新しいコンシューマーを導入するまでは正しい。今や信頼できる情報源はコードであり、ドキュメントは自信満々に古くなっています。Codexは、間違った方を読んでしまいます。

### // リネームはグラフの問題

「このクラスを参照しているのは何か?」は、マークダウンファイルからは答えられません。Codexは、モノレポ全体をgrepして祈るか、呼び出し箇所をチャットに貼り付けるようあなたに頼むしかありません。

### // コンテキストウィンドウはタダではない

Codexが「十分に知っている」と思えるまでAGENTS.mdを詰め込むと、推論に使うべきトークンを消費してしまいます。数KBを超えると、回答の質を静的なコンテキストの量と引き換えにすることになります。

## 3つのレイヤーがどう組み合わさるか

Codexユーザーは、すでにこの形で考えています。このページは、それを明確にするべきです。

- **AGENTS.md**: 合意事項 (Codexがどう振る舞うか)
- **MCP**: チャネル (どう手を伸ばすか)
- **Maguyva**: コードベースの事実 (何を見るか)

- **AGENTS.md**: このリポジトリで、Codexがどう振る舞うか。
- **MCP**: Codexが、ツールやコンテキストにどう手を伸ばすか。[(仕様)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: Codexがコードベースに質問したときに何を見るか。Semantic、AST、グラフ、テキスト検索の結果が、ファイルパスと行番号付きで返ってきます。

> AGENTS.mdは、Codexに*どう作業するか*を教える。
> Maguyvaは、Codexに*作業の拠り所*を与える。

## 3つのワークフロー

Codex特有。Codexのgrepではなく、実際のコールグラフに根ざしています。

### 01. 共有クラスをリネームする前に、すべての依存元を見つける

```text
codex> PaymentClient → BillingClientにリネーム

graph::callers(PaymentClient)            7つのパッケージにまたがる12件の参照
graph::importers(src/payments/client.ts)  インポートしている箇所9件
graph::extends(PaymentClient)             サブクラス2つ (RetryClient, MockClient)

→ Codexは、ファイル一覧を添えた21件の編集からなる移行を提案します。
[exit 0]
```

Codexは、編集を始める*前に*、Maguyvaに依存元を尋ねます。移行リストは、Codexの記憶ではなく、実際のグラフに根ざした形で返ってきます。

### 02. テストスタブではなく、実際の実装を見つける

```text
codex> normalizePhoneNumberはE.164をどのように処理していますか?

semantic::query("normalize phone E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← 実装本体
  test/util/phone.spec.ts:14  jest.mock(...)      ← スタブ
[exit 0]
```

名前は嘘をつきます。モックは実際のコードを覆い隠します。Maguyvaは、実際の実装をテストモックより上位にランク付けします。

### 03. リファクタリングの前に、影響範囲を確認する

```text
codex> QueueDispatcher.publishを呼び出しているのは?

graph::callers(QueueDispatcher.publish)
  src/billing/* に3件    src/audit/* に1件    src/notifications/* に1件
[exit 0]
```

パッケージ横断の呼び出し箇所がインラインで表示されます。差分は、Codexのgrepではなく、実際にインポートしている箇所に根ざしています。

## Codex CLIでのセットアップ

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

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

回答を検証できるよう、よく知っているものを選びましょう。

### 02. Codexの設定にMCPサーバーとしてMaguyvaを追加

`~/.codex/config.toml`

```text
export MAGUYVA_API_KEY=mgv_xxxx
codex mcp add maguyva --url https://maguyva.tools/mcp --bearer-token-env-var MAGUYVA_API_KEY
```

```toml
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"
```

### 03. 答えをすでに知っている質問をひとつ投げてみる

会社全体から始めないでください。1つのリポジトリと、検証可能な質問1つから始めましょう。

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

MCP経由でCodexを接続。検証できる質問を1つ、試してみましょう。