如何阻止 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 程式設計代理起手架文章 從構建視角講了同一套工作流。
第三層：代理必須通過的確定性測試門禁
沒有強制執行的護欄只是建議。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 席位——每個檔位都允許無限量商業客戶專案。去 定價頁 比較選項。
常見問題：真實 Monorepo 上的 AI 程式設計代理
團隊在把正式環境程式碼庫交給代理之前常問的問題：
- 這些護欄支援哪些代理?, 任何能讀 Markdown 的代理——Claude Code、Cursor、Windsurf、Copilot、Devin。支援 MCP 的用戶端還能透過
@supastack/mcp獲得結構化工具；.ai/ 文件與技能本身與工具無關。 - 只有 AGENTS.md 不夠嗎?, 有幫助，但單一檔案會腐壞。真正站得住的組合是契約（AGENTS.md）+ 記憶（.ai/ 鏡像）+ 流程（Agent Skills）+ 驗證（測試門禁）——少了任何一層都會漏。
- 測試套件到底有多大?, 693+ 自動化測試，涵蓋計費冪等、工作階段認證、工作區隔離、API 金鑰與面向代理的套件——全部無需真實憑證即可執行。
- 能把這些護欄補進現有倉庫嗎?, 可以，代價大約是兩週的細緻編寫外加自建 MCP 伺服器。這套起手架就是捷徑：契約、技能、MCP 伺服器和測試彼此早已對齊。