Claude Code в монорепозиториях: как ограничить контекст и сохранять точность

Почему в больших монорепозиториях Claude становится менее точным

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

«Контекст» — это набор файлов, фрагментов, заметок и инструкций, которые Claude видел для этой задачи, плюс то, что он может вывести из них. Когда ключевые детали отсутствуют, Claude заполняет пробелы догадками. В большом репозитории это случается чаще.

Повторяются три сценария ошибок:

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

Во‑вторых, ложное сходство. В монорепозиториях часто есть похожие пакеты: два модуля авторизации, три API‑клиента или несколько React‑приложений с похожей структурой папок. Claude может смешать паттерны между ними, обновить хелпер в неправильном пакете или импортировать из «почти подходящего» имени модуля.

В‑третьих, временной дрейф. В больших кодовых базах обычно остаются старые и новые способы решения одной и той же задачи. Если Claude видит только старые файлы, он может скопировать устаревшие паттерны (deprecated‑опции конфигурации, legacy‑API), хотя команда уже перешла на новые.

Реальный пример: вы просите внести небольшое изменение в интерфейс биллинга, и Claude правит общий компонент payments, который используют другие приложения, потому что он не увидел специфичной для приложения обёртки, которую стоило изменить.

Цель не в том, чтобы показать Claude весь монорепозиторий. Цель — предоставить меньшие, осознанные входные данные, которые отвечают на вопрос: пакет, который вы меняете, его прямые зависимости и одна‑две «источника правды» для типов и конфигурации. Также укажите зоны «не трогать» (другие приложения, infra, сгенерированный код) и подтвердите, какой пакет владеет поведением.

Начните с определения задачи, а не репозитория

Точность зависит меньше от объёма вставленного кода и больше от того, насколько ясно вы описываете задачу.

Начните с результата, которого вы хотите: конкретный фикс, рефактор или ответ. «Вопрос о коде» может оставаться на высоком уровне. Запрос «внести изменение» требует границ, входных данных и критериев успеха.

Перед тем как что‑то показывать, напишите одно предложение, завершающее фразу: «Когда вы закончите, я должен(а) смочь…». Например: «запустить unit‑тесты для пакета X без ошибок» или «увидеть новое поле в ответе API для endpoint Y». Это предложение станет северной звездой, когда репозиторий огромен.

Для изменений поделитесь минимальным набором артефактов, которые могут доказать правильность изменения: точками входа, релевантными типами/интерфейсами или схемой, одним падающим тестом или шагом воспроизведения с ожидаемым результатом и любой конфигурацией, влияющей на этот путь (роутинг, feature‑флаги, сборка или правила линтинга). Если нужно, добавьте короткую карту папок пакета, чтобы Claude понял, за что отвечает каждая директория.

Будьте явно указывать, что не смотреть. Скажите: «Игнорируй сгенерированные файлы, vendor‑папки, выходы сборки, снапшоты и lock‑файлы, если я не попрошу». Это предотвратит траты времени и правки там, что вы не будете проверять.

Также задайте ожидания по поводу неопределённости. Попросите Claude помечать предположения и неизвестности вместо того, чтобы гадать. Например: «Если ты не видишь, где вызывается эта функция, скажи об этом и предложи 2 способа найти её.»

Проведите чёткие границы, которые Claude не должен пересекать

В большом монорепозитории точность падает, когда модель «помогая», начинает подтягивать соседний код, не относящийся к задаче. Решение простое: заранее определите, что в зоне охвата, а что — нет.

Начните с границы, соответствующей организации репозитория: пакет, сервис, приложение или общая библиотека. Если изменение — «обновить UI корзины», граница, скорее всего, одно приложение, а не все места, где встречается слово «checkout».

Сигналы, которые помогают Claude оставаться в рамках: соглашения по папкам (apps/, services/, packages/, libs/), манифесты пакетов (exports и dependencies), публичные точки входа (index‑файлы, экспортируемые компоненты, хендлеры) и тесты (они часто показывают ожидаемую поверхность). README внутри папки может быть самым быстрым маркером границы.

Границы работают лучше, когда вы называете мосты между ними. Укажите конкретные интерфейсы, с которыми Claude может взаимодействовать, и считайте всё остальное запрещённым. Типичные мосты: контракты HTTP API, топики событий и их полезные нагрузки, общие типы или небольшой набор экспортируемых функций.

