Как мы используем Claude Code для поддержки монорепо Nuxt 4 + Rust

Наш стек и почему Claude Code подходит

В Open Soft наш основной продукт — это веб-сайт, построенный как монорепо: фронтенд на Nuxt 4 с TypeScript и бэкенд API на Rust/Axum с PostgreSQL. Кодовая база охватывает два языка, две системы сборки, общие контракты данных, миграции базы данных, i18n-файлы для 10 языков и инфраструктуру деплоя. Изменения часто затрагивают обе стороны стека одновременно.

Мы начали использовать Claude Code в середине 2025 года, и он стал нашим наиболее используемым инструментом разработки. Не потому, что он пишет код за нас, а потому, что он рассуждает о всей нашей кодовой базе так, как ни один другой инструмент не может. Когда вы говорите Claude Code «добавь поле published_at в articles», он читает Rust-миграцию, обновляет SQL-запросы в хендлере, модифицирует TypeScript-типы во фронтенде, корректирует Nuxt-компонент страницы, обновляет все 10 файлов локализации и запускает сборку для проверки. Именно это кросс-стековое понимание делает его незаменимым для разработки в монорепо.

CLAUDE.md: обучение агента вашим конвенциям

Основа эффективного использования Claude Code — файл CLAUDE.md. Это файл с инструкциями на уровне проекта, который Claude Code читает в начале каждой сессии. Думайте о нём как о документации для онбординга, но для вашего AI-агента.

Наш CLAUDE.md включает:

• Конвенции коммитов: Каждый коммит должен начинаться с TASK-XXX: и использовать повелительное наклонение
• Обзор архитектуры: Структура монорепо, какие директории что содержат
• Правила стиля кода: TypeScript strict mode, никаких any, только Composition API, синтаксис <script setup>
• Правила i18n: Все 10 локалей должны быть синхронизированы, ключи отсортированы по алфавиту, ключи на простом английском
• Правила безопасности: Никаких секретов в коммитах, параметризованный SQL, явные CORS-origins
• Команды разработки: npm run dev, cargo run, make fixtures и т.д.

Claude Code следует этим конвенциям стабильно. Когда он генерирует сообщение коммита, он использует префикс TASK-XXX:. Когда добавляет ключ перевода, он добавляет его во все 10 файлов локализации в алфавитном порядке. Когда пишет SQL, использует параметризованные запросы. Это устраняет целую категорию замечаний на ревью — нарушения конвенций.

Мы также поддерживаем CLAUDE.md файлы для отдельных директорий: для бэкенда (/server/CLAUDE.md) и фикстур (/server/fixtures/CLAUDE.md), предоставляя контекстно-специфичные инструкции, которые активируются при работе Claude Code в этих директориях.

Мультифайловый рефакторинг: убойный сценарий использования

Рабочий процесс, который экономит нам больше всего времени, — это кросс-стековый рефакторинг. Вот реальный пример из нашего проекта.

Задача: Добавить SEO-поля (meta_title, meta_description, focus_keyword, robots_meta) в систему статей.

Без Claude Code это изменение требует:

1. Написать SQL-миграцию, добавляющую 4 колонки
2. Обновить Rust-структуру Article
3. Обновить Rust DTO CreateArticle и UpdateArticle
4. Обновить все SQL-запросы в хендлере articles (SELECT, INSERT, UPDATE)
5. Обновить TypeScript-тип Article на фронтенде
6. Обновить форму админ-редактора для новых полей
7. Обновить страницу блог-поста для рендеринга мета-тегов
8. Обновить логику генерации sitemap
9. Обновить все файлы фикстур новыми полями
10. Запустить миграции, пересобрать, протестировать

С Claude Code мы вводим одну команду:

Добавь SEO-поля (meta_title, meta_description, focus_keyword, robots_meta) в articles.
Напиши миграцию, обнови Rust-модель и хендлер, обнови фронтенд-типы
и админ-редактор, добавь мета-теги на страницу блога и обнови фикстуры.

Claude Code выполняет это за один агентный цикл:

