# AGENTS.md каже Codex, як працювати. Але не що там є.

Canonical source: https://maguyva.ai/uk/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/uk/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 in src/billing/*    1 in src/audit/*    1 in src/notifications/*
[exit 0]
```

Місця виклику з різних пакетів з'являються прямо в результаті. Diff обґрунтований реальними імпортерами, а не 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. Поставте одне запитання, відповідь на яке можна підтвердити.