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

ШАГ 1: Новые замечания → в отдельный список кандидатов, НЕ в файл
ШАГ 2: Допуск в файл → только после повторных независимых случаев (в теории оптимум — два)
ШАГ 3: Оценка каждого правила → как часто нужно × польза/вред если выполнено − цена в токенах
ШАГ 4: Удаление → по ценности, а не по «агент это игнорирует»; вредные правила первыми
ШАГ 5: Потолок размера + небольшие пачки правок → проверка на реальных задачах

Шаги 1–4 можно делать в одном чате: загрузить файл и транскрипты, получить таблицу вердиктов. Шаг 5 — ваш ручной контроль.

Задача: Разработчик ведёт бэкенд интернет-магазина на Python с оплатой через ЮKassa. Полгода подряд после каждой сессии Claude Code он дописывал в CLAUDE.md замечания. Теперь в файле 280 строк. Среди них: «всегда запускай pytest», «пиши docstring в стиле NumPy», «используй conda» (проект давно на uv), «не коммить в main», «в тексте писем клиентам не используй слово "уважаемый"» и ещё десятки мелочей про стиль. Агент всё чаще забывает про pytest и «не коммить в main».

Промпт:

Ты — редактор файла инструкций для кодового агента. Ниже файл CLAUDE.md моего проекта (бэкенд интернет-магазина на Python, оплата через ЮKassa, окружение — uv) и три выдержки из транскриптов, где агент ошибся.

<файл>
[вставить 280 строк CLAUDE.md]


<сбои>
[вставить 3 случая: что агент сделал не так]


Для КАЖДОГО правила заполни строку таблицы:
правило | примерные токены | как часто бывает релевантно (часто / редко / почти никогда) | что будет, если агент правило выполнит (польза / нейтрально / вред) | вердикт (оставить / удалить / объединить с другим / вынести из постоянного файла)

Правила редактирования:
1. Не предлагай удалять правило ТОЛЬКО потому, что агент его игнорирует. Сначала оцени, чего стоит его нарушение.
2. Правила, которые при выполнении вредят (устарели, противоречат проекту), удаляй в первую очередь.
3. Целевой размер — не более 60 строк. Если важных правил больше, назови, какие и почему вытеснили остальные.
4. Новых правил не добавляй. Если из сбоев видно пробел — внеси его в отдельный список «кандидаты» и укажи, сколько раз пробел проявился.
5. В конце дай итоговый файл и список из 5 проверочных задач, на которых я смогу сравнить старую и новую версию.

Результат: Модель выдаст таблицу вердиктов по каждому правилу и отметит вредные, например устаревшее «используй conda». Дальше будет сжатый файл в пределах лимита и отдельный список кандидатов с числом повторов. В конце придут проверочные задачи. Решать за вас, что действительно важно в проекте, модель не может. Таблицу нужно пробежать глазами.

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

Сильная сторона. Модель хорошо классифицирует и сравнивает: «часто или редко нужно», «вредит или нет», «дублирует ли другое правило». Промпт выше использует именно это. Он заставляет оценивать правила по ценности, а не по тому, исполняются ли они.

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

Рычаги управления: - Лимит строк → меньше лимит, жёстче отбор. Для небольшого проекта хватает 20–60 строк. - Порог допуска → число повторных случаев до добавления правила. Авторы получили минимум потерь при двух наблюдениях в своих допущениях. Для критичных правил (безопасность, деньги) можно взять один. - Критерий вердикта → добавьте «стоимость ошибки», чтобы редкие, но дорогие правила не вытеснялись частыми мелочами. - Пачки правок → меняйте 5–10 правил за раз и проверяйте. Тогда видно, какая правка помогла.

Это моя сборка по принципам статьи. Готового промпта в статье нет.

Ты — редактор файла инструкций для агента ({название_агента}). Ниже файл и примеры сбоев.

<файл>
{содержимое_файла}


<сбои>
{случаи_сбоев_из_транскриптов}


Контекст проекта: {описание_проекта_и_окружения}

Для КАЖДОГО правила заполни строку таблицы:
правило | токены | релевантность (часто / редко / почти никогда) | эффект при выполнении (польза / нейтрально / вред) | вердикт (оставить / удалить / объединить / вынести)

