모노레포 또는 대형 코드베이스에 Claude Code 설정하기

모노레포 또는 대형 코드베이스에 Claude Code 설정하기 (Set up Claude Code in a monorepo or large codebase)

대형 코드베이스는 수백만 줄짜리 단일 저장소일 수도, 많은 패키지를 가진 모노레포일 수도 있습니다. Claude Code는 어떤 크기에서도 동작하지만, 코드베이스가 커질수록 작은 프로젝트를 위해 조정된 기본값이 작업과 무관한 지침과 파일 읽기로 컨텍스트 창을 채워 토큰을 낭비하고 Claude 성능을 떨어뜨릴 수 있습니다. 이 가이드는 개인 개발자와 엔지니어링 팀이 작업이 닿는 코드베이스 부분으로 Claude를 한정하는 방법을 보여줍니다.

출처: 공식문서

본문

각 절은 설정이 본인 머신에 국한된 것인지 저장소에 커밋되는 것인지 명시합니다.

이 페이지가 다루는 내용

아래 표는 각 설정과 그 기능을 나열합니다. 그 뒤의 파일 트리는 이 페이지의 모든 코드 샘플이 참조하는 예시 모노레포입니다.

이 페이지의 설정

아래 각 설정은 독립적입니다. 서로를 대체하기보다 층을 이루므로, 저장소에 맞는 것을 고르세요. Where to start Claude 선택이 설정 파일이 사는 위치를 결정하므로 먼저 읽으세요. 모두 합치기는 이들을 조합한 결과를 보여줍니다.

원하는 것	사용 설정
모든 서브시스템을 덮는 루트 파일 하나 대신, 닿는 코드의 규칙만 로드	디렉터리별 CLAUDE.md 파일
작업하지 않는 패키지의 CLAUDE.md 파일 제외	claudeMdExcludes
Claude가 빌드 출력·생성 코드·벤더 의존성을 여는 것 차단	permissions.deny의 Read 거부 규칙
파일을 스캔하는 대신 언어 서버로 심볼 정의·호출자 찾기	코드 인텔리전스 플러그인
Claude가 워크트리를 만들 때 작업이 필요한 디렉터리만 체크아웃	worktree.sparsePaths
같은 세션에서 형제 패키지나 다른 저장소 읽기·편집	--add-dir 또는 additionalDirectories
특정 영역에만 관련될 때 로드되는 절차를 Claude에게 부여	디렉터리별 스킬
많은 디렉터리별 CLAUDE.md 파일을 모두가 설치하는 규칙 하나로 대체	내부 마켓플레이스의 플러그인