Также указывайте зоны «не трогать», когда изменение не должно на них влиять. Распространённые: инфраструктура и деплой, логика безопасности и аутентификации, биллинг и платежи, миграции данных и продакшн‑схемы, общие библиотеки, используемые многими командами.

Конкретная подсказка, которая помогает:

“Make changes only inside packages/cart/ and its tests. You may read shared types in packages/types/ but do not modify them. Do not edit infra, auth, or billing.”

Как писать полезные локальные сводки

Точность улучшается, когда вы даёте маленькую, стабильную карту той области, которую хотите изменить. «Локальная сводка» — это именно такая карта: достаточно короткая, чтобы её быстро прочитать, и достаточно конкретная, чтобы предотвратить догадки.

Держите каждую сводку примерно 10–20 строк. Пишите так, будто передаёте код новому коллеге, которому нужно работать только в этой границе, а не во всём репозитории. Используйте простой язык и реальные имена из кода: папки, пакеты, экспортируемые функции.

Полезная локальная сводка отвечает на пять вопросов:

• Для чего этот пакет/сервис предназначен и для чего нет (границы ответственности)
• Где начинается работа (главные точки входа: ключевые файлы, маршруты, команды или компоненты)
• Что безопасно вызывать извне (публичные API, экспортируемые модули, события, эндпоинты)
• От чего он зависит (базы данных, очереди, кеши, конфигурация, внешние сервисы)
• Какие правила здесь важны (паттерны именования, стиль ошибок, логирование и как пишутся тесты)

Добавьте одну строку «gotchas». Тут предотвратите дорогостоящие ошибки: скрытый кеш, feature‑флаги, шаги миграции и всё, что ломается незаметно.

Вот компактный шаблон, который можно скопировать:

Local summary: <package/service name>
Purpose: <1 sentence>
Scope: <what to touch> | Not: <what not to change>
Entry points: <files/routes/commands>
Public surface: <exports/endpoints/events>
Data sources: <tables/collections/queues/caches>
Conventions: errors=<how>, logging=<how>, tests=<where/how>
Gotchas: <flags/caching/migrations/edge cases>

Пример: если вы редактируете пакет биллинга, укажите точную функцию, которая создаёт инвойсы, имена таблиц, в которые она пишет, и правило для повторяемых ошибок. Тогда Claude сможет сфокусироваться на этой границе, а не блуждать по общему auth, config или несвязанным пакетам.

Где хранить сводки и как их поддерживать актуальными

Лучшая сводка — та, которую Claude видит, когда она нужна. Поместите её рядом с кодом, который она описывает, чтобы её было трудно игнорировать и легко обновить. Например, держите короткий SUMMARY.md (или раздел в README.md) внутри каждого пакета, сервиса или приложения, а не один гигантский документ в корне репозитория.

Простая, повторяемая структура помогает. Держите её короткой, чтобы люди поддерживали её в актуальном состоянии:

• Что делает эта папка (цель в 1–2 предложениях)
• Публичная поверхность (главные точки входа, экспортируемые модули или API)
• Ключевые зависимости (внутренние и внешние)
• Границы (что нельзя импортировать или изменять)
• Как тестировать (быстрая локальная проверка)
• Last updated: YYYY-MM-DD - <что изменилось в одном предложении>

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

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

Практическая привычка: при мердже изменения добавляйте одну строку «Last updated» с кратким описанием изменения. Инструменты вроде Koder.ai могут ускорить изменение кода, но сводка — это то, что сохраняет точность будущих правок.

Пошаговый рабочий процесс, чтобы оставаться в нужном контексте

Точность часто зависит от темпа беседы. Заставьте Claude «заработать» контекст маленькими кусками, вместо того чтобы он догадывался по огромному снимку.

Шаг 1: Сначала попросите краткую карту

До любых правок попросите Claude описать, что он видит и что ему нужно. Хорошая карта короткая: ключевые пакеты, точка входа потока и где находятся тесты или типы.

Подсказка:

“Create a map of this change: packages involved, main flow, and likely touch points. Do not propose code yet.”

Шаг 2: Начните с одного среза и одной границы

Выберите узкий срез: одна функция, один пакет, один пользовательский поток. Чётко укажите границу (например: «Менять только packages/billing-api. Не трогать shared-ui или infra.»).

Рабочий цикл, который даёт контроль:

