Монорепозиторий и AI-агенты: паттерн или антипаттерн

В мае 2026 года в монорепозиторий Anthropic вливали в среднем около 2500 изменений в день, в сентябре — больше 30 тысяч. Почти все клиенты репозитория теперь агенты и автоматические задания. История главной ветки весит почти 100 ГБ, сжатая рабочая копия — больше 25 ГБ, а CI делает порядка 25 миллионов чекаутов в день. Несколько сотен внутренних зеркал Git лишь выиграли время. Команда из семи человек за пять месяцев написала собственную систему контроля версий Scion и перевела на неё весь монорепозиторий. Об этом Anthropic рассказала в статье 13 октября.¹

OpenAI пришла к тому же. По её статье от 2 ноября, в третьем квартале 2026 года в master монорепозитория попало почти в 15 раз больше коммитов, чем в первом квартале 2024-го. С конца 2025 года системы вокруг репозитория перестали успевать: пуши и фетчи тормозили, слияния срывались, надёжность временами падала ниже 90%. Компания написала новый бэкенд для Git под названием Pando, совместимый с обычным клиентом git. Ядро спроектировал один инженер, реализовали команды агентов на Codex, от старта до продакшена прошло 10 недель.

Обе компании перестраивали инструменты под монорепозиторий, а не делили его на части. Агенту нужен контекст, и в монорепозитории весь контекст лежит рядом. Платить за это приходится нагрузкой на Git и CI и токенами, которые агент тратит на поиск по большому дереву.²

Агент видит обе стороны изменения. Правку API и её вызовы во фронтенде он делает в одной сессии, и задачу хватает описать один раз. В раздельных репозиториях агенту сначала нужно понять, что контекст шире, найти второй репозиторий и обыскать его, даже если правка — одна строка в каждом. Поэтому небольшие команды сливают тесно связанные репозитории в один.

Агент видит, что сломает. Когда пакеты, тесты, документация и конфигурация CI лежат в одном дереве, последствия правки видны сразу. Если же контекст разнесён по репозиториям, агент ломает импорты, потому что не видит, что от чего зависит.

Изменение атомарно. Всех пользователей API, библиотеки или паттерна меняют одним пулреквестом и проверяют одним прогоном CI. Для Anthropic в этом главный смысл монорепозитория: общая база инструментов, на которой всё работает одинаково, и масштабная правка одним коммитом, а не кампания по сотням репозиториев со своими нормами. Shopify тоже перевела код в монорепозиторий. Бёрк Либби, который отвечает там за инструменты разработчиков, пишет, что без продуманных инструментов не обойтись и с минусами приходится долго бороться, но назад компания не вернётся.

Джереми Эдберг когда-то выступал на конференциях с докладами в защиту микросервисов, а теперь пишет: «ИИ разбирается в монорепозитории гораздо легче, чем в кластере микросервисов. ИИ меняет расчёт: с ним разработчик справляется даже с самым большим монорепозиторием, а сам ИИ работает лучше, когда весь код лежит в одном месте».³

Рядом с кодом можно держать документацию, сайт и планы. Тогда агент правит их в том же пулреквесте, что и код, а тексты проверяют маркетинг и поддержка. Глава Vercel Гильермо Раух предлагает идти дальше и класть в монорепозиторий весь контекст компании: дизайн, маркетинг, продажи, разработку и поддержку.

Контекст дорожает. Линтеры, статические анализаторы и языковые серверы с открытым кодом плохо приспособлены к монорепозиториям, поэтому агент грепает всё дерево и тратит входные токены. Готовые паттерны он находит быстрее, но не всегда те, которые нужны. Поиск по слову payment или onboarding приносит файлы из чужих доменов. В Google агенты застревали в рекурсивном грепе огромных папок хранилища Piper, хотя у них был скил поиска по коду.

Границы размываются. Агенту проще сделать внутреннюю функцию публичной, чем найти интерфейс пакета: «грепнут, найдут что-нибудь, сделают pub» (пример). Без проверок большой репозиторий постепенно превращается в большой ком грязи, где агент заново пишет то, что уже есть. Самописные библиотеки агент к тому же знает хуже открытых: он учился на открытом коде.⁴

Git не рассчитан на такой поток. Митчелл Хашимото, создатель Terraform и Ghostty, ещё в январе предупреждал, что огромные монорепозитории плохо живут с Git, а армия агентов, которая параллельно пушит в один репозиторий, сделает всё «невообразимо хуже». «И всё же агенты работают с монорепозиторием НАМНОГО лучше. Значит, что-то должно уступить». Anthropic и OpenAI решили это собственными системами. Мэтт Кэри из Cloudflare считает, что без такой системы монорепозиторий для агентов — антипаттерн. Вместо него он предлагает маленькие репозитории и CLI или MCP для поиска по коду и документации организации без чекаута.

