MemoryLake
모든 글로 돌아가기
Tutorial2026년 11월 17일·11 분 소요

대규모 코드베이스에서 Claude Code를 어떻게 설정해야 할까요? 어떤 CLAUDE.md 파일이 어디서 로드되는지, 다른 패키지의 지침을 제외하는 방법, 그리고 컨벤션을 skills에 넣어야 하는 시점 (2026)

여러분의 모노레포에는 API 패키지, 웹 앱, 공용 라이브러리, 그리고 아무도 건드리지 않는 레거시 서비스가 있습니다. 루트의 CLAUDE.md는 이 모든 것을 다루기 위해 비대해졌고, Claude는 API 경로를 수정하는 동안 웹 팀의 컴포넌트 규칙을 계속 적용합니다. 그러는 사이 매 세션의 처음 몇 분을 타입이 정의된 위치를 찾기 위해 생성된 파일들을 읽는 데 소비합니다.

Anthropic은 Claude Code 문서에서 바로 이런 상황을 위한 가이드를 제공합니다. 이 문제는 한 문장으로 요약됩니다: 코드베이스가 커짐에 따라 "작은 프로젝트에 맞춰진 기본 설정이 작업과 무관한 지침과 파일 읽기로 context 창을 채워 토큰 비용을 발생시키고 Claude의 성능을 저하시킬 수 있습니다."

이 가이드는 해당 문서에서 권장하는 내용을 다룹니다: 시작 디렉토리에 따라 어떤 CLAUDE.md 파일이 로드되는지, 디렉토리별로 지침을 계층화하는 방법, 다른 패키지의 지침을 제외하는 방법, Claude가 불필요한 코드를 읽지 않게 하는 방법, skills가 어떻게 적용되는지, 그리고 컨벤션을 CLAUDE.md에서 완전히 옮겨야 할 시점은 언제인지 설명합니다.

Claude를 시작하는 위치가 로드 대상을 결정합니다

첫 번째 결정은 가장 간단하면서도 가장 큰 영향을 미칩니다. 문서에 따르면: "claude를 실행하는 위치에 따라 Claude가 추가 권한 승인 없이 읽고 편집할 수 있는 파일, 시작 시 context에 로드되는 CLAUDE.md 파일, 그리고 적용되는 프로젝트 설정이 결정됩니다."

두 가지 선택지를 비교해 보겠습니다:

  • 리포지토리 루트에서 시작. Claude는 모든 파일에 액세스할 수 있습니다. 시작 시 루트 CLAUDE.md만 로드하며, 하위 디렉토리 파일은 필요할 때 로드됩니다.
  • 하위 디렉토리에서 시작. Claude는 더 많은 권한을 부여하기 전까지 해당 하위 트리만 액세스할 수 있습니다. 시작 시 해당 디렉토리의 CLAUDE.md와 모든 상위 디렉토리의 파일을 로드합니다.

문서에서는 작업이 여러 패키지에 걸쳐 있을 때는 루트에서 시작하고, 작업 범위가 하나의 패키지로 제한될 때는 하위 디렉토리에서 시작할 것을 권장합니다.

놓치기 쉬운 세부 사항 하나는 다음과 같습니다: ".claude/settings.json의 프로젝트 설정은 CLAUDE.md 파일처럼 상위 디렉토리에서 상속되지 않습니다." 지침은 상위 디렉토리에서 계층적으로 전달되지만, 설정은 그렇지 않습니다.

디렉토리별로 CLAUDE.md 파일 계층화하기

문서에서는 하나의 루트 파일이 제대로 작동하지 않는 이유를 설명합니다: "모든 하위 시스템의 컨벤션을 다루기 위해 비대해져서 현재 작업과 무관한 지침에 context를 낭비하거나, 너무 일반적이어서 유용하지 않게 되는 경향이 있습니다."

권장 사항은 두 가지 수준입니다:

  • 루트 CLAUDE.md: 코딩 표준 및 커밋 컨벤션과 같이 모든 곳에 적용되는 지침용.
  • 패키지 또는 하위 시스템별 CLAUDE.md: 해당 영역의 스택에 특화된 컨벤션용.

문서의 예시는 그 효과를 보여줍니다. API 패키지에서 Claude를 시작하면 해당 패키지의 CLAUDE.md와 루트 파일을 로드하며, "context에 packages/web/의 지침은 포함되지 않습니다."

실제로 어떤 파일이 로드되었는지 확인하려면 /context all을 실행하고 Memory files 아래의 목록을 확인하세요.

