# AGENTS.md říká Codexu, jak má pracovat. Ne co tam je.

Canonical source: https://maguyva.ai/cs/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 nastavuje dohodu o spolupráci. MCP umožňuje Codexu sáhnout po nástrojích. Maguyva je MCP server, který Codexu dává prohledávatelnou mapu vašeho repozitáře, takže první edit není odhad struktury souborů.

> AGENTS.md je dohoda. MCP je kanál. Maguyva je mapa.

## Vrstvená architektura

Čtyři myšlenky. Každá dělá jednu věc.

### AGENTS.md

Jak by se měl Codex chovat v tomhle repozitáři.

### MCP

Jak Codex sahá po externích nástrojích a kontextu.

### Maguyva

MCP server, který vrací podložená fakta o repozitáři.

### Za pracovní prostor, ne za uživatele

Za agenty se neúčtují samostatné licenční poplatky. [Zobrazit ceník](https://maguyva.ai/cs/pricing)

## AGENTS.md je dohoda o spolupráci. Používejte ho.

Trvalé instrukce patří do [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md). Je to správné místo pro:

- Build, test a lint příkazy, které má Codex spouštět.
- Pravidla typu „vždy dělej X / nikdy nedělej Y“, omezená na konkrétní adresář.
- Konvence pojmenování a preference pro refaktoring.
- Odkazy na kanonické záznamy rozhodnutí a architektonické poznámky.

Držte to stručné. Ohraničte to. Commitněte to.

Ale `AGENTS.md` nikdy nebyl navržený jako prohledávatelný index každého symbolu, souboru a místa volání ve vašem repozitáři.

## Kde samotný AGENTS.md ve větším měřítku zůstává statický

Čtyři selhání, jedno na kartu.

### // dohody nejsou index

Říct Codexu, *jak má pracovat*, mu neřekne, *co existuje*. První edit v neznámém balíčku je odhad cest k souborům a názvů funkcí. AGENTS.md nemůže vypsat každý symbol, a ani byste to nechtěli.

### // dokumentace se odchyluje od kódu

Blok v AGENTS.md popisující topologii vaší fronty je správný, dokud někdo nepřidá nového konzumenta. Kód je teď zdrojem pravdy a dokumentace je sebejistě zastaralá. Codex čte tu špatnou.

### // přejmenování je grafový problém

„Co odkazuje na tuhle třídu?“ se nedá zjistit z markdown souboru. Codex buď grepuje napříč monorepem a doufá, nebo vás požádá, abyste vložili místa volání do chatu.

### // kontextová okna nejsou zadarmo

Přidávat obsah do AGENTS.md, dokud Codex „neví dost“, žere tokeny, které by měly platit za uvažování. Po pár KB měníte kvalitu odpovědí za statický objem kontextu.

## Jak tři vrstvy zapadají do sebe

Uživatelé Codexu už takhle přemýšlí. Stránka by to měla jen zviditelnit.

- **AGENTS.md**: dohody (jak se Codex chová)
- **MCP**: kanál (jak sahá po věcech)
- **Maguyva**: fakta o codebase (co vidí)

- **AGENTS.md**: jak se Codex chová v tomhle repozitáři.
- **MCP**: jak Codex sahá po nástrojích a kontextu. [(specifikace)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: co Codex vidí, když se codebase na něco zeptá. Sémantické, AST, grafové a textové vyhledávání s cestami k souborům a čísly řádků.

> AGENTS.md říká Codexu, *jak má pracovat*.
> Maguyva dává Codexu *něco, z čeho může vycházet*.

## Tři workflow

Specifické pro Codex. Podložené skutečným grafem volání, ne grepem Codexu.

### 01. Přejmenujte sdílenou třídu, nejdřív najděte všechny závislé

```text
codex> přejmenuj PaymentClient → BillingClient

graph::callers(PaymentClient)            12 odkazů napříč 7 balíčky
graph::importers(src/payments/client.ts)  9 importérů
graph::extends(PaymentClient)             2 podtřídy (RetryClient, MockClient)

→ Codex navrhuje migraci o 21 editech se seznamem souborů přímo v textu.
[exit 0]
```

Codex se Maguyva zeptá na závislý kód *předtím*, než začne editovat. Seznam migrace se vrátí podložený skutečným grafem, ne Codexovou vzpomínkou.

### 02. Najděte skutečnou implementaci, ne testovací stub

```text
codex> jak normalizePhoneNumber zachází s E.164?

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

Jména lžou. Mocky zastiňují skutečný kód. Maguyva řadí skutečnou implementaci nad testovací mock.

### 03. Zkontrolujte rozsah dopadu před refaktoringem

```text
codex> co volá QueueDispatcher.publish?

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

Místa volání napříč balíčky se objeví přímo v textu. Diff je podložený skutečnými importéry, ne grepem Codexu.

## Nastavení v Codex CLI

Tři kroky. Free tarif: 3 repozitáře, Až 50K zaindexovaných řádků repa, bez kreditní karty.

### 01. Indexujte repozitář na maguyva.ai

Vyberte si repozitář, který dobře znáte, abyste mohli ověřit odpovědi.

### 02. Přidejte Maguyva jako MCP server do své konfigurace Codexu

`~/.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. Položte jednu otázku, jejíž odpověď už znáte

Nezačínejte s celou firmou. Začněte jedním repozitářem a jednou ověřitelnou otázkou.

## Indexujte jeden repozitář, který už znáte.

Připojte Codex přes MCP. Položte jednu otázku, jejíž odpověď dokážete ověřit.