Файл правил AGENTS.md: фиксация стандартов кодирования

📚 Навигация по серии: Предыдущая статья 10 Облачный режим Codex Cloud описала запуск задач в облаке с отправкой результатов в PR. В этой статье мы вернемся к локальной разработке и рассмотрим файл AGENTS.md — проектную инструкцию, которую Codex считывает перед запуском каждой задачи, но которую большинство новичков составляют некорректно.

Расскажу о забавной ошибке, которую я допустил в самом начале работы с Codex.

В прошлом году я передал Node-проект агенту Codex. Я создал в корневого каталоге файл AGENTS.md, где на первой строке написал: «В этом проекте используется pnpm. Использование npm запрещено». Но при сборке Codex запустил команду npm install. Я решил, что агент проигнорировал файл, трижды скопировал это правило, выделил его жирным шрифтом и поставил восклицательные знаки. Это не помогло.

После долгих поисков причин выяснилось: агент прочитал файл, но само правило оказалось погребено на 140-й строке. Перед ним я разместил описание компании, дорожную карту продукта и предысторию выбора фреймворка. К моменту, когда Codex дошел до запрета npm, контекстное внимание модели было рассеяно обилием ненужного текста. Проблема заключалась не в том, что агент проигнорировал указания, а в том, что полезное правило было затеряно среди информационного шума.

Файл AGENTS.md для Codex выполняет ту же роль, что и CLAUDE.md для Claude Code. Это одинаковые концепции под разными именами. Однако механизмы поиска, правила переопределения и лимиты размера файлов в Codex имеют свои особенности. В этой статье мы подробно разберем правила составления инструкций.

После прочтения этой статьи вы получите:

• Понимание цепочки поиска AGENTS.md (глобальный уровень → уровень проекта → слияние) и приоритетов при конфликтах
• Навык использования механизма временного переопределения AGENTS.override.md
• Чек-лист правил («что писать» и «что опускать») для эффективного удержания внимания модели
• Инструкции по настройке параметров project_doc_fallback_filenames и project_doc_max_bytes в config.toml
• Пошаговый алгоритм для тестирования считывания инструкций агентом

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

---

01 Назначение файла правил

Главный вывод: AGENTS.md — это файл постоянных инструкций для Codex. Агент считывает его перед началом каждого вызова, загружая правила проекта в свой активный контекст.

Каждая новая сессия (Run) в TUI запускается с чистого листа. Агент не помнит ваши текстовые указания из предыдущих диалогов. Без файла AGENTS.md вам пришлось бы пересказывать требования к стилю кода и сборке при каждом запуске клиента.

Аналогия: журнал смены на производстве. При посменной работе уходящая смена записывает на доске критические замечания: «не запускать станок №3», «провести дефектовку партии», «контакты аварийной службы». Новая смена считывает доску и приступает к работе. Файл AGENTS.md выступает в роли такой доски объявлений для Codex.

Когда нужно добавлять записи в AGENTS.md:

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

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

💡 Краткий вывод: Наполняйте AGENTS.md правилами по мере разработки. Это постоянный свод стандартов проекта, аналогичный CLAUDE.md.

---

02 Цепочка поиска файлов правил

Файлы правил могут быть размещены на разных уровнях каталогов. При запуске Codex объединяет их в единую цепочку инструкций по следующим правилам:

Сборка цепочки происходит на этапе старта сессии:

1. Глобальный уровень (Global Scope): Codex проверяет системную папку настроек ~/.codex/. Сначала выполняется поиск файла AGENTS.override.md. Если он найден, считывается только он; если нет — считывается AGENTS.md. Из двух файлов выбирается только один первый непустой.

2. Уровень проекта (Project Scope): поиск начинается в корневом каталоге проекта (корне Git) и продолжается вниз до текущей рабочей папки. В каждом промежуточном каталоге выбирается один файл по приоритету: AGENTS.override.md → AGENTS.md → резервные имена из параметра project_doc_fallback_filenames.

3. Слияние (Merge Order): все найденные файлы склеиваются последовательно (от глобального и корневого к текущему подкаталогу) через пустую строку. Правила из папок, расположенных ближе к месту запуска, имеют более высокий приоритет при конфликтах и перекрывают вышестоящие.

Схема цепочки сбора инструкций:

Схема демонстрирует логику: глобальные файлы объединяются с проектными. Чем глубже расположен файл в иерархии папок, тем выше его приоритет.

Два ключевых правила слияния:

1. Слияние, а не замена: глобальные и проектные правила действуют одновременно. Проектный файл не отменяет глобальный, а дополняет его контекст. 2. Локальный приоритет: если глобальный файл требует использования одинарных кавычек, а проектный — двойных, выиграет проектное правило, так как оно расположено ближе к каталогу запуска.

