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

Агент из коробки знает язык, фреймворки и общие практики. Дальше начинается твой проект: тесты тут запускаются одной командой, папку legacy трогать нельзя, версия фреймворка разошлась с тем, на чём модель училась. Всё это живёт в голове команды. CLAUDE.md — место, куда это выкладывают текстом.

Что это за файл

CLAUDE.md лежит в корне репозитория и подгружается в контекст перед началом работы. Никакой магии: обычный markdown, который агент читает как инструкцию от заказчика. Отличие от сообщения в чате — файл действует всегда: во всех сессиях, у всех, кто открывает проект.

У меня там одна строка

Мой CLAUDE.md выглядит так:

@AGENTS.md

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

Правило, которое спасает чаще остальных

Самый рабочий блок из моего файла:

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file
structure may all differ from your training data. Read the relevant
guide in `node_modules/next/dist/docs/` before writing any code.
Heed deprecation notices.

Почему это бьёт сильнее, чем просьба «используй актуальное API»:

• Прямо бьёт по ложной уверенности. Модель обучена на прошлых версиях и выдаёт устаревший код уверенно, без тени сомнения в голосе. Заголовок капсом в теле файла (в отличие от заголовка статьи) тут уместен: он ломает автопилот.
• Даёт конкретный адрес источника. Путь node_modules/next/dist/docs/ агент откроет прямо сейчас. Расплывчатое «посмотри документацию» так не работает.
• Требует действия до написания кода. Порядок операций задан явно: сначала читаем, потом пишем.

Любое правило в CLAUDE.md стоит прогонять по этим трём пунктам. Формулировка без источника и без момента действия — украшение.

Что стоит положить

• Команды. Запуск тестов, линтера, дев-сервера, миграций. Точные строки, которые копируются как есть.
• Расхождения с ожиданиями модели. Форк вместо оригинала, экзотическая версия, самописный слой поверх популярной библиотеки.
• Границы. Куда писать нельзя: сгенерированный код, вендоренные зависимости, чужой модуль.
• Соглашения, которые из кода не выводятся. Почему тут два клиента API, зачем дубль конфига, какой из двух похожих хелперов живой.
• Пути к внутренним докам. Один абзац со ссылками экономит десяток поисковых заходов.

Что класть бессмысленно

• Пересказ структуры папок. Агент увидит её сам за две секунды, и твой пересказ устареет к ближайшему рефакторингу.
• Общие лозунги. «Пиши чистый код», «следуй best practices» — шум, который разбавляет рабочие правила.
• То, что проверяет линтер. Правило в CLAUDE.md исполняется вероятностно. Конфиг ESLint исполняется всегда. Форматирование, порядок импортов, длина строки — работа тулинга.
• Простыни на пятьсот строк. Чем длиннее файл, тем ниже шанс, что конкретная строка сработает. Файл конкурирует за внимание с самим кодом.

Как писать формулировки

Императив и конкретика. Сравни:

• Слабо: «постарайся использовать актуальные API роутинга»
• Сильно: «Перед правкой роутов прочитай node_modules/next/dist/docs/routing.md»

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

Как этот файл ведут

Садиться и писать идеальный CLAUDE.md с нуля — пустая трата вечера. Файл растёт по факту ошибок.

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

Нужно и обратное движение. Раз в пару недель пройдись по файлу и вычисти правила про то, что уже починено в коде. Обходной манёвр вокруг давно закрытого бага теперь просто мешает.

Проверка, что файл работает

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

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