> ## 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で）

約1万行を超えるとAIエージェントは構造を幻覚します：重複ユーティリティ、回避されるテナントチェック、壊れるwebhook。.ai/ + AGENTS.md + MCP + テストゲートで安全に出荷させる全体像。

_公開日 2026-11-08._
_2026-11-08 更新._

> **Claude CodeやCursorにモノレポ構造を壊させないには？**
> エージェントにシニアエンジニアと同じコンテキストを持たせられるか次第です。機械可読な構造契約（AGENTS.mdと各パッケージの境界を記す.ai/ミラードキュメント）、.agents/skills/配下のタスク手順書、grepの勘ではなく構造化ツールでリポジトリを検査させるMCPサーバー（@supastack/mcp）、そしてレビュー前に必須の693+テストからなる資格情報不要の決定的テストゲート。supastackは4層すべてを同梱しています。

## すべてのエージェント利用者がぶつかる「1万行の壁」

Claude CodeやCursorでの最初の5,000行は魔法のようです。やがてリポジトリはエージェントが全体を見通せない大きさになり、失敗は誤記に見えなくなります。2パッケージ先に既にあるユーティリティを再実装し、`workspaceId`を付け忘れたクエリを追加し、あなたが週末を潰して直した冪等チェックを削ってwebhookハンドラを「修正」します。

これは能力の失敗ではなくコンテキストの失敗です。シニアエンジニアがその継ぎ目を踏まないのは、構造を頭に持っているからです。どのパッケージが何を所有するか、どの不変条件が荷重を受けているか、テストが何を約束しているか。エージェントが踏むのは、誰もそれを書き留めていないからです。


## 第1層：エージェントが読める書面の契約

supastackはエージェント向けコンテキストを第一級の成果物として扱います。リポジトリ直下の`AGENTS.md`は構造契約を記します——各パッケージの所有範囲、テストゲートの要求、禁止パターン。`.ai/PROJECT_CONTEXT.md`は現在の状態と決定理由を記録し、ファイルごとのミラードキュメントが、コンテキストをwikiで腐らせずコードと一緒に持ち運べるようにします。

その上に`.agents/skills/`配下の約29個のタスク手順書——Web機能追加、DBスキーマ変更、決済プロバイダ追加、変更検証——があり、エージェントは即興ではなくリポジトリ自身の手順を実行します。

```
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
```


## 第2層：@supastack/mcpが与える構造化リポジトリアクセス

ツールがなければ、700ファイルのモノレポ探索でエージェントにできることは1つ——grepして、間違ったファイルを読んで、推測するだけです。`@supastack/mcp`は`@modelcontextprotocol/sdk`と`@supastack/agents`ツールランタイム上に作られた本物のModel Context Protocolサーバーで、構造化ツール・ドキュメントリソース・既製プロンプトを通じて、MCP対応エージェント（Claude Code、Cursor、Devin、Windsurf）にリポジトリを公開します。

差は失敗率に表れます。「このパッケージは何をエクスポートしているか」「テストゲートは何を要求するか」を型付きツールで問い合わせられるエージェントは、偶然開いたファイルから答えを捏造しなくなります。[AIコーディングエージェント向けスターターキット記事](https://supastack.dev/ja/blog/ai-coding-saas-starter-kit.md)がビルド側のワークフローを解説しています。


## 第3層：エージェントが通るべき決定的テストゲート

強制力のないガードレールは単なる提案です。supastackは693+の自動テストを同梱し、課金・認証・メール・ストレージには資格情報不要のフェイクプロバイダを用意。サインアップ、決済webhook、権限付与、チーム招待という黄金経路全体をローカルで数秒に検証できます。

エージェントを安全にするループは地味です。差分を書き、ゲートを回し、失敗を読み、自己修正する——すべて人間のレビューより前に行われます。リポジトリの`verify-changes`スキルが、変更の種類ごとにどのチェックを回すべきかを指示するので、「エージェントが課金を壊した」は「エージェントが自分で捕まえた」に変わります。

| 失敗モード | ガードレールなしのリポジトリ | supastackガードレールあり |
|---|---|---|
| 既存コードの再実装 | レビューで発見——されれば | AGENTS.md + .ai/ミラーのパッケージ境界が未然に防ぐ |
| テナントチェックを静かに削除 | 本番で発覚 | ワークスペースルールは明文化されテストで担保 |
| webhookの退行 | 決済障害で初めて判明 | 冪等webhook台帳がリプレイテストで固定 |
| リポジトリ探索 | grepと推測 | @supastack/mcpツール + ドキュメントリソース |
| 検証 | エージェントが「完了」と言うだけ | レビュー前に693+テストゲート必須 |


## ガードレールがクライアントワークで複利になる理由

エージェンシーにとって計算は直接的です。すべてのクライアントリポジトリが同じ契約を継承するので、新規案件の新しいエージェントは、境界を壊しながら学ぶ代わりに1時間目から生産的です。「エージェントの速度を売る」のと「エージェントの後始末を売る」の違いです。

キットの3ティアはエージェンシーの実際の買い方に対応します——単一面案件は$199のStarter、全面3シートは$299のFull Bundle、$799のAgencyは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）＋検証（テストゲート）という組み合わせが持ちこたえます——どれか1層だけでは漏れます。
- テストスイートは実際どのくらいの規模ですか？, 693+の自動テスト。課金冪等性、セッション認証、ワークスペース分離、APIキー、エージェント向けパッケージをカバーし、すべて実資格情報なしで実行可能です。
- 既存リポジトリにこのガードレールを追加できますか？, 可能です。丁寧な文書化作業約2週間とMCPサーバー構築が目安です。このキットはその近道です——契約、スキル、MCPサーバー、テストはすでに相互に整合しています。