如何阻止 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 服务器和测试彼此早已对齐。