Аналогия: масштабирование карты. Общая карта дает направление (глобальный уровень), карта города прокладывает маршрут (корень репозитория), а табличка у подъезда показывает вход (подкаталог). Все три источника информации верны, но при несовпадении приоритет отдается ближайшей локальной табличке.

Иллюстрация показывает стек приоритетов: правила подкаталога переопределяют директивы корня репозитория и глобальной папки.

💡 Краткий вывод: Цепочка сбора: глобальный файл → корень Git → подкаталоги. Инструкции объединяются; при конфликтах переопределяются ближайшими файлами.

---

03 Механизм временного переопределения AGENTS.override.md

Файл AGENTS.override.md представляет собой уникальный механизм Codex для переопределения настроек.

Он решает следующую задачу: если вам требуется временно заменить глобальные правила в ~/.codex/AGENTS.md для конкретного эксперимента, не удаляя основной файл.

Аналогия: стикер с пометкой поверх договора. Основной контракт остается без изменений, но прикрепив поверх стикер, вы устанавливаете временное правило для текущей операции. После его удаления система возвращается к исходным условиям. Файл AGENTS.override.md заставляет Codex игнорировать стандартный AGENTS.md в той же папке.

Два сценария использования:

• Глобальное временное переопределение: создание AGENTS.override.md в папке ~/.codex/ отключает стандартный глобальный файл на время выполнения эксперимента.
• Специфические правила подкаталога: изоляция правил для конкретных папок (например, сервиса платежей services/payments/):

# services/payments/AGENTS.override.md

## 支付服务规则

- 用 `make test-payments` 替代 `npm test`
- 轮换 API Key 前必须先通知安全频道

Наличие этого файла заставит Codex игнорировать файл AGENTS.md в папке services/payments/.

Разграничивайте область действия override:

Контур	Действие AGENTS.override.md
Внутри папки	Игнорирует стандартный AGENTS.md на текущем уровне каталога
На всю цепочку	Не отменяет правила вышестоящих каталогов, а лишь участвует в стандартном слиянии

Файл AGENTS.override.md переопределяет правила только на своем уровне и не блокирует чтение глобальных файлов. Полное объединение цепочки продолжается по стандартной схеме.

При обнаружении некорректных команд в поведении агента проверьте структуру папок на предмет скрытых файлов AGENTS.override.md, перекрывающих стандартные правила.

💡 Краткий вывод: AGENTS.override.md отключает стандартный файл AGENTS.md на текущем уровне папки, но не блокирует слияние цепочки. Используется для временных переопределений.

---

04 Что писать и чего избегать в файле правил

Качественный файл правил должен содержать только важную техническую информацию для AI.

Рекомендуемые разделы:

Категория	Описание	Пример
Описание проекта	Назначение кодовой базы в одно предложение	«Бэкенд управления заказами на FastAPI»
Стек технологий	Версии компиляторов и СУБД	«Python 3.11 / PostgreSQL / pytest»
Команды запуска	Тесты, сборщики, линтеры	npm run lint, make test-payments
Стандарты стиля	Правила оформления и именования переменных	«Использовать двойные кавычки для строк»
Ограничения (Не делать)	Запрещенные каталоги, критические операции	«Не изменять файлы в папке migrations/»

Разделы команд сборки считываются агентом наиболее часто для запуска проверочных тестов перед коммитом. Раздел ограничений предохраняет критическую логику от случайных правок.

Чего следует избегать:

• ❌ Длинных описаний предыстории: миссия компании, этапы планирования и причины выбора фреймворков не нужны агенту и лишь расходуют объем контекста.
• ❌ Устаревшей информации: неактуальные команды сборки запутают Codex.
• ❌ Очевидных вещей: Codex умеет самостоятельно анализировать структуру файлов, не нужно описывать назначение каждого каталога вручную.

Лимиты размера файлов правил в Codex:

При достижении суммарного объема склеенной цепочки файлов лимита project_doc_max_bytes (32 KiB по умолчанию) считывание последующих файлов прекращается.

Лимит 32 KiB распространяется на всю объединенную цепочку (глобальные + проектные файлы). Избыточно подробный корневой файл может заблокировать чтение локальных подкаталогов. Вы можете расширить лимит в настройках или разделить инструкции по разным папкам.

Простой тест при добавлении правила: «Может ли Codex понять это из кода проекта?» Если да, опустите это правило для экономии контекста.

💡 Краткий вывод: Фиксируйте только жесткие правила сборки и стиля. Суммарный лимит цепочки составляет 32 KiB. Избегайте художественных описаний.

