> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Как не дать Claude Code и Cursor сломать ваше монорепо (правила .ai и MCP)

После примерно десяти тысяч строк AI-агенты начинают галлюцинировать архитектуру: дублированные утилиты, обойдённые проверки тенанта, сломанные вебхуки. Стек .ai/ + AGENTS.md + MCP + тестовый гейт, позволяющий агентам поставлять безопасно.

_Опубликовано 2026-11-08._
_Обновлено 2026-11-08._

> **Как не дать 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-кодовых агентов](https://supastack.dev/ru/blog/ai-coding-saas-starter-kit.md) описывает тот же рабочий процесс со стороны сборки.


## Слой третий: детерминированный тестовый гейт, который агент обязан пройти

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

Цикл, делающий агента безопасным, незатейлив: агент пишет диф, гонит гейт, читает сбой и исправляется — всё до человеческого ревью. Скилл `verify-changes` в репозитории подсказывает, какие проверки запускать под каждый тип изменений; «агент сломал биллинг» превращается в «агент сам поймал».

| Режим сбоя | Репо без ограждений | С ограждениями supastack |
|---|---|---|
| Агент заново реализует существующий код | Обнаруживается на ревью — если вообще | Границы пакетов в AGENTS.md + зеркалах .ai/ предотвращают заранее |
| Проверка тенанта тихо удалена | Взрывается в проде | Правила воркспейса записаны и покрыты тестами |
| Регрессия вебхука | Проявляется как сбой платежей | Идемпотентный журнал вебхуков закреплён replay-тестами |
| Изучение репозитория | Grep и догадки | Инструменты @supastack/mcp + ресурсы доков |
| Верификация | Агент говорит «готово» | Гейт из 693+ тестов обязателен до ревью |


## Почему ограждения дают сложный процент в клиентской работе

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

Три тарифа кита соответствуют тому, как агентства реально покупают: Starter за $199 для проектов с одной поверхностью, Full Bundle за $299 — все поверхности с 3 местами, Agency за $799 — с 10 местами; каждый тариф разрешает неограниченные коммерческие клиентские проекты. Сравните варианты на [странице цен](https://supastack.dev/#pricing).


## FAQ: AI-кодовые агенты на настоящих монорепо

Вопросы команд перед тем, как доверить агентам продакшн-кодовую базу:

- С какими агентами работают эти ограждения?, С любым агентом, умеющим читать Markdown — Claude Code, Cursor, Windsurf, Copilot, Devin. MCP-совместимые клиенты дополнительно получают структурированные инструменты через `@supastack/mcp`; сами документы .ai/ и скиллы инструментально-нейтральны.
- Одного AGENTS.md недостаточно?, Помогает, но один файл загнивает. Держится комбинация: контракт (AGENTS.md) + память (зеркала .ai/) + процедуры (Agent Skills) + проверка (тестовый гейт) — не хватит одного слоя, и протечёт.
- Насколько велик набор тестов на самом деле?, 693+ автотестов по идемпотентности биллинга, сессионной авторизации, изоляции воркспейсов, API-ключам и агентским пакетам — всё запускается без реальных учётных данных.
- Можно ли добавить эти ограждения в существующий репозиторий?, Можно — примерно две недели аккуратной документирования плюс собственный MCP-сервер. Кит — это короткий путь: контракт, скиллы, MCP-сервер и тесты уже согласованы друг с другом.