04 / 06 · Эксперт

📦 Монорепо и большие проекты

Стратегии работы с Claude Code в проектах на 100 000+ файлов: иерархия CLAUDE.md, специализированные сессии, координация изменений между пакетами.

📦
Монорепо — это самый сложный сценарий для CC. Контекстное окно ограничено, стеки разные, зависимости перекрёстные. Но с правильной организацией CC работает не хуже, чем в маленьком проекте. Страница учит управлять этой сложностью системно.

🧩 Почему монорепо сложно для CC

Claude Code читает проект через контекстное окно. Чем больше проект — тем выше вероятность, что нужные файлы не уместятся в контекст, CC потеряет ориентацию или начнёт галлюцинировать импорты.

📂
100k+ файлов
Контекстное окно физически не вмещает весь проект. CC видит только часть файлов и может не знать, что что-то уже существует в другом пакете.
🔀
Разные стеки
Laravel-правила (PSR-4, Eloquent, Blade) не применимы к Nuxt/Vue и тем более к Python/FastAPI. Смешивание правил портит качество кода.
🔗
Перекрёстные зависимости
API-контракт между backend и frontend. Типы из одного пакета используются в другом. CC не видит связи если работает только в одном пакете.
⏱️
Медленное индексирование
CC читает файлы при каждом старте. В больших проектах это медленно и дорого по токенам. Без .claudeignore — катастрофа.
⚠️
Главный симптом проблемы: CC начинает создавать функции которые уже существуют, ломать импорты из соседних пакетов или писать код в стиле одного фреймворка там где нужен другой. Это сигнал — пора применять стратегии из этой страницы.

🗂️ Иерархия CLAUDE.md для монорепо

Ключевая идея: каждый пакет получает свой CLAUDE.md с правилами именно для своего стека. Claude читает все файлы вверх по директории — от текущего места до корня. Используйте это.

E:\Clients\ ← рабочая директория ├── CLAUDE.md ← глобальные правила (краткий!) │ ├── laravel-api/ │ ├── CLAUDE.md ← Laravel-специфика │ ├── app/ │ ├── database/ │ └── tests/ │ ├── nuxt-frontend/ │ ├── CLAUDE.md ← Vue/Nuxt правила │ ├── components/ │ ├── pages/ │ └── composables/ │ └── python-etl/ ├── CLAUDE.md ← Python/FastAPI правила ├── src/ └── tests/

Когда CC запущен из laravel-api/ — он читает laravel-api/CLAUDE.md и корневой E:\Clients\CLAUDE.md. Так работает иерархия: локальные правила дополняют глобальные.

Что писать на каждом уровне

Глобальный Корневой CLAUDE.md — только общее E:\Clients\CLAUDE.md

Держите его коротким: 20–30 строк максимум. Только то, что реально применимо ко всем пакетам без исключений.

markdown E:\Clients\CLAUDE.md
# Глобальные правила — E:\Clients ## Окружение - Windows Server 2025 + WSL2 + Docker - PostgreSQL через Docker (порт 5432) - Reverse proxy: Caddy (E:\Clients\Windows\proxy) ## Общие стандарты - Код на русском в комментариях не пишем - Secrets только в .env, не в коде - Логи только через stderr, не stdout - Docker-команды через MCP, не через bash ## Структура проекта - laravel-api/ — PHP backend - nuxt-frontend/ — Vue/Nuxt frontend - python-etl/ — Python скрипты и FastAPI
Laravel Laravel-специфичные правила laravel-api/CLAUDE.md

Правила для PHP/Laravel: неймспейсы, конвенции, запрещённые паттерны.

markdown laravel-api/CLAUDE.md
# Laravel API — правила ## Стек - PHP 8.3, Laravel 11 - PostgreSQL через Eloquent ORM - API Resources для трансформации ответов - Form Requests для валидации ## Конвенции - Модели: singular PascalCase (Order, UserProfile) - Контроллеры: только Resource Controllers (7 методов) - Сервисы: app/Services/, инжектируем через конструктор - Репозитории: app/Repositories/ если логика сложная ## Запрещено - Не писать SQL-запросы напрямую — только Eloquent - Не использовать устаревший DB::statement() для CRUD - Логику не писать в контроллерах — только в сервисах ## Тесты - Feature-тесты: tests/Feature/ - Unit-тесты: tests/Unit/ - Запуск: php artisan test --parallel
Nuxt Vue/Nuxt правила nuxt-frontend/CLAUDE.md

