Claude Code 모노레포 워크플로우 설정 가이드: 멀티루트 워크스페이스, 패키지별 규칙, 슬래시 커맨드, 테스트 자동화
Claude Code 모노레포 워크플로우 완벽 설정 가이드
대규모 모노레포 프로젝트에서 Claude Code를 효율적으로 활용하려면 멀티루트 워크스페이스 감지, 패키지별 CLAUDE.md 규칙, 커스텀 슬래시 커맨드, 그리고 공유 의존성 간 자동화된 테스트 러너 통합이 필수입니다. 이 가이드에서는 실무에서 바로 적용 가능한 단계별 설정 방법을 안내합니다.
1단계: Claude Code 설치 및 초기 설정
먼저 Claude Code CLI를 설치하고 인증을 완료합니다.
# npm을 통한 전역 설치
npm install -g @anthropic-ai/claude-code
설치 확인
claude —version
인증 (브라우저 기반 OAuth 진행)
claude auth login
모노레포 루트 디렉터리에서 Claude Code를 초기화합니다.
cd ~/projects/my-monorepo
claude init
2단계: 멀티루트 워크스페이스 감지 구성
모노레포에서는 여러 패키지가 독립적인 컨텍스트를 가집니다. Claude Code는 디렉터리 계층 구조의 CLAUDE.md 파일을 자동으로 탐지하여 현재 작업 위치에 맞는 규칙을 적용합니다.
모노레포 디렉터리 구조 예시
my-monorepo/
├── CLAUDE.md # 루트 레벨 글로벌 규칙
├── package.json
├── turbo.json
├── packages/
│ ├── shared-utils/
│ │ ├── CLAUDE.md # shared-utils 전용 규칙
│ │ ├── package.json
│ │ └── src/
│ ├── web-app/
│ │ ├── CLAUDE.md # web-app 전용 규칙
│ │ ├── package.json
│ │ └── src/
│ └── api-server/
│ ├── CLAUDE.md # api-server 전용 규칙
│ ├── package.json
│ └── src/
└── .claude/
└── commands/
├── test-affected.md
└── lint-package.md
Claude Code는 현재 작업 디렉터리에서 루트까지 모든 CLAUDE.md를 병합하여 컨텍스트를 구성합니다. 하위 디렉터리의 규칙이 상위 규칙보다 우선합니다.
3단계: 패키지별 CLAUDE.md 규칙 작성
루트 CLAUDE.md (글로벌 규칙)
# 모노레포 글로벌 규칙
프로젝트 구조
- 패키지 매니저: pnpm
- 빌드 시스템: Turborepo
- 테스트 프레임워크: Vitest
코딩 컨벤션
- TypeScript strict 모드 필수
- 모든 exports는 barrel file(index.ts)을 통해 노출
- 공유 타입은 packages/shared-utils/types에 정의
커밋 규칙
- Conventional Commits 형식 사용
scope는 패키지명 사용: feat(web-app): 설명
packages/web-app/CLAUDE.md (프런트엔드 규칙)
# Web App 패키지 규칙
## 기술 스택
- React 19 + Next.js 15 App Router
- 상태관리: Zustand
- 스타일: Tailwind CSS v4
## 테스트
- 컴포넌트 테스트: Vitest + Testing Library
- 실행 명령: pnpm --filter web-app test
## 주의사항
- shared-utils를 import할 때 workspace 프로토콜 사용
- API 호출은 반드시 api-server의 타입 정의를 참조packages/api-server/CLAUDE.md (백엔드 규칙)
# API Server 패키지 규칙
## 기술 스택
- Hono + Node.js
- ORM: Drizzle
- 인증: JWT (환경변수 AUTH_SECRET 사용)
## 테스트
- 통합 테스트는 실제 DB 사용 (mock 금지)
- 실행 명령: pnpm --filter api-server test
## API 규칙
- 모든 엔드포인트는 Zod 스키마로 입/출력 검증
- 에러 응답은 RFC 7807 Problem Details 형식4단계: 커스텀 슬래시 커맨드 생성
.claude/commands/ 디렉터리에 마크다운 파일을 생성하여 반복 작업을 자동화합니다.
.claude/commands/test-affected.md
변경된 파일을 기반으로 영향받는 패키지의 테스트를 실행해주세요.
- git diff —name-only로 변경된 파일 목록을 확인
- 변경된 파일이 속한 패키지를 식별
- 해당 패키지의 의존성 그래프를 분석하여 영향받는 패키지도 포함
- 다음 명령으로 테스트 실행: pnpm —filter …[$PACKAGE_NAME] test
실패한 테스트가 있으면 원인 분석 및 수정 제안
.claude/commands/sync-types.md
shared-utils의 타입 변경사항을 모든 의존 패키지에 동기화해주세요.
1. packages/shared-utils/src/types/ 디렉터리의 변경사항 확인
2. 해당 타입을 import하는 모든 패키지 파일 검색
3. 타입 변경으로 인한 호환성 문제 식별
4. 필요한 수정사항을 각 패키지에 적용
5. pnpm typecheck 실행으로 전체 타입 검증사용 방법:
# Claude Code 대화 중 슬래시 커맨드 실행
/test-affected
/sync-types
5단계: 공유 의존성 간 자동 테스트 러너 통합
모노레포에서 공유 패키지 변경 시 의존하는 모든 패키지의 테스트를 자동으로 실행하도록 구성합니다.
turbo.json 설정
{
“$schema”: “https://turbo.build/schema.json”,
“tasks”: {
“test”: {
“dependsOn”: [“^build”],
“inputs”: [“src/”, “tests/”, “package.json”],
“outputs”: [“coverage/**”]
},
“test:affected”: {
“dependsOn”: [“^build”]
},
“typecheck”: {
“dependsOn”: [“^build”]
}
}
}
루트 package.json 스크립트
{
"scripts": {
"test": "turbo run test",
"test:affected": "turbo run test --filter=...[origin/main]",
"typecheck": "turbo run typecheck",
"test:shared-deps": "turbo run test --filter=...shared-utils"
}
}Claude Code 대화에서 다음과 같이 활용합니다.
# shared-utils 변경 후 영향받는 모든 패키지 테스트
claude “shared-utils의 formatDate 함수를 수정했어. 영향받는 패키지를 찾아서 테스트 돌려줘”
특정 패키지 컨텍스트에서 작업
cd packages/api-server
claude “이 패키지의 실패하는 테스트를 분석하고 수정해줘”
6단계: CI/CD 파이프라인 연동
Claude Code를 GitHub Actions와 연동하여 PR 리뷰를 자동화할 수 있습니다.
# .github/workflows/claude-review.yml
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
model: claude-sonnet-4-6
trigger_phrase: "/review"
## Pro Tips: 파워 유저를 위한 고급 설정
- **컨텍스트 최적화**: .claudeignore 파일을 사용하여 node_modules, dist, .next 등 불필요한 디렉터리를 제외하면 응답 속도가 크게 향상됩니다.- **세션 유지**: claude --resume 플래그로 이전 대화 컨텍스트를 이어갈 수 있어 장시간 리팩터링 작업에 유용합니다.- **병렬 세션**: 각 패키지 디렉터리에서 별도의 Claude Code 세션을 열어 독립적인 작업을 병렬 수행할 수 있습니다.- **메모리 시스템 활용**: ~/.claude/projects/ 경로에 프로젝트별 메모리를 저장하면 세션 간 컨텍스트가 유지됩니다.- **Headless 모드**: claude -p "질의내용"으로 비대화형 실행이 가능하여 스크립트에 통합하기 좋습니다.
## Troubleshooting: 자주 발생하는 문제 해결
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| CLAUDE.md가 인식되지 않음 | 파일명 대소문자 불일치 | 정확히 CLAUDE.md로 작성 (전체 대문자) |
| 슬래시 커맨드가 목록에 없음 | 경로 오류 | .claude/commands/ 디렉터리 위치를 프로젝트 루트로 확인 |
| 패키지 간 타입 참조 실패 | 빌드 순서 문제 | turbo.json에서 dependsOn: ["^build"] 설정 확인 |
| 테스트 실행 시 모듈 미발견 | 워크스페이스 링크 미설정 | pnpm install 재실행으로 심볼릭 링크 갱신 |
| 컨텍스트 윈도우 초과 경고 | 대규모 파일 포함 | .claudeignore에 대용량 생성 파일 패턴 추가 |
Q1: CLAUDE.md 파일의 우선순위는 어떻게 결정되나요?
Claude Code는 현재 작업 디렉터리에서 루트 디렉터리까지 모든 CLAUDE.md 파일을 탐색합니다. 하위 디렉터리의 규칙이 상위 디렉터리의 동일한 규칙보다 우선 적용됩니다. 예를 들어, 루트에서 "TypeScript strict 모드"를 지정하고 특정 패키지에서 별도 설정을 명시하면 패키지 레벨의 규칙이 적용됩니다. 또한 ~/.claude/CLAUDE.md에 사용자 글로벌 규칙을 설정할 수 있으며, 이는 가장 낮은 우선순위를 가집니다.
Q2: 커스텀 슬래시 커맨드에서 동적 변수를 사용할 수 있나요?
네, 슬래시 커맨드 마크다운 파일 내에서 $ARGUMENTS를 사용하여 실행 시 인자를 전달할 수 있습니다. 예를 들어 /test-package web-app과 같이 호출하면 커맨드 내의 $ARGUMENTS가 “web-app”으로 치환됩니다. 이를 통해 하나의 커맨드 템플릿으로 여러 패키지에 동일한 워크플로우를 적용할 수 있습니다.
Q3: 대규모 모노레포에서 Claude Code의 성능을 최적화하는 방법은?
세 가지 핵심 전략이 있습니다. 첫째, .claudeignore 파일에 빌드 산출물(dist/, .next/, node_modules/)과 대용량 생성 파일을 등록하세요. 둘째, 특정 패키지 디렉터리로 이동한 후 Claude Code를 실행하면 해당 패키지 컨텍스트에 집중합니다. 셋째, CLAUDE.md에 패키지 간 의존성 관계를 명시하면 Claude가 관련 파일만 참조하여 응답 품질과 속도가 모두 향상됩니다.