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к символов, ответы точнее, меньше правок на ревью.

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

archkit v0.1 — генератор TypeScript-библиотек с Clean Architecture: от спека до npm за один день

Неделю назад опубликовал на npm первый пакет, @autosergach/archkit. Одна команда:

npx @autosergach/archkit create my-lib

И получаешь TypeScript-библиотеку с Clean Architecture из коробки: domain, application, ports, рабочий use case и пять зелёных тестов. Не «hello world», а каркас который показывает как слои должны выглядеть. Ниже как это устроено и четыре грабли по дороге к npm publish.

Что внутри

my-lib/
├── src/
│   ├── domain/      # User, DomainError
│   ├── application/ # createUser use case
│   ├── ports/       # UserRepository interface
│   └── index.ts
├── tests/           # InMemoryUserRepository + 5 тестов
└── package.json     # ESM, strict TS, vitest 3, eslint 9

pnpm install && pnpm test, пять зелёных с первого запуска. Стек намеренно современный: ESM only, Node 20+, TypeScript 5.7+, vitest 3.2, eslint 9 flat config.

Архитектура изнутри

Забавно, что archkit изнутри устроен точно так же, как проект который генерирует: порты и адаптеры до мозга костей. Монорепо: приватный archkit-core (весь движок) и @autosergach/archkit (то что на npm). tsup бандлит core через noExternal, потребитель ставит один пакет.

FileSystemPort с двумя адаптерами: InMemoryFileSystemAdapter для тестов и NodeFileSystemAdapter для продакшена. Pipeline в три шага: buildInitPlan, renderTemplate, executePlan. С --dry-run третий шаг не выполняется.

Тесты: 35 + 3

35 unit-тестов гоняют весь движок через in-memory, без диска, меньше секунды на весь suite. 3 e2e-теста запускают настоящий pnpm install && pnpm test в os.tmpdir(). Именно они дают уверенность что сгенерированный проект работает у пользователя, и поймали несколько багов в шаблоне до публикации.

Один день с Claude Code

Весь v0.1.1, от пустой папки до npm publish, написал за одну сессию, примерно шесть часов. 9 атомарных коммитов: Claude Code писал код, я проверял и коммитил. До Claude Code такой объём занял бы неделю, и тесты я бы срезал.

4 урока из npm publish

1. cac и --no-X флаги. При --skip-install cac выставляет skipInstall: true по умолчанию, неявно. Фикс: проверять === true, а не !== undefined. Потерял час пока разобрался.

2. npm проверяет similarity, а не только занятость. archkit свободное имя, но npm отклонил из-за заброшенного arch-kit (2022, 12 загрузок). Ушёл в scoped namespace @autosergach/archkit, зато все следующие пакеты там же.

3. workspace:* в dependencies. Приватного archkit-core нет в registry. Если он в dependencies, npm падает при install у потребителя. Перенести в devDependencies, tsup бандлит его в dist.

4. Granular npm tokens и 2FA. Granular-токен с правами publish не проходит без «Bypass 2FA for publish». Опция выключена по умолчанию, нигде не выделена жирным. Получил 403.

Что дальше

v0.2: NestJS плюс React fullstack шаблон и --ai-ready флаг, который автогенерирует CLAUDE.md, .claude/settings.json, agents.md. Пишите в Issues если есть что сказать.

npm: https://www.npmjs.com/package/@autosergach/archkit
GitHub: https://github.com/autosergach/archkit

npx @autosergach/archkit create my-lib
cd my-lib && pnpm install && pnpm test
# → 5 passing

Понял кое-что про CLAUDE.md после полугода в продакшене.

Пока файл маленький, всё работает. Потом он вырастает до 30-40 правил, и начинается: агент читает всё разом и выбирает интерпретацию которая ему удобнее. Три правила про тесты противоречат друг другу. «Никогда не делай X» конкурирует с «всегда делай X для случаев Y».

Решение которое у нас заработало: корневой CLAUDE.md только для жёстких инвариантов (что никогда нельзя, архитектурные решения). Всё остальное переехало в slash-команды и вложенные CLAUDE.md. Правило грузится только когда нужно, не конкурирует с соседями.

Плоский файл на 50 правил, это не инфраструктура, это эссе. Эссе никто не исполняет буквально.

Как вы с этим справляетесь в своих проектах?