Правила для Nuxt 3: composables, Pinia, соглашения по компонентам.

markdown nuxt-frontend/CLAUDE.md
# Nuxt Frontend — правила ## Стек - Nuxt 3, Vue 3 Composition API - Pinia для state management - Tailwind CSS 4 - TypeScript (strict mode) ## Конвенции - Компоненты: PascalCase в components/ - Composables: use-префикс (useCart, useAuth) - API-вызовы: только через composables, не в компонентах - Типы: types/ директория, импортируем явно ## API-контракт с backend - Base URL: NUXT_PUBLIC_API_URL из .env - Авторизация: Bearer token в заголовке - Обработка ошибок: useApiError composable ## Запрещено - Не использовать Options API - Не писать fetch() напрямую — только $fetch/useFetch
Python Python/FastAPI правила python-etl/CLAUDE.md

Правила для Python: типизация, структура FastAPI, стиль ETL-скриптов.

markdown python-etl/CLAUDE.md
# Python ETL/FastAPI — правила ## Стек - Python 3.12, FastAPI, SQLAlchemy 2 - Pydantic v2 для схем - asyncpg для PostgreSQL ## Конвенции - Типизация обязательна (mypy strict) - Схемы: src/schemas/, модели: src/models/ - Сервисы: src/services/ - ETL-скрипты: scripts/, каждый с if __name__ == "__main__" ## PostgreSQL — осторожно! - При ETL: SET max_parallel_workers_per_gather=1 - Вернуть после завершения: SET к дефолту - work_mem=64MB — не менять ## Запрещено - Не использовать raw SQL если есть ORM-аналог - Не хранить credentials в коде

🚫 .claudeignore для монорепо

Файл .claudeignore в корне проекта говорит CC что не нужно индексировать. В монорепо это критически важно — без него CC потратит токены на vendor-зависимости, бинарники и чужие пакеты.

conf .claudeignore
# Зависимости — никогда не читаем vendor/ node_modules/ .pnpm-store/ __pycache__/ *.egg-info/ .venv/ venv/ # Сборки и кэш .nuxt/ .output/ dist/ build/ *.pyc *.pyo .mypy_cache/ .pytest_cache/ .ruff_cache/ # Логи и временные файлы *.log logs/ storage/logs/ /tmp/ # Медиа и бинарники *.jpg *.jpeg *.png *.gif *.svg *.mp4 *.mp3 *.zip *.tar.gz storage/app/public/ public/storage/ # Git и IDE .git/ .idea/ .vscode/ *.swp # Secrets — особенно важно .env .env.* *.pem *.key
PHP / Laravel
  • vendor/ — Composer пакеты
  • storage/framework/ — кэш фреймворка
  • bootstrap/cache/ — bootstrap кэш
  • public/hot — Vite hot-reload
JS / Nuxt
  • node_modules/ — npm/pnpm пакеты
  • .nuxt/ — Nuxt build cache
  • .output/ — production build
  • dist/ — Vite dist
Python
  • __pycache__/ — compiled bytecode
  • .venv/ — virtual environment
  • .mypy_cache/ — mypy cache
  • *.egg-info/ — package metadata
Всегда исключать
  • .git/ — git история
  • .env* — секреты!
  • *.log — логи
  • *.png, *.jpg — бинарники
✅
Сколько токенов экономит .claudeignore: Типичный Laravel-проект с vendor/ содержит 15 000+ PHP-файлов. Без игнора CC тратит время и токены на их индексирование. С игнором — только ваш код. Экономия: 60–80% токенов при старте сессии.

🎯 Стратегия специализированных сессий

Вместо одной большой сессии для всего монорепо — несколько специализированных сессий, каждая в своей поддиректории. CC видит только нужный пакет плюс глобальные правила.

Сессия 1
📦 Laravel API
cd laravel-api
claude
Видит: laravel-api/ + корневой CLAUDE.md
Сессия 2
🌐 Nuxt Frontend
cd nuxt-frontend
claude
Видит: nuxt-frontend/ + корневой CLAUDE.md
Сессия 3
🐍 Python ETL
cd python-etl
claude
Видит: python-etl/ + корневой CLAUDE.md
📏
Меньше контекст — лучше качество
CC который видит 2000 файлов работает лучше чем тот который видит 50 000. Меньше шума — точнее ответы.
⚡
Правильные правила без смешивания
Запущен из laravel-api/ — CC знает PSR-4 и Eloquent, но не путается в Pinia и composables.
💰
Экономия токенов
Специализированная сессия тратит в 3–5 раз меньше токенов на инициализацию чем сессия в корне монорепо.
🔄
Параллельная работа
Открывайте несколько CC-сессий одновременно: одна на backend, другая на frontend. Работайте параллельно.

