本文へスキップ

Codex CLIユーザー向け

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

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

無料で始めるCodexのセットアップを読む

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

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

レイヤー構造

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

// 合意事項

AGENTS.md

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

// 伝送路

MCP

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

// コードベース

Maguyva

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

// 支払うのは誰か

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

エージェントはシート料金を払いません。料金を見る

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

永続的な指示は、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が、ツールやコンテキストにどう手を伸ばすか。(仕様)
  • Maguyva Codexがコードベースに質問したときに何を見るか。Semantic、AST、グラフ、テキスト検索の結果が、ファイルパスと行番号付きで返ってきます。

AGENTS.mdは、Codexにどう作業するかを教える。

Maguyvaは、Codexに作業の拠り所を与える。

3つのワークフロー

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

// workflow 01

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

codex> PaymentClient → BillingClientにリネーム

graph::callers(PaymentClient)            12 references across 7 packages
graph::importers(src/payments/client.ts)  9 importers
graph::extends(PaymentClient)             2 subclasses (RetryClient, MockClient)

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

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

// workflow 02

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

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

semantic::query("normalize phone E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← real impl
  test/util/phone.spec.ts:14  jest.mock(...)      ← stub
[exit 0]

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

// workflow 03

リファクタリングの前に、ブラストラディウスを確認する

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

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

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

Codex CLIでのセットアップ

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

  1. // step 01

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

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

  2. // step 02

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

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

# equivalent ~/.codex/config.toml
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"

  3. // step 03

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

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

セルフサーブ登録受付中。

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

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

最初のリポジトリをインデックスする互換性ドキュメントを見る

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