Файл правил: как написать его, чтобы агент слушался

У модели ограниченное внимание. Anthropic называет это бюджетом внимания: каждый новый кусок текста немного его расходует.

LLMs have an "attention budget" that they draw on when parsing large volumes of context.

У языковых моделей есть «бюджет внимания», и они тратят его, когда разбирают большие объёмы контекста.

Anthropic, «Effective context engineering for AI agents», 29 сентября 2025

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

В документации Claude Code это сказано прямо и даже с диагнозом. Если агент упорно делает то, что вы запретили, скорее всего, файл слишком длинный и правило в нём потерялось:

If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost.

Если Claude продолжает делать то, чего вы не хотите, хотя против этого есть правило, файл, вероятно, слишком длинный, и правило в нём теряется.

Anthropic, «Best practices for Claude Code»

Обычная реакция на непослушание: дописать правило ещё раз, капслоком, с пометкой «ВАЖНО». Файл от этого только растёт. Та же документация предупреждает: если выделить много строк, не выделяется ни одна.

То же касается всех агентов. AGENTS.md читают все популярные агенты: Codex, Cursor, GitHub Copilot, а Claude Code читает его сам, если в папке нет CLAUDE.md. Поэтому дальше речь про один файл, и правила для него общие.

Куда что класть, зависит от того, что агент читает сразу, а что потом. Сразу он читает две вещи. Первая: файл правил целиком, от первой строки до последней. Вторая: по одной строке описания от каждого скилла. Сами скиллы он на старте не открывает.

Потом приходит ваша задача. Агент сверяет её с описаниями скиллов и решает, какой подходит. Только тогда он открывает этот скилл и читает его целиком: шаги, примеры, проверки. Так же с файлами: если в правилах стоит маршрут «клиенты и тарифы лежат в clients.md», агент откроет этот файл, когда понадобится клиент.

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

Claude loads them on demand without bloating every conversation.

Claude загружает скиллы по требованию и не раздувает ими каждый разговор.

Anthropic, «Best practices for Claude Code», про скиллы

OpenAI описывает в документации Codex ту же механику: сначала агент видит имя и описание каждого скилла, полную инструкцию читает, когда решил скилл взять. Значит, вывод один для всех агентов. Процедуры живут в скиллах, а в правилах остаётся маршрут к ним.

Я проверяю свои папки по четырём мерилам. Первые три про файл правил, четвёртое про скиллы.

1. Каждая строка правил это маршрут, граница или постоянное поведение

   Маршрут ведёт к файлу или скиллу, граница говорит, чего нельзя, постоянное поведение действует на любую задачу. Остальное переезжает: процедура с шагами в скилл, история решений в git, справка в отдельный файл, правило одной подпапки во вложенный AGENTS.md. Git здесь это история изменений папки, где у каждой правки есть дата и причина. Как памятка новому сотруднику: где что лежит, чего не трогать, как говорить с клиентами. Регламенты всех отделов в неё не вклеивают.

2. Файл правил до 200 строк

   Это ориентир Anthropic. У Codex есть и жёсткий предел: 32 КБ на все файлы правил вместе, остальное до агента не доходит. Как инструктаж перед сменой: пять минут слушают все, на сороковой минуте не слушает никто.

3. AGENTS.md работает навигатором

   Детали живут в своих файлах и скиллах, а в правилах стоит строка-маршрут к ним. Агент сам откроет нужное, когда до него дойдёт работа. Как табличка на ресепшене: «бухгалтерия на втором этаже». Саму бухгалтерию на ресепшене не держат.

4. Описание скилла отвечает на вопрос «когда меня брать»

   В нём сказано, что скилл делает и в какой ситуации нужен. Оно короткое и не пересекается с описаниями других скиллов. Как подпись на папке в шкафу: «Договоры с поставщиками, 2026» находят за секунду, а папку «Разное» не открывает никто.

Проверка для каждой строки есть прямо в документации Claude Code. Задайте себе вопрос: «Если удалить эту строку, агент ошибётся?» Если нет, строку можно удалять.

Возьмём выдуманную, но узнаваемую папку: онлайн-школа английского, агент пишет посты, отчёты клиентам и планы уроков. Файл правил рос год. Каждую ошибку агента владелец закрывал новой строкой, каждое решение записывал туда же. Вот кусок такого файла:

# Правила

Отвечай по-русски.
Мы школа английского для взрослых, работаем с 2019 года...

## Как публиковать пост в Telegram
1. Открой папку posts/drafts и найди последний черновик.
2. Проверь, что в тексте нет длинных тире.
3. Подбери обложку 1280×720, шрифт крупный...
... ещё 37 шагов

## История
12.03 решили писать клиентам на «вы».
15.04 передумали: на «ты», кроме корпоративных.
02.05 Маша попросила не трогать таблицу оплат.

## Клиенты
ООО «Ромашка»: тариф «Команда», 12 человек, менеджер Ольга...
... ещё 80 клиентов

## Папка с уроками
В lessons/ называй файлы так: урок-номер-тема...

Цены клиентам не называй, отправляй к менеджеру.

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

