AGENTS.md: инструкция, которую агент Codex действительно читает перед работой

Вы объясняете Codex одно и то же в каждой сессии: какой командой гонять тесты, куда не лезть, в каком стиле писать код. А через задачу агент снова запускает не тот тест и лезет в папку, которую трогать нельзя. Решение — не длиннее объяснять в чате, а один раз положить правила в файл, который агент читает сам, до того как напишет первую строку. Этот файл называется AGENTS.md.

Коротко (TL;DR)

AGENTS.md — это текстовый файл в корне репозитория (или в подпапке), куда вы записываете правила проекта для агента: команды сборки и тестов, стиль кода, запретные зоны, ожидания к pull request. Codex находит и читает его автоматически при старте задачи и учитывает как контекст — как заметку от тимлида новому разработчику.

Что нужно знать сразу:

• Файл находится сам. Codex идёт от корня проекта вниз к текущей папке и собирает все AGENTS.md по пути; отдельно читает глобальный ~/.codex/AGENTS.md.
• Ближайший к задаче файл главнее. Правило в apps/web/AGENTS.md перекрывает правило из корневого AGENTS.md.
• Есть лимит. Codex складывает файлы, пока суммарный размер не упрётся в project_doc_max_bytes — по умолчанию 32 KiB; дальше добавлять перестаёт.
• Создаётся командой. В Codex CLI есть команда /init — она генерирует стартовый AGENTS.md под ваш репозиторий.
• Это открытый формат. Тот же файл читают Cursor, GitHub Copilot, Gemini CLI, Devin и ещё два десятка агентов — вы пишете инструкцию один раз на всю команду инструментов.

Дальше — как именно работает иерархия, что писать внутрь, готовый шаблон и где всё это ломается.

BYBIT COPY TRADINGКопитрейдинг на BybitОткрытая статистика трейдеров, старт с $10, отключение в один клик.Выбрать трейдера

Что такое AGENTS.md

AGENTS.md — это файл инструкций проекта для кодинг-агента: в официальной документации OpenAI его называют «README для агентов». Разница с обычным README простая. README пишут для человека — как запустить проект, что он делает. AGENTS.md пишут для агента — детальный контекст, который человеку в README не нужен, но без которого агент действует наугад: точные команды, границы, соглашения по коду.

Codex для не-программиста: как собрать первый рабочий продукт

Один продукт на Codex: как довести идею до живого URL, не утонув в коде

AMD Instinct Coder: стойка на восьми MI325X обещает минус 70% к цене токенов

Codex под контролем: как песочница и одобрения решают, что агенту можно

Codex — не чат-бот, а агент: как формулировать задачи, чтобы он делал их правильно

Агент читает этот файл при старте и держит его в контексте всю сессию. Поэтому в него кладут то, что вы иначе повторяли бы вручную каждый раз: «тесты гоняй через just test, а не cargo test», «в папку legacy/ не заходи», «перед PR прогони линтер». Codex не додумывает эти правила — он берёт их из файла.

Ключевая мысль: AGENTS.md не делает агента «умнее», он делает его предсказуемым. Одна и та же задача с хорошим AGENTS.md и без него даёт разный результат — не потому что модель разная, а потому что во втором случае агент не знает ваших договорённостей.

Если вы уже работали с Claude Code, аналогия прямая: там ту же роль играет файл CLAUDE.md. Идея одна — вынести правила проекта в файл, который агент читает сам; про сам подход управления агентом через такой файл мы подробно разбирали в материале о методе работы с кодинг-агентом. Здесь фокус на Codex-специфике: как именно OpenAI Codex находит, сливает и ограничивает эти файлы.

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

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

Область 1. Проект: от корня вниз к текущей папке

Codex определяет корень проекта (обычно это корень git-репозитория) и идёт вниз по дереву папок до вашей текущей рабочей директории. В каждой папке по пути он проверяет наличие файла: сначала AGENTS.override.md, потом AGENTS.md, потом запасные имена из настройки project_doc_fallback_filenames. Последнее — настраиваемый список альтернативных имён файла инструкций (например, TEAM_GUIDE.md или .agents.md); по умолчанию он не задан, и Codex ищет только AGENTS.md. Из каждой папки берётся не больше одного файла.

