AGENTS.md помог Codex соблюдать правила проекта: 0 нарушений из 13 против 5 из 13
Новая сессия AI-агента не помнит вчерашних договорённостей: кладёт SQL прямо в сервис, заводит лишнюю колонку cancelled_at и забывает записать действие в журнал аудита. Tech Lead Сергей Прощаев прогнал 18 сессий Codex на небольшом Python-сервисе. Без правил агент нарушал 5 из 13 решений проекта, а с файлом AGENTS.md или со skill — 0 из 13. Поэтому в файл стоит записывать только то, что агент без подсказки сделает иначе.
AI-обработка оригинала Habr AI; редакция Hamidun News
Вы неделю делаете проект вместе с AI-агентом и договариваетесь: SQL лежит только в db.py, ошибки идут через AppError, а отмена подписки меняет поле status и пишет запись в журнал аудита. Сессия закрывается. Назавтра новая сессия добавляет отчёт по выручке, кладёт conn.execute прямо в сервис, заводит колонку cancelled_at и забывает про аудит. Тесты зелёные, отчёт считает верно, а решения команды остались во вчерашнем чате. Tech Lead Сергей Прощаев проверил на 18 сессиях Codex, лечит ли это файл AGENTS.md. Это обычный текстовый файл с правилами проекта, который агент читает при старте. Результат: без правил агент нарушал 5 из 13 проверяемых решений, с AGENTS.md или со skill, то есть отдельным каталогом с инструкциями, — 0 из 13.
Что показал эксперимент
Автор запускал Codex CLI 0.166.0 на небольшом Python-сервисе. Задача: подписки с ценой в рублях, отмена и отчёт по выручке. Каждая сессия стартовала с нуля, в изолированном каталоге и без истории диалогов. Сравнивали три варианта: без правил, с AGENTS.md и с отдельным skill. Каждый вариант прогнали по три раза.
В первом круге было восемь проверок. Без правил агент нарушил по две в каждой сессии: назвал денежную колонку price_kopecks вместо принятого имени и положил SQL в сервис, хотя соседний users.py ходит в базу через db.py. Остальное он выводил из кода сам: хранил деньги в копейках, брал время через clock, поднимал AppError.
Во втором круге автор добавил пять решений, которые расходятся с привычками модели. Без правил во всех трёх сессиях агент завёл cancelled_at вместо status, не вызвал db.add_audit, хотя функция лежала в проекте, и написал коды ошибок в старом стиле bad_price. Это те самые 5 нарушений из 13 проверок. С AGENTS.md и со skill нарушений не было вообще. Приёмочные тесты при этом проходили во всех вариантах, включая «без правил». Обычные тесты таких договорённостей не видят, поэтому понадобился отдельный скрипт check.py, который разбирает код через ast.
Два показателя автор честно убрал из зачёта. UUID агент взял и без правил, потому что сигнатура требовала строковый id. Формат логов не нарушен, потому что логов в новом модуле просто не было.
Как записывать правила
Шаг 1: про каждое решение задайте вопрос, сделает ли агент так сам. Проверять надо не догадкой, а сессией без правил. Шаг 2: у правила должны быть причина и наблюдаемый признак нарушения, а запрещённое названо прямо (cancelled_at, execute). Если старый код правилу не соответствует, напишите это в самом правиле, иначе агент сочтёт образцом то, что видит рядом.
Шаг 3: в корневой AGENTS.md кладите решения, касающиеся любой правки. Codex читает глобальный файл, затем по одному файлу на каталог по пути до рабочего. Общий лимит project_doc_max_bytes по умолчанию 32 КиБ. Правила одного модуля лучше держать в AGENTS.md его каталога.
Шаг 4: длинное выносите в skill, но ссылайтесь на него из AGENTS.md. Агент видит у skill только шапку и сам решает, загружать ли остальное. В замере Vercel на документации Next.js 16 skill не вызывался в 56% случаев, и доля решённых задач осталась на уровне 53%, как без документации. Явная фраза в AGENTS.md подняла её до 79%, а сжатый индекс прямо в файле дал 100%. В эксперименте Прощаева ссылка была всегда, и skill открывался в шести сессиях из шести.
Шаг 5: проверяйте правила в чистой среде. У автора в глобальном AGENTS.md 62 КБ личных правил и около сотни skills, так что вариант «без правил» без изоляции не был бы таковым. Для проверки HOME и CODEX_HOME указывают на временный каталог. Шаг 6: превращайте решения в автоматические проверки и тестируйте сами проверки на заведомо сломанном коде.
Ограничения и цена
Эксперимент маленький: одна модель, одна задача, по три сессии на вариант. Долю нарушений для других агентов отсюда не вывести. Skill не дал измеримого преимущества перед AGENTS.md, выигрыш только организационный. Скрипт check.py ловит лишь заранее известные формы нарушений: SQL через другой helper он пропустит.
Файл контекста стоит денег. По исследованию ETH Zurich «Evaluating AGENTS.md» файлы, сгенерированные моделью, не повысили долю решённых задач, а стоимость выросла на 20–23%. Файлы, написанные разработчиками, дали +2,4% решённых задач, статистически незначимо, при росте стоимости до 19%. Агенты начинают больше исследовать и тестировать, а это тоже токены.
Практический вывод: возьмите три последние правки, которые вы вносили за агентом вручную, запишите их правилами с признаком нарушения и прогоните одну сессию в чистой среде. Правила, которые агент нарушает без файла и соблюдает с ним, и составляют ваш AGENTS.md. Остальное лишь добавляет расходы. Поддержка форматов зависит от инструмента: Claude Code читает CLAUDE.md, Gemini CLI по умолчанию GEMINI.md, поэтому документацию своего агента стоит проверить.
- 21 нояб. 2026 г.Meta готовит ИИ-тамагочи Muse Charm за $300 с годом 5G от Verizon
- 21 нояб. 2026 г.Dreamteam привлёк $53M на CRM, которая сама заполняется из почты и звонков
- 21 нояб. 2026 г.22 агента Claude шесть недель искали ответы по чёрным дырам — и решили две задачи
- 21 нояб. 2026 г.Google построила закрытую копию интернета с фейковыми банками, чтобы учить ИИ-агентов Chrome
Вопросы и ответы по материалу
Что известно по теме: что показал эксперимент?
Автор запускал Codex CLI 0.166.0 на небольшом Python-сервисе. Задача: подписки с ценой в рублях, отмена и отчёт по выручке. Каждая сессия стартовала с нуля, в изолированном каталоге и без истории диалогов. Сравнивали три варианта: без правил, с AGENTS.md и с отдельным skill. Каждый вариант прогнали по три раза. В первом круге было восемь проверок.
Что известно по теме: как записывать правила?
Шаг 1: про каждое решение задайте вопрос, сделает ли агент так сам. Проверять надо не догадкой, а сессией без правил. Шаг 2: у правила должны быть причина и наблюдаемый признак нарушения, а запрещённое названо прямо (cancelled_at, execute). Если старый код правилу не соответствует, напишите это в самом правиле, иначе агент сочтёт образцом то, что видит рядом. Шаг 3: в корневой AGENTS.md кладите решения, касающиеся любой правки. Codex читает глобальный файл, затем по одному файлу на каталог по пути до рабочего.
Что известно по теме: ограничения и цена?
Эксперимент маленький: одна модель, одна задача, по три сессии на вариант. Долю нарушений для других агентов отсюда не вывести. Skill не дал измеримого преимущества перед AGENTS.md, выигрыш только организационный. Скрипт check.py ловит лишь заранее известные формы нарушений: SQL через другой helper он пропустит. Файл контекста стоит денег. По исследованию ETH Zurich «Evaluating AGENTS.md» файлы, сгенерированные моделью, не повысили долю решённых задач, а стоимость выросла на 20–23%.
Соберите рабочего ИИ-агента или сервис своими руками без ручного кода
В Академии Жемала Хамидуна (academy.hamidun.com) открыт бесплатный 72-часовой тест-драйв: интерактивные скетч-уроки по Claude Code и Cursor, живой Tech Radar и готовые шаблоны агентов.
Главное из мира ИИ — раз в неделю
7 ключевых событий недели, отобранных вручную. Без шума, репостов и пресс-релизов.
Готово! Проверьте почту — мы отправили подтверждение.