AGENTS.md для Codex CLI: что это за файл и как его писать

AGENTS.md в Codex CLI — это файл, который агент читает перед началом работы, чтобы знать правила вашего проекта: как ставить зависимости, как запускать тесты, какие соглашения по коду приняты. Это не конфиг с моделями и инструментами, а обычный Markdown, по сути README для агента. Ниже — как Codex ищет такие файлы, что в них писать и как подключить Codex к Zukko. Всё сверено с официальным руководством Codex по AGENTS.md и сайтом agents.md.

Что такое AGENTS.md

AGENTS.md — открытый формат инструкций для агентов программирования. У файла нет обязательной структуры и специальных полей: Codex склеивает найденные файлы и добавляет их к инструкциям в начале сессии. Строки вида «Model: gpt-5.6-sol» или «Tools: file_write» в AGENTS.md ничего не настраивают. Модель и провайдер задаются в config.toml, а инструменты и разрешения — флагами и настройками Codex.

Тот же файл понимают и другие агенты. На сайте agents.md в списке поддержки есть, например, Cursor, Aider, Zed, Gemini CLI, Kilo Code и RooCode. Один AGENTS.md в репозитории пригодится всей команде, кто бы каким агентом ни пользовался.

Как Codex находит AGENTS.md

Цепочка инструкций собирается один раз при запуске (в интерактивном режиме — при старте сессии):

1. Глобальный уровень. В домашней папке Codex (~/.codex, если не задан CODEX_HOME) читается AGENTS.override.md, а если его нет — AGENTS.md. Берётся первый непустой файл.
2. Уровень проекта. От корня проекта (обычно корень git) Codex идёт вниз до текущей папки. В каждой папке проверяет AGENTS.override.md, затем AGENTS.md, затем имена из project_doc_fallback_filenames. Из одной папки берётся не больше одного файла.
3. Слияние. Файлы склеиваются от корня к текущей папке через пустую строку. Более близкие к рабочей папке инструкции стоят позже и поэтому перекрывают общие.

Пустые файлы пропускаются. Когда суммарный размер доходит до project_doc_max_bytes (по умолчанию 32 KiB), Codex перестаёт добавлять файлы. Лимит можно поднять в ~/.codex/config.toml:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

AGENTS.override.md удобен для временной замены: положили рядом с обычным файлом — действует он, удалили — вернулись общие правила.

Что писать в AGENTS.md

Пишите то, что агенту иначе пришлось бы угадывать или выяснять запусками:

• команды установки, сборки, линтера и тестов, в точности как они запускаются;
• где что лежит, если структура неочевидна;
• соглашения, которые не ловит линтер: именование, слои, куда класть новые модули;
• правила для PR и коммитов;
• запреты: не трогать сгенерированные файлы, не добавлять зависимости без вопроса.

Пример корневого файла:

## Setup
- Install deps: `pnpm install`
- Run tests: `pnpm test`
- Lint and typecheck: `pnpm lint && pnpm typecheck`

## Code style
- TypeScript strict mode, no `any` in new code
- API handlers live in `src/api/`, business logic in `src/services/`
- Never edit files in `src/generated/`, regenerate them with `pnpm codegen`

## Before you finish
- Run `pnpm lint` and `pnpm test`; fix failures before proposing a commit
- Ask before adding a new production dependency

Для отдельной части монорепозитория положите свой файл рядом с кодом, например services/payments/AGENTS.md с командой make test-payments. Codex возьмёт и корневой файл, и этот, если запущен из services/payments.

Чего избегать:

• общих слов вроде «пиши чистый код» — агент и так старается, а токены тратятся;
• копий кода и целых гайдов по стилю — лучше сослаться на файл или линтер;
• устаревших команд: неверная команда тестов хуже, чем никакой.

Как создать и проверить

В интерактивном Codex команда /init создаёт заготовку AGENTS.md в текущей папке. Её останется отредактировать под проект. Проверить, что инструкции подхватились, можно так:

codex --ask-for-approval never "Summarize the current instructions."

Codex должен пересказать пункты из глобального и проектного файлов. Если что-то не подхватилось: проверьте, что файл не пустой, нет ли выше по дереву AGENTS.override.md, и какой CODEX_HOME задан. Кэша нет: инструкции пересобираются при каждом запуске.

Подключение Codex к Zukko

Провайдер и модель задаются в ~/.codex/config.toml:

model = "gpt-5.6-sol"
model_provider = "zukko"

[model_providers.zukko]
name = "Zukko"
base_url = "https://api.zukko.pro/v1"
wire_api = "responses"
requires_openai_auth = true

Ключ Zukko хранится в ~/.codex/auth.json как OPENAI_API_KEY. Проще всего записать его командой входа по ключу:

export OPENAI_API_KEY="fetch_ваш_ключ"
printenv OPENAI_API_KEY | codex login --with-api-key

Файл ~/.codex/auth.json хранит ключ открытым текстом, относитесь к нему как к паролю. Ключ создаётся в кабинете Zukko↗, пошаговая настройка — в документации Zukko по Codex↗. Актуальный список моделей — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете. Модель в сессии меняется командой /model.

Размер AGENTS.md и расход токенов

Инструкции из AGENTS.md входят в контекст, который агент отправляет модели при каждом запросе сессии. Поэтому размер файла умножается на число запросов. Пример: AGENTS.md занимает 2 000 токенов, сессия сделала 200 запросов. Это 2 000 × 200 = 400 000 входных токенов, на gpt-5.6-sol ($0.3 за 1M) — 0.4 × $0.3 = $0.12. Оговорка про кэш: у вендора чтение из кэша промптов стоит около 10% входной цены, а в Zukko кэшированные токены оплачиваются по обычной входной цене. Для таких повторяющихся блоков реальная разница с официальным прайсом меньше, чем при прямом сравнении цен.

Посчитать размер файла в токенах можно через эндпоинт count_tokens↗:

jq -n --rawfile t AGENTS.md '{model: "claude-sonnet-5", messages: [{role: "user", content: $t}]}' |
curl -s https://api.zukko.pro/v1/messages/count_tokens \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @-

Ответ содержит input_tokens. У GPT-моделей другой токенизатор, так что число будет немного иным, но для оценки размера этого достаточно.

Частые вопросы

Можно ли указать в AGENTS.md, какую модель использовать?

Нет. AGENTS.md — только текст инструкций. Модель задаётся ключом model в config.toml, в сессии — командой /model.

Чем AGENTS.md отличается от README?

README пишут для людей: описание проекта, быстрый старт. AGENTS.md — для агента: точные команды, соглашения и запреты, которые засоряли бы README.

У меня уже есть файл с правилами под другим именем. Переименовывать?

Не обязательно: добавьте его имя в project_doc_fallback_filenames в config.toml, и Codex будет читать его, когда в папке нет AGENTS.md.

Нужно ли коммитить AGENTS.md?

Да, проектный файл — часть репозитория. Личные предпочтения держите в ~/.codex/AGENTS.md.