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

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

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

실제로 바뀌는 점
첫 번째 차이점은 지침 파일이 작아진다는 것입니다. CLAUDE.md는 무엇을 해야 하는지에 집중하고, 그 이유는 다른 곳에 보관할 수 있습니다.
두 번째는 더 쉬운 온보딩입니다. 새로운 팀원은 패키지가 왜 그렇게 작동하는지 읽어볼 수 있습니다.
세 번째는 도구 간의 일관성입니다. 동일한 리포지토리에서 작업하는 Codex도 동일한 결정을 사용할 수 있습니다.
대규모 코드베이스에서의 Claude Code 모범 사례
작업이 있는 곳에서 시작하세요. 어떤 CLAUDE.md 파일이 로드될지 결정합니다.
디렉토리별로 지침을 계층화하세요. 루트는 모든 곳을 위해, 패키지는 자체 스택을 위해.
무엇이 로드되었는지 확인하세요. /context all을 사용하세요.
절대 건드리지 않는 것은 제외하세요. claudeMdExcludes는 정적이므로 한 번만 설정하면 됩니다.
생성된 코드의 읽기를 거부하세요. 하위 프로세스는 포함되지 않는다는 점을 기억하세요.
skill 설명은 짧게 유지하세요. 요청에 포함될 단어로 시작하세요.
비대해지는 컨벤션은 skills나 플러그인으로 옮기세요. 필요할 때 로드되도록 하세요.
결론
Claude Code는 시작 위치에 따라 CLAUDE.md 파일을 로드합니다. 루트에서는 루트 파일만, 하위 디렉토리에서는 해당 패키지 파일과 모든 상위 파일을 로드하며 다른 파일은 필요에 따라 로드됩니다. 대규모 코드베이스를 위한 Anthropic의 가이드는 디렉토리별 지침 계층화, claudeMdExcludes를 사용한 무관한 파일 제외, 생성된 코드의 읽기 차단, 그리고 해당 패키지에 맞는 skills 범위 설정을 권장합니다.
디렉토리별 파일이 더 이상 확장되지 않을 때, 가이드는 컨벤션을 필요에 따라 로드되는 skills, 플러그인 또는 MCP 서버로 옮길 것을 제안합니다. 이러한 컨벤션 뒤에 숨겨진 결정 사항들을 직접 관리하는 곳에 보관하여 파일과 함께 변질되지 않도록 하세요.