# AGENTS.md mówi Codex, jak pracować. Nie co tam jest.

Canonical source: https://maguyva.ai/pl/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 ustala umowę roboczą. MCP pozwala Codex sięgać po narzędzia. Maguyva to serwer MCP, który daje Codex przeszukiwalną mapę Twojego repo, więc pierwsza edycja nie jest zgadywaniem struktury plików.

> AGENTS.md to umowa. MCP to kanał. Maguyva to mapa.

## Warstwowy stos

Cztery idee. Każda pełni jedną funkcję.

### AGENTS.md

Jak Codex powinien się zachowywać w tym repo.

### MCP

Jak Codex sięga po zewnętrzne narzędzia i kontekst.

### Maguyva

Serwer MCP, który zwraca fakty potwierdzone w kodzie repo.

### Workspace'y, nie użytkownicy

Bez osobnych opłat za każdego agenta. [Zobacz cennik](https://maguyva.ai/pl/pricing)

## AGENTS.md to umowa robocza. Korzystaj z niej.

Trwałe instrukcje należą do [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md). To dobre miejsce na:

- Komendy budowania, testów i lintowania, które powinien uruchamiać Codex.
- Zabezpieczenia typu “zawsze rób X / nigdy nie rób Y” ograniczone do katalogu.
- Konwencje nazewnictwa i preferencje refaktoryzacji.
- Odnośniki do kanonicznych logów decyzji i notatek architektonicznych.

Trzymaj to zwięźle. Ogranicz zakres. Commituj.

Ale `AGENTS.md` nigdy nie miał być przeszukiwalnym indeksem każdego symbolu, pliku i miejsca wywołania w Twoim repo.

## Gdzie sam AGENTS.md staje się statyczny w większej skali

Cztery tryby awarii, po jednym na kartę.

### // umowy to nie indeks

Powiedzenie Codex *jak pracować* nie mówi mu, *co istnieje*. Pierwsza edycja w nieznanym pakiecie to zgadywanie ścieżek plików i nazw funkcji. AGENTS.md nie może wymienić każdego symbolu i wcale byś tego nie chciał.

### // dokument odbiega od kodu

Blok AGENTS.md opisujący topologię Twojej kolejki jest poprawny, dopóki ktoś nie wprowadzi nowego konsumenta. Kod jest teraz źródłem prawdy, a dokument jest pewny siebie i nieaktualny. Codex czyta ten zły.

### // zmiana nazwy to problem grafowy

Na pytanie „Co odwołuje się do tej klasy?” nie da się odpowiedzieć na podstawie pliku markdown. Codex albo grep-uje i się modli po całym monorepo, albo prosi Cię o wklejenie miejsc wywołań do czatu.

### // okna kontekstu nie są darmowe

Upychanie AGENTS.md, aż Codex „wie wystarczająco dużo”, zjada tokeny, które powinny opłacać wnioskowanie. Powyżej kilku KB zamieniasz jakość odpowiedzi na objętość statycznego kontekstu.

## Jak te trzy warstwy się łączą

Użytkownicy Codex już myślą w tych kategoriach. Strona powinna to uwidocznić.

- **AGENTS.md**: umowy (jak zachowuje się Codex)
- **MCP**: kanał (jak sięga)
- **Maguyva**: fakty o kodzie (co widzi)

- **AGENTS.md**: jak Codex zachowuje się w tym repo.
- **MCP**: jak Codex sięga po narzędzia i kontekst. [(specyfikacja)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: co widzi Codex, gdy zadaje bazie kodu pytanie. Wyszukiwanie semantyczne, AST, grafowe i tekstowe zwracane ze ścieżkami plików i numerami linii.

> AGENTS.md mówi Codex *jak pracować*.
> Maguyva daje Codex *coś, od czego może zacząć*.

## Trzy przepływy pracy

Specyficzne dla Codex. Ugruntowane na rzeczywistym grafie wywołań, a nie na grep Codex.

### 01. Zmień nazwę współdzielonej klasy, najpierw znajdź wszystkie zależne elementy

```text
codex> zmień nazwę PaymentClient → BillingClient

graph::callers(PaymentClient)            12 odwołań w 7 pakietach
graph::importers(src/payments/client.ts)  9 plików importujących ten kod
graph::extends(PaymentClient)             2 podklasy (RetryClient, MockClient)

→ Codex proponuje migrację z 21 edycjami wraz z listą plików od razu.
[exit 0]
```

Codex pyta Maguyva o elementy zależne od tej klasy *zanim* zacznie edytować. Lista migracji wraca ugruntowana w rzeczywistym grafie, a nie w pamięci Codex.

### 02. Znajdź prawdziwą implementację, nie atrapę testową

```text
codex> jak normalizePhoneNumber obsługuje E.164?

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

Nazwy kłamią. Atrapy przesłaniają prawdziwy kod. Maguyva stawia prawdziwą implementację wyżej niż atrapę testową.

### 03. Sprawdź zasięg wpływu przed refaktoryzacją

```text
codex> co wywołuje QueueDispatcher.publish?

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

Miejsca wywołań między pakietami pojawiają się od razu. Diff opiera się na rzeczywistych elementach importujących ten kod, a nie na wynikach grepa w Codex.

## Konfiguracja w Codex CLI

Trzy kroki. Plan Free: 3 repozytoria, Do 50 tys. zindeksowanych linii repo, bez karty kredytowej.

### 01. Zaindeksuj repo na maguyva.ai

Wybierz repo, które dobrze znasz, żeby móc zweryfikować odpowiedzi.

### 02. Dodaj Maguyva jako serwer MCP w konfiguracji Codex

`~/.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. Zadaj jedno pytanie, na które już znasz odpowiedź

Nie zaczynaj od całej firmy. Zacznij od jednego repo i jednego sprawdzalnego pytania.

## Zaindeksuj jedno repo, które już znasz.

Podłącz Codex przez MCP. Zadaj jedno pytanie, którego odpowiedź możesz zweryfikować.