어떤 저장소에서도 컨텍스트를 작게 유지하는 워크플로 기법(예: 파일 읽기를 메인 대화 밖으로 빼는 [서브에이전트에서 탐색 실행](/docs/en/best-practices#use-subagents-for-investigation))은 [Claude Code 베스트 프랙티스](/docs/en/best-practices)를 보세요. 조직의 모든 개발자에게 기준 구성(roll-out)을 배포하려면 [조직용 Claude Code 설정](/docs/en/admin-setup)을 보세요.

예시 모노레포

이 페이지 전반의 예시는 세 패키지를 가진 모노레포를 참조합니다. 같은 패턴은 큰 단일 트리 코드베이스에서도 동작합니다: 예시가 packages/api/를 쓸 때 자신의 서브시스템 디렉터리(src/backend/, lib/core/ 등)로 대체하세요.

monorepo/
  CLAUDE.md                     # root instructions
  packages/
    api/
      CLAUDE.md                 # API-specific instructions
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # frontend-specific instructions
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # shared library instructions
      src/

클로드 시작 위치 선택

claude를 어디서 시작하느냐에 따라 Claude가 추가 권한 허가 없이 읽고 편집할 수 있는 파일, 시작 시 컨텍스트로 로드되는 CLAUDE.md 파일, 적용되는 프로젝트 설정이 결정됩니다.

시작 위치	파일 접근	시작 시 로드되는 CLAUDE.md	사용 시점
저장소 루트	모든 파일	루트만. 하위 디렉터리 파일은 Claude가 거기서 읽을 때 온디맨드 로드	작업이 여러 패키지·서브시스템에 걸침
하위 디렉터리	그 서브트리만(더 허용할 때까지)	그 디렉터리 + 모든 조상	작업이 한 패키지·서브시스템에 국한됨

.claude/settings.json의 프로젝트 설정은 CLAUDE.md 파일처럼 부모 디렉터리에서 상속되지 않습니다. 세션이 어떤 디렉터리의 .claude/settings.json을 읽는지는 Claude Code가 각 파일을 찾는 위치를 보세요.

아래 각 절은 설정 파일이 저장소 루트에 있는지 시작하는 하위 디렉터리에 있는지, 커밋되는지 로컬로 유지되는지를 명시합니다.

디렉터리별 CLAUDE.md 파일 레이어링

대형 코드베이스에서 저장소 루트의 단일 CLAUDE.md는 모든 서브시스템의 규칙을 덮도록 커지거나(현재 작업과 무관한 지침으로 컨텍스트를 소모), 너무 일반적이어서 쓸모없게 되는 경향이 있습니다. 지침을 디렉터리별 파일로 나누면 Claude가 저장소 전체 규칙에 더해 자신이 작업 중인 코드의 규칙만 로드합니다.

Claude Code는 시작 시 작업 디렉터리와 모든 부모 디렉터리의 모든 CLAUDE.md 파일을 로드하고, 거기서 파일을 읽을 때 각 하위 디렉터리의 파일을 온디맨드로 로드합니다. 루트 파일이 저장소 전체 규칙을 설정하고 각 하위 디렉터리가 자신의 규칙을 추가합니다.

흔한 분리는 두 수준입니다:

• 루트 CLAUDE.md: 코딩 표준, 커밋 규칙처럼 어디에나 적용되는 지침
• 하위 디렉터리별 CLAUDE.md: 해당 영역 스택에 특화된 규칙. 모노레포에서는 패키지당 하나. 큰 단일 트리에서는 src/db/, src/api/ 같은 서브시스템당 하나

이 파일들은 팀원이 상속받도록 저장소에 커밋하세요. 각 디렉터리의 담당자가 보통 그 파일을 유지합니다.

이미 체크인된 파일을 줄이려면 /doctor 점검을 실행하세요. 루트 CLAUDE.md는 모든 패키지에 적용되는 규칙을 담습니다:

Run package scripts from the package directory, not the monorepo root.
Prefix commit subjects with the package name, for example `api: add rate limiting`.
Never edit files under packages/*/generated/. Run `npm run codegen` in the package instead.

각 하위 디렉터리의 CLAUDE.md(여기선 packages/api/CLAUDE.md)는 그 영역에 특화된 규칙을 더합니다:

Copy `.env.example` to `.env` before running anything. Tests and the dev server fail without it.
Write database queries with the Knex query builder. Never put raw SQL strings in route handlers.
Never edit a migration after it has merged. Add a new migration instead.

packages/api/에서 Claude를 시작하면 packages/api/CLAUDE.md와 루트 CLAUDE.md가 둘 다 로드됩니다. Claude는 저장소 전체 규칙 옆에 로컬 지침을 보며, packages/web/의 지침은 컨텍스트에 없습니다. 모노레포가 아닌 트리의 어떤 하위 디렉터리에서도 마찬가지입니다. 어떤 파일이 로드됐는지 확인하려면 /context를 실행하고 Memory files 아래 목록을 확인하세요.

코드베이스와 모델이 변함에 따라 파일을 최신으로 유지하는 몇 가지 방법:

• 풀 리퀘스트에서 리뷰: CLAUDE.md 편집을 다른 문서 변경처럼 취급해 규칙이 코드를 따라가게 함
• 주요 모델 릴리스 후 재검토: 옛 모델의 한계를 우회하던 지침은 새 모델이 그 경우를 스스로 처리하면 오버헤드가 될 수 있음. 예를 들어 한계가 사라지면 단일 파일 리팩터를 강제하던 규칙을 삭제할 수 있음
• 업데이트를 제안하는 Stop 훅 추가: Stop 훅은 Claude가 응답을 끝낼 때 세션 트랜스크립트 경로를 받으므로, 스크립트가 세션을 검토해 노출된 공백이 생생한 동안 CLAUDE.md 업데이트를 제안할 수 있음

CLAUDE.md 파일이 어떻게 로드되고 상호작용하는지 더 보려면 메모리와 프로젝트 지침을 보세요.

디렉터리별 CLAUDE.md와 경로 스코프 규칙 중 선택

디렉터리별 CLAUDE.md 파일과 .claude/rules/ 아래의 경로 스코프 규칙은 둘 다 트리의 일부에 지침을 한정할 수 있습니다. 파일이 사는 위치와 로드 시점이 다릅니다.

접근법	파일 위치	로드 시점	사용 시점
디렉터리별 CLAUDE.md	디렉터리 안, 코드 옆	그 디렉터리에서 시작하면 시작 시, 또는 Claude가 거기서 파일을 읽으면 온디맨드	디렉터리 담당자가 자신의 규칙 유지. 지침이 코드와 함께 버전 관리
.claude/rules/의 경로 스코프 규칙	저장소 루트의 중앙 .claude/	Claude가 규칙의 paths: glob과 일치하는 파일 작업 시	모든 규칙을 한 곳에 두고 싶거나, 같은 규칙이 많은 흩어진 경로에 적용

스킬도 다루는 비교는 유사 기능 비교를 보세요.

무관한 CLAUDE.md 파일 제외

저장소 루트에서 Claude를 시작하면, 각 하위 디렉터리의 CLAUDE.md는 Claude가 그 디렉터리에서 파일을 읽는 즉시 로드됩니다. claudeMdExcludes 설정은 특정 파일을 경로나 glob 패턴으로 건너뛰어 로드하지 않게 합니다.

작업하지 않는 디렉터리(다른 팀의 패키지, 레거시 코드, 벤더 서브트리)에 쓰세요. 제외 목록은 정적이며 작업별 스위치가 아닙니다. 오늘 한 패키지, 내일 다른 패키지에 집중하려면, 제외를 편집하는 대신 그 패키지 디렉터리에서 Claude를 시작하세요.

제외를 자신에게만 적용하려면 .claude/settings.local.json에 설정을 두세요. Claude Code는 그 파일에 설정을 저장할 때 그 파일을 전역 gitignore에 추가합니다. 여기서 손으로 만드므로 직접 gitignore에 추가하세요. 패턴은 절대 파일 경로에 일치시키는 glob 구문을 쓰므로, 상대 스타일 패턴은 트리 어디에서나 일치하도록 **/로 시작하세요. 아래 예시는 다른 팀이 소유한 패키지를 제외합니다:

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

이것은 그 패키지 아래의 모든 CLAUDE.md와 규칙 파일을 건너뜁니다. 루트 CLAUDE.md와 작업하는 패키지는 여전히 정상 로드됩니다.

이 패턴들은 다른 일반적인 경우를 다룹니다:

• "**/packages/*/CLAUDE.md": 루트를 유지하면서 모든 패키지의 CLAUDE.md 제외
• "**/packages/legacy-*/**": 이름이 glob과 일치하는 모든 패키지 제외(규칙 포함)
• "/home/user/monorepo/legacy/CLAUDE.md": 절대 경로로 특정 파일 하나 제외

관리 정책 CLAUDE.md 파일은 제외할 수 없으므로 조직 전반 지침은 항상 적용됩니다. claudeMdExcludes는 설정 스코프(user, project, local, managed) 어디에서나 설정할 수 있습니다. 배열은 스코프 간 병합되므로 팀은 프로젝트 수준 기본값을 설정하고 개인은 로컬 오버라이드를 추가할 수 있습니다.

전체 제외 문서는 특정 CLAUDE.md 파일 제외를 보세요.

Claude가 읽는 것을 줄이기

지침은 컨텍스트에 들어가는 것의 일부일 뿐입니다. 파일 읽기는 코드베이스와 함께 커지는 또 다른 비용입니다. 아래 설정은 무관한 경로의 읽기를 차단하고 전수 파일 스캔을 언어 서버 조회로 대체합니다.

생성 및 벤더 코드 읽기 차단

Claude의 내용 검색은 기본적으로 .gitignore를 존중하므로 node_modules/, dist/, build/처럼 이미 거기 있는 경로는 추가 설정 없이 검색 결과에서 빠집니다.

벤더 SDK나 커밋된 생성 코드처럼 체크인된 경로는 permissions.deny에 Read 거부 규칙을 추가해 Claude가 그 파일을 여는 것을 차단하세요.

거부 규칙은 어떤 설정 파일에 두느냐에 따라 저장소에서 작업하는 모두, 자신만, 또는 머신의 모든 세션을 덮을 수 있습니다:

• 저장소에서 작업하는 모두: 규칙을 .claude/settings.json에 커밋하세요. 거기서 Claude를 시작한다면 저장소 루트에, 하위 디렉터리에서 시작한다면 각 패키지의 .claude/에. 이 페이지의 다른 프로젝트 설정처럼 그 파일은 부모 디렉터리에서 상속되지 않습니다.
• 자신만: 저장소 루트의 .claude/settings.local.json을 쓰세요. 이 파일은 시작 디렉터리와 무관하게 저장소 안의 모든 CLI 세션에서 로드되지만, Windows처럼 Claude Code가 저장소 루트를 사용하지 않는 경우는 제외됩니다. 예시의 Read(./**/vendor/**/*) 같은 상대 패턴은 여전히 저장소 루트보다 세션의 현재 작업 디렉터리에 고정되므로, 하위 디렉터리에서 세션을 시작한다면 이 파일의 규칙을 Read(//absolute/path/to/repo/**/vendor/**/*) 같은 // 절대 경로로 쓰세요. v2.1.211 이전에는 .claude/settings.local.json도 시작 디렉터리에서만 로드됐습니다.
• 모두, 모든 세션에서 강제: 관리 설정에 규칙을 두세요. user와 project 설정이 이를 덮을 수 없습니다.

아래 예시는 빌드 산출물과 벤더 SDK를 차단합니다. 디렉터리 패턴은 /**가 아니라 /**/*로 끝나므로, 각 규칙이 디렉터리 자체가 아니라 디렉터리 안의 모든 것을 덮습니다. 그러면 Claude는 여전히 ls dist나 cd build처럼 그 디렉터리를 나열하거나 이동할 수 있습니다.

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

거부 규칙은 Claude의 내장 파일 도구를 덮습니다. Bash에서는 Claude Code가 인식하는 cat, head, grep, find 같은 파일 명령이 거부된 경로를 인자로 받거나 < file 같은 리다이렉션 대상을 받을 때 덮습니다. Claude Code는 거부된 경로를 내장 Grep·Glob 도구 결과에서 빼려고 최선을 다합니다. 거부된 파일을 포함하는 디렉터리 위의 grep -r이나 find 같은 Bash 검색은 여전히 그 파일을 출력에 포함합니다.

거부 규칙은 파일을 스스로 여는 하위 프로세스를 덮지 않습니다. 전체 패턴 구문은 Read·Edit 권한 규칙을 보세요.

코드 인텔리전스로 파일 읽기 줄이기

대형 코드베이스에서 심볼이 정의되거나 사용되는 곳을 찾는 것은 많은 파일 읽기와 grep 호출을 소모할 수 있습니다. 코드 인텔리전스 플러그인은 Claude를 언어 서버에 연결해 트리를 스캔하는 대신 정의로 점프하고, 참조를 찾고, 타입 오류를 직접 표면화하게 합니다.

공식 마켓플레이스에는 TypeScript, Python, Go, Rust와 다른 일반 언어용 플러그인이 있습니다. Claude Code 세션 안에서 아래 명령을 실행해 TypeScript 플러그인을 설치하세요:

/plugin install typescript-lsp@claude-plugins-official

설치가 실패하면 Claude Code가 보고하는 메시지에 맞추세요:

• Marketplace "claude-plugins-official" not found: /plugin marketplace add anthropics/claude-plugins-official로 마켓플레이스를 추가한 후 설치를 재시도하세요.
• 플러그인이 마켓플레이스에서 발견되지 않음: 플러그인 이름을 확인하세요.

자신이 설치하는 대신 저장소의 모두에게 플러그인을 활성화하려면 enabledPlugins 프로젝트 설정에 추가하세요.

코드 인텔리전스 플러그인은 각 개발자 머신에 해당 언어의 언어 서버 바이너리가 필요합니다. 각 언어가 요구하는 바이너리를 보세요. 공식 마켓플레이스에서 설치하려면 마켓플레이스가 호스팅되는 GitHub에 네트워크 접근이 필요합니다. 제한된 네트워크에서는 내부 Git 호스트나 로컬 경로에서 마켓플레이스를 추가하세요.

이것은 위의 claudeMdExcludes와 Read 거부 규칙과 잘 어울립니다. 그것들은 무관한 내용을 컨텍스트에서 빼고, 코드 인텔리전스는 정의를 찾으려고 남은 것을 읽지 않게 합니다.

워크트리와 파일 접근 스코프

이 설정들은 워크트리에 무엇이 디스크에 있는지, 그리고 시작 지점 너머로 Claude가 읽고 쓸 수 있는 디렉터리를 제어합니다.

필요한 디렉터리만 체크아웃

--worktree 플래그는 새 git 워크트리에서 세션을 시작해 변경이 기본 체크아웃에서 격리되게 합니다. 기본적으로 전체 저장소를 체크아웃합니다. 대형 저장소에서 worktree.sparsePaths 설정은 git sparse-checkout을 사용해 나열된 디렉터리와 루트 수준 파일만 디스크에 쓰므로, 워크트리가 더 빨리 시작되고 공간을 덜 씁니다.

이 디렉터리에서 작업하는 모두가 같은 경로를 필요로 한다면 설정을 .claude/settings.json에 커밋하세요. 자신에게만 경로를 추가하려면 .claude/settings.local.json을 쓰세요: 목록은 스코프 간 병합되므로 로컬 파일이 커밋된 목록에 경로를 추가할 수 있지만 제거하지는 못합니다.

이 페이지의 JSON 예시는 설정을 하나씩 보여줍니다. .claude/settings.json에 이미 위의 permissions.deny 규칙 같은 다른 키가 있으면, 파일을 교체하지 말고 worktree 키를 옆에 추가하세요. 모두 합치기가 결합 결과를 보여줍니다.

아래 예시는 커밋된 파일을 보여줍니다:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ]
  }
}