Правила редактирования:
1. Не удаляй правило только потому, что агент его игнорирует. Сначала оцени цену нарушения.
2. Вредные и устаревшие правила удаляй первыми.
3. Целевой размер — не более {лимит_строк} строк. Если не помещается, объясни, что вытеснено и почему.
4. Новых правил не добавляй. Пробелы из сбоев вноси в список «кандидаты» с числом повторов.
5. Правило допускается в файл только если проблема проявилась не менее {порог_повторов} раз.
6. В конце дай итоговый файл и {число} проверочных задач для сравнения старой и новой версии.

Подставьте: файл целиком, 3–10 случаев сбоев из реальных транскриптов, короткое описание проекта, лимит строк и порог повторов (по умолчанию 2).

⚠️ Эксперимент далёк от реальных файлов: Оптимум и падение качества измеряли на пулах от 200 до 3200 инструкций. В настоящих AGENTS.md десятки строк. Для небольших файлов авторы сами приводят работы, где падения соблюдения правил не видно.

⚠️ Искусственные инструкции: Правила брали из реальных файлов, но модель переписала их в проверяемые правила про слова в ответе. Задачи — тексты разных форматов, а не работа кодового агента с репозиторием.

⚠️ Узкая проверка: Всего 60 задач и две модели одного семейства. Конкретные цифры оптимума переносить на свой случай нельзя.

⚠️ Теория держится на допущениях: Главное допущение — каждая добавленная инструкция не повышает соблюдение остальных. Число «два повтора перед добавлением» верно в рамках модели и не проверялось на живых агентах.

⚠️ Часть выводов требует инженерии: Алгоритм пробного перебора пачками правил и оценки ценности предполагает код и ручной ревью. Руками применимы принципы, но не весь алгоритм.

⚠️ Размер эффекта в реалистичном диапазоне не показан: Кратное падение (в разы) наблюдали при загрузке всего пула из тысяч инструкций.

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

Для проверки собрали пул из 3200 правил из реальных файлов репозиториев. 2560 из них Claude Sonnet переписал в проверяемые автоматически правила о словах в ответе. Остальные 640 оставили как есть, и они ничего не давали в подсчёте. Пул и файлы увеличивали ступенями (файл от 5 правил до всего пула), на 60 задачах ManyIFEval в шести форматах. Правила шли в системный промпт, задача — в пользовательский, всего по 2880 запусков для Claude Haiku 4.5 и Sonnet.

Результат: при пуле 3200 обе модели лучше всего работали на файле в 200 правил. Haiku выполнял около 5 релевантных правил, Sonnet около 24. При загрузке всего пула показатели падали до 0,6 и 4,0. Удивительно, что при росте пула лучший размер файла оставался небольшим. Практический вывод: рост списка идей не оправдывает рост файла.

Ниже мои идеи, не из статьи.

🔧 Техника: правило для агента, который сам пишет себе память → допуск по повтору

Если ваш агент дописывает выводы в файл памяти, добавьте в его инструкции:

Новые замечания по итогам сессии записывай в файл candidates.md, а не в AGENTS.md. 
Для каждого указывай, в скольких разных сессиях проблема проявилась.
Переноси замечание в AGENTS.md только когда оно встретилось не менее двух раз в разных сессиях 
и ты можешь назвать, что именно сломается без него.
При переносе назови, какое существующее правило можно удалить, чтобы файл не вырос.

Это прямое следствие вывода о двух сигналах и об ограничении размера. Здесь «удалить при добавлении» — моя добавка.

Экстраполяция: проверка перед удалением. Перед тем как убрать «игнорируемое» правило, прогоните 3–5 задач, где оно важно, с ним и без него. Если без него агент стал ошибаться, правило нужно усилить или поставить выше, а не удалять.

• Curating Always-Loaded Context for LLM Agents: A Capacitated Assortment Model with Censored Feedback — Zexuan Liu (University of Illinois at Urbana-Champaign), Yuning Yang (Georgia Institute of Technology), Tiancheng Zhao (Saint Louis University)
• ManyIFEval (Harada et al., 2025) — задачи с множеством инструкций
• Gloaguen et al. (2026) — контекстные файлы и рост стоимости запросов
• Chakrabarti (2026) — рост файлов в 1867 репозиториях
• McMillan (2026), Zhang et al. (2026a) — работы без падения соблюдения в малых диапазонах