CLAUDE.md: файл, который делает агента ветераном вашего проекта

Каждый новый диалог ИИ-агент начинает с чистого листа: он забыл ваши договорённости, запреты и всю историю проекта. Лекарство - файл-памятка в корне проекта: CLAUDE.md для Claude Code, AGENTS.md для Codex. Агент читает его на старте каждой сессии и сразу знает, куда попал и по каким правилам здесь работают.

Разница между пустой и зрелой памяткой - это разница между стажёром в первый день и сотрудником с годовым стажем. Мы ведём такие файлы для семи агентов флота и набили на этом все возможные шишки - включая памятку, которая разрослась до 118 килобайт и едва не парализовала целую сессию. Делимся выводами.

Что написать в первый CLAUDE.md

Стартовую версию делает сам агент - командой /init он осмотрит проект и составит черновик. Дальше файл растёт руками. Костяк хорошей памятки:

• Что это за проект. Два-три предложения: что за бизнес, для кого, что важно.
• Как запускать и проверять. Команды сборки, тестов, предпросмотра - агент перестанет их угадывать.
• Запреты. Что трогать нельзя: боевую базу, папку с оплатами, чужие разделы. Запреты - самая окупаемая часть файла.
• Принятые решения. «Даты храним в UTC», «тексты пишем без англицизмов» - всё, что вы уже решили и обсуждать заново без надобности.
• Словарь. Названия брендов, имена, термины, которые агент обязан писать правильно.

Формулируйте правила проверяемо

Главная ошибка памяток - пожелания вместо правил. Агент покорно кивнёт на «пиши аккуратно и качественно», но исполнить это невозможно: критерий отсутствует.

Работает переформулировка в проверяемое:

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

Обновляйте после ошибок, по расписанию это бессмысленно

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

Обратное тоже верно: правило, которое ни разу за месяцы никого ни от чего защитило, - кандидат на удаление.

Когда файл разжирел: наша история про 118 КБ

Памятка читается агентом целиком в начале каждой сессии - и её размер это налог на каждый диалог. Мы однажды позволили CLAUDE.md рабочего проекта дорасти до 118 килобайт: 80 из них занимала подробная карта файлов. Результат - агент захлёбывался: память сессии забивалась за три хода, работа встала. После разреза файла до 34 килобайт всё ожило.

Правила, которые мы с тех пор соблюдаем:

• Памятка - до 20-30 КБ. Больше - значит, внутри лежит справочник вместо правил.
• Перечисления - в отдельные файлы. Карты файлов, схемы базы, списки страниц уходят в docs/, в памятке остаётся строка-указатель: «схема базы - в docs/db.md, читать при работе с базой».
• Правила и запреты живут в памятке всегда. Их сокращают формулировкой, но выносить нельзя: вынесенное правило агент прочитает только по случаю, то есть поздно.

Принцип: памятка - точка входа и свод законов; энциклопедии место рядом, в docs/. Знания лежат рядом и подгружаются по задаче - так же, как это устроено в навыках агента.

Несколько уровней памяток

Файлов может быть больше одного, и это удобно:

• Глобальная (в домашней папке) - ваши личные правила для всех проектов: язык, тон, стиль кода.
• Проектная (в корне проекта) - всё, что описано выше.
• Локальная (в подпапке) - правила подпроекта: у папки с ботом свои команды и запреты, агент подхватит их при работе именно там.

Действует принцип матрёшки: чем ближе файл к месту работы, тем он главнее при конфликте.

Самое важное - в автоматические проверки

Текстовое правило агент способен проигнорировать - редко, но способен. Для критичного есть уровень надёжнее: проверки, которые выполняются кодом. Запрет на секреты в репозитории надёжнее закрыть автоматической проверкой перед каждым сохранением, чем строкой в памятке; требования к текстам - скриптом, который ищет запрещённые слова. Памятка говорит «как надо», автоматика гарантирует.

Частые вопросы

CLAUDE.md и AGENTS.md - нужны оба? При работе с двумя агентами - да, но содержание одно: ведите один файл, второй сделайте его копией или ссылкой. Стандарт AGENTS.md понимает всё больше инструментов.

Кто должен писать памятку - я или агент? Вместе: черновик и структуру - агент (/init), правила и запреты - вы. Формулировать записи тоже удобно через агента: «добавь в памятку правило про…».

Как понять, что памятка работает? По исчезновению повторных ошибок. Агент перестал путать бренд и трогать запретное - файл выполняет свою работу.

Что запрещено писать в памятку? Секреты: пароли, ключи, токены. Памятка попадает в репозиторий и читается каждой сессией - место секретов в .env.

Сколько времени уходит на ведение? Минуты в неделю: строка после ошибки, чистка раз в месяц. Это самые окупаемые минуты во всей работе с агентом.

Что запомнить

• CLAUDE.md - память проекта: агент читает её на старте каждой сессии и работает как сотрудник со стажем.
• Костяк: суть проекта, команды запуска, запреты, принятые решения, словарь.
• Правила формулируются проверяемо; пожелания «делай хорошо» агент теряет.
• Файл растёт после ошибок и худеет на чистках; больше 20-30 КБ - сигнал резать справочники в отдельные файлы.
• Критичные запреты дублируйте автоматическими проверками - текст советует, код гарантирует.