모노레포·대형 코드베이스 설정

기준일: 2026-07-26
공식 기준: Set up Claude Code in a monorepo or large codebase

개요

수백만 줄 저장소나 다패키지 모노레포에서도 Claude Code는 동작하지만, 소형 프로젝트 기본값은 관련 없는 지침·파일 읽기로 컨텍스트를 채울 수 있습니다. 작업이 닿는 부분으로 스코프를 좁히는 설정을 계층적으로 적용합니다. 설정은 서로 겹치며 대체하지 않습니다.

핵심 개념

목표	수단
서브시스템 컨벤션만	디렉터리별 CLAUDE.md
안 쓰는 패키지 제외	claudeMdExcludes
산출물·벤더 차단	permissions.deny Read
심볼 탐색	code intelligence / LSP 플러그인
worktree 범위	worktree.sparsePaths 등
패키지 반복 작업	디렉터리 .claude/skills/

상세

예제 모노레포 트리

monorepo/
  CLAUDE.md
  packages/
    api/
      CLAUDE.md
      .claude/skills/
      src/
    web/
      CLAUDE.md
      .claude/skills/
      src/
    shared/
      CLAUDE.md
      src/

시작 위치

패키지 루트에서 시작하면 해당 CLAUDE.md·설정이 중심에 옵니다. 모노레포 루트에서 시작하면 excludes·deny로 좁혀야 합니다.

CLAUDE.md 계층

루트: 전역 규칙. packages/api/CLAUDE.md: API 전용. 하위 파일은 Claude가 그 디렉터리 파일을 Read할 때 온디맨드 로드. path-scoped rules vs 디렉터리 CLAUDE.md 선택은 원문 표 참고.

제외

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

읽기 줄이기

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)",
      "Read(./**/*.generated.*)",
      "Read(./vendor/**)"
    ]
  }
}

code intelligence 플러그인/LSP로 정의·참조를 찾아 전 트리 스캔을 줄입니다.

worktree·교차 패키지 접근

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  },
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ],
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)"
    ]
  }
}

{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}

디렉터리 스킬

mkdir -p packages/api/.claude/skills/api-testing

SKILL.md에 description을 구체화해 discovery를 유지합니다.

한곳에 모은 배치 예

monorepo/
  CLAUDE.md
  .claude/settings.json
  packages/
    api/
      CLAUDE.md
      .claude/settings.json
      .claude/skills/api-testing/SKILL.md
    web/
      CLAUDE.md
      .claude/skills/component-patterns/SKILL.md
    shared/
      CLAUDE.md

계층이 한계에 달하면 공통 규칙을 플러그인으로 중앙화하고 plugin relevance로 세션 시작 제안을 켭니다.

패키지 가로지르는 변경

Plan mode로 영향 패키지를 나열한 뒤 패키지별 세션 또는 agent teams로 나눕니다.

체크리스트

• 작업 패키지 근처에서 세션을 시작한다
• 루트/패키지 CLAUDE.md + excludes 검토
• dist/build/vendor Read deny
• 필요 시 sparsePaths·additionalDirectories
• 패키지 스킬 description이 검색 가능

다음 단계

• Memory
• Permissions
• Skills
• Plugin relevance

기준일

• 문서 작성·동기화 기준일: 2026-07-26
• 원문: https://code.claude.com/docs/en/large-codebases