Claude Code 모노레포 활용 가이드: Turborepo, Nx에서의 실전 전략

모노레포는 점점 더 많은 조직이 선택하는 구조이지만, 동시에 개발자에게 독특한 도전 과제를 안겨 줍니다. 여러 패키지가 서로를 참조하고, 앱마다 빌드 구성이 다르며, 변경 하나가 예상치 못한 패키지에 영향을 줄 수 있습니다. Claude Code는 이 복잡성을 관리하기 위한 강력한 도구이지만, 기본 설정 그대로 쓰면 컨텍스트가 과하게 커지거나 잘못된 패키지를 수정하는 실수가 발생할 수 있습니다. 이 글은 Turborepo, Nx, pnpm workspace 같은 대표 도구와 Claude Code를 결합해 효율적으로 작업하는 실전 전략을 정리합니다.

1. 모노레포 구조 이해하기

전략을 논하기 전에, 대부분의 모노레포가 채택하는 디렉터리 구조를 공유 기반으로 놓고 시작합시다. 일반적으로 apps/에는 배포 대상 애플리케이션이, packages/에는 공유 라이브러리가, tools/에는 빌드/린트/스크립트 같은 인프라가 위치합니다. Claude Code가 이 구조를 인식하게 하려면 최상위 CLAUDE.md에 구조를 명시하고, 각 워크스페이스의 루트에 더 구체적인 CLAUDE.md를 두는 계층화 전략이 효과적입니다.

# CLAUDE.md (루트)
## 프로젝트 구조
- apps/web: Next.js 프런트엔드
- apps/api: NestJS 백엔드
- packages/ui: 공유 React 컴포넌트
- packages/sdk: 내부 API 클라이언트
- packages/config: 공유 eslint/tsconfig

## 규칙
- 앱 간 직접 import 금지. 반드시 packages 경유.
- 스타일 토큰은 packages/ui/tokens.ts 만 사용.

2. 도구별 특화 설정

Turborepo와의 통합

Turborepo는 태스크 그래프 기반 빌드 오케스트레이터입니다. Claude Code가 "이 변경이 어느 패키지에 영향을 미치는가"를 파악하려면 Turborepo의 turbo run build --dry=json 출력을 활용하는 것이 효과적입니다. Claude에 "터보의 dry run 결과를 분석해서 변경 범위와 영향 패키지를 표로 정리해 줘"라고 요청하면, 안전하게 머지해도 되는지 한눈에 판단할 수 있습니다.

turbo run build --dry=json --filter=...[HEAD^1] \
  | claude -p "이 변경이 영향을 미치는 패키지와 테스트를 표로 정리해줘"

Nx와의 통합

Nx는 태그 기반 경계 검증과 정교한 그래프 분석이 강점입니다. nx graph --file=graph.json으로 의존성 그래프를 JSON으로 내보낸 뒤 Claude에 함께 전달하면, 구조적 질문에 매우 정확한 답을 얻을 수 있습니다. "이 패키지를 둘로 쪼개면 어떤 순환 의존이 깨지는가?" 같은 질문도 가능합니다.

pnpm workspace

단순한 pnpm workspace 구조에서는 pnpm -r list --json과 pnpm why를 Claude에 연결해 쓰세요. Claude가 "이 라이브러리를 쓰는 모든 패키지" 같은 질문에 즉시 답할 수 있게 됩니다.

3. 컨텍스트 경계 관리

모노레포에서 가장 흔한 실수는 "전체 리포를 Claude에 통째로 넘기는 것"입니다. 1M 토큰 컨텍스트라도 프로젝트 규모에 따라 여전히 부족할 수 있고, 과한 컨텍스트는 오히려 집중을 흐립니다. 다음 세 가지 원칙을 기억하세요.

• 작업 범위를 앱 또는 패키지 단위로 제한: Claude 세션을 해당 디렉터리에서 시작합니다.
• 공유 패키지는 참조만: 실제 수정이 필요할 때만 컨텍스트에 포함시킵니다.
• 영향 패키지 목록을 먼저 계산: 터보/Nx의 그래프 도구로 범위를 좁힌 뒤 Claude에 전달합니다.