또한 문서에서는 이 파일들을 최신 상태로 유지하는 세 가지 방법을 제시합니다:

  • 풀 리퀘스트에서 CLAUDE.md 수정을 검토하세요. 다른 문서와 마찬가지입니다.
  • 주요 모델 출시 후 다시 검토하세요. 이전 모델의 한계를 보완하기 위한 지침은 최신 모델이 해당 케이스를 처리하게 되면 오버헤드가 될 수 있습니다.
  • 업데이트를 제안하는 Stop hook을 추가하세요. Stop hook은 세션 트랜스크립트 경로를 수신하므로, 기억이 생생할 때 스크립트가 CLAUDE.md 변경 사항을 제안할 수 있습니다.

필요에 따라 로드되는 하위 디렉토리 파일은 루트 파일과 다른 크기 동작을 보입니다. 이에 대해서는 Claude Code의 하위 디렉토리 CLAUDE.md 제한 가이드에서 다루었습니다.

디렉토리별 CLAUDE.md 또는 경로 범위 규칙

Claude Code에는 트리의 특정 부분에 지침을 타겟팅하는 두 번째 방법이 있습니다: .claude/rules/ 아래에 paths: glob을 사용하는 규칙 파일입니다. 문서에서는 이 두 가지를 비교합니다.

디렉토리별 CLAUDE.md는 해당 코드와 함께 디렉토리 내부에 위치합니다. 해당 디렉토리에서 시작할 때 또는 필요할 때 로드됩니다. 디렉토리 소유자가 자신의 컨벤션을 직접 관리하는 팀에 적합합니다.

경로 범위 규칙(path-scoped rule)은 리포지토리 루트의 중앙 .claude/ 폴더에 위치합니다. Claude가 해당 glob과 일치하는 파일로 작업할 때 로드됩니다. 모든 컨벤션을 한 곳에 모으고 싶거나, 흩어져 있는 많은 경로에 적용되는 규칙을 원하는 팀에 적합합니다.

규칙 파일의 작동 방식은 Claude Code 규칙이란 무엇인가 가이드에서 다루었습니다.

다른 패키지의 지침 제외하기

루트에서 시작할 때, Claude가 해당 파일을 건드리면 각 하위 디렉토리의 CLAUDE.md가 필요에 따라 로드될 수 있습니다. claudeMdExcludes 설정은 경로 또는 glob을 통해 특정 파일을 건너뛰어 "절대 로드되지 않도록" 합니다.

문서에서는 다른 팀의 패키지, 레거시 코드 또는 외부 라이브러리(vendored) 하위 트리와 같이 절대 작업하지 않는 디렉토리에 이 설정을 사용할 것을 제안합니다. 예상대로 작동하는지 결정하는 몇 가지 세부 사항은 다음과 같습니다:

  • 정적입니다. "제외 목록은 정적이며 작업별 스위치가 아닙니다." 매일 다른 패키지에 집중하려면 제외 설정을 편집하는 대신 해당 패키지에서 Claude를 시작하세요.
  • 패턴은 절대 경로와 일치합니다. 트리 어디에서나 일치시키려면 상대 스타일 패턴을 **/로 시작하세요.
  • 규칙도 포함됩니다. 패키지 폴더를 제외하면 그 아래의 모든 CLAUDE.md 및 규칙 파일을 건너뛰는 반면, 루트 CLAUDE.md와 작업 중인 패키지는 정상적으로 로드됩니다.
  • 범위가 병합됩니다. 사용자, 프로젝트, 로컬 또는 관리형 범위에서 설정할 수 있으며, 배열은 범위 간에 병합되므로 팀 기본값과 개인 추가 사항이 결합됩니다.
  • 관리형 파일은 여전히 로드됩니다. 조직에서 관리형 CLAUDE.md를 배포하는 경우, 이와 일치하는 패턴이 있어도 건너뛰지 않습니다.

본인에게만 적용되는 제외 사항의 경우, 문서에서는 .claude/settings.local.json을 제안합니다. 이 파일을 직접 생성하는 경우 gitignore에 직접 추가하세요.

Claude가 불필요한 코드를 읽지 않게 하기

지침은 context를 채우는 요소 중 일부일 뿐입니다. 문서에 따르면: "파일 읽기는 코드베이스와 함께 증가하는 또 다른 비용입니다."

Gitignored 경로. Claude의 콘텐츠 검색은 기본적으로 .gitignore를 준수하므로 node_modules/, dist/, build/와 같은 경로는 검색 결과에서 제외됩니다.

커밋된 생성 코드 또는 외부 코드. 커밋된 경로의 경우 permissions.deny에 Read 거부 규칙을 추가하세요. 리포지토리의 모든 사람을 위해 .claude/settings.json에, 본인을 위해 .claude/settings.local.json에, 또는 모든 곳에 강제 적용하려면 관리형 설정에 추가하세요.