• Определите цель и границу в одном предложении.\n- Требуйте предположения и неизвестности (Claude должен их перечислить).\n- Попросите назвать точные файлы, которые ему нужны дальше (ограничьте 3–6).\n- Дайте только эти файлы, затем повторите.\n- Потребуйте короткий план перед любым патчем.

Шаг 3: Заставьте явно обозначать предположения и запросы файлов

Если Claude чего‑то не хватает, он должен об этом сказать. Попросите его написать: (1) предположения, которые он делает, (2) что опровергло бы эти предположения, и (3) какие файлы нужны дальше для подтверждения.

Пример: нужно добавить поле в ответ Invoice в одном пакете. Claude запрашивает handler, DTO/тип и один тест. Вы делитесь только этими файлами. Если вы используете чат‑ориентированный билдер вроде Koder.ai, то правило то же: сначала минимальный набор исходников, расширяйте только при необходимости.

Используйте ограничения и контракты в подсказках

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

Начните с границы, которую легко проверять и соблюдать. Ясно укажите, где разрешены правки, и назовите зоны «не трогать», чтобы не было соблазна уходить в сторону.

Шаблон контракта:

• Only modify files under packages/payments/.\n- Do not edit packages/auth/, infra/, or any shared configs.\n- If you need changes outside scope, stop and ask first.\n- Keep changes minimal: fix the bug, avoid refactors.

Затем определите критерии приёмки. Без них Claude может сгенерировать код, который выглядит правильно, но нарушает реальные правила репозитория.

• Запустите unit‑тесты для пакета (назовите команду).\n- Запустите lint/format (укажите инструмент или «использовать существующую конфигурацию»).\n- Прогоните typecheck/build для пакета.\n- Подтвердите, что приложение стартует (простая команда запуска достаточна).

Стилевые ограничения тоже важны. Скажите, какие паттерны использовать и чего избегать, опираясь на текущий код. Например: «Используй существующие helper‑функции для ошибок в этом пакете; не добавляй новые зависимости; сохраняй имена функций в camelCase; не вводи новый уровень архитектуры.»

Наконец, требуйте короткий план перед правками:

“Before editing, list the 3–5 files you expect to touch and the exact behavior change. Wait for approval.”

Пример:

“Fix rounding in invoice totals. Only edit packages/billing/src/ and tests under packages/billing/test/. Acceptance: pnpm -C packages/billing test and typecheck. Follow existing money utils; do not rewrite API types. Provide a 4-step plan first.”

Частые ловушки, которые вызывают дрейф и неправильные правки

Самый быстрый путь получить неверные правки в монорепозитории — дать Claude слишком много сразу. Когда вы вставляете большой кусок кода, модель часто возвращается к общим паттернам, а не к специфическому дизайну вашего репозитория.

Ещё одна ловушка — позволить ей догадываться про архитектуру. Если вы не показываете реальные точки входа, она может выбрать первый файл, который кажется подходящим, и вшить логику туда. На практике точность обеспечивается небольшим набором «источников правды» (entry‑модули, роутеры, регистраторы сервисов, документы границ пакетов). Если их нет в контексте, модель заполняет пробелы.

Имена тоже вводят в заблуждение. В монорепозитории могут быть ui, ui-kit, shared-ui или дублирующиеся helpers вроде date.ts в двух местах. Если смешать фрагменты из обоих, Claude может пропатчить один файл, рассуждая про другой. Пример: вы просите изменить стиль кнопки, он правит packages/ui/Button.tsx, но приложение импортирует packages/ui-kit/Button.tsx. Дифф выглядит нормально, но в production ничего не меняется.

Конфигурация — ещё один тихий источник дрейфа. Поведение может зависеть от env‑переменных, feature‑флагов, настроек сборки или workspace tooling. Если вы этого не упомянули, Claude может убрать «странную» проверку, которая важна при включённом флаге, или добавить код, ломающий шаг сборки.

Сигналы‑красные флаги дрейфа:

• Ответ рассуждает про «типичные паттерны», не называя ваши реальные файлы\n- Появляется новая общая утилита вместо использования существующей\n- Изменяются импорты через границы пакетов\n- Игнорируются feature‑флаги или ветки, зависящие от окружения\n- Предлагается добавить зависимость в ядро

Рассматривайте cross‑package импорты как сознательное решение, а не как действие по умолчанию. Держите правки локальными, если вы сознательно не расширяете область.