Claude가 워크트리를 만들 때 전체 트리 대신 .claude/, packages/api/, packages/shared/만 체크아웃합니다. sparsePaths의 경로는 Claude를 어느 하위 디렉터리에서 시작하든 저장소 루트를 기준으로 합니다. 여기서는 패키지 루트뿐 아니라 어떤 디렉터리 경로도 동작합니다.

이것은 서브에이전트 워크트리 격리에 특히 유용합니다. 서브에이전트는 서브태스크를 위해 생성된 병렬 Claude 인스턴스이며, 워크트리에서 실행되는 각 서브에이전트는 전체 트리 대신 가벼운 체크아웃을 받습니다. 한 세션의 모든 워크트리는 같은 sparsePaths를 공유하므로, 한 서브에이전트가 packages/api/를 필요로 하고 다른 하나가 packages/web/를 필요로 하면 둘 다 나열하세요.

sparsePaths에는 개별 파일이 아니라 디렉터리를 나열하세요. package.json, tsconfig.base.json, 락 파일 같은 루트 수준 파일은 항상 나열한 디렉터리 옆에 체크아웃됩니다. 루트 수준 디렉터리는 그렇지 않으므로, 워크트리 안에서 저장소 루트의 .claude/settings.json, .claude/rules/, .claude/skills/를 쓰려면 목록에 .claude를 포함하세요.

