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

Агент забывает. AGENTS.md помнит.

Коротко

Что такое AGENTS.md и кто его читает?

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

Codex читает их в определённом порядке. Сначала общую памятку в домашней папке Codex, где лежат твои сквозные привычки. Потом он идёт от корня проекта вниз до папки, в которой ты открыл чат, и в каждой папке берёт по одной. Чем ближе памятка к работе, тем позже она попадает в инструкции и тем сильнее её слово.

На практике это значит простую вещь. Ты один раз записал правило, и оно действует в каждом новом чате этой папки. Объяснять заново не нужно, напоминать тоже.

Разницу между чатом, режимом «Работа» и Codex я разбирал отдельно в материале чат, «Работа» или Codex. Здесь речь только о Codex и других агентах, которые работают с папкой на компьютере.

Куда класть знание: правило, скилл или второй мозг?

На обучении для отдела дизайна разговор зашёл о линиях на макете. Я сказал: «Это скорее не скилл, это правило». Его место - в AGENTS.md папки с листовками.

Накануне в той же группе тот же вопрос звучал с другой стороны. Агент нашёл ошибки на макетах, и встал вопрос, как закрепить такую проверку надолго.

Я показал две разные фразы. Скажешь агенту «запомни», и он запишет правило в постоянные инструкции. Скажешь «сохрани это как скилл», и он соберёт отдельный скилл, а дальше ты говоришь «примени скилл проверки», и он идёт по пунктам.

Справка Codex описывает механику скиллов именно так: агент сначала видит только имя и описание каждого скилла, а полный текст открывает, когда выбрал его под задачу. Поэтому процедура на двадцать шагов в скилле почти ничего не стоит, пока не нужна. В AGENTS.md она съедает место в каждом чате.

Второй мозг делается один раз. На второй день обучения я так и объяснил группе: это долгосрочная память агента, а под каждый проект можно завести свою структуру знаний поменьше. Когда задача повторяется и просится в скилл, критерий я разбирал в статье задача повторилась третий раз.

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

Когда правка становится правилом?

На обучении я сказал группе фразу, которую повторяю почти всем: «Если ты ему в чате это даёшь, он конечно же это потом забудет, а если он это запишет в Markdown-формат, то он это будет всегда читать». Чат - краткосрочная память. Новый чат начинается с чистого листа, и всё, что ты объяснял вчера, для него не существовало.

Правки в работе с визуалом обычно выглядят так. Ты делаешь скриншот, кидаешь агенту в чат и просишь повернуть текст, который стоит под другим углом, чем изделие. Один раз это правка. Если через день ты пишешь то же самое про другой макет, пора превращать правку в правило.

1. Заметь повтор

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

2. Попроси агента записать правило

   «Запиши в AGENTS.md этой папки правило: ... Сформулируй коротко, одной строкой, так, чтобы его можно было проверить».

3. Прочитай, что он записал

   Агент склонен расписать абзац. Попроси сжать до строки и убрать объяснения, которые не меняют поведение.

4. Проверь новым чатом

   Открой новый чат в той же папке и дай похожую задачу без напоминания. Правило сработало - оставляешь. Не сработало - переформулируй.

Тот же цикл «ошибка - новая строка» для Claude Code я описывал в материале про память агента. Механика у Codex та же, меняются только имя памятки и агент, который её читает.

Что записать в AGENTS.md, если ты не программист?

Примеры AGENTS.md в интернете почти все про код: команды сборки, тесты, стиль. Человеку, который ведёт в папке макеты, отчёты или тексты, они не помогают. Его правила другие, и на обучении для дизайнеров я показывал, какие.

Первый шаг я давал группе одной фразой: «Создай в корне этой папки файл agents.md, короткая карта проекта», и дописать своими словами, какие правила важны именно здесь. Дальше памятка растёт из правок. Для папки с листовками она может выглядеть так:

# Листовки к новинкам

Что здесь: макеты листовок по образцу и брифу.
Исходники - в brief/, готовые макеты - в out/.

