// соглашение
AGENTS.md
Как Codex должен вести себя в этом репозитории.
Для пользователей Codex CLI
AGENTS.md рассказывает Codex, как работать.
Но не что в репозитории.
AGENTS.md задаёт рабочее соглашение. MCP позволяет Codex обращаться к инструментам. Maguyva — это MCP-сервер, который даёт Codex карту вашего репозитория с возможностью запроса, так что первая правка — не догадка о структуре файлов.
Тариф Free: 3 репозитория, До 50 тыс. проиндексированных строк, без карты.
AGENTS.md — это соглашение. MCP — это канал. Maguyva — это карта.Слоистый стек
Четыре идеи. У каждой своя задача.
// транспорт
MCP
Как Codex обращается к внешним инструментам и контексту.
// кодовая база
Maguyva
MCP-сервер, который возвращает обоснованные факты о репозитории.
// кто платит
Рабочие пространства, а не места
Агенты не платят за места. Смотреть тарифы
AGENTS.md — это рабочее соглашение. Используйте его.
Постоянные инструкции — место для них в AGENTS.md. Это правильное место для:
- Команд сборки, тестирования и линтинга, которые должен запускать Codex.
- Ограничений вида “всегда делай X / никогда не делай Y”, привязанных к директории.
- Соглашений об именовании и предпочтений по рефакторингу.
- Ссылок на канонические журналы решений и заметки об архитектуре.
Держите его кратким. Ограничивайте область применения. Коммитьте.
Но AGENTS.md никогда не задумывался как индекс с возможностью запроса по каждому символу, файлу и месту вызова в вашем репозитории.
Где AGENTS.md сам по себе становится статичным при росте масштаба
Четыре сценария сбоя, по одному на карточку.
// соглашения — это не индекс
Рассказать Codex, как работать, не значит рассказать, что существует. Первая правка в незнакомом пакете — это догадка о путях файлов и именах функций. AGENTS.md не может перечислить каждый символ, да и не должен.
// документ расходится с кодом
Блок в AGENTS.md, описывающий топологию ваших очередей, верен, пока кто-то не добавит нового потребителя. Теперь источник истины — код, а документ уверенно устарел. Codex читает не тот источник.
// переименование — это задача про граф
На вопрос «что ссылается на этот класс?» markdown-файл не ответит. Codex либо делает grep и надеется на удачу по всему монорепозиторию, либо просит вас вставить места вызова в чат.
// окно контекста не бесплатно
Раздувание AGENTS.md, пока Codex не «узнает достаточно», съедает токены, которые должны идти на рассуждение. После нескольких килобайт вы меняете качество ответа на объём статичного контекста.
Как три слоя сочетаются друг с другом
Пользователи Codex уже мыслят в этой форме. Страница должна сделать это очевидным.
AGENTS.md
соглашения
как ведёт себя Codex
MCP
канал
как он обращается
Maguyva
факты о кодовой базе
что он видит
- AGENTS.md как Codex ведёт себя в этом репозитории.
- MCP как Codex обращается к инструментам и контексту. (спецификация)
- Maguyva что видит Codex, когда задаёт вопрос кодовой базе. Семантический, AST, графовый и текстовый поиск с путями к файлам и номерами строк.
AGENTS.md рассказывает Codex, как работать.
Maguyva даёт Codex то, от чего можно оттолкнуться.
Три сценария
Специфично для Codex. Обоснованно — на основе реального графа вызовов, а не grep'а Codex.
// workflow 01
Переименуйте общий класс, сначала найдя все зависимости
codex> переименовать PaymentClient → BillingClient graph::callers(PaymentClient) 12 ссылок в 7 пакетах graph::importers(src/payments/client.ts) 9 импортёров graph::extends(PaymentClient) 2 подкласса (RetryClient, MockClient) → Codex предлагает миграцию из 21 правки со списком файлов прямо в выводе. [exit 0]
Codex спрашивает у Maguyva о зависимых элементах перед тем, как начать редактировать. Список миграции возвращается обоснованным реальным графом, а не воспоминаниями Codex.
// workflow 02
Найдите настоящую реализацию, а не тестовую заглушку
codex> как normalizePhoneNumber обрабатывает E.164? semantic::query("normalize phone E.164") src/util/phone.ts:88 normalizePhoneNumber() ← реальная реализация test/util/phone.spec.ts:14 jest.mock(...) ← заглушка [exit 0]
Имена лгут. Моки заслоняют настоящий код. Maguyva ранжирует настоящую реализацию выше тестового мока.
// workflow 03
Проверьте радиус влияния перед рефакторингом
codex> что вызывает QueueDispatcher.publish? graph::callers(QueueDispatcher.publish) 3 в src/billing/* 1 в src/audit/* 1 в src/notifications/* [exit 0]
Места вызова между пакетами всплывают прямо в выводе. Дифф обоснован реальными импортёрами, а не grep'ом Codex.
Настройка в Codex CLI
Три шага. Тариф Free: 3 репозитория, До 50 тыс. проиндексированных строк, без карты.
// step 01
Проиндексируйте репозиторий на maguyva.ai
Выберите тот, который хорошо знаете, чтобы можно было проверить ответы.
// step 02
Добавьте Maguyva как MCP-сервер в конфигурации 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
Задайте один вопрос, ответ на который вы уже знаете
Не начинайте сразу со всей компании. Начните с одного репозитория и одного проверяемого вопроса.