Как настроить кодового агента под монорепозиторий

Кодовые агенты — Claude Code от Anthropic, Cursor, GitHub Copilot в режиме agent, Windsurf — хорошо работают на компактных проектах, но в монорепозитории на сотни пакетов ведут себя иначе. Агент пытается прочитать слишком много файлов, упирается в лимит контекстного окна, теряет нить и вносит правку в чужой пакет. Проблема не в модели, а в том, что ей не задали границы. Ниже — как настроить агента, чтобы монорепа стала для него не свалкой, а картой.

Почему монорепа ломает поведение агента

Монорепозиторий — это один git-репозиторий, где лежат десятки или сотни независимых пакетов, сервисов и библиотек с общими зависимостями и инструментами сборки. Nx, Turborepo, Bazel, pnpm workspaces — всё это про монорепы. Для человека удобно: один clone, одна история, атомарные коммиты через несколько пакетов сразу. Для агента — минное поле.

Три типичных сбоя:

• Переполнение контекста. Агент индексирует или читает файлы за пределами задачи. Контекстное окно¹ забивается кодом, который к задаче отношения не имеет, и модель начинает "забывать" начало разговора.
• Правка не в тот пакет. В монорепе часто есть utils в трёх местах и Button.tsx в пяти. Агент открывает первый попавшийся и меняет его.
• Игнорирование границ сборки. Агент не знает, что пакет A не должен импортировать из пакета B напрямую, и радостно нарушает архитектурное правило, которое линтер потом завернёт.

Базовый приём: файл с инструкциями в корне и в пакетах

Почти все современные агенты читают специальный markdown-файл с правилами проекта перед началом работы. У Claude Code это CLAUDE.md, у Cursor — .cursorrules или .cursor/rules, у Copilot — .github/copilot-instructions.md. Ключевая идея для монорепы: таких файлов должно быть несколько уровней.

1. Корневой файл — общая карта: где что лежит, какой пакетный менеджер, как запускать тесты, какие пакеты трогать нельзя без ревью.
2. Файл на уровне пакета — локальные правила: стиль, соседние зависимости, чего в этом пакете делать нельзя. Агент, работая внутри пакета, подхватывает и корневой, и локальный файл.

Пример содержания корневого файла — не код, а инструкция человеческим языком: "Это pnpm-монорепа. Пакеты в packages/, приложения в apps/. Перед изменением пакета в packages/core предупреди — от него зависят все приложения. Тесты запускаются командой pnpm test --filter=<имя>, не запускай тесты всей монорепы разом."

Агент делает ровно то, что вы разрешили, и ещё немного того, чего не запретили. Границы задаются явно, а не подразумеваются.

Ограничьте область: скоуп вместо всего репозитория

Второй рычаг — сузить область, которую агент вообще видит. Здесь подходы у инструментов разные.

Игнор-файлы

Cursor уважает .cursorignore, многие агенты — .gitignore и собственные аналоги. Внесите туда сборочные артефакты (dist, build, .next), снапшоты, сгенерированный код и пакеты, которые в текущей задаче точно не участвуют. Чем меньше файлов в индексе, тем меньше мусора в контексте.

Запуск из подкаталога

Claude Code и большинство CLI-агентов берут за корень рабочей области ту директорию, из которой запущены. Открываете сессию не из корня монорепы, а из apps/checkout — и агент по умолчанию смотрит туда. Общие пакеты подтянет по мере необходимости, но стартовая точка задана.

Явное указание пакета в промпте

Банально, но работает: вместо "поправь валидацию формы" пишите "поправь валидацию в packages/forms/src/validators.ts, не трогай другие пакеты". Явный путь снимает половину ошибок с выбором не того файла.

Сравнение подходов по инструментам

Данные ниже отражают состояние инструментов на начало 2025 года. Функциональность агентов обновляется часто — сверяйтесь с документацией конкретного продукта.

Точные имена файлов и поддержку вложенных правил проверяйте в актуальной документации: вендоры переименовывают и добавляют форматы.

Дайте агенту инструменты вместо чтения файлов

Мощный, но недооценённый приём — научить агента спрашивать структуру у инструментов сборки, а не читать всё подряд. Nx и Turborepo умеют строить граф зависимостей пакетов. Если в инструкции написать "чтобы понять, что зависит от пакета X, выполни nx graph или посмотри nx show projects --affected", агент получит точную карту связей за одну команду вместо десятков открытых файлов.

То же с поиском: направьте агента на ripgrep с фильтром по каталогу пакета, а не на чтение файлов пачками. Для больших кодовых баз это заметно экономит контекст.

Кому это пригодится и кому нет

Пригодится:

• Команде с монорепой на pnpm/Nx/Turborepo, где 20+ пакетов и агент регулярно "промахивается" мимо нужного.
• Тем, кто гоняет агента по CI или в автоматических правках — там цена ошибки выше, и жёсткие границы обязательны.
• Проектам с архитектурными правилами импортов: локальные файлы правил в пакетах напоминают агенту о запретах до того, как их поймает линтер.

Не даст выигрыша:

• Одиночному репозиторию на пару десятков файлов — там агент и так видит всё сразу, настройка избыточна.
• Задачам, где всё равно нужен сквозной рефакторинг через все пакеты: тут границы мешают, и лучше работать вручную по шагам.
• Командам без дисциплины по обновлению файлов правил: устаревший CLAUDE.md, где путь apps/web давно переехал, собьёт агента сильнее, чем его отсутствие.

Порядок настройки за один заход

1. Создайте корневой файл правил с картой репы, командами тестов и списком "опасных" пакетов.
2. Добавьте локальные файлы правил в 3–5 самых нагруженных пакетах.
3. Заполните игнор-файл: артефакты сборки, генерируемый код, неактуальные пакеты.
4. Пропишите в правилах команды для графа зависимостей и поиска, чтобы агент спрашивал структуру, а не читал всё.
5. Проверьте на реальной задаче: дайте правку в конкретный пакет и посмотрите, не полез ли агент за его границы.

¹ Контекстное окно — объём текста (кода, инструкций, истории диалога), который модель удерживает одновременно. Измеряется в токенах. Когда лишние файлы забивают окно, полезная информация вытесняется, и качество ответов падает.