문서는 제한 사항을 명확히 합니다: "거부 규칙은 파일을 직접 여는 하위 프로세스에는 적용되지 않습니다."

언어 서버 조회. 코드 인텔리전스 플러그인은 Claude를 언어 서버에 연결하여 "트리를 스캔하는 대신" 정의로 이동하고 참조를 찾을 수 있게 합니다. 문서에 따르면 이는 제외 및 거부 규칙과 잘 어울립니다. 이러한 규칙은 무관한 콘텐츠를 배제하고, 코드 인텔리전스는 Claude가 남은 내용을 일일이 읽지 않도록 도와줍니다.

필요한 것만 체크아웃하고 디렉토리를 신중하게 추가하기

작업 트리(worktrees)의 경우, worktree.sparsePaths 설정은 git sparse-checkout을 사용하여 나열된 디렉토리와 루트 수준 파일만 씁니다. 루트의 설정과 규칙을 작업 트리 내에서 사용하려면 목록에 .claude를 포함하세요.

한 패키지에서 시작하여 형제 패키지에 대한 액세스가 필요할 때, 액세스 권한을 부여하는 방식에 따라 로드되는 대상이 달라집니다. 문서의 표 내용입니다:

  • additionalDirectories 설정: CLAUDE.md, 규칙 또는 skills를 절대 로드하지 않습니다.
  • --add-dir 플래그 또는 /add-dir 명령: skills를 로드하며, CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 환경 변수가 설정된 경우에만 CLAUDE.md와 규칙을 로드합니다.

따라서 형제 패키지를 추가하면 Claude에게 파일 액세스 권한은 주어지지만, 해당 패키지의 컨벤션이 반드시 주어지는 것은 아닙니다. 형제 패키지의 규칙이 작업에 중요하다면 환경 변수와 함께 --add-dir을 사용하세요.

디렉토리별로 skills 추가하기

Skills는 관련이 있을 때만 로드되어야 하는 참조 자료에 적합합니다. 문서에 따르면 모든 하위 디렉토리는 해당 영역의 코드와 함께 커밋된 자체 .claude/skills/ 아래에 skills를 정의할 수 있습니다. 예시: API 패키지의 API 테스트 skill과 웹 패키지의 컴포넌트 패턴 skill. Claude가 한 패키지의 파일로 작업할 때 해당 패키지의 skill을 로드합니다.

많은 skills를 사용할 때 주의할 점이 있습니다. Claude는 발견된 모든 skill의 이름과 설명을 읽어 skill을 선택하며, "선택된 skill의 전체 내용만 context에 로드됩니다." 문서에 따르면 skill이 너무 많으면 일부 skill의 설명이 완전히 누락될 수 있습니다. 조언: "설명을 짧게 유지하고 요청에 포함될 법한 단어로 시작하세요."

어떤 skills가 범위에 포함되는지는 시작 위치에 따라 다릅니다:

  • 하위 디렉토리에서: 해당 디렉토리의 skills, 루트까지의 모든 상위 디렉토리, 그리고 사용자 및 엔터프라이즈 skills.
  • 루트에서: 루트 skills와 Claude가 건드리는 모든 하위 디렉토리의 skills가 포함되며, "이는 수백 개로 누적될 수 있습니다."

PR 컨벤션이나 배포 체크리스트와 같이 많은 디렉토리가 공유하는 skills의 경우, 문서에서는 루트의 .claude/skills/를 제안합니다.

계층화가 더 이상 확장되지 않을 때

문서에서는 디렉토리별 파일이 모든 것을 해결해주지는 않는다고 솔직하게 말합니다: "컨벤션은 변질되고, 파일은 낡으며, 아무도 루트를 관리하지 않게 됩니다."

권장 사항은 항상 로드되는 CLAUDE.md에서 컨벤션과 참조 콘텐츠를 필요에 따라 로드되는 메커니즘으로 옮기는 것입니다:

  • Skills: 관련이 있을 때 로드되는 참조 자료용.
  • Plugins: 플랫폼 팀이 소유하고 관리형 설정을 통해 모든 사람에게 설치할 수 있는 skills, hooks, 명령의 버전 관리된 번들입니다. 플러그인 skills는 네임스페이스를 사용하므로 디렉토리별 skills와 충돌하지 않습니다.
  • MCP 서버: 조직에서 이미 리포지토리에 대해 코드 검색 또는 검색 인덱스를 운영 중인 경우.