• Читает существующие файлы миграций для понимания схемы
• Читает Rust-модель для понимания текущей структуры
• Читает хендлер для нахождения всех SQL-запросов
• Читает фронтенд-типы и компоненты
• Вносит все изменения в 12+ файлов
• Запускает cargo check для проверки компиляции Rust-кода
• Запускает npm run build для проверки сборки фронтенда
• Исправляет ошибки и итерирует до успешного прохождения обоих

Весь процесс занимает около 5 минут вместо 45-60 минут ручной работы. Что ещё важнее, он ловит баги перекрёстных ссылок, которые пропускают люди.

Написание миграций

Миграции базы данных особенно хорошо подходят для Claude Code, потому что требуют понимания текущей схемы, желаемого конечного состояния и безопасного пути трансформации между ними.

Когда мы просим Claude Code написать миграцию, он:

1. Читает все существующие файлы миграций для понимания текущей схемы
2. Читает Rust-модели для понимания целевого состояния
3. Пишет SQL миграции с правильными ALTER TABLE выражениями
4. Добавляет защиты IF NOT EXISTS для идемпотентности где уместно
5. Обновляет Rust-модели и хендлеры для использования новой схемы

Claude Code производит полную, работающую функциональность: файл миграции, модель с serde-деривами, хендлер со всеми CRUD-операциями на параметризованных sqlx-запросах, регистрацию маршрутов в main.rs и корректную обработку ошибок.

Генерация тестов

Мы активно используем Claude Code для генерации тестовых фикстур и SQL seed-данных. Наши файлы фикстур содержат реалистичный, объёмный контент (статьи на 1500+ слов) с корректными SEO-метаданными, и писать их вручную — утомительно и чревато ошибками.

Рабочий процесс:

1. Описываем нужные статьи (тема, угол, техническая глубина)
2. Claude Code генерирует SQL INSERT-выражения с полным Markdown-контентом
3. Следует нашим UUID-конвенциям (d0000000-... для статей, a0000000-... для категорий)
4. Добавляет ON CONFLICT (slug) DO NOTHING для идемпотентности
5. Связывает статьи с тегами через junction-таблицу article_tags

Для Rust unit-тестов Claude Code читает реализацию, выявляет граничные случаи и генерирует тестовые функции с описательными именами.

Ревью кода с Claude Code

Перед открытием merge request мы запускаем Claude Code как ревьюера:

Проверь все изменения на этой ветке на баги, проблемы безопасности,
проблемы производительности и соответствие нашим конвенциям из CLAUDE.md.

Claude Code:

• Запускает git diff main...HEAD для просмотра всех изменений
• Анализирует каждый файл на потенциальные проблемы
• Проверяет SQL-инъекции (непараметризованные запросы)
• Верифицирует наличие i18n-ключей во всех 10 локалях
• Проверяет вызовы .unwrap() в продакшн-коде на Rust
• Проверяет обработку ошибок на соответствие нашим паттернам
• Сообщает о находках с путями к файлам и номерами строк

Это ловит около 30% проблем, которые иначе были бы найдены на человеческом ревью, позволяя людям сосредоточиться на архитектуре и бизнес-логике.

Хуки: автоматизация контроля качества

Claude Code поддерживает хуки — скрипты, которые запускаются автоматически до или после определённых действий. Мы используем хуки для обеспечения качества:

Pre-commit хук: Запускает cargo fmt --check и cargo clippy перед тем, как Claude Code создаст коммит. Если что-то не проходит, Claude Code исправляет проблемы и повторяет.

Post-edit хук: После того как Claude Code модифицирует любой файл в /i18n/locales/, хук запускает скрипт, проверяющий идентичность наборов ключей во всех 10 файлах локализации. Если ключи отсутствуют, Claude Code добавляет их.

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

MCP-серверы: расширение возможностей Claude Code

Model Context Protocol (MCP) серверы позволяют дать Claude Code доступ к внешним инструментам. Мы используем два кастомных MCP-сервера:

1. MCP-сервер базы данных: Позволяет Claude Code напрямую запрашивать наш PostgreSQL для разработки. При отладке проблем с данными Claude Code может выполнять SELECT-запросы для инспекции реального состояния БД, понять проблему и написать исправление — всё в одном цикле.

