> ## 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 弄壞你的 Monorepo（用 .ai 規則與 MCP）

程式碼超過約一萬行，AI 代理就開始產生架構幻覺：重複的工具函式、被繞過的租戶校驗、被改壞的 webhook。這裡是用 .ai/ + AGENTS.md + MCP + 測試門禁讓代理安全交付的完整打法。

_釋出於 2026-11-08._
_更新於 2026-11-08._

> **如何阻止 Claude Code 或 Cursor 破壞 Monorepo 架構？**
> 取決於能否給代理提供與資深工程師相同的上下文：機器可讀的架構契約（AGENTS.md 與寫明每個套件邊界的 .ai/ 鏡像文件）、.agents/skills/ 下的任務手冊、讓代理透過結構化工具而非 grep 猜測來檢查倉庫的 MCP 伺服器（@supastack/mcp），以及一套由 693+ 測試組成、必須在評審前通過的免憑證確定性測試門禁。supastack 四層全部預裝。

## 每個代理使用者都會撞上的「一萬行高牆」

用 Claude Code 或 Cursor 寫前 5,000 行像變魔術。然後倉庫大到代理再也看不全——失敗也開始不像筆誤：它重新實作了兩個套件之外早已存在的工具函式；它新增的查詢忘了帶 `workspaceId`；它「修好」了一個 webhook 處理器，順手刪掉了你花一個週末才做對的冪等校驗。

這是上下文失敗，不是能力失敗。資深工程師不踩這些縫，是因為架構就在他們腦子裡：哪個套件管什麼、哪些不變量承重、測試承諾什麼。代理踩縫，是因為沒人替他們把這些寫下來。


## 第一層：一份代理能讀懂的書面契約

supastack 把代理上下文當作一等交付物。倉庫根部的 `AGENTS.md` 寫明架構契約——每個套件管什麼、測試門禁要求什麼、哪些模式被禁止。`.ai/PROJECT_CONTEXT.md` 記錄目前狀態與決策背後的理由，再配上一份份隨檔案而存的鏡像文件，讓上下文跟著程式碼走，而不是爛在 wiki 裡。

其上還有 `.agents/skills/` 下約 29 個任務手冊——新增 Web 功能、改資料庫 schema、接入支付商、驗證改動——讓代理執行倉庫自己的流程，而不是臨場發揮。

```
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 檔案的 Monorepo 只有一種方式：grep、讀到錯誤的檔案、然後猜。`@supastack/mcp` 是一個真正的 Model Context Protocol 伺服器，基於 `@modelcontextprotocol/sdk` 與 `@supastack/agents` 工具執行時構建——它透過結構化工具、文件資源與現成提示詞，把倉庫暴露給支援 MCP 的代理（Claude Code、Cursor、Devin、Windsurf）。

差別直接體現在失敗率上。一個能透過型別化工具查詢「這個套件匯出什麼」「測試門禁要求什麼」的代理，就不會再用它碰巧打開的那個檔案腦補答案。我們的 [AI 程式設計代理起手架文章](https://supastack.dev/zh-tw/blog/ai-coding-saas-starter-kit.md) 從構建視角講了同一套工作流。


## 第三層：代理必須通過的確定性測試門禁

沒有強制執行的護欄只是建議。supastack 自帶 693+ 自動化測試，針對計費、認證、郵件與儲存提供免憑證的虛擬轉接器，整條黃金路徑——註冊、收款 webhook、授權發放、團隊邀請——幾秒內在本地完成驗證。

讓代理變安全的循環樸素無華：代理寫 diff、跑門禁、讀失敗訊息、自我糾正——全部發生在人工評審之前。倉庫的 `verify-changes` 技能告訴代理按改動類型該跑哪些檢查，於是「代理弄壞了計費」變成了「代理自己抓到了」。

| 失敗模式 | 無護欄的倉庫 | 有 supastack 護欄 |
|---|---|---|
| 代理重複實作已有程式碼 | 評審時才發現——如果發現的話 | AGENTS.md + .ai/ 鏡像中的套件邊界預先阻止 |
| 租戶校驗被悄悄丟掉 | 在正式環境爆雷 | 工作區規則白紙黑字且有測試涵蓋 |
| webhook 回歸 | 支付出事才暴露 | 冪等 webhook 帳本由重送測試釘死 |
| 倉庫探索 | 靠 grep 和猜 | @supastack/mcp 工具 + 文件資源 |
| 驗證 | 代理口頭說「完成了」 | 評審前必須通過 693+ 測試門禁 |


## 為什麼護欄對客戶工作是複利

對外包公司來說，這筆帳很直接：每個客戶倉庫繼承同一份契約，新專案上的新代理第一小時就有產出，而不是靠踩坑來學習邊界。這就是「賣代理的速度」與「賣代理的善後」之間的差別。

產品的三個檔位正好對應外包公司的購買方式——單端面專案用 $199 的 Starter，全端面含 3 席位用 $299 的 Full Bundle，$799 的 Agency 含 10 席位——每個檔位都允許無限量商業客戶專案。去 [定價頁](https://supastack.dev/#pricing) 比較選項。


## 常見問題：真實 Monorepo 上的 AI 程式設計代理

團隊在把正式環境程式碼庫交給代理之前常問的問題：

- 這些護欄支援哪些代理?, 任何能讀 Markdown 的代理——Claude Code、Cursor、Windsurf、Copilot、Devin。支援 MCP 的用戶端還能透過 `@supastack/mcp` 獲得結構化工具；.ai/ 文件與技能本身與工具無關。
- 只有 AGENTS.md 不夠嗎?, 有幫助，但單一檔案會腐壞。真正站得住的組合是契約（AGENTS.md）+ 記憶（.ai/ 鏡像）+ 流程（Agent Skills）+ 驗證（測試門禁）——少了任何一層都會漏。
- 測試套件到底有多大?, 693+ 自動化測試，涵蓋計費冪等、工作階段認證、工作區隔離、API 金鑰與面向代理的套件——全部無需真實憑證即可執行。
- 能把這些護欄補進現有倉庫嗎?, 可以，代價大約是兩週的細緻編寫外加自建 MCP 伺服器。這套起手架就是捷徑：契約、技能、MCP 伺服器和測試彼此早已對齊。