Skip to content

Файл правил 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): все найденные файлы склеиваются последовательно (от глобального и корневого к текущему подкаталогу) через пустую строку. Правила из папок, расположенных ближе к месту запуска, имеют более высокий приоритет при конфликтах и перекрывают вышестоящие.

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

Процесс слияния: глобальный уровень (~/.codex/) → корень Git → подкаталоги с приоритетом локальных правил

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

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

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/):
md
# 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:

toml
# ~/.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, расширьте лимит:

toml
# ~/.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: Инициализация репозитория

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

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

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

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

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

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

## 常用命令

- `npm test` —— 运行测试

## 编程约定

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

## 注意事项

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

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

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

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

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

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

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

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

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

bash
mkdir -p services/payments

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

md
# services/payments/AGENTS.override.md

## 支付服务规则

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

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

bash
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 · Слэш-команды и горячие клавиши мы детально разберем слэш-команды управления сессией на лету и настроим горячие клавиши для ускорения разработки.


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