> ## 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줄은 마법 같습니다. 이후 리포지토리가 에이전트가 전체를 볼 수 없을 만큼 커지면, 실패는 오타처럼 보이지 않습니다. 두 패키지 너머에 이미 있는 유틸리티를 재구현하고, `workspaceId`를 빠뜨린 쿼리를 추가하고, 당신이 주말을 들여 바로잡은 멱등 체크를 지워 webhook 핸들러를 「수정」합니다.

이것은 능력의 실패가 아니라 컨텍스트의 실패입니다. 시니어 엔지니어가 그 이음매를 밟지 않는 것은 아키텍처를 머리에 담고 있기 때문입니다. 어느 패키지가 무엇을 소유하는지, 어떤 불변 조건이 하중을 받는지, 테스트가 무엇을 약속하는지. 에이전트가 밟는 것은 아무도 그것을 적어주지 않았기 때문입니다.


## 첫 번째 계층: 에이전트가 읽을 수 있는 서면 계약

supastack은 에이전트 컨텍스트를 일급 산출물로 취급합니다. 리포지토리 루트의 `AGENTS.md`는 아키텍처 계약을 적습니다—각 패키지의 소유 범위, 테스트 게이트 요구사항, 금지 패턴. `.ai/PROJECT_CONTEXT.md`는 현재 상태와 결정의 근거를 기록하고, 파일별 미러 문서가 컨텍스트를 wiki에서 썩지 않고 코드와 함께 옮기게 합니다.

그 위로 `.agents/skills/` 아래 약 29개의 작업 플레이북—웹 기능 추가, 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
```


## 두 번째 계층: @supastack/mcp의 구조화된 리포지토리 접근

도구가 없으면 700개 파일의 모노레포 탐색에서 에이전트가 할 수 있는 일은 하나뿐입니다—grep하고, 틀린 파일을 읽고, 추측하기. `@supastack/mcp`는 `@modelcontextprotocol/sdk`와 `@supastack/agents` 도구 런타임 위에 만든 진짜 Model Context Protocol 서버로, 구조화된 도구·문서 리소스·준비된 프롬프트를 통해 MCP 지원 에이전트(Claude Code, Cursor, Devin, Windsurf)에 리포지토리를 노출합니다.

차이는 실패율로 드러납니다. 「이 패키지가 무엇을 내보내는가」「테스트 게이트가 무엇을 요구하는가」를 타입 있는 도구로 조회할 수 있는 에이전트는, 우연히 연 파일에서 답을 지어내지 않습니다. [AI 코딩 에이전트 스타터 킷 글](https://supastack.dev/ko/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)에서 비교하세요.


## FAQ: 실제 모노레포에서 AI 코딩 에이전트 쓰기

프로덕션 코드베이스를 에이전트에 맡기기 전 팀이 묻는 질문입니다:

- 이 가드레일은 어떤 에이전트와 호환되나요?, Markdown을 읽는 모든 에이전트—Claude Code, Cursor, Windsurf, Copilot, Devin. MCP 지원 클라이언트는 추가로 `@supastack/mcp`로 구조화된 도구를 얻고, .ai/ 문서와 스킬 자체는 도구 비종속입니다.
- AGENTS.md 하나만으로는 부족한가요?, 도움은 되지만 단일 파일은 부패합니다. 버티는 조합은 계약(AGENTS.md) + 기억(.ai/ 미러) + 절차(Agent Skills) + 검증(테스트 게이트)—어느 한 계층만으로는 샙니다.
- 테스트 스위트 규모가 실제로 어느 정도인가요?, 693+ 자동 테스트가 결제 멱등성, 세션 인증, 워크스페이스 격리, API 키, 에이전트용 패키지를 커버—모두 실자격 증명 없이 실행됩니다.
- 기존 리포지토리에 이 가드레일을 추가할 수 있나요?, 가능합니다—꼼꼼한 문서화 약 2주와 MCP 서버 구축이 목표치입니다. 이 킷이 지름길입니다: 계약, 스킬, MCP 서버, 테스트가 이미 서로 정렬돼 있습니다.