컨벤션이 플러그인에 저장되면, 익숙하지 않은 트리에 있는 팀원은 어떤 플러그인이 적용되는지 모를 수 있습니다. 문서에서는 시작 디렉토리를 적절한 플러그인에 매핑하고 권장 사항을 출력하는 SessionStart hook을 제안합니다. Claude Code는 첫 번째 프롬프트 전에 hook의 출력을 Claude의 context에 추가하기 때문입니다.

패키지에 걸친 변경 사항

공용 타입과 모든 호출 지점과 같이 여러 패키지를 건드리는 변경 사항의 경우, 문서에서는 두 가지 기술을 제시합니다. 한 세션에서 Claude에게 전체 변경 사항을 맡겨 각 편집 뒤에 있는 결정이 일관되게 유지되도록 하세요. 그리고 먼저 계획을 세우세요: 계획 모드에서 Claude는 계획을 파일에 기록하며, "Claude Code는 각 압축(compaction) 후에 계획 파일을 다시 주입하므로 대화 기록이 사라지더라도 계획은 유지됩니다."

사람들이 처음에 시도하는 것들

모든 것을 루트 CLAUDE.md에 넣기. 무관한 지침으로 인해 context 비용이 발생합니다.

작업마다 claudeMdExcludes 편집하기. 이것은 정적입니다. 대신 해당 패키지에서 시작하세요.

거부 규칙이 모든 읽기를 차단할 것이라 기대하기. 파일을 직접 여는 하위 프로세스는 포함되지 않습니다.

additionalDirectories로 형제 패키지를 추가하고 CLAUDE.md를 기대하기. 이 설정은 CLAUDE.md나 skills를 절대 로드하지 않습니다.

긴 skill 설명 작성하기. skill이 많으면 설명이 잘릴 수 있습니다.

해결책: 현재 코드에 맞는 지침 로드하기

1단계: 시작 위치 선택

집중적인 작업은 패키지에서, 패키지 간 작업은 루트에서 시작하세요.

2단계: 디렉토리별로 CLAUDE.md 분할

리포지토리 전체 규칙은 루트에, 스택별 컨벤션은 각 패키지에 유지한 다음 /context all로 확인하세요.

3단계: 불필요한 항목 제외 및 거부

다른 팀의 지침에는 claudeMdExcludes를 사용하고, 생성되거나 외부에서 가져온 코드에는 Read 거부 규칙을 사용하세요.

4단계: 각 컨벤션의 존재 이유 기록

지침 파일은 무엇을 해야 하는지 알려줍니다. 그 뒤에 숨겨진 결정과 폐기되는 결정들은 그들만의 공간이 필요합니다.

MemoryLake에서 설정하기

대규모 코드베이스에서 컨벤션은 많은 파일과 소유자에게 분산되어 있습니다. API가 왜 쿼리 빌더를 사용하는지 또는 왜 레거시 서비스가 동결되었는지와 같은 결정 배경은 새로운 팀원과 새로운 세션이 계속해서 묻게 되는 내용입니다.

MemoryLake는 아키텍처 결정, 패키지 소유권, 컨벤션의 이유와 같은 프로젝트 context를 위한 memory 레이어입니다. 여러분이 관리하는 한 곳에 보관되며 ChatGPT, Claude Code, Codex와 같이 연결된 어시스턴트가 사용할 수 있습니다.

항목은 여러분의 언어로 직접 작성합니다. CLAUDE.md 파일, 규칙 또는 skills, 설정 파일, 세션 또는 벤더의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다. CLAUDE.md 로딩, 제외 및 skills는 Anthropic이 설명한 방식대로 작동합니다.

1단계: API 키 생성

로그인하고 대시보드에서 키를 생성하세요. 다른 자격 증명과 마찬가지로 리포지토리 외부에 저장하세요.

에이전트에서 사용하기 위해 새 키를 생성하고 복사하는 API 키 화면을 보여주는 MemoryLake 콘솔
에이전트에서 사용하기 위해 새 키를 생성하고 복사하는 API 키 화면을 보여주는 MemoryLake 콘솔

2단계: 첫 번째 memories 업로드

해결책의 4단계에서 작성한 내용부터 시작하세요: 패키지별로 그룹화된 컨벤션 뒤의 결정 사항들입니다. 항목당 하나의 결정과 소유자를 포함하세요.

첫 번째 문서가 업로드된 MemoryLake 워크스페이스, 각 파일이 검색 가능한 memory가 됨에 따라 목록에 표시됨
첫 번째 문서가 업로드된 MemoryLake 워크스페이스, 각 파일이 검색 가능한 memory가 됨에 따라 목록에 표시됨