2. MCP-сервер статуса деплоя: Подключается к нашему CI/CD-пайплайну. Claude Code может проверить, успешен ли последний деплой, прочитать логи сборки и диагностировать ошибки.

MCP-серверы — это простые JSON-RPC сервисы. Реализация одного занимает около 100 строк кода. Рычаг огромен — каждый MCP-сервер добавляет новую возможность, которую Claude Code может использовать автономно в своём агентном цикле.

Советы для больших кодовых баз с контекстом 1M

Контекстное окно Claude Code в 1M токенов — его самая мощная функция для работы с монорепо. Вот как мы максимизируем его:

Позвольте Claude Code исследовать. Не пытайтесь заранее выбрать, какие файлы показать. Опишите, что вам нужно, и позвольте Claude Code использовать свои инструменты (Grep, Glob, Read) для поиска релевантного кода.

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

Разбивайте мега-задачи на фазы. Даже с 1M токенов задача вроде «рефакторинг всей системы аутентификации» выигрывает от поэтапного подхода: сначала анализ и план, потом реализация модуль за модулем, потом тестирование.

Доверяйте агентному циклу. Когда Claude Code вносит изменение, запускает сборку, видит ошибку и исправляет её — этот цикл и есть главная функция. Не прерывайте его на полпути. Дайте ему сойтись.

Подводные камни и обходные пути

Подводный камень: Claude Code переусложняет. Иногда он добавляет абстракции или паттерны, которые не нужны. Обходной путь: добавьте «KISS — Не переусложняй» в ваш CLAUDE.md.

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

Подводный камень: недетерминированный вывод. Один и тот же промпт может дать разный код при разных запусках. Обходной путь: используйте конкретные, детальные промпты.

Подводный камень: качество тестовых данных. AI-сгенерированные тестовые данные могут быть внутренне противоречивыми. Обходной путь: всегда проверяйте сгенерированные фикстуры и запускайте полный набор тестов.

Подводный камень: агрессивные изменения файлов. Claude Code иногда модифицирует файлы, которые вы не просили трогать. Обходной путь: тщательно проверяйте дифф перед принятием.

FAQ

Сколько стоит Claude Code при ежедневном использовании?

Для нашей команды из 4 разработчиков мы тратим примерно $200-300/месяц на использование API Claude Code по всем проектам. Max план за $20/месяц на разработчика — более предсказуемая альтернатива.

Работает ли Claude Code офлайн?

Нет. Claude Code требует подключения к интернету для связи с API Anthropic. Вся обработка кода происходит на стороне сервера.

Может ли Claude Code сломать нашу сборку?

Да, но он ловит большинство проблем сам. Claude Code запускает ваши команды сборки как часть агентного цикла. Если cargo check падает, он читает ошибку и исправляет. По нашему опыту, около 90% сборок проходят с первого раза, а 99% — после цикла самокоррекции.

Как вы обрабатываете секреты и переменные окружения?

Claude Code уважает .gitignore и может быть настроен на исключение чувствительных файлов. Мы никогда не храним секреты в репозитории. Наши .env файлы в gitignore, а .env.example используется для документации необходимых переменных без значений.

Подходит ли Claude Code для разработчика-одиночки?

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

Заключение

Claude Code — это не волшебная палочка, которая пишет приложение за вас. Это мультипликатор силы, который превосходит в кросс-стековом рассуждении, обеспечении конвенций и утомительных мультифайловых изменениях. Комбинация CLAUDE.md для постоянных знаний о проекте, хуков для обеспечения качества и MCP-серверов для доступа к внешним инструментам делает его наиболее способным AI-инструментом разработки для работы с монорепо.

Ключевой инсайт после 9 месяцев ежедневного использования: Claude Code наиболее ценен не для написания нового кода, а для поддержки существующего — рефакторинга, миграции, тестирования и ревью. Это задачи, которые занимают 70% времени разработчика и больше всего выигрывают от агента, понимающего всю кодовую базу.