Коротко
Почему агент каждый раз начинает с нуля
Он не тупой. Он слепой.
Вот типичная картина. Ты второй месяц работаешь с ИИ-агентом, наладил ритм, и всё равно каждый новый чат начинается одинаково: «у меня проект на таком-то стеке, пакеты ставим вот так, не трогай эту папку, коммить только по моей команде». Пять минут пересказа. Потом задача. И так по десять раз в день.
На практике это значит одно: ты работаешь личной памятью для агента. Дорогая роль для человека, у которого есть дела поважнее.
Разберём простым языком, почему так происходит. У модели есть контекстное окно - то, что она держит перед глазами прямо сейчас. Между сессиями оно обнуляется. Агент не «забыл» твои правила, он их вообще никогда не видел в этой сессии. Всё, что ты рассказал вчера, для него не существует.
И вот тут самое интересное: лечится это не более умной моделью и не более длинным промптом. Лечится файлом.
Что такое CLAUDE.md простыми словами
CLAUDE.md - это обычный файл в формате Markdown, который лежит в корневой папке проекта. Claude Code подхватывает его сам, без напоминаний: агент открывает файл до того, как возьмётся за твою задачу. То же самое умеют и другие агенты - у каждого свой файл-память, механика одинаковая.
Я объясняю это ученикам так: представь, что к тебе вышел новый сотрудник. Очень способный, но про твою компанию не знает ничего. Ты можешь каждое утро объяснять ему, где кухня и по каким правилам мы живём. А можешь один раз выдать трудовой договор и карту офиса - и дальше он работает сам.
CLAUDE.md - это и есть договор с картой. Один раз написал - агент читает его в каждой сессии.
Не путай две разные вещи. CLAUDE.md - твои инструкции агенту: правила, которые ты задал сознательно. Автопамять - заметки агента про тебя, которые он копит сам. Первое ты контролируешь полностью, второе - побочный продукт работы. Настоящий контроль даёт именно файл.
Это частный случай большой дисциплины - контекст-инжиниринга. Если коротко, суть такая: качество результата определяет не формулировка запроса, а то, что агент видит перед глазами. Подробно я разбирал это в статье про то, почему дело не в промпте, а в папке. CLAUDE.md - первый файл этой папки и самый важный.
Осталось понять, что именно в него писать. Тут большинство и промахивается.
Что писать внутрь: семь блоков
Первое, что делает новичок, - пишет в файл «будь профессиональным разработчиком, пиши качественный код». Это пустая строка: она не меняет поведение агента ни на грамм. Работают только конкретные, проверяемые вещи.
Вот семь блоков, которые реально влияют на результат.
1. Что за проект и для кого. Две-три строки: что мы строим, кто пользователь, какая задача решается. Без этого агент предлагает технически красивые решения, которые не нужны твоему бизнесу.
2. Стек и команды. Какой фреймворк, какая база, какой пакетный менеджер. И главное - как запускать. Пример из моего собственного проекта: движок статей, где вместо привычного мне менеджера пакетов нужен другой, родной для этого репозитория. Одна строка «здесь npm, не pnpm - иначе сломается сборка» экономит по часу на каждой ошибке.
3. Структура папок. Куда что кладём: планы сюда, черновики сюда, документы клиентов вот сюда. Агент без карты создаёт файлы там, где ему удобнее, и через месяц ты не находишь собственные материалы.
4. Правила работы. Как мы вообще ведём проект. Мои, например: большая задача - сначала план в отдельном файле; после каждой готовой фичи прогнать пять проверок; добавлять файлы в коммит поимённо, а не всё подряд.
5. Красные линии. Что агенту нельзя ни при каких условиях: не читать файлы с ключами и паролями, не удалять без подтверждения, не выкладывать в интернет без прямой команды. Это не паранойя, а гигиена: агент работает быстро и уверенно, в том числе когда ошибается.
6. Навигация по деталям. Не пересказывай в файле всю документацию - дай маршрут: «нужны цены - смотри такой-то файл», «нужен голос бренда - вот этот». Агент дойдёт сам.
7. Выученные ошибки. Самый ценный блок, про него отдельно ниже.
Ключей, паролей, токенов, номеров карт, персональных данных клиентов. CLAUDE.md - обычный текстовый файл, он уезжает в репозиторий вместе с кодом и попадает в контекст каждой сессии. Секреты живут в отдельном защищённом файле, который агенту читать запрещено.
Готовый скелет, который можно скопировать
Не изобретай форму. Возьми этот скелет, замени содержимое на своё - и файл готов за полчаса.
# Проект: <название>
## Что это
Что строим, для кого, какую задачу решает. 2-3 строки.
## Стек и команды
- Технологии: <фреймворк, база, хостинг>
- Пакетный менеджер: <какой именно и почему>
- Запуск: <команда>
- Сборка перед публикацией: <команда>
## Структура
- plans/ - планы больших задач
- docs/ - документация
- <папка> - <что внутри>
## Как мы работаем
- Большая задача (больше часа) - сначала план в plans/, потом код.
- После каждой фичи - самопроверка: ошибки, упущенное, безопасность.
- Файлы в коммит добавляем поимённо.
## Красные линии
- Не читать файлы с ключами и секретами.
- Ничего не удалять без моего подтверждения.
- Не публиковать наружу без прямой команды.
## Куда смотреть за деталями
- Цены и условия - <файл>
- Голос бренда и тон - <файл>
- Данные о клиентах - <файл>
## Выученные правила
- <ошибка, которая уже случалась> -> <как делать правильно>Заметь, чего тут нет: длинных объяснений, философии, описания архитектуры на три экрана. Только то, что меняет поведение агента.
А теперь про три правила, которые отличают рабочий файл от мёртвого груза.
Три правила, без которых файл начинает вредить
Правило 1. До 200 строк. Файл читается в каждой сессии и занимает место в контекстном окне. Раздул до полутора тысяч строк - агент начинает хуже думать, а лимиты тают быстрее. Мой личный потолок - 200 строк, и я его держу осознанно: как только упираюсь, выношу детали в отдельные файлы.
Правило 2. Роутинг вместо содержания. CLAUDE.md - оглавление, а не книга. Вместо трёх экранов про целевую аудиторию пишешь одну строку: «портрет аудитории - в файле audience.md». Агент откроет, когда понадобится. Так контекст остаётся чистым, а глубина не теряется.
Правило 3. Никаких меняющихся цифр. Цены, метрики, состав команды, дедлайны - всё это протухает, а агент будет уверенно повторять устаревшее полгода спустя. Держи такие данные в одном живом файле-источнике, а в CLAUDE.md ставь только ссылку на него.
Проверка на здоровье файла простая, и её же рекомендует официальная документация: пройди по строкам и спроси себя про каждую.
Пиши коротко. По каждой строке спрашивай: «Если убрать это, Claude начнёт ошибаться?» Если нет - вырезай. Из-за раздутых файлов CLAUDE.md Claude игнорирует твои настоящие инструкции.
Признак, что файл перерос сам себя: ты уже прописал правило, а агент всё равно делает по-своему. Обычно это не упрямство модели, а потеря правила в шуме.
Как наполнять файл: ошибки превращаются в правила
Вот здесь начинается настоящая работа с памятью агента, и её почти никто не делает.
Схема простая. Агент сделал не так, как ты хотел. Ты не просто поправил его в чате - ты сформулировал правило и дописал строку в CLAUDE.md. Всё. Одна ошибка - одна строка.
Заметил промах
Агент сделал не то: не тот формат, не та папка, полез туда, куда не просили.Сформулировал правило
Одним предложением, в повелительном наклонении: «что делать» или «чего не делать».Дописал строку
В блок «Выученные правила». Коротко, без объяснений на абзац.Проверил в новой сессии
Открыл новый чат, дал похожую задачу. Правило сработало - оставляем.
У меня в проектах так накопились самые полезные строки. Например: «перед публикацией запускай полную сборку, а не только проверку типов - линтер ловит то, что проверка типов пропускает». Это не теория из документации. Это след от конкретного падения на боевом сервере.
На практике это значит вот что: файл, который ты ведёшь два месяца, стоит дороже любого золотого промпта из интернета. Промпт универсальный, а файл - про твой проект и твои грабли.
Отдельно про формат правила. Пиши так, чтобы его можно было проверить. «Будь аккуратнее с базой» - мусор. «Не запускай миграции на боевой базе без моего подтверждения» - правило.
Дальше сам собой возникает вопрос: если файл такой полезный, почему бы не завести один большой на все проекты?
Один файл на проект или один на всё
Claude Code читает память с нескольких уровней сразу: есть личный файл, который подключается во всех твоих проектах, и есть файл конкретного проекта. Работает это как слои: сначала общее, потом частное.
| Уровень | Что кладём | Пример |
|---|---|---|
| Личный (общий для всех проектов) | Кто ты, как с тобой общаться, сквозные предпочтения | «Отвечай по-русски, на ты. Оспаривай слабые решения» |
| Проектный (в корне проекта) | Стек, структура, правила и красные линии проекта | «Здесь npm, не pnpm. Не пушить без команды» |
Логика деления простая: если правило верно во всех твоих проектах - оно личное. Если только в этом - проектное. Не тащи специфику одного проекта в общий файл, иначе агент начнёт применять её там, где она вредит.
И ещё одно. CLAUDE.md - это не весь второй мозг проекта, а его входная дверь. За ней - папки с контекстом: кто ты, что за бизнес, какие методологии используешь. Как это устроено целиком, я разбирал в гайде про вайбкодинг для предпринимателя, а сам инструмент - в статье про то, что такое Claude Code.
Частые вопросы
Частые вопросы
Главный вывод
Если коротко, суть такая. Большинство людей, работающих с ИИ-агентами, каждый раз объясняют заново, кто они и что делают, - и упираются в потолок «модель тупая». Модель не тупая. Ей просто не дали контекст.
CLAUDE.md - это тот самый контекст в самой дешёвой форме: один текстовый файл, полчаса на первую версию, дальше по строке после каждого промаха. Ты перестаёшь быть памятью агента и становишься тем, кто задаёт правила. Роль другая, и результат другой.
Ошибки, кстати, продолжатся - и это нормально. Разница в том, что теперь каждая из них делает твой проект сильнее, а не повторяется по кругу. Если хочется системнее посмотреть на проверку результатов работы агента - читай про то, как ловить его галлюцинации.
Как думаешь: файл-память агента - это временный костыль, пока модели не научились помнить всё сами, или постоянная часть работы, такая же обязательная, как регламент для команды?