---

05 Параметры настроек в config.toml

Для кастомизации считывания файлов правил используются два параметра в ~/.codex/config.toml:

1. Изменение имени файла правил

Если в вашем репозитории уже используется файл стандартов (например, TEAM_GUIDE.md), вы можете указать Codex считывать его вместо стандартного AGENTS.md:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

Это переопределяет цепочку приоритетов на: AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md (выбирается первый найденный файл).

Иные имена файлов будут проигнорированы клиентом.

2. Увеличение лимита размера

Если цепочка инструкций превышает 32 KiB, расширьте лимит:

# ~/.codex/config.toml
project_doc_max_bytes = 65536

Это увеличит лимит до 64 KiB. Тем не менее, рекомендуется оптимизировать файлы, а не увеличивать лимиты без крайней необходимости.

Случаи изменения настроек:

Ситуация	Используемый параметр
Использование существующего файла правил	project_doc_fallback_filenames
Превышение суммарного лимита склейки файлов	project_doc_max_bytes
Использование отдельного профиля настроек	Переменная CODEX_HOME

⚠️ Внимание: после редактирования файла config.toml перезапустите сессию Codex для применения настроек.

💡 Краткий вывод: Настраивайте имена файлов в project_doc_fallback_filenames и лимиты в project_doc_max_bytes. Все изменения требуют перезапуска Codex.

---

06 Практический тест считывания правил

Создадим тестовый файл правил и проверим его чтение агентом:

В Windows выполняйте команды Git в консоли Git Bash или PowerShell.

Шаг 1: Инициализация репозитория

mkdir agents-md-demo
cd agents-md-demo
git init

Ожидаемый результат: создание каталога и инициализация Git.

Шаг 2: Создание файла правил

Создайте файл AGENTS.md со следующим содержимым:

# agents-md-demo — 一个演示用的最小项目

只有用来演示 AGENTS.md 怎么写，没有真实业务逻辑。

## 常用命令

- `npm test` —— 运行测试

## 编程约定

- 所有函数必须有类型注解
- 字符串一律用双引号

## 注意事项

- 不要新增任何生产依赖，需要时先问我

Ожидаемый результат: создание файла правил.

Шаг 3: Проверка чтения правил агентом

Запустите команду для проверки считывания инструкций:

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

Ожидаемый результат: вывод текстового саммари правил, содержащего указанные вами ограничения (npm test, двойные кавычки, запрет на зависимости).

Флаг --ask-for-approval never используется исключительно для отключения интерактивных запросов TUI во время этого теста.

Шаг 4: Тест локального переопределения

Создайте подкаталог и поместите в него файл AGENTS.override.md:

mkdir -p services/payments

Содержимое файла services/payments/AGENTS.override.md:

# services/payments/AGENTS.override.md

## 支付服务规则

- 用 `make test-payments` 替代 `npm test`

Запустите проверку из подкаталога:

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

Ожидаемый результат: Codex перечислит источники (глобальный, корень, локальный override), при этом команда тестирования для подкаталога сменится на make test-payments.

⚠️ При сбоях считывания: проверьте статус слияния через codex status, убедитесь в отсутствии скрытых AGENTS.override.md и проверьте, что файлы правил не являются пустыми.

💡 Краткий вывод: Создайте AGENTS.md → проверьте чтение командой Summarize... → проверьте приоритеты переопределения с помощью AGENTS.override.md в подкаталоге.

---

07 Резюме

Основные выводы:

Параметр	Описание
Назначение	Постоянный файл правил проекта, аналогичный CLAUDE.md
Цепочка поиска	Глобальный уровень → корень репозитория → подкаталоги
Приоритеты	Локальные правила переопределяют вышестоящие при конфликтах
Override	Временное отключение стандартного файла правил на текущем уровне
Наполнение	Только жесткие правила, стили и команды сборки. Без описания архитектуры
Ограничение размера	Суммарно до 32 KiB на цепочку. Лимит меняется в project_doc_max_bytes
Флаги настроек	project_doc_fallback_filenames и project_doc_max_bytes в config.toml

Фиксация стандартов кодирования в компактных файлах AGENTS.md обеспечивает стабильный контекст для работы агента Codex на всех этапах.

В следующей статье 12 · Слэш-команды и горячие клавиши мы детально разберем слэш-команды управления сессией на лету и настроим горячие клавиши для ускорения разработки.

---

Рекомендуемые материалы

• Практические рекомендации по работе с агентами
• Оптимизация контекста и ускорение ответов
• Быстрый старт в CLI-клиенте