Claude Code 모노레포 가이드: Turborepo·pnpm·Nx·Bun 워크스페이스 (2026)
Claude Code를 모노레포에서 확장하려면 3가지 패턴이 필수입니다 — 패키지별 CLAUDE.md (컨텍스트 격리), cd packages/<pkg>로 범위 제한된 편집, Admin API의 workspace_id를 활용한 패키지별 비용 추적. 이 패턴들이 없으면 단일 루트 CLAUDE.md가 매 세션 3-8K 토큰을 컨텍스트로 소모하고, Claude가 의도하지 않은 시블링 패키지를 수정하는 일이 발생합니다. 이 가이드는 Turborepo + pnpm 예제와 함께 Nx·Bun 참고 사항, 그리고 2026년에 팀들이 반복해서 부딪힌 5가지 함정을 다룹니다.
왜 모노레포가 Claude Code 기본 워크플로우를 깨는가
루트 레벨 CLAUDE.md 하나는 Claude Code의 기본 권장 사항이고 약 50개 파일 미만의 레포에서는 잘 작동합니다. 실제 모노레포에서는 세 가지 방식으로 동시에 실패합니다:
-
컨텍스트 비대화. 매 세션이 전체 루트 CLAUDE.md를 로드합니다.
apps/web,apps/api,packages/ui,packages/db,packages/types를 한 파일에 문서화하면 첫 프롬프트가 도착하기 전에 3-8K 토큰을 소모합니다. -
잘못된 패키지 수정. 레포 전체가 범위에 있으면 "debounce 훅 추가"가
apps/web/src/hooks에 들어가야 할 때packages/ui에 들어갈 수 있습니다. 모노레포에 중복 유틸리티(앱당 하나)가 쌓이는 것을 봤습니다 — Claude가 어느 패키지가 해당 개념을 "소유"하는지 구분 못해서. -
추적 불가능한 비용. 모든 Claude API 호출이 같은 워크스페이스를 사용합니다. "이번 달
apps/api가 우리 비용을 얼마나 썼는가?"를 수동 태깅 없이 답할 방법이 없습니다.
해결책은 "모노레포 분할"이 아닙니다. Turborepo, pnpm, Nx, Bun이 빌드 시스템에 워크스페이스 경계를 가르치듯 Claude Code에도 가르치는 것입니다.
패턴 1: 패키지별 CLAUDE.md
각 패키지가 자체 CLAUDE.md를 가지면 Claude는 작업 중인 워크스페이스에 맞는 컨텍스트만 로드합니다.
my-monorepo/
├── CLAUDE.md ← 루트 (모노레포 공통 규칙만, 30줄)
├── apps/
│ ├── web/
│ │ └── CLAUDE.md ← Next.js 앱 컨텍스트
│ └── api/
│ └── CLAUDE.md ← FastAPI 백엔드 컨텍스트
└── packages/
├── ui/
│ └── CLAUDE.md ← shadcn/ui 컴포넌트 라이브러리
└── db/
└── CLAUDE.md ← Prisma 스키마 + 마이그레이션
cd apps/web && claude 실행 시 Claude는 (1) 루트 CLAUDE.md, (2) apps/web/CLAUDE.md 모두 로드합니다. 다른 패키지의 CLAUDE.md는 로드되지 않습니다.
루트 CLAUDE.md 예시
# Monorepo: ChartFly Platform
## 구조
- apps/web — Next.js 15 (사용자 대시보드)
- apps/api — FastAPI (Python 3.13)
- packages/ui — shadcn/ui 컴포넌트
- packages/db — Prisma 스키마 + DB 클라이언트
- packages/types — 공유 TypeScript 타입
## 규칙
- 코드 작성 시 반드시 cd로 해당 패키지로 이동 후 작업
- 시블링 패키지 수정 금지 (의도된 경우만 명시적으로)
- packages/db의 마이그레이션은 PR에 별도 검토 필요
## 명령어
- `bun install` — 전체 의존성 설치
- `bun dev` — 모든 앱 동시 실행 (Turborepo)
- `bun test` — 모든 패키지 테스트
패키지 CLAUDE.md 예시 (apps/web)
# apps/web — Next.js 15 대시보드
## 스택
- Next.js 15 App Router + TypeScript
- Tailwind + packages/ui (shadcn)
- packages/db로 DB 접근 (직접 prisma 호출 금지)
## 규칙
- 컴포넌트는 src/components, 라우트는 src/app
- API 호출은 apps/api로만, 직접 외부 호출 금지
- 페이지 컴포넌트는 항상 'use client' 또는 'use server' 명시
## 자주 쓰는 명령어
- `bun dev:web` — 로컬 실행 (포트 3000)
- `bun test:web` — 테스트
패턴 2: Scoped Edits
Claude Code를 패키지 디렉토리에서 시작하면 자연스럽게 그 패키지에 집중합니다.
# 잘못된 예 (루트에서 시작)
cd ~/my-monorepo
claude
> "UI 컴포넌트에 dark mode 추가해줘"
# → Claude가 apps/web에 dark mode 추가할 수 있음 (의도와 다름)
# 올바른 예
cd ~/my-monorepo/packages/ui
claude
> "dark mode 지원 추가해줘"
# → Claude는 packages/ui 내에서만 작업
추가 안전망: Claude가 다른 패키지 파일을 수정하려 할 때 차단하는 hook.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "input=$(cat); path=$(echo \"$input\" | jq -r '.tool_input.file_path'); pwd=$(pwd); if ! echo \"$path\" | grep -q \"$pwd\"; then echo \"Cross-package edit blocked: $path\" >&2; exit 2; fi"
}
]
}
]
}
}
자세한 hook 패턴은 Claude Code Hooks 8가지 패턴을 참고하세요.
패턴 3: Workspace별 비용 추적
Anthropic Admin API는 workspace_id 필드로 API 호출을 분류할 수 있습니다.
# 각 패키지에서 워크스페이스 별도 키 사용
# apps/web/.env.local
ANTHROPIC_API_KEY=sk-ant-api03-...workspace_web
# apps/api/.env.local
ANTHROPIC_API_KEY=sk-ant-api03-...workspace_api
# packages/ui/.env.local
ANTHROPIC_API_KEY=sk-ant-api03-...workspace_ui
월말에 Admin API로 워크스페이스별 사용량 조회:
import anthropic
client = anthropic.Anthropic()
usage = client.admin.usage.list(
starting_at="2026-05-01",
ending_at="2026-05-31",
group_by="workspace_id"
)
for row in usage.data:
print(f"{row.workspace_id}: ${row.total_cost:.2f}")
결과:
workspace_web: $42.50
workspace_api: $128.40
workspace_ui: $18.20
이제 "이번 달 apps/api가 비용을 가장 많이 썼다"가 데이터로 확인됩니다.
5가지 흔한 함정
1. 루트 CLAUDE.md에 모든 패키지 정보 넣기
50개 파일 미만이면 괜찮지만, 패키지 5개 이상이면 컨텍스트가 비대해집니다. 패키지별로 분리하세요.
2. Claude를 루트에서만 실행
cd <package> && claude 습관 들이세요. 그래야 Claude가 의도된 범위 내에서 작업합니다.
3. 단일 API 키로 모든 워크스페이스 사용
비용 추적이 불가능해집니다. 패키지별로 별도 키 발급하세요.
4. CLAUDE.md를 .gitignore에 추가
CLAUDE.md는 팀과 공유할 컨텍스트입니다. 커밋하세요. 시크릿이 들어가지 않도록 검토만.
5. Turborepo의 tasks 정의를 CLAUDE.md에서 누락
turbo.json의 tasks(build, test, lint, dev)는 CLAUDE.md에 명시하세요. Claude가 어떤 명령으로 패키지를 빌드/테스트하는지 알아야 합니다.
Frequently Asked Questions
Turborepo와 pnpm 워크스페이스에서 다른 설정이 필요한가요?
기본 패턴은 동일합니다. Turborepo는 turbo.json에 패키지 그래프와 작업 의존성을 정의하므로 루트 CLAUDE.md에 "테스트는 turbo run test로 실행" 같은 명령을 명시하면 됩니다. pnpm은 pnpm-workspace.yaml에 패키지 목록이 있고 pnpm -F <pkg> test로 패키지 단위 작업.
Nx 또는 Bun 워크스페이스는?
Nx는 nx.json + project.json이 패키지 메타데이터를 가지므로 CLAUDE.md에 "프로젝트 구조는 nx.json 참고"라고 명시하면 Claude가 자동 분석합니다. Bun은 package.json의 workspaces 배열이 패키지 정의이고 bun --filter <pkg> test로 실행.
패키지가 100개 넘으면?
각 패키지에 CLAUDE.md가 있어야 하지만, 패키지별 CLAUDE.md는 짧게(20-30줄) 유지하세요. 루트 CLAUDE.md는 "패키지 목록은 turbo.json 참고"로 위임하면 됩니다.
모노레포에서 sub-agent를 어떻게 활용하나요?
각 sub-agent를 다른 패키지에 할당해 병렬 실행. 예: agent A는 apps/web 수정, agent B는 apps/api 수정. 워크트리 + sub-agent 조합이 가장 효과적. 자세한 패턴은 Claude Code 워크트리 가이드를 참고하세요.
Claude가 다른 패키지를 수정하지 못하게 강제할 수 있나요?
위에서 보인 PreToolUse hook으로 가능합니다. 또는 CLAUDE.md에 "절대 시블링 패키지를 수정하지 말 것. 의도된 경우 명시적 사용자 확인 필요"라고 명시. Hook 방식이 더 강제력 있습니다.
Claude Code 모노레포 패턴 마스터하기
P1 Power Prompts 300 ($29) — 모노레포 패턴, 패키지별 CLAUDE.md 작성, sub-agent 분배 전략을 포함한 300개의 검증된 프롬프트. 솔로 개발자 기준 월 평균 50시간 절약.