sparse 체크아웃은 sparse 워크트리가 존재하는 동안 git이 저장소의 공유 .git/config에서 extensions.worktreeConfig를 활성화해야 합니다. Claude Code는 마지막 워크트리가 제거된 후 그 항목을 제거하되, Claude Code가 추가한 경우에만 그렇습니다. 자신이 직접 설정한 값을 제거하지는 않습니다. v2.1.207 이전에는 마지막 워크트리 제거 후에도 항목이 남아, tea 같은 go-git 기반 도구가 git config --unset extensions.worktreeConfig를 실행할 때까지 저장소를 열지 못했습니다.

node_modules 같은 큰 디렉터리를 워크트리 간 중복하지 않으려면 같은 .claude/settings.json에서 sparsePaths를 symlinkDirectories와 짝지으세요:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

이것은 각 워크트리의 node_modules/에서 메인 저장소의 복사본으로의 심볼릭 링크를 만들어 디스크에서 중복하지 않게 합니다.

`sparsePaths`와 `symlinkDirectories` 설정은 워크트리가 생성되기 전에 시작 디렉터리에서 읽힙니다. 생성 후 세션의 작업 디렉터리는 시작한 하위 디렉터리가 아니라 워크트리 루트입니다. 따라서 워크트리 안의 프로젝트 설정은 저장소 루트 파일의 체크아웃된 복사본인 워크트리 루트의 `.claude/settings.json`에서 로드됩니다. 워크트리 안에 필요한 권한 규칙이나 훅 같은 다른 설정은 저장소 루트의 `.claude/settings.json`에 두세요.

