# AGENTS.md kertoo Codexille, miten työskennellä. Ei sitä, mitä siellä on.

Canonical source: https://maguyva.ai/fi/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 määrittää yhteiset työtavat. MCP antaa Codexille pääsyn työkaluihin. Maguyva on MCP-palvelin, joka antaa Codexille kysyttävän kartan reposta, joten ensimmäinen muokkaus ei ole arvaus tiedostorakenteesta.

> AGENTS.md on sopimus. MCP on kanava. Maguyva on kartta.

## Kerroksittainen pino

Neljä ideaa. Jokainen hoitaa yhden tehtävän.

### AGENTS.md

Miten Codexin tulisi käyttäytyä tässä repossa.

### MCP

Miten Codex tavoittaa ulkoiset työkalut ja kontekstin.

### Maguyva

MCP-palvelin, joka palauttaa ankkuroituja repofaktoja.

### Työtiloja, ei käyttäjäpaikkoja

Agenteista ei veloiteta käyttäjäpaikkamaksuja. [Katso hinnoittelu](https://maguyva.ai/fi/pricing)

## AGENTS.md on sopimus työtavoista. Käytä sitä.

Pysyvät ohjeet kuuluvat tiedostoon [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md). Se on oikea paikka:

- Build-, testi- ja lint-komennoille, jotka Codexin tulisi ajaa.
- “Tee aina X / älä koskaan tee Y” -kaiteille, jotka on rajattu hakemistoon.
- Nimeämiskonventioille ja refaktorointimieltymyksille.
- Viittauksille kanonisiin päätöslokeihin ja arkkitehtuurimuistiinpanoihin.

Pidä se tiiviinä. Rajaa se. Committaa se.

Mutta `AGENTS.md`-tiedostoa ei ole koskaan suunniteltu kysyttäväksi indeksiksi jokaisesta symbolista, tiedostosta ja kutsupaikasta repossasi.

## Missä pelkkä AGENTS.md jää staattiseksi laajassa koodikannassa

Neljä vikaantumistapaa, yksi per kortti.

### // sopimukset eivät ole indeksi

Kertominen Codexille *miten työskennellä* ei kerro sille, *mitä on olemassa*. Ensimmäinen muokkaus tuntemattomassa paketissa on arvaus tiedostopoluista ja funktioiden nimistä. AGENTS.md ei voi listata jokaista symbolia, eikä sen pitäisikään.

### // dokumentti ei enää vastaa koodia

AGENTS.md-lohko, joka kuvaa jonorakennettasi, on oikein, kunnes joku ottaa käyttöön uuden kuluttajan. Koodi on nyt totuuden lähde ja dokumentti on itsevarmasti vanhentunut. Codex lukee väärän.

### // nimeäminen on graafiongelma

“Mikä viittaa tähän luokkaan?” ei ole vastattavissa markdown-tiedostosta. Codex joko grep-ja-rukoilee koko monorepon läpi tai pyytää sinua liittämään kutsupaikat chattiin.

### // konteksti-ikkunat eivät ole ilmaisia

AGENTS.md:n täyttäminen kunnes Codex “tietää tarpeeksi” syö tokeneita, joiden pitäisi maksaa päättelystä. Muutaman kilotavun jälkeen vaihdat vastausten laadun staattiseen kontekstimäärään.

## Miten kolme kerrosta sopivat yhteen

Codex-käyttäjät ajattelevat jo tässä muodossa. Sivun pitäisi tehdä siitä ilmeinen.

- **AGENTS.md**: sopimukset (miten Codex käyttäytyy)
- **MCP**: kanava (miten se tavoittaa)
- **Maguyva**: koodikannan faktat (mitä se näkee)

- **AGENTS.md**: miten Codex käyttäytyy tässä repossa.
- **MCP**: miten Codex tavoittaa työkalut ja kontekstin. [(spesifikaatio)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: mitä Codex näkee, kun se kysyy koodikannalta kysymyksen. Semanttinen, AST-, graafi- ja tekstihaku palautettuna tiedostopolkujen ja rivinumeroiden kera.

> AGENTS.md kertoo Codexille *miten työskennellä*.
> Maguyva antaa Codexille *jotain, mistä lähteä liikkeelle*.

## Kolme työnkulkua

Codex-kohtainen. Ankkuroitu oikeaan kutsugraafiin, ei Codexin grepiin.

### 01. Nimeä jaettu luokka uudelleen, löydä ensin jokainen riippuvainen komponentti

```text
codex> nimeä uudelleen PaymentClient → BillingClient

graph::callers(PaymentClient)            12 viittausta 7 paketissa
graph::importers(src/payments/client.ts)  9 tuovaa kohdetta
graph::extends(PaymentClient)             2 aliluokkaa (RetryClient, MockClient)

→ Codex ehdottaa 21 muokkauksen migraatiota, jonka tiedostoluettelo näkyy suoraan vastauksessa.
[exit 0]
```

Codex kysyy Maguyva-palvelulta riippuvaisista komponenteista *ennen* muokkaamista. Migraatioluettelo perustuu todelliseen graafiin, ei Codexin muistiin.

### 02. Löydä oikea toteutus, ei testitynkää

```text
codex> miten normalizePhoneNumber käsittelee E.164-muodon?

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

Nimet valehtelevat. Mockit peittävät oikean koodin. Maguyva järjestää oikean toteutuksen testimockin yläpuolelle.

### 03. Tarkista vaikutusalue ennen refaktorointia

```text
codex> mikä kutsuu QueueDispatcher.publish-metodia?

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

Pakettirajat ylittävät kutsupaikat tulevat esiin suoraan. Diffi on ankkuroitu oikeisiin tuojiin, ei Codexin grepiin.

## Asennus Codex CLI:ssä

Kolme vaihetta. Free-taso: 3 repositoriota, Enintään 50 000 indeksoitua repo-riviä, ei luottokorttia.

### 01. Indeksoi repo osoitteessa maguyva.ai

Valitse sellainen, jonka tunnet hyvin, jotta voit tarkistaa vastaukset.

### 02. Lisää Maguyva MCP-palvelimeksi Codex-konfiguraatioosi

`~/.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. Kysy yksi kysymys, jonka vastauksen jo tiedät

Älä aloita koko yrityksestäsi. Aloita yhdestä reposta ja yhdestä todennettavasta kysymyksestä.

## Indeksoi yksi repo, jonka jo tunnet.

Yhdistä Codex MCP:n yli. Kysy yksi kysymys, jonka vastauksen voit tarkistaa.