AGENTS.md и CLAUDE.md: что писать, чтобы агент не путался

Вы завели AGENTS.md или CLAUDE.md и постепенно сложили туда всё: архитектурные заметки, старые договорённости, правила на любой случай. Файл разросся. Агент стал путаться: тянет подход, от которого вы давно отказались, а после замечания извиняется и ломает то, что работало.

Разберемся, как писать AGENTS.md и CLAUDE.md: что на самом деле класть в файл инструкций, как подавать контекст под конкретную задачу и как формулировать правки, чтобы агент не уходил в спираль извинений.

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

Почему больше контекста не делает агента умнее

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

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

Вторая ловушка — иллюзия большого окна. Большое окно позволяет загрузить много, но не гарантирует, что агент одинаково внимателен ко всему загруженному. Важная деталь может просто потеряться среди сотни второстепенных файлов и длинных логов.

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

Что класть в AGENTS.md и CLAUDE.md, а что — нет

Файл AGENTS.md или CLAUDE.md — это постоянный контекст: агент читает его в каждой сессии. Поэтому туда стоит класть только то, что верно почти всегда, а всё, что относится к конкретной задаче, держать отдельно. Если смешать оба вида в один большой файл, агенту труднее рассуждать. Правило проекта и заметка по давно закрытому багу для него выглядят одинаково.

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

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

Как давать агенту контекст под задачу

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

1. Начните с малого. Формулировка задачи, ключевые ограничения, пара очевидно нужных файлов. Остальное — по мере надобности.

2. Спросите агента, что ему нужно. Вместо всего репозитория — вопрос: «Прежде чем что-то менять: какие файлы тебе нужны, каких сведений не хватает и какие допущения ты сейчас делаешь?» Пробелы агент назовёт сам.

3. Покажите, откуда что взято. Допустим, одно утверждение агент взял из текущего кода, а другое — из плана двухлетней давности. Если источники подписаны, он взвесит их правильно: рабочий код важнее старого документа.

4. Проверьте противоречия до кода. Перед реализацией попросите: «Просмотри контекст и перечисли противоречащие друг другу инструкции и устаревшие допущения. Код пока не меняй». Так конфликт всплывёт раньше, чем станет кодом.

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

Почему приказ «исправь» запускает спираль извинений

Вторая половина проблемы — не что вы даёте агенту, а как с ним говорите. Представьте: вы замечаете ошибку и пишете короткую команду вроде «тут баг, исправь». Агент рассыпается в извинениях, правит одну строку и ломает что-то рядом. Вы поправляете снова — он снова извиняется и добавляет защитные обёртки, которые ломают уже другое.

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

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

Вопрос вместо команды: как формулировать правки

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

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

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

Вопрос не обязан содержать ответ. Достаточно перевести подозрение — «что-то тут не так с жизненным циклом» — в сценарий, который агент должен прогнать в голове.

Запреты в инструкциях и вопрос перед правкой

Отдельная боль — правки «заодно». Вы просите исправить три строки, а агент попутно переименовывает переменные и переписывает соседние модули. Первая реакция — дописать в запрос «не трогай остальной код» заглавными буквами.

Есть гипотеза, что такой запрет может сработать наоборот: он фокусирует внимание модели как раз на «остальном коде» и затягивает его в работу. Важное ограничение: механизм не доказан, это рабочее объяснение. Но на практике окрик посреди задачи часто не помогает.

Вместо запрета можно добавить в конец запроса вопрос — такой приём тоже описывал Марк Хеджес. Спросите агента, станет ли риск регрессий ниже, если он сосредоточится только на этом решении и не будет трогать другие проблемы, замеченные по пути. Агент сам приходит к выводу, что маленький дифф — набор изменений в коде — безопаснее, и строит план под него. Огромный дифф разбирать не придётся.

Ключевые термины

• Постоянный контекст — Правила, верные почти всегда: стандарты кода, границы архитектуры, правила безопасности и именования.
• Задачный контекст — Сведения, нужные только для текущей работы: один баг-репорт, одно требование, один модуль или набор логов.
• Минимально достаточный контекст — Объём информации, которого хватает агенту для правильного решения, без всего остального, что есть в проекте.
• Прогрессивное раскрытие контекста — Подход, при котором агент начинает с минимума и получает новые файлы, только когда задача их требует.
• Спираль извинений — Цикл, в котором агент на каждое замечание извиняется, латает симптом и вносит новые ошибки, засоряя контекст.
• Премортем-вопрос — Вопрос перед правкой, который заставляет агента заранее оценить риск регрессий от объёма изменений.

Итог: короткие правила, контекст по задаче, вопросы вместо приказов

Проверьте файл инструкций и привычки работы с агентом по короткому списку:

• В AGENTS.md или CLAUDE.md остались только правила, верные почти для любой задачи.
• Заметки по конкретным багам, миграциям и инцидентам вынесены из постоянного файла.
• У временных правил есть условие, когда их удалить.
• Задачу вы начинаете с малого контекста и спрашиваете агента, чего ему не хватает.
• Перед реализацией агент перечисляет противоречия и устаревшие допущения.
• Правки вы формулируете вопросами о последствиях, а не командами.
• Вместо запрета «не трогай лишнее» вы просите агента оценить, снизит ли узкая правка риск регрессий.

Проверьте себя

1. Что из этого стоит держать в AGENTS.md постоянно? (Верных ответов несколько.)

• А. Логи вчерашнего инцидента
• Б. Временный обходной путь на время миграции без срока окончания
• В. Правило «не добавлять зависимости без согласования»
• Г. Соглашения об именовании

2. В README сказано держать логику в обработчиках, а в AGENTS.md — в сервисах. Что разумнее сделать перед задачей?

• А. Положиться на то, что агент сам выберет правильный вариант
• Б. Попросить агента перечислить противоречия в контексте и устранить их до правок
• В. Добавить третий документ с пояснением

3. Агент оставил в коде утечку подписки. Какая формулировка вероятнее приведёт к надёжному исправлению?

• А. «Отмени подписку в строке 42»
• Б. «В твоём коде утечка, исправь немедленно»
• В. «Что произойдёт с подпиской, если пользователь уйдёт со страницы во время запроса?»

4. Почему устаревший контекст может быть опаснее отсутствующего?

• А. Он занимает больше токенов
• Б. Агент всегда игнорирует старые файлы
• В. Он даёт агенту уверенность в неверном решении, а не сомнение

5. Вы спросили агента о возможной проблеме, а он объяснил, что она уже решена в другом месте. Что делать?

• А. Всё равно приказать внести правку
• Б. Принять ответ, если объяснение сходится с кодом
• В. Начать новую сессию, чтобы агент «забыл» спор