// umowa
AGENTS.md
Jak Codex powinien się zachowywać w tym repo.
Dla użytkowników Codex CLI
AGENTS.md mówi Codex, jak pracować.
Nie co tam jest.
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.
Plan Free: 3 repozytoria, Do 50 tys. zindeksowanych linii repo, bez karty.
AGENTS.md to umowa. MCP to kanał. Maguyva to mapa.Warstwowy stos
Cztery idee. Każda robi jedno zadanie.
// transport
MCP
Jak Codex sięga po zewnętrzne narzędzia i kontekst.
// baza kodu
Maguyva
Serwer MCP, który zwraca ugruntowane fakty o repo.
// kto płaci
Workspace'y, nie stanowiska
Agenci nie płacą za stanowiska. Zobacz cennik
AGENTS.md to umowa robocza. Korzystaj z niej.
Trwałe instrukcje należą do 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
„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 tym kształcie. 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)
- 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.
// workflow 01
Zmień nazwę współdzielonej klasy, najpierw znajdź wszystkie zależne
codex> zmień nazwę PaymentClient → BillingClient graph::callers(PaymentClient) 12 odwołań w 7 pakietach graph::importers(src/payments/client.ts) 9 importerów 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 zależności zanim zacznie edytować. Lista migracji wraca ugruntowana w rzeczywistym grafie, a nie w pamięci Codex.
// workflow 02
Znajdź prawdziwą implementację, nie atrapę testową
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ą.
// workflow 03
Sprawdź promień rażenia przed refaktoryzacją
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 jest ugruntowany na rzeczywistych importerach, a nie na grep Codex.
Konfiguracja w Codex CLI
Trzy kroki. Plan Free: 3 repozytoria, Do 50 tys. zindeksowanych linii repo, bez karty.
// step 01
Zaindeksuj repo na maguyva.ai
Wybierz repo, które dobrze znasz, żeby móc zweryfikować odpowiedzi.
// step 02
Dodaj Maguyva jako serwer MCP w konfiguracji Codex
$ 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"// step 03
Zadaj jedno pytanie, na które już znasz odpowiedź
Nie zaczynaj od całej firmy. Zacznij od jednego repo i jednego sprawdzalnego pytania.