5 ошибок в CLAUDE.md, которые я сделал за полгода

Использую CLAUDE.md с ноября 2024 года. За это время успел наступить на все грабли, на которые только можно. Вот пять конкретных ошибок, которые стоили времени и денег.

Ошибка 1: Засунул всё в один файл

К марту файл вырос до 40к символов. Архитектурные решения, стайл-гайд, правила тестирования, примеры промптов, доменная модель, онбординг. Всё это съедало 13% контекстного окна на каждый запрос. Claude начал «забывать» вещи из середины файла, потому что трансформер физически хуже удерживает контекст в середине.

Починил просто: CLAUDE.md только постоянный контекст, до 8к символов. Остальное в отдельные файлы, загружаются по запросу.

Ошибка 2: Писал «как надо» вместо «что нельзя»

«Используй Clean Architecture», «следуй DDD», «пиши читаемый код». Claude кивал и делал по-своему. Переформулировал в запреты: «Не используй any в TypeScript», «Не создавай сервисы с зависимостями от конкретных реализаций». Следующий же день показал разницу.

Ошибка 3: Не добавил антипаттерны явно

Написал «мы используем NestJS», но не написал «мы не используем class-validator для бизнес-валидации, только на уровне DTO». Claude честно добавлял его куда попало, потому что это «правильный NestJS». Теперь раздел «Запрещено» занимает треть файла.

Ошибка 4: Обновлял раз в квартал

Перешли с Express на NestJS в феврале, обновил CLAUDE.md только в апреле. Два месяца файл врал, и Claude иногда предлагал Express-паттерны. Теперь правило: любое архитектурное решение, принятое на ревью, идёт в CLAUDE.md в тот же день.

Ошибка 5: Не добавил примеры кода

«Используй Repository pattern» работает хуже, чем «Используй Repository pattern вот так:» плюс три строки реального кода из проекта. Без примера Claude угадывает что вы имеете в виду. Угадывает плохо.

После всех исправлений: файл 6к символов, ответы точнее, меньше правок на ревью.

Какую ошибку делали чаще всего?