Есть один файл, который заводят почти все, кто работает с кодинг-агентами, и почти все заводят его криво. Называется CLAUDE.md, или AGENTS.md, или .cursorrules, от имени суть не меняется. Идея звучит здорово. Пишешь агенту правила один раз, и он перестаёт каждый день переспрашивать, какой у тебя стек и через что гонять тесты. А на практике выходит ровно наоборот. Человек запихивает в файл пятьсот строк "полной документации проекта", агент от этого тупеет, и задачи начинают валиться чаще, чем вообще без файла. Сейчас разберём, почему так выходит и как перестать стрелять себе в ногу.
это не README, это записка для робота
Аналогия, которая сразу всё расставляет по местам. Ты нанял удалённого разработчика, толкового, но у него первый день в проекте. Можно каждый раз заново диктовать "у нас Node, тесты через npm test, config.prod не трогай, миграции только через make migrate". А можно один раз написать памятку "правила нашей кухни" и больше не повторяться. CLAUDE.md это вторая история, текстовый файл в корне проекта, который агент читает сам перед каждой задачей. И вот что тут важно: README пишут для людей, а файл для агента пишут для машины. Жанры разные, не стоит их путать и тем более дублировать один в другой.
Маленькая деталь, про которую обычно молчат. У всех агентов файл по сути одинаковый, меняется только имя. Claude Code читает CLAUDE.md, OpenAI Codex и Amp читают AGENTS.md, Cursor берёт правила из .cursor/rules, Gemini CLI смотрит в GEMINI.md. В августе 2025 OpenAI, Google, Cursor, Factory и Sourcegraph скинулись и сделали общий стандарт AGENTS.md, его уже читают больше двадцати тысяч репозиториев. Так что вместо зоопарка файлов-близнецов держи один AGENTS.md, а остальные подружи с ним симлинком. Claude Code, правда, сам AGENTS.md пока не подхватывает, ему нужен костыль:
ln -s AGENTS.md CLAUDE.md # симлинк: один файл, два имени
@AGENTS.md # или строка-импорт внутри CLAUDE.md
почему длинный файл делает агента глупее
Всем хочется описать проект до последнего винтика. Вот это и есть та самая яма. У агента, как у живого человека, внимание ограничено. Сунешь ему в начало диалога пятьсот строк, он честно прочитает первые тридцать и последние тридцать, а середину молча пролистает. И не предупредит, что забыл, просто сделает по-своему. Называется эта штука context rot, гниение контекста.
Цифры отрезвляют. Anthropic советует держаться в пределах 150-200 строк, а по факту лучше всего работает 50-100 строк плотного текста, всё что сверху это балласт, который жжёт токены и не приносит пользы. Исследование ETH Zurich за февраль 2026 на двух с половиной тысячах репозиториев показало вещь, от которой многие дёрнутся: плохой файл хуже, чем его отсутствие. Машинно-сгенерированный через /init снижает успех задач на три процента. А написанный руками, по делу, поднимает на четыре. Вывод простой как палка, тридцать строк по существу бьют триста строк для галочки.
что туда писать и что нельзя
Фильтр простой. Пиши только то, что нельзя угадать из самого кода. Команды запуска, версии стека, ловушки, ваши внутренние договорённости. Вот рабочий минимум, который закрывает большинство проектов:
# Что за проект
Telegram-бот для записи на стрижку. Python + aiogram + PostgreSQL.
# Как запускать
- Установить: poetry install
- Запустить локально: make dev
- Тесты: pytest
- Линтер: ruff check
# Правила
- Логирование через loguru, не print
- Все деньги храним в копейках (int), не в рублях (float)
- Миграции БД только через alembic revision --autogenerate
# Чего не делать
- Не трогать bot/db/migrations/ это автогенерация
- Секреты только в .env, никогда в коде
- При работе с прод-БД спроси меня сначала
А теперь грабли, на которые наступают по кругу. Не дублируй README, агент его и так прочитает. Выкини generic-советы вроде "пиши чистый код" и "следуй best practices", этому его уже научили при обучении, такие фразы только воруют место. Не ставь запреты без альтернативы. "Никогда не используй console.log" оставляет агента в тупике, он будет каждый раз переспрашивать, а "для логов бери src/utils/logger.ts" это уже нормальная инструкция. И, бога ради, убери капс с драматизмом. Современная модель от "CRITICAL: YOU MUST NEVER!!!" начинает нервничать и обмазывать весь код лишними защитными обёртками.
критичное тексту доверять нельзя
Вот тут начинается взрослый разговор. На GitHub есть реальный кейс. Человек написал в файле "NEVER COMMIT API KEYS", капсом, с эмодзи, всё как положено. Агент за один день трижды закоммитил живые ключи в публичный репозиторий. А на прямой вопрос "ты что, файл не читал?" ответил гениально: прочитал, мог выполнить, и всё равно не выполнил. Запомни эту цифру, агент слушается текста процентов на восемьдесят, не больше.
Поэтому всё, что реально критично, выноси не в уговоры, а в хуки. Хук это скрипт, который срабатывает на сто процентов, до или после действия. Агент полез править .env, хук PreToolUse это увидел, вернул ошибку и заблокировал. Никакой капс в файле так не отработает. По той же логике длинные процедуры, типа деплоя со сборкой, тестами, пушем и тегами, не пихай в основной файл. Заведи отдельный Skill, который подгружается только когда нужен, а в CLAUDE.md оставь одну строчку-триггер.
разнеси по модулям и сэкономишь деньги
Эталон лаконичности это репозиторий cline/cline, шестьдесят две тысячи звёзд на GitHub. Их CLAUDE.md это две строки, которые просто маршрутизируют на подмодули, а настоящие правила подгружаются по необходимости. И обратный пример с Reddit: у человека файл жёг двадцать две тысячи токенов ещё до первого сообщения, это примерно двадцать центов за каждый запрос на ровном месте. Разбил на модули, стало тысяча восемьсот. Экономия в двенадцать раз, на пустом месте.
И последнее, что стоит зашить в привычку. Не пиши правила заранее, на всякий случай, иначе файл превратится в кладбище инструкций против багов, которых ещё не было. Жди, пока агент два раза подряд накосячит одинаково, вот тогда добавляй строку. А проверить, читает ли он файл вообще, можно одним фокусом: припиши в самом конце "всегда обращайся ко мне Шеф". Перестал обращаться через десять сообщений, значит файл вылез за лимит внимания, режь.
Так что если твой файл-инструкция перевалил за две сотни строк, поздравляю, ты пишешь его не для агента, а для собственного спокойствия. Лучший CLAUDE.md это тот, который влезает на один экран и не врёт ни строчки. Остальное модель додумает сама, для этого её и делали.