Дальше — самое важное, что упускают почти все гайды. Codex склеивает найденные файлы от корня вниз, разделяя их пустой строкой. Файлы, которые ближе к вашей текущей папке, идут в собранном промпте позже — и поэтому перекрывают то, что было выше. «Ближе к задаче = главнее».

SpaceX · xStockSpaceX — частная компания. Торгуй её токеном на Bybit за крипту.Торговать SpaceX →

Разберём на конкретном дереве монорепозитория:

myproject/
├── AGENTS.md              ← правила всего репозитория
├── apps/
│   └── web/
│       └── AGENTS.md      ← правила только фронтенда
└── services/
    └── api/
        └── AGENTS.md      ← правила только бэкенда

Если вы запускаете задачу внутри apps/web/, Codex соберёт цепочку: сначала myproject/AGENTS.md, затем apps/web/AGENTS.md. Правила фронтенда идут последними и перекрывают общие там, где конфликтуют (например, корень говорит «форматируй через Prettier», а apps/web уточняет свою конфигурацию). Файл services/api/AGENTS.md в эту задачу вообще не попадёт — он не на пути от корня к текущей папке.

Насколько это реальный, а не теоретический механизм: в собственном репозитории OpenAI (openai/codex) — 88 файлов AGENTS.md, по одному на пакеты и подсистемы. Это и есть каскадная модель в работе — общие правила в корне, точечные в подпапках.

Область 2. Глобальный уровень: ~/.codex

Кроме проекта, Codex читает глобальный файл в своей домашней папке — по умолчанию ~/.codex (каталог можно переопределить переменной CODEX_HOME). Здесь Codex берёт первый непустой файл: сначала проверяет AGENTS.override.md, если его нет — AGENTS.md.

Глобальный файл — для ваших личных привычек на все проекты: как вы любите оформлять финальный ответ, спрашивать ли перед коммитом, общий тон общения. Проектные файлы — для того, что имеет смысл только в конкретном репозитории: команды, структура, соглашения команды.

Важный момент про приоритет, который почти нигде не проговаривают: глобальный файл идёт в общей цепочке первым и потому имеет низший приоритет. Проектные файлы (даже корневой AGENTS.md) добавляются после него и перекрывают глобальные правила там, где они спорят. То есть личная привычка из ~/.codex/AGENTS.md работает по умолчанию, но конкретный проект может её переопределить.

AGENTS.override.md — замена файла своего уровня, а не всей цепочки

Обычные AGENTS.md по дереву складываются. Но иногда в конкретной папке нужно не добавить правило поверх базового AGENTS.md, а заменить его. Для этого есть AGENTS.override.md. Если Codex находит такой файл в директории, он берёт на этом уровне только его и игнорирует соседний AGENTS.md в той же папке. Важно: это замена на уровне одной директории, а не отмена всего, что выше — родительские файлы (например, корневой AGENTS.md) по-прежнему участвуют в цепочке. На глобальном уровне override удобен для временной замены: положили ~/.codex/AGENTS.override.md, поработали в другом режиме, удалили — вернулась обычная общая инструкция. Ничего стирать не пришлось.

Лимит размера: 32 KiB

Codex складывает файлы цепочки не бесконечно. Как только суммарный размер собранных инструкций упирается в project_doc_max_bytes (по умолчанию 32 KiB), Codex перестаёт добавлять следующие файлы. Пустые файлы он пропускает. Практический вывод: раздутый на десятки килобайт AGENTS.md опасен не тем, что «много букв», а тем, что часть инструкций может молча не поместиться в контекст. Об этом — в разделе про риски.

Как создать AGENTS.md: команда /init

Руками файл создавать не обязательно. В Codex CLI есть команда /init — по описанию из документации она «создаёт файл AGENTS.md с инструкциями для Codex». Запускаете /init в корне репозитория, агент осматривает проект и генерирует стартовый файл: структуру, обнаруженные команды, базовые соглашения. Это удобная заготовка, но не финал — сгенерированный черновик почти всегда нужно дочистить под реальные договорённости команды.