전체 워크트리 설정 참조는 Worktree settings를 보세요.

패키지 간 또는 저장소 간 접근 허용

이 절은 하위 디렉터리에서 Claude를 시작하거나 작업이 여러 체크아웃에 걸칠 때 적용됩니다. 큰 단일 트리에서 저장소 루트에서 시작한다면 Claude는 이미 모든 파일에 접근하므로 건너뛰어도 됩니다.

packages/api/에서 Claude를 시작하면 그 디렉터리 안의 파일을 읽고 쓸 수 있습니다. 작업이 api와 web이 모두 임포트하는 공유 타입 업데이트처럼 여러 패키지에 걸친 변경을 요구하면 형제 디렉터리에 접근을 허용해야 합니다. 같은 메커니즘이 별도로 체크아웃된 저장소에도 접근을 허용합니다.

.claude/settings.json의 additionalDirectories 설정은 Claude에게 작업 디렉터리 밖의 디렉터리 접근을 부여합니다. 아래 예시는 두 형제 패키지에 접근을 허용합니다:

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

상대 경로는 Claude를 시작한 디렉터리를 기준으로 해석됩니다. 이 구성으로 Claude는 packages/api/에서 작업하면서 packages/shared/와 packages/web/의 파일을 읽고 편집할 수 있습니다.