4. 워크트리 기반 병렬 작업

모노레포에서는 여러 개발자가 동시에 다른 앱이나 패키지를 수정하는 일이 많습니다. Claude Code의 워크트리 격리 기능을 사용하면, 각 작업이 서로 영향을 주지 않는 별도의 브랜치에서 진행될 수 있습니다. 백엔드 API 변경과 프런트엔드 컴포넌트 리팩토링을 각각의 워크트리에서 동시에 돌리면, 한쪽이 실패해도 다른 쪽이 영향을 받지 않습니다.

# 각 작업마다 독립된 워크트리에서 Claude 실행
cd apps/api && claude --worktree feature/api-auth
cd packages/ui && claude --worktree feature/ui-revamp

5. 경계 위반 자동 감지

모노레포의 건강을 지키는 핵심은 "패키지 간 허용된 의존만 유지되는가"입니다. Nx의 module-boundaries 규칙이나 eslint-plugin-boundaries로 정적 검사를 강제하세요. Claude에 "이 리포의 경계 규칙에 어긋나는 import를 찾아서 수정해 줘"라고 요청하면, 일괄 정리해 줍니다. 이 작업은 팀이 수시로 돌리는 위생 활동으로 자리잡으면 좋습니다.

6. 공통 타입/스키마 동기화

프런트엔드와 백엔드가 공유하는 타입이나 스키마는 한곳에 정의되어야 하고, 모든 패키지가 그것을 참조해야 합니다. Claude에 "API 스키마에서 새 필드를 추가하고, 이를 사용하는 모든 패키지의 타입을 함께 업데이트해 줘"라고 요청하면, 일관성 있는 전체 변경이 수행됩니다. 스키마 원천은 보통 packages/shared-types나 OpenAPI/Protobuf 파일입니다.

claude "packages/shared-types/user.ts 의 User 인터페이스에
'locale: Locale' 필드를 추가하고,
apps/web 과 apps/api 에서 이 필드를 사용하는 부분을
모두 찾아 적절히 수정해줘.
각 파일마다 개별 커밋으로 분리해줘."

7. 빌드 캐시와 Claude의 결합

Turborepo의 원격 캐시, Nx Cloud는 빌드 시간을 극적으로 줄이는 핵심 기능입니다. Claude 세션에서 변경한 패키지만 타깃 빌드를 돌리면, CI가 아닌 로컬에서도 수 초 안에 검증이 끝납니다. Claude에 "현재 변경된 파일이 영향을 주는 패키지만 빌드하고 테스트해 줘"라고 지시하면 됩니다.

turbo run test --filter=...[HEAD]
# 또는
nx affected:test

8. CODEOWNERS와 책임 분리

모노레포에서는 여러 팀이 코드베이스를 공유하므로, 변경 시 적절한 리뷰어가 지정되어야 합니다. CODEOWNERS 파일을 잘 작성하고, Claude에 "내 변경 범위를 보고 관련 팀이 리뷰에 필요한지 알려 줘"라고 물으면, PR 작성 전에 미리 조율이 가능합니다.

9. 공유 Claude 설정의 관리

모노레포 내 모든 패키지가 동일한 품질 기준을 따르도록 하려면, Claude 관련 설정도 공유되어야 합니다. 루트의 .claude/settings.json에 공통 훅, 허용 도구, 모델 기본값을 정의하고, 각 패키지의 .claude/CLAUDE.md에는 해당 패키지의 도메인 규칙만 기록하는 구조가 이상적입니다.

10. 대규모 변경의 단계별 실행

