Как не дать Claude Code или Cursor сломать архитектуру монорепо?
Зависит от того, можете ли вы дать агенту тот же контекст, что у сеньор-инженера: машиночитаемые архитектурные контракты (AGENTS.md плюс зеркальные документы .ai/ с границами каждого пакета), плейбуки задач в .agents/skills/, MCP-сервер (@supastack/mcp), позволяющий агенту инспекировать репозиторий структурированными инструментами вместо угадывания по grep, и детерминированный тестовый гейт из 693+ тестов — без учётных данных — обязательный до ревью. supastack предподключает все четыре слоя.
Стена десяти тысяч строк, о которую бьётся каждый пользователь агентов
Первые 5 000 строк с Claude Code или Cursor — как магия. Потом репозиторий становится слишком большим, чтобы агент мог видеть его целиком, — и сбои перестают походить на опечатки: он заново реализует утилиту, которая существует двумя пакетами дальше; добавляет запрос, забыв workspaceId; «чинит» обработчик вебхука и удаляет проверку идемпотентности, на которую ушёл ваш уикенд.
Это сбой контекста, а не способностей. Сеньор-инженер не наступает в эти щели, потому что несёт архитектуру в голове: какой пакет чем владеет, какие инварианты несущие, что обещают тесты. Агент наступает, потому что никто не записал это для него.
Слой первый: письменный контракт, который агент умеет читать
supastack относится к контексту для агентов как к артефакту первого класса. AGENTS.md в корне фиксирует архитектурный контракт: чем владеет каждый пакет, что требует тестовый гейт, какие паттерны запрещены. .ai/PROJECT_CONTEXT.md фиксирует текущее состояние и мотивы решений, а зеркальные документы на файл позволяют контексту путешествовать вместе с кодом, а не гнить в вики.
Выше лежат ~29 плейбуков задач в .agents/skills/ — добавить веб-фичу, изменить схему БД, подключить платёжного провайдера, проверить изменение — чтобы агент выполнял собственные процедуры репозитория, а не импровизировал.
your-saas/
AGENTS.md architecture contract every agent reads first
.ai/
PROJECT_CONTEXT.md current state, decisions, ship status
apps/web/src/... per-file mirror docs that travel with code
.agents/skills/ ~29 task playbooks for agent workflows
packages/mcp/ MCP server: structured repo access for agentsСлой второй: @supastack/mcp даёт агентам структурированный доступ к репо
Без инструментов у агента один способ изучать монорепо на 700 файлов: grep, чтение не тех файлов и догадки. @supastack/mcp — настоящий сервер Model Context Protocol, построенный на @modelcontextprotocol/sdk и рантайме инструментов @supastack/agents; он открывает репозиторий MCP-совместимым агентам (Claude Code, Cursor, Devin, Windsurf) через структурированные инструменты, ресурсы документации и готовые промпты.
Разница видна в частоте сбоев. Агент, который может спросить типизированным инструментом «что экспортирует этот пакет» или «что требует тестовый гейт», перестаёт выдумывать ответы из случайно открытого файла. Наша статья про стартер-кит для AI-кодовых агентов описывает тот же рабочий процесс со стороны сборки.
Слой третий: детерминированный тестовый гейт, который агент обязан пройти
Ограждения без принуждения — лишь предложения. supastack включает 693+ автотеста с фейковыми провайдерами без учётных данных для биллинга, авторизации, почты и хранилища; весь золотой путь — регистрация, платёжный вебхук, выдача энтайтлмента, приглашение в команду — проверяется локально за секунды.
Цикл, делающий агента безопасным, незатейлив: агент пишет диф, гонит гейт, читает сбой и исправляется — всё до человеческого ревью. Скилл verify-changes в репозитории подсказывает, какие проверки запускать под каждый тип изменений; «агент сломал биллинг» превращается в «агент сам поймал».
| Режим сбоя | Репо без ограждений | С ограждениями supastack |
|---|---|---|
| Агент заново реализует существующий код | Обнаруживается на ревью — если вообще | Границы пакетов в AGENTS.md + зеркалах .ai/ предотвращают заранее |
| Проверка тенанта тихо удалена | Взрывается в проде | Правила воркспейса записаны и покрыты тестами |
| Регрессия вебхука | Проявляется как сбой платежей | Идемпотентный журнал вебхуков закреплён replay-тестами |
| Изучение репозитория | Grep и догадки | Инструменты @supastack/mcp + ресурсы доков |
| Верификация | Агент говорит «готово» | Гейт из 693+ тестов обязателен до ревью |
Почему ограждения дают сложный процент в клиентской работе
Для агентства расчёт прямой: каждая клиентская кодовая база наследует один и тот же контракт, поэтому новый агент на новом проекте продуктивен с первого часа, а не учит границы, ломая их. Это разница между «продать скорость агента» и «продать уборку за агентом».
Три тарифа кита соответствуют тому, как агентства реально покупают: Starter за $199 для проектов с одной поверхностью, Full Bundle за $299 — все поверхности с 3 местами, Agency за $799 — с 10 местами; каждый тариф разрешает неограниченные коммерческие клиентские проекты. Сравните варианты на странице цен.
FAQ: AI-кодовые агенты на настоящих монорепо
Вопросы команд перед тем, как доверить агентам продакшн-кодовую базу:
- С какими агентами работают эти ограждения?, С любым агентом, умеющим читать Markdown — Claude Code, Cursor, Windsurf, Copilot, Devin. MCP-совместимые клиенты дополнительно получают структурированные инструменты через
@supastack/mcp; сами документы .ai/ и скиллы инструментально-нейтральны. - Одного AGENTS.md недостаточно?, Помогает, но один файл загнивает. Держится комбинация: контракт (AGENTS.md) + память (зеркала .ai/) + процедуры (Agent Skills) + проверка (тестовый гейт) — не хватит одного слоя, и протечёт.
- Насколько велик набор тестов на самом деле?, 693+ автотестов по идемпотентности биллинга, сессионной авторизации, изоляции воркспейсов, API-ключам и агентским пакетам — всё запускается без реальных учётных данных.
- Можно ли добавить эти ограждения в существующий репозиторий?, Можно — примерно две недели аккуратной документирования плюс собственный MCP-сервер. Кит — это короткий путь: контракт, скиллы, MCP-сервер и тесты уже согласованы друг с другом.