Узкие места остаются и после кода. Общий CI и общий выпуск тормозят все проекты сразу, правила вроде обязательного ревью действуют на весь репозиторий, а порядок деплоев усложняется (Кэлвин Груневальд). Даже в Shopify главной проблемой монорепозитория называют сам Git: индекс, push и pull, GitHub и место на диске. Открытый код плохо уживается с закрытым: команда opencode перешла на несколько репозиториев, потому что один большой репозиторий трудно защитить от атак на цепочки поставок, а AI сделал переезд почти безболезненным.

Решение Anthropic, по её же словам, подходит не всем. Идеи Scion имеют смысл только для по-настоящему огромных монорепозиториев, где работают десятки тысяч инженеров или рои агентов. К тому же Anthropic тратит на внутреннюю разработку столько токенов, сколько не стал бы тратить ни один обычный бизнес.⁵

Монорепозиторий — не один репозиторий на всю компанию и не монолит. Это способ держать вместе связанные пакеты, например бэкенд, фронтенд и мобильное приложение одного продукта. Границу проверяют так: если два пакета обычно меняются в одном пулреквесте, им место в одном репозитории. Если они почти никогда не выходят вместе, соседство даёт в основном общую очередь CI и более медленную сборку.

Внутри репозитория границы держат механизмы, а не договорённости. OpenAI в феврале описала эксперимент: три инженера, позже семь, построили продукт, не написав руками ни строчки. За пять месяцев Codex написал около миллиона строк кода, слито около 1500 пулреквестов. Каждый бизнес-домен в этом репозитории разбит на фиксированные слои: Types → Config → Repo → Service → Runtime → UI. Зависимости идут только вперёд по этой цепочке, а сквозные вещи вроде авторизации и телеметрии входят через один явный интерфейс Providers. Правила проверяют собственные линтеры, которые написал тот же Codex, и структурные тесты. «Такую архитектуру обычно откладывают, пока инженеров не станет сотни. С кодинг-агентами она нужна с самого начала», — пишут в OpenAI.⁶

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

У Claude Code есть отдельное руководство по монорепозиториям и большим кодовым базам, у Codex правила описаны в документации AGENTS.md.

Корневой файл инструкций держат картой. OpenAI сначала попробовала один большой AGENTS.md, и он не сработал: огромный файл вытесняет из контекста задачу и код, когда всё важно, ничего не важно, а правила быстро устаревают. Теперь у них AGENTS.md примерно на 100 строк работает оглавлением, а знания лежат в папке docs/. Подробнее о таких файлах — в статье «Что писать в AGENTS.md».

Augment Code измерила, как десятки файлов AGENTS.md из её монорепозитория влияют на код агента. Лучшие дали прирост качества, сравнимый с переходом с Haiku на Opus, худшие сделали результат хуже, чем вообще без файла. Лучше всего сработали файлы модулей на 100–150 строк с несколькими справочными документами: в модулях примерно из 100 основных файлов они улучшили все метрики на 10–15%. Огромные общие файлы в корне репозитория проиграли модульным. Для монорепозитория корень может выглядеть так:

# Магазин: монорепозиторий на pnpm и Turborepo

## Пакеты
- `apps/web` — витрина на Next.js, правила в `apps/web/AGENTS.md`
- `apps/api` — API на Fastify, правила в `apps/api/AGENTS.md`
- `packages/db` — схема и миграции Prisma
- `packages/ui` — общие компоненты

## Команды
- тесты одного пакета: `pnpm turbo run test --filter <пакет>`
- только затронутое изменениями: `pnpm turbo run test --affected`

## Границы
- `apps/*` не импортируют друг друга, общий код — только из `packages/*`
- схему БД меняют только миграциями в `packages/db`

Агента запускают в папке пакета. Claude Code, запущенный из packages/api, загрузит CLAUDE.md этого пакета и всех папок выше, а инструкции соседних пакетов в контекст не попадут. При запуске из корня он загружает только корневой файл, а файлы подпапок подхватывает, когда открывает или правит что-то в них. Codex при старте склеивает AGENTS.md от корня репозитория до текущей папки. Файлы глубже он автоматически не подставляет: системный промпт велит модели самой проверять их, когда она работает в подпапке. Надёжнее запускать его сразу в нужном пакете: codex --cd services/payments. Как Claude Code склеивает и исключает файлы инструкций, разобрано в статье о контексте и памяти.⁷

