# AGENTS.md рассказывает Codex, как работать. Но не о том, что есть в репозитории.

Canonical source: https://maguyva.ai/ru/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 задаёт рабочее соглашение. MCP позволяет Codex обращаться к инструментам. Maguyva — это MCP-сервер, который даёт Codex карту вашего репозитория с возможностью поиска, так что первая правка — не догадка о структуре файлов.

> AGENTS.md — это соглашение. MCP — это канал. Maguyva — это карта.

## Многоуровневый стек

Четыре идеи. У каждой своя задача.

### AGENTS.md

Как Codex должен вести себя в этом репозитории.

### MCP

Как Codex обращается к внешним инструментам и контексту.

### Maguyva

MCP-сервер, который возвращает факты о репозитории, подтверждённые кодом.

### За пространство, не за пользователя

За каждого агента не взимается отдельная плата. [Смотреть тарифы](https://maguyva.ai/ru/pricing)

## AGENTS.md — это рабочее соглашение. Используйте его.

Постоянные инструкции следует хранить в [`AGENTS.md`](https://developers.openai.com/codex/guides/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 обращается к инструментам и контексту. [(спецификация)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: что видит Codex, когда задаёт вопрос кодовой базе. Семантический, AST, графовый и текстовый поиск с путями к файлам и номерами строк.

> AGENTS.md рассказывает Codex, *как работать*.
> Maguyva даёт Codex *то, от чего можно оттолкнуться*.

## Три сценария

Сценарии для Codex. Они опираются на данные реального графа вызовов, а не grep'а Codex.

### 01. Переименуйте общий класс, сначала найдя все зависимые элементы

```text
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.

### 02. Найдите настоящую реализацию, а не тестовую заглушку

```text
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 ранжирует настоящую реализацию выше тестового мока.

### 03. Проверьте радиус влияния перед рефакторингом

```text
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 тыс. проиндексированных строк, без банковской карты.

### 01. Проиндексируйте репозиторий на maguyva.ai

Выберите тот, который хорошо знаете, чтобы можно было проверить ответы.

### 02. Добавьте Maguyva как MCP-сервер в конфигурации 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. Задайте один вопрос, ответ на который вы уже знаете

Не начинайте сразу со всей компании. Начните с одного репозитория и одного проверяемого вопроса.

## Проиндексируйте один репозиторий, который вы уже знаете.

Подключите Codex через MCP. Задайте один вопрос, ответ на который можно перепроверить.