Рядом в CLI есть родственные команды, которые пригодятся при настройке: /status (показать текущую конфигурацию сессии), /permissions (выбрать, что Codex разрешено делать), /model (модель и уровень reasoning), /review (ревью изменений). По умолчанию Codex CLI работает на модели gpt-5.6-sol в режиме medium (данные на 17 июля 2026 — имена моделей у OpenAI меняются часто, проверяйте актуальные в /model).

Что писать в AGENTS.md — и чего не писать

Хороший AGENTS.md — это не пересказ README и не список благих пожеланий. Это исполняемые правила: то, что агент может взять и применить дословно. Начинать стоит с короткого seed-файла на 12–20 строк и расширять его только когда всплывает повторяющаяся проблема, а не заливать сразу гигантский шаблон.

Вот что реально работает и что тратит впустую лимит и внимание агента:

Посмотреть, как это выглядит на большом проекте, можно прямо в исходниках Codex: в AGENTS.md репозитория openai/codex встречаются строки вроде «Не запускай cargo test напрямую — используй just test, чтобы прогон шёл по правилам репозитория» и «Держи модули Rust меньше 500 строк, не считая тестов». Это ровно тот жанр — конкретное правило, которое агент может проверить, а не пожелание.

Готовый шаблон-пример AGENTS.md

Стартовый seed, с которого удобно начать (замените команды и пути на свои):

# AGENTS.md

## Стек и структура
- Node.js 20 + TypeScript, пакетный менеджер — pnpm.
- Код приложения: src/. Тесты: tests/. Не трогай build/ и dist/.

## Команды
- Установка: pnpm install
- Тесты: pnpm test (гоняй после правок в src/)
- Линт: pnpm lint (обязателен перед PR)
- Сборка: pnpm build

## Границы
- Не меняй файлы в migrations/ без явной задачи.
- Не добавляй прод-зависимости без подтверждения.
- Секреты берём из .env, в код не хардкодим.

## Pull request
- Один PR — одна задача. В описании: что и зачем.
- Перед PR: pnpm lint && pnpm test — оба зелёные.

## Готово, когда
- Тесты проходят, линт чистый, задача из тикета закрыта.

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

AGENTS.md, config.toml и системный промпт — три разных слоя

Ещё один источник путаницы: у Codex есть несколько мест, где что-то «настраивается», и их постоянно смешивают. На самом деле это три независимых слоя с разными ролями.

Проще всего запомнить так: системный промпт — это «характер» агента, который вы не меняете; AGENTS.md отвечает на вопрос «что делать в этом проекте»; config.toml — «как технически запускать» (какая модель, что агенту разрешено, сеть, песочница). Настройка config.toml и подключение внешних инструментов через MCP — отдельные темы, они не про этот файл; здесь важно одно: правила поведения живут в AGENTS.md, а не в конфиге.

AGENTS.md — это открытый стандарт, а не фишка Codex

Легко подумать, что AGENTS.md — приватный формат OpenAI. Это не так, и это меняет ценность вложения в файл. AGENTS.md — открытый формат, которым по данным agents.md (на июль 2026) пользуется более 60 000 open-source проектов. Он вырос из совместных усилий экосистемы (OpenAI Codex, Amp, Google Jules, Cursor, Factory) и сейчас курируется Agentic AI Foundation под эгидой Linux Foundation.

Практический смысл: один и тот же AGENTS.md понимают более двадцати разных агентов — Codex, Cursor, GitHub Copilot, Gemini CLI, Devin, Windsurf, Amp, Aider и другие. Вы пишете правила проекта один раз, а не отдельный файл под каждый инструмент. Для команды, где разные разработчики сидят на разных агентах, это экономит и время, и рассинхрон правил. (Claude Code в этот список не входит — у него своя конвенция, файл CLAUDE.md; о нём — ниже в сравнении.)