Тесты и линтер тоже запускают по пакету: полный прогон после правки одного сервиса, предупреждает Anthropic, кончается таймаутами и лишним выводом в контексте.

Шум прячут от агента. Сгенерированный код, сборки и вендорные зависимости Claude Code не откроет, если запретить их чтение в .claude/settings.json той папки, откуда его запускают. Запрет действует на инструмент чтения Claude, а не на программы, которые он запускает:

{
  "permissions": {
    "deny": ["Read(./**/dist/**/*)", "Read(./**/vendor/**/*)"]
  }
}

Языковой сервер вместо грепа. Греп по популярному имени функции в большом репозитории возвращает тысячи совпадений, а языковой сервер — только ссылки на тот же символ. В Claude Code его подключают плагином, например /plugin install typescript-lsp@claude-plugins-official.

Скилы держат в пакетах. Скилы из packages/api/.claude/skills/ Claude Code подгружает, когда впервые открывает файл в этом пакете, а скил с повторяющимся именем получает префикс папки, например /apps/web:deploy. Codex ищет скилы в .agents/skills от текущей папки до корня репозитория. Подробнее — в статье о скилах в Claude Code.⁸

Для параллельных агентов нужны отдельные рабочие копии. Claude Code с флагом --worktree создаёт для сессии git worktree, а настройка worktree.sparsePaths выписывает на диск только нужные папки и файлы из корня. Так рабочие копии большого репозитория создаются быстрее и занимают меньше места:

{
  "worktree": {
    "sparsePaths": [".claude", "packages/api", "packages/shared"],
    "symlinkDirectories": ["node_modules"]
  }
}

Если агенты гоняют тесты одновременно, каждой рабочей копии нужны свои порты и база, иначе они мешают друг другу. О worktree и откатах — в статье «Git для работы с AI-агентом».

Общий контекст можно дать агенту и без монорепозитория. Простейший вариант — папка с рабочими копиями нескольких репозиториев, в которой запускают Claude Code или Codex CLI и просят поменять сразу несколько проектов. Так работает Саймон Уиллисон. Минус в том, что всё общее для нескольких репозиториев приходится решать в каждом из них.

Мэтт Покок, автор курсов Total TypeScript и AI Hero, называет более аккуратный вариант Home Repo. Скилы, правила и вики лежат в отдельном «домашнем» репозитории, агента запускают там, а в AGENTS.md записано, где лежит каждый рабочий репозиторий и откуда его клонировать, если копии нет.

По статье Покока, монорепозиторий хорош, когда он возможен, а домашний репозиторий заменяет его, когда невозможен: например, если публичные репозитории смешаны с приватными или команда не хочет монорепозиторий. Каждый репозиторий клонируется один раз, а под каждую задачу внутри клона создаётся worktree, так что несколько агентов работают в одном репозитории одновременно. Цена такой схемы — дополнительные инструменты: чтобы она ощущалась как монорепозиторий, их приходится писать самим.

Соседний репозиторий можно подключить и флагом: claude --add-dir ../frontend. В Claude Code такая папка даёт доступ к файлам, но не к настройкам: её скилы подгружаются, а CLAUDE.md только с переменной окружения CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. У Codex CLI тоже есть флаг --add-dir, он открывает запись в дополнительные папки.

Ограничения инструментов быстро меняются, поэтому переезжать в монорепозиторий только ради них рискованно. Ещё в марте облачный Claude Code работал с одним приватным репозиторием за сессию, и Уиллисон жалел, что у него нет монорепозитория. Теперь в облачную сессию можно добавить несколько репозиториев. Такая сессия стартует в папке над клонами и берёт из .claude/settings.json каждого репозитория только список плагинов. Правила доступа и хуки не применяются, и зависимости ставят скриптом настройки окружения. Подробнее о правилах облачных сессий — в статье «Облачные агенты Claude Code и Codex на практике».

Небольшой команде монорепозиторий с границами и картой помогает: одна задача — один пулреквест, и весь контекст рядом. Без границ и карты тот же репозиторий превращается в дерево, которое агент грепает наугад и постепенно размывает. Где монорепозиторий невозможен, его роль берёт на себя домашний репозиторий с картой остальных. Собственная система контроля версий, как у Anthropic, нужна только огромным монорепозиториям, где работают десятки тысяч инженеров или рои агентов.