# AGENTS.md beritahu Codex macam mana nak bekerja. Bukan apa yang ada di sana.

Canonical source: https://maguyva.ai/ms/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 tetapkan perjanjian kerja. MCP bagi Codex capai alat. Maguyva ialah pelayan MCP yang bagi Codex peta repo anda yang boleh ditanya, supaya suntingan pertama bukan tekaan struktur fail.

> AGENTS.md perjanjiannya. MCP saluran perantaraannya. Maguyva petanya.

## Stack berlapis

Empat idea. Setiap satu buat satu kerja.

### AGENTS.md

Macam mana Codex patut berkelakuan pada repo ini.

### MCP

Macam mana Codex mencapai alat luaran dan konteks.

### Maguyva

Pelayan MCP yang pulangkan fakta repo yang terbukti.

### Ruang kerja, bukan pengguna

Tiada caj per pengguna untuk ejen. [Lihat harga](https://maguyva.ai/ms/pricing)

## AGENTS.md ialah perjanjian kerja. Gunakannya.

Arahan kekal patut berada dalam [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md). Ia tempat yang betul untuk:

- Arahan binaan, ujian, dan lint yang Codex patut jalankan.
- Sekatan “sentiasa buat X / jangan sekali buat Y” yang terhad kepada satu direktori.
- Konvensyen penamaan dan keutamaan refactor.
- Petunjuk kepada log keputusan kanonik dan nota seni bina.

Kekalkan ia ringkas. Skopkan ia. Commit ia.

Tapi `AGENTS.md` tak pernah direka untuk jadi indeks yang boleh ditanya untuk setiap simbol, fail, dan tapak panggilan dalam repo anda.

## Di mana AGENTS.md sahaja tidak lagi mencukupi pada skala besar

Empat mod kegagalan, satu setiap kad.

### // perjanjian bukan indeks

Beritahu Codex *macam mana nak bekerja* tak beritahu ia *apa yang wujud*. Suntingan pertama pada pakej yang tak biasa adalah tekaan tentang laluan fail dan nama fungsi. AGENTS.md tak boleh senaraikan setiap simbol, dan anda pun tak nak ia begitu.

### // dokumen menyimpang daripada kod

Blok AGENTS.md yang terangkan topologi queue anda betul sehingga seseorang perkenalkan consumer baharu. Kod kini sumber kebenaran dan dokumen itu basi dengan yakin. Codex baca yang salah.

### // tukar nama ialah masalah graf

“Apa yang rujuk class ini?” tak boleh dijawab daripada fail markdown. Codex sama ada grep-and-berharap merentasi monorepo atau minta anda tampal tapak panggilan ke dalam chat.

### // tetingkap konteks bukan percuma

Menyumbat AGENTS.md sehingga Codex “cukup tahu” makan token yang patut dibayar untuk penaakulan. Lepas beberapa KB anda tukar kualiti jawapan dengan jumlah konteks statik.

## Macam mana tiga lapisan ini bercantum

Pengguna Codex dah pun berfikir dalam bentuk ini. Halaman ini patut jelaskannya.

- **AGENTS.md**: perjanjian (macam mana Codex berkelakuan)
- **MCP**: saluran (macam mana ia mencapai alat)
- **Maguyva**: fakta pangkalan kod (apa yang ia nampak)

- **AGENTS.md**: macam mana Codex berkelakuan pada repo ini.
- **MCP**: macam mana Codex mencapai alat dan konteks. [(spesifikasi)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: apa yang Codex nampak bila ia tanya pangkalan kod satu soalan. Carian semantik, AST, graf, dan teks dipulangkan dengan laluan fail dan nombor baris.

> AGENTS.md beritahu Codex *macam mana nak bekerja*.
> Maguyva bagi Codex *sesuatu untuk dijadikan asas kerja*.

## Tiga aliran kerja

Khusus Codex. Terbukti berdasarkan graf panggilan sebenar, bukan grep Codex.

### 01. Tukar nama class yang dikongsi, cari setiap dependen dahulu

```text
codex> tukar nama PaymentClient → BillingClient

graph::callers(PaymentClient)            12 rujukan merentasi 7 pakej
graph::importers(src/payments/client.ts)  9 pengimport
graph::extends(PaymentClient)             2 subkelas (RetryClient, MockClient)

→ Codex cadangkan migrasi 21-suntingan dengan senarai fail terus.
[exit 0]
```

Codex tanya Maguyva untuk dependen *sebelum* ia mula menyunting. Senarai migrasi berdasarkan graf sebenar, bukan ingatan Codex.

### 02. Cari implementasi sebenar, bukan stub ujian

```text
codex> macam mana normalizePhoneNumber uruskan E.164?

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

Nama boleh menipu. Mock membayangi kod sebenar. Maguyva susun implementasi sebenar di atas mock ujian.

### 03. Semak lingkungan impak sebelum refactor

```text
codex> apa yang panggil QueueDispatcher.publish?

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

Tapak panggilan merentas pakej tertonjol terus. Diff itu berasaskan pengimport sebenar, bukan grep Codex.

## Sediakan Codex CLI

Tiga langkah. Peringkat Free: 3 repositori, Sehingga 50K baris repo terindeks, tanpa kad.

### 01. Indeks repo di maguyva.ai

Pilih satu yang anda kenal betul-betul, supaya anda boleh sahkan jawapannya.

### 02. Tambah Maguyva sebagai pelayan MCP dalam config Codex anda

`~/.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. Tanya satu soalan yang anda dah tahu jawapannya

Jangan mula dengan seluruh syarikat anda. Mula dengan satu repo dan satu soalan yang boleh disahkan.

## Indeks satu repo yang anda dah kenal.

Sambung Codex melalui MCP. Tanya satu soalan yang anda boleh sahkan jawapannya.