TL;DR
CLAUDE.md, AGENTS.md и другие файлы-инструкции для AI-агентов постоянно растут — их размер увеличивается в среднем на 226% за жизненный цикл файла и почти никогда не уменьшается сам по себе. Исследователи нашли решение: добавлять к каждой инструкции комментарий, который объясняет, почему она появилась, какую проблему решала и сработала ли. Это не меняет то, что видит исполнитель (AI-агент), но помогает следующему человеку понять — можно ли эту инструкцию удалить.
Проблема в человеческой памяти, а не в лени. Когда вы добавляете инструкцию в промпт ("всегда отвечай тремя предложениями"), причина её появления живёт у вас в голове ровно до следующего созвона или смены задачи. Через пару месяцев никто не помнит, зачем строка появилась — а удалить её страшно: вдруг именно она чинит баг, который вылезет через неделю. Проще дописать новую строчку, чем разбираться со старой. Отсюда парадокс: даже если задача не меняется, файл будет расти только из-за забывания причин, а не из-за того, что появляются новые требования.
Метод простой: рядом с инструкцией пишется скрытый комментарий — что не работало, какая гипотеза была выдвинута, и как это отработало на практике. Комментарий не отправляется исполнителю (модели, которая выполняет задачу) — его видит только следующий человек (или агент), который редактирует файл. В экспериментах это убрало 99,3% лишних инструкций и повысило точность соблюдения требований на до 23%.
Схема метода
ШАГ 1: Инструкция появляется в файле → добавляется в общий список (без изменений в текущей практике)
ШАГ 2 (НОВОЕ): Рядом с инструкцией пишется скрытый комментарий → формат: [что не работало] + [гипотеза-решение] + [сработало/не сработало]
ШАГ 3: Исполнитель (агент) видит только инструкции, комментарии перед ним "вырезаются" → выполнение задачи как обычно
ШАГ 4: Когда нужно почистить файл → человек/агент читает комментарии → понимает, какие инструкции устарели или избыточны → удаляет с уверенностью
Всё происходит в одном файле — комментарии просто дописываются рядом с инструкциями при каждом изменении, отдельных запросов не требуется.
Пример применения
Задача: Вы веду́те CLAUDE.md для проекта — файл с инструкциями для Claude Code, который правит код в вашем репозитории. За полгода файл разросся до 60 строк: "не используй библиотеку X", "всегда пиши тесты", "отвечай на русском в комментариях к коду" — и вы уже не помните, зачем половина строк там появилась.
Промпт для новой инструкции (добавляете в CLAUDE.md):
Всегда используй async/await вместо .then() в JS-коде.
# 2024-11-03: агент сгенерировал код с цепочкой .then(),
# ревьюер попросил переписать на async/await —
# добавляю правило, чтобы не повторялось;
# после добавления баг не повторялся 3 итерации подряд
Промпт для чистки файла (раз в месяц или квартал):
Вот CLAUDE.md с комментариями к каждой инструкции.
Прочитай комментарии и скажи:
1. Какие инструкции решают проблему, которая больше не актуальна (например, старая версия библиотеки)?
2. Какие инструкции никогда не "сработали" по своим же комментариям — то есть добавлены, но проблема не подтвердилась повторно?
3. Какие можно объединить, потому что комментарии описывают одну и ту же причину?
[вставить CLAUDE.md с комментариями]
Результат: Модель проанализирует комментарии и вернёт список инструкций-кандидатов на удаление с объяснением почему — вместо того чтобы вы гадали "а вдруг эта строка защищает от чего-то важного". Файл станет короче, агент будет точнее следовать оставшимся правилам (меньше "шума" — противоречащих или избыточных указаний).
Почему это работает
Модели плохо следуют инструкциям, когда их слишком много — это давно известный эффект: чем длиннее список правил, тем чаще модель путается или игнорирует часть из них. Поэтому короткий, актуальный файл инструкций работает лучше раздутого.
Но люди (и агенты, которые редактируют файл от их имени) не удаляют инструкции без причины — удалить строку "на всякий случай" рискованно: если она защищала от бага, баг вернётся, а связь между удалением и поломкой можно не заметить сразу. Проще добавить новую строку, чем разбираться со старой — добавление дешёвое, удаление дорогое, потому что требует восстановить утраченную причину.
Комментарий решает это дешёвым способом: записать причину в момент, когда она ещё свежа в голове (это стоит секунд), вместо того чтобы пытаться восстановить её через месяцы (это требует перепроверки всех связанных сценариев). Модель хорошо умеет резюмировать и анализировать текст — поэтому если причина зафиксирована рядом с инструкцией, любая LLM может позже прочитать историю правок и подсказать, что можно безопасно убрать.
Рычаги управления: - Формат комментария (что не работало / гипотеза / результат) → упрощайте под свою задачу, но сохраняйте связь "проблема → решение → итог", иначе комментарий превращается в шум - Периодичность чистки → чаще чистить = меньше накопленного долга, но больше рутины; выберите ритм (раз в месяц, раз в квартал) - Кто пишет комментарий → если сами добавляете правило — пишите сразу; если это агент — попросите его дописывать комментарий автоматически при каждом изменении файла инструкций
Шаблон промпта
Для добавления новой инструкции с комментарием:
{новая инструкция}
# {дата}: проблема — {что не работало / какая ошибка повторялась}
# гипотеза — {почему это правило должно помочь}
# результат — {сработало ли за последние N попыток, или "пока не проверено"}
Для периодической чистки файла инструкций:
Вот файл инструкций {название файла} с комментариями к каждому правилу.
Комментарии объясняют, почему правило появилось и сработало ли оно.
Проанализируй и укажи:
1. Правила, чья причина больше не актуальна
2. Правила, которые по своим комментариям никогда не подтвердили эффективность
3. Правила, которые дублируют друг друга по смыслу комментария
{вставить файл с комментариями}
🚀 Быстрый старт — вставь в чат:
Вот принцип ведения файла инструкций для AI-агента (CLAUDE.md/AGENTS.md) —
рядом с каждым правилом писать скрытый комментарий: какую проблему оно решает,
какая гипотеза за ним стоит, сработало ли на практике. Комментарий не видит
исполнитель, только человек при чистке файла.
Помоги мне применить это к моему файлу: {вставь свой файл инструкций}.
Допиши комментарии к существующим правилам на основе того, что я тебе расскажу
о причине каждого — задавай вопросы по каждому правилу.
LLM спросит про историю каждой инструкции (когда добавлена, какую проблему решала) — потому что без этой информации комментарий будет пустым и не поможет при будущей чистке.
Ограничения
⚠️ Требует дисциплины на входе: метод работает только если комментарий пишется в момент добавления инструкции, когда причина ещё свежа. Если начать комментировать задним числом — эффект слабее, потому что придётся восстанавливать ту же забытую причину.
⚠️ Комментарий должен содержать результат, не только историю: исследование показало — если писать только "что пробовали" без "сработало или нет", эффект почти пропадает. Пустой нарратив без исхода — один из худших вариантов, хуже, чем вообще без комментариев.
⚠️ Не спасает от изначально плохих инструкций: метод помогает решить, что удалить, но не улучшает качество новых правил — если правило сформулировано криво, комментарий это не исправит.
⚠️ Нужен инструмент/привычка для скрытия комментариев от исполнителя: в реальном use-case важно, чтобы AI-агент, выполняющий задачу, не путал комментарий с самой инструкцией. Если вы вставляете такой файл целиком в диалог, стоит явно попросить модель игнорировать строки с комментариями.
Как исследовали
Команда взяла 1867 репозиториев на GitHub с файлами вроде CLAUDE.md и AGENTS.md и проследила 247 694 отдельные инструкции — не просто как менялся размер файла, а как жила и умирала каждая конкретная строка правил. Оказалось: файлы растут в среднем на 226% за жизнь, и чем старше инструкция, тем меньше шанс, что её удалят (а не просто перепишут вместе с остальными).
Чтобы понять причину роста, исследователи проверили три версии: правила устаревают со временем (тогда шанс удаления рос бы с возрастом), хрупкие правила умирают молодыми (тогда — падал бы через состав файла), или люди просто забывают, зачем правило появилось (тогда — падал бы именно с возрастом и сильнее при смене авторов). Данные подтвердили третью версию — забывание причины, а не устаревание задачи.
Дальше — самое интересное: чтобы проверить, работает ли комментарий, нужно знать "идеальный" размер файла инструкций (сколько правил действительно нужно), а это в реальности неизвестно. Тогда они взяли готовый бенчмарк IFEval (там заранее известно, сколько правил нужно для задачи) и вывернули его наизнанку: спрятали правильный список правил, дали модели только общее описание задачи и заставили "открывать" правила заново через пробы и ошибки — как в реальной жизни. Это позволило измерить, насколько раздутым получается файл с комментариями и без них — и комментарии сократили лишние правила почти до нуля (с +211% раздутости до +1.4%). На реальных данных (WildIFEval) те же комментарии подняли точность соблюдения правил на 23%.
Оригинал из исследования
Do not truncate or cut off your response; always
complete every sentence and thought you begin.
# r1: response was truncated mid-sentence ("A
body that you often s") suggesting response
generation stopped prematurely; may indicate token
limit, instruction conflict, or assistant aborting
output; this directive ensures responses are
complete
Контекст: Так выглядит инструкция с комментарием в реальном эксперименте — комментарий (после #) описывает конкретный провал, гипотезу и её логику. Именно такие комментарии, а не просто заметки "для порядка", дали основной эффект в исследовании.
Адаптации и экстраполяции
💡 Адаптация для персональных промптов-заготовок: Если вы храните набор промптов для повторяющихся задач (например, шаблон для деловой переписки, промпт для анализа резюме), применяйте тот же принцип — рядом с каждым добавленным условием пишите одну строку: почему это условие появилось.
Всегда указывай зарплатную вилку в вакансии, если кандидат из региона.
# добавлено 15.10: без вилки кандидаты из регионов игнорировали вакансию
# в 40% случаев (по фидбеку рекрутера); с вилкой отклик вырос
🔧 Техника: сделать комментарий обязательным полем → предотвратить накопление "мёртвого груза"
Вместо того чтобы дописывать комментарий постфактум, встройте это в сам процесс: при любом изменении файла инструкций для агента просите LLM спросить "а почему добавляем это правило?" перед тем, как записать правило в файл. Это превращает разовую технику в привычку.