CLAUDE.md правильно: ≤200 строк

Что такое CLAUDE.md

Это файл в корне проекта (или в .claude/CLAUDE.md), который Claude читает первым при старте каждой сессии. Он загружается прямо в системный промпт. Всё что там написано — Claude выполняет. Каждую сессию. Стабильно.

Пишешь "всегда писать тесты перед реализацией" — будет писать. Пишешь "никогда не использовать console.log, использовать кастомный логгер" — будет следовать каждый раз.

Правило №1: ≤200 строк (идеально 150)

Типичное полевое наблюдение: "CLAUDE.md на 400 строк — половина инструкций игнорируется. Сокращаешь до 150 — всё начинает работать лучше."

Почему:

• Длинные файлы тратят токены в каждом сообщении
• Модель хуже следует раздутым инструкциям
• Контекст нужен для работы с кодом, а не для чтения манифестов

Что писать

✅ Команды сборки/тестов/линтера

npm run dev
npm run test
npm run lint
npm run build

✅ Ключевые архитектурные решения

"Монорепо с turborepo. Все handlers в src/handlers/. Shared types в src/types/"

✅ Неочевидные подводные камни

"Strict TypeScript: unused imports — это ошибка, не варнинг" "Tests используют реальную локальную DB, не mocks. Запусти npm run db:test:reset первым"

✅ Соглашения

"Use zod for request body validation" "Return shape is always " "Never expose stack traces to the client"

Что НЕ писать

❌ Конфиги линтера/форматтера — это делает Prettier/ESLint, не нужно дублировать

❌ Полную документацию — дай ссылку, не копируй

❌ Длинные абзацы с теорией — Claude и так знает что такое SOLID

❌ Описания отдельных функций — пусть читает код

Эталонный CLAUDE.md (20 строк)

Project: Acme API
 
Commands
npm run dev       # Start dev server
npm run test      # Run tests (Jest)
npm run lint      # ESLint + Prettier check
npm run build     # Production build
 
Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/
- Shared types in src/types/
 
Conventions
- Use zod for request body validation
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log
 
Watch out for
- Tests use a real local DB, not mocks. Run `npm run db:test:reset` first
- Strict TypeScript: no unused imports, ever

Клод получает всё что нужно. Без воды.

Если твой CLAUDE.md длинный

Три варианта рефакторинга:

1. Вынести в .claude/rules/ с path-scoping

Для специфичных правил, которые нужны только в некоторых директориях. Пример .claude/rules/api-conventions.md:

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---
 
API Design Rules
All handlers return { data, error } shape
Use zod for request body validation
Never expose internal error details to clients

Это правило загружается только когда Claude редактирует файлы внутри src/api/ или src/handlers/. Не засоряет общий контекст.

Подробнее про path-scoping — в Модуле 3.

2. CLAUDE.local.md для личных предпочтений

Иногда у тебя есть настройки только твои — предпочитаешь другой тест-раннер, хочешь чтобы Claude открывал файлы определённым образом. Создай CLAUDE.local.md в корне проекта:

• Claude читает его вместе с основным CLAUDE.md
• Автоматически попадает в .gitignore
• Твои личные настройки никогда не попадут в репозиторий

3. Skills для нагруженных workflow

Если "инструкция" на самом деле — целый рабочий процесс (deploy, release, migration), это не CLAUDE.md, это skill. В Модуле 2, урок 5.

Проверка

# Сколько строк сейчас?
wc -l CLAUDE.md
 
# Если > 200 — рефактор

Практика (15 минут)

1. Посмотри на текущий CLAUDE.md твоего проекта (если есть)
2. Если нет — создай по шаблону выше
3. Пройдись по каждой строке и ответь: это реально помогает Claude сейчас?
4. Вырежи:
   • Всё что описано в конфигах линтера
   • Общие факты про технологию (React, Node и т.д.)
   • Длинные абзацы объяснений
5. Сохрани. Запусти новую сессию. Проверь /memory — стал короче?

Что дальше

Следующий урок: режим планирования и техника "interview me". Перестанешь получать момент "Claude переписал весь проект, а я не просил".