## Правила
- Каждый макет сдавать в трёх видах: AI в слоях, векторный PDF и PNG.
- Шрифты не переводить в кривые.
- Перед любым макетом открыть guidelines.md: кегли, толщина линий, отступы.
- Бриф противоречит образцу - не выбирать самому, выписать противоречие и спросить.

Каждая строка здесь собрана из того, что происходило на занятии. Требование сдавать макеты в слоях дизайнеры дописывали в задания прямо на занятии, потому что плоская картинка им не годится. Строка про противоречия появилась после того, как агент сам нашёл в техническом задании противоречия и остановился с вопросом, а не выбрал сам.

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

Вложенные AGENTS.md: своя памятка на каждую папку

Сайт формата приводит пример: в главном репозитории OpenAI на момент написания их страницы было 88 файлов AGENTS.md. Каждая часть проекта несёт свои правила. Агент читает ближайшую к работе памятку, и при конфликте побеждает именно она.

У меня рабочая папка устроена так же. В корне лежит памятка с правилами, общими для всех проектов: на каком языке отвечать, что нельзя делать без моего подтверждения, где лежат правила, выученные на ошибках. В папке каждого проекта - своя: стек, где что лежит, особенности именно этой работы. Проектов сейчас около пятидесяти, и корень ничего не знает про специфику каждого.

Как делить правила между уровнями, решается одним вопросом. Правило верно во всех твоих папках - оно в корне или в общем файле Codex в домашней папке. Верно только здесь - оно в AGENTS.md этой папки.

Как не раздуть AGENTS.md?

На обучении я описывал AGENTS.md как оглавление книги. Это не огромный документ на тысячу строк со всем, что тебе нравится и не нравится. Это короткие пункты: что лежит в папке, для чего, где искать подробности.

Признаюсь честно: моя собственная корневая памятка этот принцип нарушила. Когда я сверял её со справкой Codex для этой статьи, оказалось, что она весит около 48 КБ при лимите по умолчанию в 32 КБ. Значит, хвост Codex не видит, пока я не подниму лимит в настройках или не разрежу её по папкам. Справка предлагает оба пути, я бы выбрал второй: короткий корень и подробности по папкам.

Что помогает держать AGENTS.md в форме:

• Ссылка вместо содержания. Гайдлайны, регламенты, справочники - отдельными документами, в AGENTS.md строка «перед X открой Y».
• Процедуры - в скиллы. Всё, что расписывается по шагам, живёт отдельным скиллом.
• Знания о себе - во второй мозг. Тон, ценности и привычки не относятся к правилам конкретной папки.
• Чистка раз в месяц. Устаревшие и противоречащие друг другу строки хуже, чем их отсутствие: агент не знает, какой из спорящих строк верить.

Последний пункт удобно делать руками агента. Когда в первый день у группы появились вопросы, зачем агент создал в папке второго мозга столько файлов, я сказал: «А вы не у меня спросите, а у агента спросите. Это он же делал, не я». С правилами так же: попроси его найти строки, которые повторяют друг друга или спорят между собой, и объяснить, зачем нужна каждая.

AGENTS.md и CLAUDE.md в одной папке

Многие работают с двумя агентами сразу: Codex в приложении ChatGPT и Claude Code. Документация Claude Code описывает три варианта.

У меня в корне рабочей папки исторически лежат две памятки-близнеца, по одной на каждого агента. Это работает, но удваивает работу: каждое новое правило надо вносить дважды, и рано или поздно близнецы расходятся. Новичку я советую одну памятку с правилами и импорт.

Как устроена память Claude Code по уровням, я разбирал в материале что писать в CLAUDE.md. Почему вообще всё решают документы в папке, а не формулировка запроса, - в разборе про контекст-инжиниринг.

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

Главный вывод

Начни с малого. Открой папку, в которой работаешь с агентом чаще всего, и вспомни замечание, которое ты писал ему больше одного раза. Попроси записать его одной строкой в AGENTS.md и проверь новым чатом.

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

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