한 번의 PR에 모노레포 전체의 변경을 담으면 리뷰가 불가능해집니다. Claude에 "이 변경을 영향 패키지 단위로 분리해 작은 PR 시리즈로 계획해 줘"라고 요청하면, 논리적으로 독립적인 단계로 나눈 체크리스트를 얻을 수 있습니다. 각 단계는 독립적으로 배포 가능해야 하며, 단계 사이의 시간 간격은 최소 하루를 두는 것이 안정적입니다.

11. 공통 워크플로우 템플릿

자주 반복되는 작업은 슬래시 명령으로 고정하세요. 예를 들어 /new-package 명령으로 새 패키지 생성(폴더, package.json, tsconfig, eslint, 테스트 스캐폴드까지), /bump-deps로 워크스페이스 전반의 의존성 업데이트를 표준화할 수 있습니다.

# .claude/commands/new-package.md
새 패키지를 packages/$ARGUMENTS 에 생성해줘.
- package.json: name 은 @yourorg/$ARGUMENTS
- tsconfig: packages/config/tsconfig.json 를 extend
- eslint: packages/config/eslint.js 사용
- src/index.ts 와 __tests__/index.test.ts 스캐폴드 생성
- 루트의 CODEOWNERS 에 적절한 팀 할당

12. 흔한 함정

• 전체 탐색 남용: 매번 grep -r로 전체 리포를 뒤지는 것은 느리고 토큰 낭비입니다. Turbo/Nx 그래프를 먼저 활용하세요.
• 버전 드리프트: 패키지별 의존성 버전이 미묘하게 달라지면 지옥이 시작됩니다. syncpack 같은 도구를 함께 쓰세요.
• 공유 패키지 과도 수정: 공유 패키지를 수정하면 모든 소비자가 영향을 받습니다. 변경 전 영향 분석이 필수입니다.
• 캐시 무효화 실수: 빌드 산출물의 해시가 잘못 잡히면 잘못된 캐시가 공유될 수 있습니다. 입력값에 빠진 파일이 없는지 주기적으로 점검하세요.

사례 연구: 15개 앱, 40개 패키지의 pnpm 모노레포

한 핀테크 회사는 15개의 앱과 40개의 공유 패키지로 구성된 pnpm workspace를 운영합니다. Claude Code 도입 전에는 전체 CI 시간이 평균 40분이었으며, 스키마 변경 시 리그레션이 잦았습니다. 도입 후 다음 세 가지 변화가 있었습니다. 첫째, 루트 CLAUDE.md에 경계 규칙을 명시해 잘못된 import가 PR 단계에서 걸러졌습니다. 둘째, Claude가 영향 범위를 미리 계산해 필요한 테스트만 돌려, PR 평균 CI 시간이 12분으로 줄었습니다. 셋째, 스키마 변경 PR의 리뷰 타임이 절반으로 줄고, 리뷰어가 "놓친 사용처"를 지적하는 코멘트가 사라졌습니다.

마무리: 모노레포의 진짜 가치는 일관성

모노레포가 좋은 이유는 한 저장소에 모든 것이 있기 때문이 아니라, 전체를 동시에 일관되게 변경할 수 있기 때문입니다. Claude Code는 이 "동시 일관성"을 인간이 혼자 감당하기 어려운 수준까지 확장해 줍니다. 제대로 쓰면 여러 앱에 걸친 스키마 변경, 디자인 토큰 전환, 의존성 업그레이드 같은 작업이 몇 시간 안에 끝납니다.

오늘부터 여러분의 모노레포에 CLAUDE.md 계층을 도입하고, 영향 범위 계산을 자동화하며, 워크트리 기반 병렬 작업을 시도해 보세요. 3개월 뒤에는 "우리 모노레포가 이렇게 빨리 변경 가능한 구조가 될 줄 몰랐다"는 감회를 느끼게 될 것입니다. Claude Korea는 앞으로 Nx, Turborepo, Bazel 등 도구별 심화 가이드를 차례로 다룰 예정입니다.

모노레포의 크기는 약점이 아닙니다. 다만 일관성을 지킬 수 없을 때 약점이 될 뿐입니다.

관련 리소스