설정을 편집하지 않고 런타임에 접근을 허용할 수도 있습니다: Claude를 시작할 때 --add-dir을 전달하세요.

claude --add-dir ../shared

어떻게 디렉터리를 추가하든 Claude는 그 안의 파일을 읽고 편집할 수 있습니다. 그 디렉터리의 CLAUDE.md, .claude/rules/ 파일, 스킬도 로드되는지는 어떻게 추가했느냐에 달려 있습니다:

추가 방법	CLAUDE.md와 rules 로드	스킬 로드
additionalDirectories 설정	절대 안 함	절대 안 함
--add-dir 플래그 또는 /add-dir 명령	아래 환경 변수로만	예

--add-dir 또는 /add-dir로 추가한 디렉터리에서 CLAUDE.md와 rules 파일을 로드하려면 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 환경 변수를 설정하세요:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared

환경 변수는 additionalDirectories 설정에 나열된 디렉터리에는 효과가 없습니다. 자세한 내용은 추가 디렉터리에서 로드를 보세요.

이 영역의 모두가 필요로 하는 형제 디렉터리에는 additionalDirectories를 .claude/settings.json에 커밋하세요. 개인 선택이나 일회성 접근은 .claude/settings.local.json을 쓰거나 시작 시 --add-dir을 전달하세요.

디렉터리별 스킬 추가

어떤 하위 디렉터리든 자신의 스택에 스코프된 스킬을 정의할 수 있습니다. 스킬은 Claude가 관련 있다고 판단할 때 온디맨드 로드되므로 API 특화 도구가 프런트엔드 작업 중 컨텍스트를 소모하지 않습니다.

스킬은 디렉터리 안의 .claude/skills/ 아래에 있습니다. 그 영역의 코드와 함께 커밋해 저장소를 클론하는 누구나 얻도록 하세요. 모노레포에서는 패키지당 스킬 세트 하나일 수 있습니다. 큰 단일 트리 코드베이스에서는 src/db/.claude/skills/ 같은 서브시스템당 하나입니다.

하위 디렉터리 안에 스킬 디렉터리를 만드세요:

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

그런 다음 그 디렉터리 안, 여기선 packages/api/.claude/skills/api-testing/SKILL.md에 SKILL.md를 쓰세요. 이 예시는 Claude에게 API 패키지의 테스트 패턴을 가르칩니다:

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
---

## Test structure

Tests are in `src/__tests__/` mirroring the `src/` directory structure.
Each route file has a corresponding `.test.ts` file.

## Running tests

- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`
- Watch mode: `npm test -- --watch`

## Test utilities

- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()` for database tests
- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()` for authenticated endpoints

## Patterns

- Use `supertest` for HTTP assertions, not raw fetch
- Always wrap database tests in a transaction that rolls back
- Mock external services in `src/__tests__/mocks/`

다른 하위 디렉터리는 같은 방식으로 다른 스킬을 담습니다: packages/web/.claude/skills/component-patterns/는 테스트 대신 프런트엔드의 컴포넌트 규칙을 설명합니다. Claude가 packages/api/의 파일에서 작업하면 api-testing 스킬을 로드합니다. packages/web/에서 작업하면 대신 component-patterns를 로드합니다. 다른 쪽의 작업 중에는 어느 디렉터리의 스킬도 로드되지 않습니다.

스킬을 배치 대신 파일 패턴으로 스코프할 수도 있습니다. paths 프런트매터 필드는 glob 패턴을 받으며, Claude는 일치하는 파일로 작업할 때만 스킬을 자동으로 로드합니다. 저장소 루트의 .claude/skills/에 있지만 어디에 나타나든 특정 파일에만 적용되는 스킬(예: **/migrations/**에 스코프된 데이터베이스 마이그레이션 스킬)에 쓰세요.

스킬 생성과 구성에 대해 더 보려면 스킬 (Skills)을 보세요.

스킬 발견 가능성 유지

스킬이 많은 디렉터리에 퍼져 있으면 Claude가 고르는 목록이 커질 수 있습니다. Claude는 발견된 모든 스킬의 이름과 설명을 읽어 스킬을 고르며, 선택된 스킬의 전체 내용만 컨텍스트에 로드됩니다. 이 절은 목록을 작게 유지하고 축약에서 살아남는 설명을 쓰는 방법을 다룹니다.

어느 스킬이 범위 안인지는 Claude를 어디서 시작하느냐에 달려 있습니다:

• packages/api/ 같은 하위 디렉터리에서: 그 디렉터리, 저장소 루트까지의 모든 부모, user·enterprise 수준의 스킬
• 저장소 루트에서: 루트 스킬에 더해 Claude가 세션 중 닿는 모든 하위 디렉터리의 스킬. 수백 개까지 쌓일 수 있음
• --add-dir로 형제를 추가한 후: 그 형제의 스킬도 로드. additionalDirectories 설정은 파일 접근만 허용하고 스킬은 로드하지 않음

이름은 항상 로드되지만, 많을 때 설명이 축약되어 Claude가 스킬 적용 여부를 정하는 데 쓰는 키워드가 벗겨질 수 있습니다. 설명을 짧게 유지하고 요청에 들어갈 만한 단어(예: "writing or modifying tests in packages/api/")로 시작하세요.

PR 규칙이나 배포 체크리스트처럼 많은 디렉터리가 공유하는 스킬은 저장소 루트의 .claude/skills/에 두어 어떤 시작 디렉터리에서든 로드되게 하세요. 공유 스킬이 자체 버전 이력을 필요로 하거나 여러 저장소에서 동작해야 한다면 플러그인으로 패키지하세요. 플러그인 스킬은 plugin-name:skill-name 네임스페이스를 쓰므로 디렉터리별 스킬과 절대 충돌하지 않습니다. 플랫폼 팀이 한 곳에서 버전을 관리하고 업데이트할 수 있습니다.

어떤 스킬이 사용되지 않는지 찾으려면 OpenTelemetry logs exporter를 활성화하고 OTEL_LOG_TOOL_DETAILS=1을 설정해 스킬 이름이 레드랙트되지 않고 그대로 기록되게 하세요. skill_activated 이벤트는 skill.name 속성에 모든 호출을 기록하며, invocation_trigger는 명령, Claude, 중첩 스킬 중 무엇이 호출했는지 기록해 무엇을 통합하거나 폐기할지 알려줍니다.

레이어링이 확장을 멈출 때 규칙 중앙화

코드베이스가 커지면 디렉터리별 CLAUDE.md 파일을 관리하기 어려워질 수 있습니다. 규칙이 어긋나고, 파일이 낡고, 루트를 소유하는 사람이 없습니다. 이를 해결하는 것은 보통 각자 자신의 영역에서 작업하는 개발자가 아니라 저장소의 Claude Code 설정을 유지하는 팀의 몫입니다.

규칙과 참조 내용을 항상 로드되는 CLAUDE.md에서 옮겨 온디맨드로 로드되는 메커니즘에 넣으세요:

• 스킬 (Skills): Claude가 작업과 관련될 때만 로드하는 참조 자료
• 플러그인 (Plugins): 플랫폼 팀이 중앙에서 소유하는 버전 관리된 스킬·훅·명령 번들
• MCP 서버: 조직이 저장소 위에서 코드 검색이나 RAG 인덱스를 이미 운영한다면, MCP 도구로 노출해 Claude가 파일을 직접 읽는 대신 조회하게 함

플랫폼 팀이 이들을 중앙에서 강제하는 방법은 server-managed 또는 endpoint-managed 설정을 보세요.

세션 시작 시 올바른 플러그인 추천

규칙이 플러그인에 살면, 트리의 낯선 부분에서 Claude를 시작하는 팀원은 그 영역 담당자가 유지하는 플러그인이 무엇인지 알 신호가 없습니다. SessionStart 훅이 그 공백을 메울 수 있습니다. Claude Code는 훅이 stdout으로 출력하는 일반 텍스트를 첫 프롬프트 전에 Claude의 컨텍스트에 추가하기 때문입니다.

예를 들어 훅 입력에서 시작 디렉터리를 읽고, 저장소에 커밋된 경로-플러그인 맵에서 조회한 뒤, Claude가 첫 답변에서 전달할 추천을 출력하는 스크립트를 쓸 수 있습니다. 훅 작성·등록은 훅으로 작업 자동화를 보세요.

모두 합치기

아래 결합 구성은 모노레포 레이아웃을 사용합니다. 같은 파일은 큰 단일 트리의 어떤 하위 디렉터리에서도 동작합니다. 각 하위 디렉터리의 .claude/settings.json은 루트 파일에 층을 쌓는 대신 자체 완결적이어야 합니다.

이 예시는 .claude/settings.json에 worktree, additionalDirectories, Read 거부 규칙을 커밋해 packages/api/의 모든 개발자가 같은 형제 접근, sparse 경로, 제외를 얻도록 합니다. 아래 파일은 packages/api/의 커밋된 영역별 설정입니다:

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

이 세션이 packages/api/에서 시작하므로 형제 패키지의 CLAUDE.md 파일은 이미 범위 밖이라 claudeMdExcludes가 여기 필요 없습니다. 루트에서도 세션을 시작한다면 저장소 루트의 .claude/settings.local.json에 추가하세요.

additionalDirectories 항목은 packages/api/에서 Claude를 직접 시작할 때 적용됩니다. 이 세션에서 만든 워크트리 안에서는 작업 디렉터리가 워크트리 루트이므로 이 설정 파일이 로드되지 않습니다. 형제 패키지는 그것 없이도 워크트리 안에서 이미 닿을 수 있지만, 거부 규칙은 워크트리 세션이 그걸 받도록 워크트리 설정 노트가 설명하는 대로 저장소 루트의 .claude/settings.json에 두 번째 복사본이 필요합니다:

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

설정 후 저장소는 이 레이아웃을 갖습니다:

monorepo/
  CLAUDE.md
  .claude/settings.json                           # deny rules for worktree sessions
  packages/
    api/
      CLAUDE.md
      .claude/settings.json                       # worktree, additionalDirectories, deny rules
      .claude/skills/api-testing/SKILL.md
    web/
      CLAUDE.md
      .claude/skills/component-patterns/SKILL.md
    shared/
      CLAUDE.md

이 설정으로 packages/api/에서 Claude를 시작하면:

• 루트 CLAUDE.md와 packages/api/CLAUDE.md 로드, packages/web/CLAUDE.md 건너뜀
• packages/api/와 packages/shared/의 파일 읽기·편집 가능
• packages/api/의 dist/와 build/ 아래 빌드 출력 읽기 건너뜀
• api-testing 스킬 온디맨드로 사용 가능
• .claude/, packages/api/, packages/shared/, 루트 수준 파일을 담는 워크트리 생성, 루트 설정 파일에서 거부 규칙이 워크트리 전반에 적용

패키지에 걸친 변경 스코프와 계획

위 구성은 Claude가 보는 것을 제어합니다. 단일 변경이 공유 타입과 그걸 쓰는 모든 호출 지점 업데이트처럼 여러 패키지에 닿을 때, 작업을 스코프하고 순서를 정하는 방식도 결과에 영향을 줍니다.

두 기법이 크로스 패키지 변경을 일관되게 유지하는 데 도움이 됩니다:

• 한 세션에서 Claude에게 전체 변경을 주기: 공유 편집과 그 호출 지점을 함께 넘기면 각 편집 뒤의 결정을 재도출하는 대신 일관되게 유지합니다
• 편집 전 계획: plan mode에서 먼저 계획하고, Claude가 계획을 파일에 씁니다. 긴 크로스 패키지 세션은 진행 중 컨텍스트를 압축합니다. Claude Code는 각 압축 후 계획 파일을 다시 주입하므로, 계획은 대화 이력이 살아남지 못할 수 있어도 살아남습니다

다음 단계

이 구성이 자리 잡으면 다듬을 수 있습니다:

• 훅 (/hooks-guide)으로 Claude가 파일을 편집한 후 디렉터리별 린터나 타입 검사기를 실행
• 비용 효과적 관리 (Manage costs effectively)를 검토해 코드베이스 크기가 토큰 사용량에 미치는 영향과 더 넓은 배포 전 지출 한도를 설정하는 법을 이해
• Claude 블로그의 How Claude Code works in large codebases를 읽어 이 페이지의 저장소별 구성 위에 놓이는 조직 배포 패턴과 소유권 모델 파악

더 알아보기

관련 가이드:

• 베스트 프랙티스 (Best practices for Claude Code): 어떤 저장소에서도 컨텍스트를 작게 유지하는 워크플로 기법
• 워크트리 (Worktrees): --worktree 플래그와 서브에이전트 워크트리 격리, sparse-path 체크아웃
• 스킬 (Skills): 디렉터리별·경로 스코프 스킬 생성과 구성
• 메모리 (Memory): CLAUDE.md 파일 로딩과 프로젝트 지침