Быстрый чек‑лист перед тем, как задать вопрос Claude

Самый быстрый путь получить корректные правки — начать с ограничений, а не объёма. Хорошая подсказка немного строга: она говорит Claude, куда смотреть, что игнорировать и что значит «готово».

Перед тем как вставлять код, напишите короткую префейсу, которая привязывает работу к одному месту в репозитории. Назовите пакет, точную папку и конкретную цель. Затем включите локальную сводку (назначение, ключевые зависимости, важные конвенции) и точку входа, которая фиксирует изменение.

Чек‑лист:

• Boundary: Work only in <package>/<path>. Goal: <one sentence>. Ignore everything else unless asked.\n- Context starter: Local summary: <5-10 lines>. Entry file: <path/to/file>.\n- Constraints: Allowed folders: <...>. Must not change: <folders/files or APIs>. Keep behavior: <what must stay true>.\n- File requests first: “Before proposing changes, list the minimum files you need to see (max 5) and why.”\n- Output format: “Reply with a short plan first. After I confirm, give patch-style suggestions by file.”

Если Claude предлагает изменения за пределами вашей границы, воспринимайте это как сигнал: либо ужесточите подсказку, либо сознательно расширьте границу и повторите её явно.

Пример: внести изменение в один пакет, не будя весь монорепозиторий

Предположим, в монорепозитории есть apps/web-store (React‑приложение) и packages/ui-kit (общие кнопки, инпуты и стили). Нужно добавить кнопку «Сохранить на потом» на странице корзины, используя новый SaveIcon из ui-kit. Ничего больше менять не надо.

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

# apps/web-store/LOCAL_SUMMARY.md
Purpose: Customer shopping UI.
Entry points: src/routes.tsx, src/pages/cart/CartPage.tsx
Cart rules: cart state lives in src/cart/useCart.ts
Do not touch: checkout flow (src/pages/checkout), payments, auth.
Tests: npm test -w apps/web-store

# packages/ui-kit/LOCAL_SUMMARY.md
Purpose: shared UI components.
Exports: src/index.ts
Icons: src/icons/*, add new icons by exporting from index.
Do not touch: theming tokens, build config.
Tests: npm test -w packages/ui-kit

Затем держите цикл коротким:

1. Map: «Это изменение ограничено CartPage и иконками ui‑kit. Никаких правок в checkout/auth.»\n2. Assumptions: потребуйте список предположений и дождитесь подтверждения.\n3. File requests: одобрите только те файлы, которые действительно нужны (CartPage, useCart, иконки ui‑kit, индекс ui‑kit).\n4. Plan: подтвердите, что он соответствует границам.\n5. Edits: сделайте минимальный diff, затем попросите обновлённые тесты.

После изменения задокументируйте его, чтобы будущий контекст оставался маленьким:

• Обновите обе локальные сводки с новым экспортом и точными файлами, которые были изменены.\n- Добавьте короткий комментарий в шапку cart page: расскажите, что делает кнопка и где обрабатывается состояние.\n- Зафиксируйте команды тестов, которые прошли (и какие снапшоты были обновлены).

Следующие шаги: сделать это повторяемым для команды

Если подход работает у одного человека, но не у команды, обычно не хватает повторяемости. Сделайте «хорошую гигиену контекста» значением по умолчанию, а не личной привычкой.

Превратите лучшие подсказки в шаблон команды

Сохраните один скелет подсказки, который все могут копировать и заполнять. Держите его коротким, но строгим. Включите цель (как выглядит «готово»), разрешённую область, жёсткие границы (и почему), локальную сводку и контракт вывода (сначала план, потом патч‑стиль и тесты).

Поддерживайте сводки актуальными простым ритмом

Не устраивайте большие ежемесячные ревью, которые никто не делает. Привязывайте обновления сводок к обычной работе: когда изменение меняет поведение, зависимости или API, обновляйте локальную сводку в том же PR.

Простое правило: если коллега может спросить «где это находится?» или «кто от этого зависит?», то сводка устарела.

Если вы предпочитаете чат‑первый рабочий процесс, Koder.ai помогает сделать итерации безопаснее. Planning mode позволяет согласовать область и границы перед правками, а снимки с возможностью отката дают шанс попробовать изменения без серьёзных последствий, если догадка оказалась неверной.