> ## 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/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 服务器和测试彼此早已对齐。