Вот тот же файл после разбора:

# Школа английского: правила агента

Отвечай по-русски. Клиентам пиши на «ты», корпоративным на «вы».

## Куда идти
- Пост в Telegram пиши через скилл telegram-post.
- Отчёт клиенту собирай скиллом client-report.
- Клиенты и тарифы: clients.md.
- Правила папки с уроками: lessons/AGENTS.md.

## Границы
- Цены клиентам не называй, отправляй к менеджеру.
- Таблицу оплат только читай.
- Перед отправкой чего-либо клиенту покажи текст мне.

Ничего не потерялось. Шаги публикации стали скиллом telegram-post. Список клиентов переехал в clients.md. Правила про уроки легли во вложенный файл правил папки lessons, который агент прочитает, когда начнёт там работать. История осталась в git, а в правила попал только её итог: «на “ты”, кроме корпоративных» и «таблицу оплат только читай». Правило про цены поднялось наверх и теперь стоит среди трёх границ, где его нельзя не заметить.

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

description: Помогает с постами.

description: Пишет пост в Telegram-канал школы по черновику из posts/drafts и подбирает обложку. Брать, когда просят пост, анонс или публикацию в канал.

OpenAI советует то же самое: описание короткое, с ясными границами. Главный сценарий и слова, по которым агент узнает задачу, стоят в самом начале. Ещё одна частая беда: два скилла с похожими описаниями, например «помогает с текстами» и «пишет тексты для соцсетей». Агент не знает, какой выбрать, и берёт любой.

Цифра 200 из документации Claude Code. Anthropic советует держать каждый файл правил короче 200 строк и объясняет почему:

Longer files consume more context and reduce adherence.

Длинные файлы занимают больше контекста и хуже соблюдаются.

Anthropic, документация Claude Code, раздел про память

Там же есть оговорка. Если разнести правила по нескольким файлам и подключить их ссылкой через значок @, это не помогает. Подключённые файлы всё равно загружаются в начале работы целиком. Порядок появляется, а вес остаётся.

У Codex предел жёстче и считается в байтах. Он склеивает все файлы AGENTS.md от корня проекта до папки, где вы начали работу. Когда набирается 32 КБ, текст дальше не добавляется. Русскому тексту здесь тяжелее: русская буква весит 2 байта, латинская 1. Мой файл правил для папки с уроками занимает 81 строку и весит 14 КБ. Это почти половина бюджета Codex, хотя по строкам до предела Anthropic ещё далеко.

Поэтому 200 строк это потолок. Хороший навигатор для одной папки обычно укладывается в 40–60 строк.

Когда процедуры переезжают в скиллы, возникает соблазн завести скилл на всё. Но у каталога тоже есть цена. Описание каждого скилла агент читает в каждой работе, так же как файл правил.

У меня 93 скилла. Их описания на старте занимают около 8,7 тысячи токенов. Токен это кусочек слова: в них агенты считают объём текста.

Codex ставит этому каталогу жёсткий предел. На стартовый список скиллов он отводит 2% окна контекста, а если размер окна неизвестен, 8000 символов. Когда скиллов слишком много, Codex сначала сокращает описания, а потом часть скиллов вообще убирает из списка.

If many skills are installed, Codex shortens skill descriptions first. For large skill sets, Codex may omit some skills from the initial list and show a warning.

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

OpenAI, документация Codex, «Build skills»

Сто скиллов с размытыми описаниями это та же простыня, только в другом месте. Скиллы, которыми вы не пользуетесь, стоит удалять. Те, что делают почти одно и то же, стоит сливать в один.

1. Посчитайте строки. Попросите агента: «Сколько строк и килобайт в моём AGENTS.md?» Больше 200 строк или 32 КБ значит, что файл пора разбирать.
2. Пройдите по строкам с одним вопросом. Если удалить строку, агент ошибётся? Нет, значит удаляйте.
3. Разложите остальное по местам. Процедура с шагами в скилл, история в git, справка в отдельный файл, правило подпапки во вложенный AGENTS.md. В правилах оставьте маршрут.
4. Перечитайте описания скиллов. Каждое должно отвечать, что скилл делает и когда его брать. Два похожих описания перепишите или слейте скиллы.
5. Удалите скиллы, которыми не пользуетесь. Каждый из них занимает место в каждой работе.

Можно не делать это руками. Я собрал скилл audit-agent-rules. Он проверяет папку по тем же четырём мерилам и показывает таблицу «что не так и куда перенести». Файлы он правит только после вашего «да». Вставьте агенту эту фразу:

Установи скилл по ссылке:
https://github.com/serejaris/personal-corp-os/tree/main/skills/audit-agent-rules

После установки попросите агента проверить правила в папке. Сам скилл устроен по тем же правилам. Его описание отвечает, когда его брать, а шаги агент откроет, только когда вы попросите проверку.

Если агент переспрашивает то, что в файле уже написано, документация Claude Code советует перечитать формулировку: скорее всего, она двусмысленная. А жёсткий запрет лучше ставить в настройках агента. Файл правил агент читает как совет, настройки выполняются всегда.