Это же полезно и не-программисту, который собирает продукт с ИИ: подход «вайб-кодинга» работает надёжнее, когда агент действует по записанным границам, а не по устной просьбе в чате, которую он забудет к следующей сессии.

Где AGENTS.md ломается: риски и грабли

Раздел, которого нет у большинства гайдов «всё всегда работает». Вот реальные риски и грабли AGENTS.md.

• Файл раздули — часть правил не доехала. Лимит project_doc_max_bytes (32 KiB) не абстрактный: как только суммарная цепочка AGENTS.md его превышает, Codex перестаёт добавлять файлы. В большом монорепо с десятком уровней это реально. Держите файлы короткими; общее — в корне, частное — в подпапках.
• Секреты в файле. AGENTS.md уходит в контекст модели и почти всегда коммитится в git. Ключи, пароли и токены туда писать нельзя — это утечка. Секреты — в .env и в системах секретов, а в AGENTS.md максимум «бери ключи из переменных окружения».
• Устаревшие команды опаснее их отсутствия. Если в файле написана команда тестов, которой уже нет, агент честно попробует её выполнить и сломается или сделает не то. AGENTS.md — часть кода: устарел — поправьте, иначе он вредит.
• Лозунги вместо правил. «Пиши качественно» агент не может проверить и по сути игнорирует. Работают только правила с командой или конкретной границей: не «делай тесты хорошо», а «после правок в src/ гоняй pnpm test».
• Конфликт файлов без понимания приоритета. Если правила корня и подпапки спорят, побеждает ближайший к задаче. Пишете противоречащие инструкции на разных уровнях, не помня об этом, — получаете «агент делает не то, что в корне». Держите переопределения осознанными.

Как проверить, что AGENTS.md загрузился

Не гадайте — спросите агента напрямую. Официальная документация рекомендует из корня репозитория выполнить:

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

Codex перечислит инструкции, которые реально попали в контекст, в порядке приоритета. Если в ответе есть ваши правила (команда тестов, запретная папка) — файл подхватился. Если чего-то нет — проверьте имя файла, путь и не упёрлись ли вы в лимит 32 KiB.

FAQ

Где должен лежать файл AGENTS.md? В корне репозитория — это база для всего проекта. Для отдельных модулей кладите дополнительные AGENTS.md в их подпапки: Codex возьмёт ближайший к вашей текущей директории и наложит его поверх корневого. Личные правила на все проекты — в ~/.codex/AGENTS.md.

Чем AGENTS.md отличается от config.toml? AGENTS.md описывает, что агенту делать в проекте: правила, команды, стиль, границы. config.toml задаёт, как запускать Codex технически: модель, режим одобрения, песочницу, профили. Первый — инструкция для агента, второй — настройки инструмента. Это разные файлы с разными задачами.

Обязательно ли писать AGENTS.md вручную? Нет. Команда /init в Codex CLI сгенерирует стартовый AGENTS.md по вашему репозиторию. Но сгенерированный файл — черновик: его стоит сократить до реальных правил команды, а не оставлять как есть.

Что будет, если AGENTS.md слишком большой? Codex складывает файлы, пока не упрётся в project_doc_max_bytes (по умолчанию 32 KiB), и затем перестаёт добавлять следующие. Часть инструкций может не попасть в контекст. Поэтому файлы держат короткими, а специфику выносят в AGENTS.md подпапок.

Будет ли этот файл работать не только в Codex? Да. AGENTS.md — открытый формат, его читают более двадцати агентов, включая Cursor, GitHub Copilot, Gemini CLI и Devin. Один файл описывает правила проекта для всех инструментов сразу, отдельный под каждый агент не нужен. Исключение — Claude Code: у него своя конвенция, файл CLAUDE.md.

Что важнее при конфликте — корневой AGENTS.md или файл в подпапке? Файл ближе к вашей текущей папке. Codex склеивает цепочку от корня вниз, и более глубокие файлы идут позже, перекрывая общие правила там, где они спорят. Поэтому общее держат в корне, а уточнения — в подпапках.