🔍 Навигация между пакетами

Иногда задача требует понимания связей между пакетами. CC не видит соседние директории автоматически — нужно явно давать ему контекст.

Как давать кросс-пакетный контекст

1
Явно описывайте связи в промпте
Не пишите «обнови компонент корзины». Пишите: «Компонент nuxt-frontend/components/Cart.vue вызывает POST /api/cart/add из laravel-api/routes/api.php. API возвращает CartResource. Нужно обновить компонент чтобы отображать новое поле discount_amount».
2
Вставляйте нужные части из соседних пакетов
Если работаете во frontend-сессии и нужно знать структуру API-ответа — скопируйте содержимое laravel-api/app/Http/Resources/CartResource.php прямо в промпт. CC увидит структуру без переключения контекста.
3
Используйте specs/ для контрактов
Создайте директорию specs/ в корне монорепо и держите в ней API-контракты, типы и интерфейсы. Ссылайтесь на эти файлы в промптах: «смотри specs/cart-api.md».
4
Shared types в отдельном пакете
В больших монорепо выносите общие типы (TypeScript interfaces, Pydantic schemas) в отдельный пакет shared/. Оба пакета ссылаются на него — CC видит единый источник правды.
markdown Пример: кросс-пакетный промпт
Работаю в nuxt-frontend/. Нужно отобразить скидку в компоненте корзины. Backend контракт (из laravel-api/app/Http/Resources/CartResource.php): { "id": 1, "items": [...], "total": 1500.00, "discount_amount": 150.00, // НОВОЕ поле "final_total": 1350.00 } Текущий компонент: nuxt-frontend/components/Cart/CartSummary.vue Нужно добавить строку со скидкой между total и final_total. Стиль: как существующие строки summary. Используй Tailwind.

🔄 Координация изменений между пакетами

Когда задача затрагивает несколько пакетов — важен порядок. Сначала меняем контракт (backend), убеждаемся что он работает, потом обновляем потребителей (frontend, ETL).

🗄️
1. Миграция БД
laravel-api/
→
📦
2. Модель + Resource
laravel-api/
→
🧪
3. API тесты
коммит
→
🌐
4. Frontend
nuxt-frontend/
→
🐍
5. ETL (если нужно)
python-etl/

Правило: коммитите между пакетами

bash Правильный порядок работы
# Шаг 1: работаем в backend cd laravel-api # Claude сессия: добавляем поле discount_amount php artisan test # убеждаемся что API работает git add -p && git commit -m "feat: add discount_amount to CartResource" # Шаг 2: переключаемся на frontend cd ../nuxt-frontend # Новая Claude сессия: обновляем компонент # Вставляем в промпт структуру CartResource (из шага 1) npm run build # проверяем TypeScript git commit -m "feat: display discount in CartSummary"
⚠️
Частая ошибка новичков: запустить CC из корня монорепо и попросить его одновременно изменить Laravel-контроллер и Nuxt-компонент. CC видит оба стека, но правила из Laravel-CLAUDE.md и Nuxt-CLAUDE.md конфликтуют — он начинает писать Eloquent-стиль в TypeScript или Composition API в PHP. Всегда делайте кросс-пакетные изменения двумя отдельными сессиями с явной передачей контракта.
💡
Антипаттерн: не пытайтесь делать backend + frontend изменения в одной CC-сессии из корня монорепо. CC запутается в контексте двух стеков. Лучше две сессии и явная передача контракта между ними.

📋 Сводка: чеклист для монорепо

Задача Действие Где
Настройка при старте Создать .claudeignore в корне E:\Clients\.claudeignore
Правила для пакета CLAUDE.md в каждой поддиректории package/CLAUDE.md
Работа с одним пакетом Запускать CC из директории пакета cd package && claude
Кросс-пакетная задача Вставлять контракт в промпт явно Промпт
API-контракты Хранить в specs/ в корне specs/*.md
Порядок изменений Backend → коммит → Frontend git
📚
Смотрите также: Базовую иерархию конфигов и механику @import в CLAUDE.md — в разделе Продвинутый: Иерархия конфигов. Оптимизацию токенов для больших проектов: Оптимизация токенов.