Семь ошибок в CLAUDE.md, которые тихо ухудшают качество вывода Claude Code

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

Ошибка 1: расплывчатое описание стека

Фраза вроде Mы используем React и базу данных. почти ничего не говорит Claude. Он будет догадываться о использовании роутера Next.js, выбирать библиотеку состояния примерно наугад и писать тесты в фреймворке, который вы не используете. Результат скомпилируется, но всё равно не будет соответствовать вашей кодовой базе.

Вместо этого укажите всё подробно:

Framework: Next.js 15, app router only
State: TanStack Query v5 for server state, Zustand for client state
Testing: Vitest + React Testing Library
Package manager: pnpm

Точные версии и стандарты превращают общий результат в код, который кажется частью вашего репозитория. Укажите их названия.

Ошибка 2: отсутствие ограничений, отсутствие правила «никогда этого не делать»

Это самая распространённая скрытая ошибка. Люди описывают проект, но так и не устанавливают чётких границ. При отсутствии ограничений Claude запускает npm в проекте pnpm, редактирует сгенерированные файлы и переписывает код, о котором вы не упоминали. Это не галлюцинации — это разумные предположения, сделанные из-за отсутствия противоположных правил.

Добавьте блок с ограничениями:

Constraints:
- Never install new dependencies without asking first
- Never edit files under /generated or /prisma/migrations
- Always use pnpm, never npm or yarn
- Do not refactor code outside the scope of the current task

Правила о том, чего не следует делать, дают больше результатов, чем просто описания, потому что они предотвращают дорогостоящие ошибки ещё до их возникновения.

Ошибка 3: игнорирование агентов и субагентов

Большинство файлов CLAUDE.md написаны так, будто одна модель работает самостоятельно, без указаний относительно специализированных субагентов, выполняющих задачи параллельно с основной сессией. Если вы используете субагентов для тестирования, создания документации или развертывания, укажите это в файле: перечислите каждого агента, сферу его ответственности и ситуации, в которых основной агент должен передавать ему задачи.

Agents & delegation:
- test-agent: runs Vitest, owns /tests — do not write tests in the main session
- docs-agent: handles JSDoc and README updates only
- main agent: feature code, routing, API handlers

Если вы всё ещё разрабатываете модель делегирования, будет полезно понять, чем отличаются навыки, субагенты, команды вида slash и MCP, прежде чем выбрать оптимальную структуру.

Ошибка 4: чрезмерно объёмный файл, исчерпывающий лимит контекста

Больше не значит лучше. Файл CLAUDE.md объемом 2 000 строк, заполненный полными руководствами по стилю, документацией к API и журналами изменений, загружает всё это в каждую сессию — независимо от того, нужно ли это или нет. Это мешает выполнять основную задачу, и поскольку способность к концентрации снижается при наличии избыточной информации, в итоге у вас получается модель, которая технически прочитала ваши правила, но всё равно не может их корректно применять.

Оставьте только самое необходимое. Укажите файлы или разделы, где хранятся детали, вместо того чтобы вставлять их напрямую. Правило, касающееся одного пакета, должно находиться в соответствующем файле, а не в корневой директории. Посчитайте количество токенов в файле до и после упрощения, чтобы убедиться, что изменения действительно помогли.

Ошибка 5: инструкции, которые Claude не может выполнить

Возьмем пример Напиши чистый, поддерживаемый и качественный код. Claude уже считает, что делает это, поэтому расплывчатые прилагательства не оказывают никакого влияния. Замените их на конкретные правила, которые можно проверить:

- Functions must be under 40 lines
- No default exports
- Colocate test files next to source files
- No inline styles — use CSS modules

Регламенты работы предоставляют модели четко определенную цель для достижения. Амбициозные формулировки такой цели не дают.

Ошибка 6: устаревшие правила, противоречащие коду

Проблема устаревания файла CLAUDE.md действительно существует. Представьте, что через шесть месяцев после перехода команды на Zustand в файле по-прежнему указано «использовать Redux». Такое правило не остается безвредным: оно противоречит фактическому коду, и Claude постоянно меняет свою ориентацию между верой в одно из них и другим.

Проверяйте файл каждый раз, когда зависимости существенно меняются, и включите эту проверку в список задач для PR. Храните информацию об изменениях в Git, чтобы видеть, когда было последнее изменение каждого правила. Устаревший файл CLAUDE.md часто бывает хуже, чем его отсутствие вовсе.

Ошибка 7: один огромный неструктурированный файл

В монорепозитории единственный неструктурированный файл CLAUDE.md заставляет Claude применять правила фронтенда к коду бэкенда и наоборот. Когда все объединено в один неразделенный блок, становится невозможным определить контекст применения правил.

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

# Project Overview
# Stack & Versions
# Constraints
# Agents & Delegation
# Per-Package Notes

Структура указывает Claude, какие правила применимы где.

Быстрая проверка и чек-лист

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

Рассмотрите следующие вопросы:

• Указаны ли точные версии фреймворков и библиотек?
• Есть ли раздел с ограничениями, содержащий строгие правила вида «никогда этого не делайте»?
• Перечислены ли существующие агенты и что принадлежит каждому из них?
• Количество строк меньше 200, причем детали вынесены в отдельные навыки или связанные файлы?
• Все инструкции являются практическими, а не умозрительными?

Кто-нибудь проверял его на наличие устаревших правил за последние 30 дней?

Является ли он структурированным по заголовкам или по отдельным файлам в рамках каждого пакета, если используется монорепозиторий?

Если вы ответили «нет» более чем на два из этих вопросов, ваш CLAUDE.md, скорее всего, стоит вам дороже, чем приносит пользы.