Файл CLAUDE.md — текстовая инструкция, которую Claude Code читает перед каждым действием. Если описать в нём бизнес-правила, структуру папок и запреты, агент перестаёт «фантазировать» и работает по вашему регламенту. В статье разберём, как составить такой файл для реального проекта малого бизнеса, какие блоки в него включить и где чаще всего допускают ошибки. После прочтения вы сможете написать свой CLAUDE.md за вечер и сразу проверить результат.
Что такое CLAUDE.md и зачем он нужен?
Claude Code при запуске ищет файл CLAUDE.md в корне проекта. Всё, что там написано, становится частью контекста — агент учитывает эти указания при генерации кода, рефакторинге, работе с файлами. Без такого файла агент опирается только на свои общие знания и вашу текущую команду. С файлом — действует в рамках, которые вы задали.
На практическом курсе Zerocoder приводят пример «Умного реорганизатора» — ИИ-агента, который наводит порядок в рабочих документах и папках, следуя строго заданным правилам через CLAUDE.md (Zerocoder). Без инструкции агент переименовывал бы файлы по своей логике. С инструкцией — сортирует по тем папкам и с теми именами, которые приняты в компании.
Какие блоки включить в CLAUDE.md?
Универсального шаблона нет, но есть набор блоков, которые закрывают типичные задачи небольшой команды. Вот структура, от которой удобно отталкиваться:
| Блок | Что писать | Пример |
|---|---|---|
| Описание проекта | Одно-два предложения: что за продукт, для кого | «Интернет-магазин стройматериалов для b2b-клиентов в Беларуси. Цены в BYN.» |
| Стек и структура | Язык, фреймворк, ключевые папки | «Python 3.12, FastAPI. Бизнес-логика — в /app/services, шаблоны — в /templates» |
| Запреты | Чего агент делать не должен | «Не удаляй и не переименовывай файлы в /data без явной команды» |
| Стиль кода | Форматирование, именование переменных | «snake_case для функций, docstring на русском» |
| Бизнес-правила | Логика, которую нельзя нарушать | «Скидка не может превышать 15 %. Минимальная сумма заказа — 50 BYN» |
| Безопасность | Что нельзя выводить в логи или коммиты | «Не включай API-ключи в код. Храни в .env» |
Блок с запретами — самый недооценённый. Агент по умолчанию старается «помочь» и может, например, удалить дублирующий файл или переписать конфигурацию. Явный запрет в CLAUDE.md это предотвращает.
Как описать бизнес-правила, чтобы агент их понял?
Пишите конкретно и коротко. Агент лучше воспринимает правила в формате «если — то — иначе», чем абстрактные пожелания. Сравните:
- Плохо: «Учитывай специфику белорусского рынка при формировании цен»
- Хорошо: «Все цены — в BYN. При конвертации из USD бери курс из переменной EXCHANGE_RATE. Округляй до двух знаков после запятой»
Ещё пример из области аналитики. На курсе Zerocoder разбирают «Панель продаж» — скрипт, который читает данные из Excel, собирает сводную таблицу и выгружает PDF-отчёт (Zerocoder). Чтобы агент не перепутал столбцы или не поменял формулы, в CLAUDE.md прописывают: какой столбец содержит дату, какой — сумму, какой — категорию товара. Без этого агент угадывает — и угадывает не всегда верно.
Для проектов с несколькими ИИ-агентами используют ещё и файл AGENTS.md, где описывают роли: один агент пишет код, другой проверяет, третий работает с документацией. Но для малого бизнеса обычно хватает одного CLAUDE.md.
Как проверить, что агент действительно следует инструкциям?
Написать CLAUDE.md — половина дела. Вторая половина — убедиться, что агент его читает и применяет. Три простых способа:
- Дайте агенту задачу, которая конфликтует с правилом из файла. Например, попросите удалить файл из защищённой папки. Если агент откажется или спросит подтверждение — правило работает.
- Попросите агента пересказать правила проекта. Claude Code может процитировать содержимое CLAUDE.md, и вы увидите, что именно он «запомнил».
- После генерации кода проверьте, соблюдены ли конкретные ограничения: правильная валюта, корректные лимиты, нужное именование. Проверка сайта, написанного ИИ-агентом, на ошибки — отдельная задача, но начинается она с таких ручных тестов.
Типичные ошибки при составлении CLAUDE.md
- Слишком длинный файл. Контекстное окно ограничено. Если CLAUDE.md занимает 3 000 слов, агент может «выронить» правила из конца файла. Держите объём в пределах 500–800 слов, пишите только то, что агент обязан знать при каждом запуске.
- Абстрактные формулировки. «Пиши качественный код» — не инструкция. «Каждая функция — не длиннее 30 строк, покрывай тестами публичные методы» — инструкция.
- Нет запретов. Правила «что делать» работают хуже, чем правила «чего не делать». Агент изобретателен, и без явных ограничений он найдёт способ сделать «как лучше» по-своему.
- Забыли про безопасность. API-ключи, токены, пароли к базе данных — всё это агент может случайно вывести в лог или вставить в коммит. Отдельная строка «Никогда не включай значения переменных окружения в код или вывод» закрывает проблему. Подробнее о security review вайбкодинг-проекта — в отдельном материале.
- Не обновляют файл. Проект живёт, правила меняются. Если добавили новый микросервис или поменяли структуру папок — обновите CLAUDE.md в тот же день.
Code-подписка или API: на что влияет способ подключения?
Формат работы с Claude Code зависит от того, используете вы подписку или API. На Хабре разбирают, что у Claude в режиме harness фактически два пути: Code-подписка с фиксированной оплатой и API с оплатой за токены (Хабр). Для CLAUDE.md разницы в синтаксисе нет — файл работает одинаково. Но при API-доступе каждый запрос стоит денег, поэтому компактный CLAUDE.md экономит бюджет: агент тратит меньше токенов на чтение инструкций.
Если вы подключаете к Claude Code внешние инструменты — базу данных, GitHub, другие сервисы — через MCP-серверы, добавьте в CLAUDE.md блок с описанием доступных подключений и ограничений на их использование. Например: «Читай из базы данных, но не выполняй DELETE-запросы без моего подтверждения».
3 шага, которые можно сделать сегодня:
- Создайте файл CLAUDE.md в корне проекта. Опишите в двух предложениях, что за проект и на каком стеке. Добавьте три-пять явных запретов.
- Запустите Claude Code и дайте ему задачу, которая затрагивает одно из правил. Убедитесь, что агент правило учитывает.
- Через неделю работы пересмотрите файл: уберите правила, которые ни разу не пригодились, и добавьте те, которых не хватило. Живой документ работает лучше идеального черновика.