3단계: AI 및 에이전트 연결

Claude Code, Codex 및 사용하는 다른 어시스턴트를 연결하세요. 세션이 어떤 패키지에서 시작되든 각 어시스턴트는 동일한 결정을 활용할 수 있습니다.

memory 레이어에 연결할 수 있는 AI 클라이언트 및 에이전트 프레임워크를 나열하는 MemoryLake 통합 화면
memory 레이어에 연결할 수 있는 AI 클라이언트 및 에이전트 프레임워크를 나열하는 MemoryLake 통합 화면

실제로 바뀌는 점

첫 번째 차이점은 지침 파일이 작아진다는 것입니다. CLAUDE.md는 무엇을 해야 하는지에 집중하고, 그 이유는 다른 곳에 보관할 수 있습니다.

두 번째는 더 쉬운 온보딩입니다. 새로운 팀원은 패키지가 왜 그렇게 작동하는지 읽어볼 수 있습니다.

세 번째는 도구 간의 일관성입니다. 동일한 리포지토리에서 작업하는 Codex도 동일한 결정을 사용할 수 있습니다.

대규모 코드베이스에서의 Claude Code 모범 사례

작업이 있는 곳에서 시작하세요. 어떤 CLAUDE.md 파일이 로드될지 결정합니다.

디렉토리별로 지침을 계층화하세요. 루트는 모든 곳을 위해, 패키지는 자체 스택을 위해.

무엇이 로드되었는지 확인하세요. /context all을 사용하세요.

절대 건드리지 않는 것은 제외하세요. claudeMdExcludes는 정적이므로 한 번만 설정하면 됩니다.

생성된 코드의 읽기를 거부하세요. 하위 프로세스는 포함되지 않는다는 점을 기억하세요.

skill 설명은 짧게 유지하세요. 요청에 포함될 단어로 시작하세요.

비대해지는 컨벤션은 skills나 플러그인으로 옮기세요. 필요할 때 로드되도록 하세요.

결론

Claude Code는 시작 위치에 따라 CLAUDE.md 파일을 로드합니다. 루트에서는 루트 파일만, 하위 디렉토리에서는 해당 패키지 파일과 모든 상위 파일을 로드하며 다른 파일은 필요에 따라 로드됩니다. 대규모 코드베이스를 위한 Anthropic의 가이드는 디렉토리별 지침 계층화, claudeMdExcludes를 사용한 무관한 파일 제외, 생성된 코드의 읽기 차단, 그리고 해당 패키지에 맞는 skills 범위 설정을 권장합니다.

디렉토리별 파일이 더 이상 확장되지 않을 때, 가이드는 컨벤션을 필요에 따라 로드되는 skills, 플러그인 또는 MCP 서버로 옮길 것을 제안합니다. 이러한 컨벤션 뒤에 숨겨진 결정 사항들을 직접 관리하는 곳에 보관하여 파일과 함께 변질되지 않도록 하세요.

자주 묻는 질문

Claude Code는 모노레포를 어떻게 처리하나요?

시작 위치에 따라 CLAUDE.md 파일을 로드합니다. 패키지에서 시작하면 해당 패키지 파일과 모든 상위 파일을 로드합니다. 루트에서 시작하면 루트 파일을 로드하고 나머지는 필요에 따라 로드합니다.

CLAUDE.md를 하나만 써야 할까요, 여러 개 써야 할까요?

Anthropic은 리포지토리 전체 규칙을 위한 루트 파일 하나와 스택별 컨벤션을 위한 패키지 또는 하위 시스템별 파일 하나씩을 권장합니다.

Claude가 다른 팀의 CLAUDE.md를 로드하지 않게 하려면 어떻게 하나요?

본인을 위해 .claude/settings.local.json 등에 claudeMdExcludes 패턴을 추가하세요.

claudeMdExcludes가 관리형 CLAUDE.md 파일도 건너뛰나요?

아니요. 관리형 CLAUDE.md와 일치하는 패턴이 있어도 건너뛰지 않습니다.

Claude가 왜 형제 패키지의 규칙을 따르지 않나요?

additionalDirectories 설정은 CLAUDE.md나 skills를 절대 로드하지 않습니다. 이를 로드하려면 환경 변수와 함께 --add-dir을 사용하세요.

어떤 CLAUDE.md 파일이 로드되었는지 어떻게 확인하나요?

/context all을 실행하고 Memory files 아래의 목록을 확인하세요.

컨벤션을 언제 skills로 옮겨야 하나요?

디렉토리별 파일을 관리하기 어려워질 때입니다. Skills는 관련이 있을 때만 로드됩니다.