Claude가 임의로 선택하기 전에 충돌하는 CLAUDE.md 레이어를 조정하는 방법 (2026년 가이드)

먼저 지침이 적용되는 영역(surface)이 얼마나 많은지부터 살펴보겠습니다. 대부분의 사람들은 생각보다 더 많은 영역을 실행하고 있습니다.

공식 문서에는 CLAUDE.md의 위치가 "가장 넓은 범위에서 가장 구체적인 범위 순으로 로드되는 순서"대로 나열되어 있습니다. 시스템 경로에 위치하며 "IT/DevOps가 관리하는 조직 전체 지침"을 담고 있다고 설명된 관리형 정책(managed policy) 파일(macOS의 경우 /Library/Application Support/ClaudeCode/CLAUDE.md, Linux 및 WSL의 경우 /etc/claude-code/CLAUDE.md, Windows의 경우 Program Files 경로), ~/.claude/CLAUDE.md에 위치한 사용자 지침(User instructions), 그리고 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 위치한 프로젝트 지침(Project instructions)이 있습니다.

그리고 쉽게 잊어버리는 것들이 있습니다. 현재 작업 디렉토리 상위 계층에 있는 모든 CLAUDE.md는 실행 시 로드됩니다. 그 옆에 있는 모든 CLAUDE.local.md도 함께 로드됩니다. 하위 디렉토리에 있는 파일들도 감지됩니다. "실행 시 로드하는 대신, Claude가 해당 하위 디렉토리의 파일을 읽을 때 포함됩니다." 그리고 .claude/rules/ 폴더에는 원하는 만큼 마크다운 파일을 담아둘 수 있습니다.

6개의 영역에 디렉토리 레벨당 1개씩 추가되고, 여기에 규칙(rules) 폴더까지 더해집니다. 이제 그 메커니즘을 살펴보겠습니다.

"발견된 모든 파일은 서로를 덮어쓰는 대신 컨텍스트에 병합(concatenate)됩니다."

병합됩니다. 승자가 결정되어 병합되거나 덮어씌워지는 것이 아니라, 뒤에 덧붙여지는(appended) 것입니다. 순서는 문서화되어 있습니다. "콘텐츠는 파일 시스템 루트에서 작업 디렉토리 방향으로 정렬"되므로 "Claude를 실행한 위치와 가까운 지침이 가장 마지막에 읽힙니다." 그리고 디렉토리 내에서 CLAUDE.local.md는 CLAUDE.md 뒤에 오므로 "개인 메모는 해당 레벨에서 Claude가 마지막으로 읽는 내용"이 됩니다. 하지만 순서가 곧 우선순위를 의미하지는 않습니다. 마지막에 읽힌다고 해서 이기는 것은 아닙니다.

규칙 폴더는 이를 암묵적이 아닌 명시적으로 보여줍니다.

"paths frontmatter가 없는 규칙은 실행 시 .claude/CLAUDE.md와 동일한 우선순위로 로드됩니다."

동일한 우선순위입니다. 명확하게 명시되어 있습니다. 공식 문서에는 이러한 레이어 간의 동점 처리 규칙(tiebreaker)이 설명되어 있지 않으며, 그 이유는 전체 문서에서 가장 중요한 문장에 나와 있습니다.

"Claude는 이를 강제된 설정(configuration)이 아니라 컨텍스트(context)로 취급합니다."

이것이 핵심입니다. 이 파일들은 우선순위 엔진에 의해 해결되는 설정 파일이 아니라, 프롬프트에 배치되는 텍스트입니다. 공식 문서는 그 결과에 대해 솔직하게 밝히고 있습니다. "강제된 설정이 아니라 컨텍스트이기 때문에, 지침을 어떻게 작성하느냐가 Claude가 지침을 얼마나 안정적으로 따르는지에 영향을 미칩니다. 구체적이고 간결하며 잘 구조화된 지침이 가장 효과적입니다." 또한 탈출구에 대해서도 언급합니다. "Claude의 결정과 관계없이 특정 작업을 차단하려면 대신 PreToolUse 훅을 사용하세요."

이는 불평하기보다 인정해야 할 부분입니다. 다른 도구들은 우선순위를 공개합니다. GitHub Copilot은 개인 지침을 가장 높은 우선순위로, 조직 지침을 가장 낮은 우선순위로 문서화합니다. Tabnine은 관리자 콘솔이 로컬 가이드라인 파일보다 우선한다고 명시합니다. Cursor는 팀 규칙이 프로젝트 및 사용자 규칙보다 우선한다고 문서화합니다. 이들 각각은 결정론적 동작을 얻는 대신, 단 하나의 파일만 보고 모델이 무엇을 보게 될지 파악할 수 있는 능력을 잃게 됩니다. Claude Code의 답은 모든 것이 컨텍스트이며 그 어떤 것도 암묵적으로 이기지 않는다는 것이며, 이는 조정 작업을 사용자에게 넘깁니다.

올해 이 문제가 더 중요해진 이유는 관리형 정책(managed policy) 레이어 때문입니다. 이제 조직은 모든 컴퓨터에 CLAUDE.md를 배포할 수 있으며, 최근 Claude Code 릴리스에서는 관리형 claudeMd가 트리거하던 보안 승인 대화 상자가 제거되어 조용히 적용됩니다. 그 파일은 여러분의 프로젝트를 모르는 사람들이 작성한 것이고, 여러분의 파일과 병합되며, 두 파일이 충돌할 때 이를 중재하는 장치는 없습니다. 이것이 Claude가 사내 컨벤션을 잊어버리는 현상과 같은 수많은 보고 뒤에 숨겨진 메커니즘입니다. 컨벤션도 컨텍스트에 있고, 그것과 상반되는 내용도 컨텍스트에 존재하기 때문입니다.

프로젝트 파일에서 규칙을 더 강력하게 반복하기. 공식 문서에서 구체적이고 잘 구조화된 지침이 더 잘 준수된다고 명시하고 있으므로 가끔 효과가 있습니다. 하지만 파일 크기가 커지고, 아무리 강조하더라도 서로 모순되는 두 지침은 여전히 모순되는 두 지침일 뿐입니다.

가장 마지막에 읽힌다는 이유로 CLAUDE.local.md에 규칙 넣기. 마지막에 읽히는 것이 이긴다는 가정에 기반한 방법입니다. 공식 문서는 우선순위가 아닌 순서를 설명하고 있으며, 파일들이 서로를 덮어쓰는 대신 병합된다고 명시적으로 밝히고 있습니다.

사용자 레벨 파일 삭제하기. 효과적이지만 대가가 큽니다. 개인적인 선호도가 문제가 아니라, 그것과 프로젝트 표준 간의 실제 충돌이 문제였기 때문입니다.

모든 내용을 하나의 거대한 프로젝트 CLAUDE.md로 이동하기. 파일 간의 충돌은 해결되지만, 크기 가이드를 위반하게 됩니다. 공식 문서에서는 파일당 200줄 미만을 유지할 것을 권장하며, 파일이 길어질수록 "더 많은 컨텍스트를 소비하고 준수율을 떨어뜨린다"고 지적합니다. 충돌 문제를 준수율 문제와 맞바꾼 셈입니다.

Claude에게 어떤 규칙을 따르고 있는지 물어보기. 합리적인 진단 방법이며, 실제로 /context는 로드된 메모리 파일 목록을 보여주고 /status는 적용 중인 관리형 소스 이름을 알려줍니다. 하지만 모델에게 임의의 선택에 대해 자가 분석을 요청한다고 해서 그 선택이 덜 임의적이 되는 것은 아닙니다.

훅(hook) 사용하기. 강력한 제약 조건을 위한 공식 문서의 권장 사항이며, 작업을 차단하는 데는 올바른 방법입니다. 하지만 훅은 팀이 결정한 두 가지 스타일 컨벤션 중 어느 것을 따라야 하는지 Claude에게 알려줄 수는 없습니다.

이러한 패턴들의 공통점은 여섯 가지 방법 모두 충돌에서 이기려고만 할 뿐, 충돌 자체를 제거하지는 못한다는 점입니다. 그리고 두 개의 명령형 지침 간의 충돌은 우선순위를 매기는 것만으로는 해결할 수 없습니다. 우선순위를 정하는 데 필요한 정보가 두 파일 어디에도 없기 때문입니다.

세 가지 단계가 있습니다. 실제로 무엇이 로드되는지 확인하고, 각 레이어에 단 하나의 역할만 부여하며, 모순이 쌓이는 원인을 제거하는 것입니다.

1단계: 실제로 컨텍스트에 있는 항목 나열하기

세션에서 /context를 실행하고 Memory files 아래의 목록을 읽어보세요. 이것이 가장 확실한 답이며, 대개 놀라운 결과를 보여줍니다. 누군가 작년에 추가한 세 단계 상위 디렉토리의 CLAUDE.md, 잊고 있었던 CLAUDE.local.md, 무조건 로드되는 .claude/rules/ 안의 파일 4개 등이 나타날 수 있습니다. /status도 실행하여 자신에게 적용되는 관리형 소스의 이름을 지정하는 Setting sources 줄을 확인하여 조직 파일이 작동 중인지 파악하세요.

점검하는 동안 주의해야 할 문서화된 두 가지 특이 사항이 있습니다. 임포트(Import)는 실제 콘텐츠입니다. CLAUDE.md는 @path/to/import 구문으로 다른 파일을 가져올 수 있으며, 이 파일들은 "실행 시 확장되어 컨텍스트에 로드"되므로 한 줄짜리 파일도 크기가 커질 수 있습니다. 또한 임포트 파싱은 "마크다운 코드 스팬 및 펜스 코드 블록을 건너뜁니다." 즉, 백틱 안의 경로는 리터럴로 유지되는 반면, 백틱 밖의 동일한 경로는 파일을 임포트합니다. 백틱 없이 경로를 문서화했다면, 언급만 하려 했던 파일을 실제로 임포트하고 있을 수 있습니다.

또 다른 유용한 팁: 블록 수준의 HTML 주석은 "콘텐츠가 Claude의 컨텍스트에 주입되기 전에 제거"되므로, 토큰을 소비하지 않고 인간 유지보수자를 위한 메모를 남기기에 적합한 장소입니다.

다른 팀의 파일이 감지되는 모노레포(monorepo) 환경에서는 claudeMdExcludes를 사용하여 이를 건너뛸 수 있습니다. 이는 실제 충돌 원인에 대한 확실한 해결책이며, 이 목록에서 파일의 순서를 바꾸는 대신 컨텍스트에서 파일을 실제로 제거하는 유일한 방법입니다.

2단계: 각 레이어에 정확히 하나의 역할만 부여하기

이제 각 레이어가 서로 다른 것에 대해 이야기하도록 범위를 할당하여 두 레이어가 서로 충돌할 수 없도록 만듭니다.

관리형 정책(Managed policy)은 보안 요구사항, 규정 준수 규칙, 라이선스 등 진정으로 조직적인 제약 조건을 담습니다. 팀원 중 누구도 이의를 제기하지 않을 내용들입니다. 만약 여기에 프레임워크에 대한 의견이 담겨 있다면 그것이 충돌의 원인이며, 이는 프로젝트 파일이 아니라 이를 배포하는 담당자와 논의해야 할 문제입니다.

사용자 지침(User instructions)은 응답 스타일, 터미널 선호도, 단축키 등 개인적으로 선호하는 작업 방식을 담습니다. 프로젝트에 관한 내용은 여기에 포함되어서는 안 됩니다. 이는 팀원의 규칙과 암묵적으로 충돌하는 가장 흔한 원인이며, Claude가 코딩 스타일을 고수하도록 만드는 것을 필요 이상으로 어렵게 만드는 잘못된 배치입니다.

프로젝트 지침(Project instructions)은 명령어, 컨벤션, 아키텍처 사실 등 이 리포지토리에 대해 참인 정보를 담습니다. 이 파일은 공유되고 검토되어야 하는 파일입니다.

paths frontmatter가 있는 .claude/rules/는 조건부 항목을 담습니다. 이는 매우 중요한데, 경로 범위가 지정된 규칙은 다른 경로에 대한 규칙과 충돌할 수 없기 때문입니다. 두 규칙이 동시에 적용되는 일은 결코 없습니다. 무조건적인 파일에서 규칙을 paths 범위 규칙으로 이동하면 잠재적인 모순이 겹치지 않는 두 개의 문장으로 변환됩니다. paths가 없는 규칙은 프로젝트 파일과 동일한 우선순위로 무조건 로드되므로, 규칙이 특정 파일에만 적용되는 경우 항상 frontmatter를 사용하세요.

스킬(Skills)은 작업별 절차를 담습니다. 공식 문서에서는 이 구분을 명확히 하고 있습니다. 규칙은 "매 세션마다 또는 일치하는 파일이 열릴 때 컨텍스트에 로드"되는 반면, "항상 컨텍스트에 있을 필요가 없는 작업별 지침의 경우 대신 스킬을 사용하세요."

시간을 크게 절약해 줄 사실 한 가지: "Claude Code는 AGENTS.md가 아니라 CLAUDE.md를 읽습니다." 리포지토리에 이미 다른 도구를 위한 AGENTS.md가 있는 경우, 문서화된 접근 방식은 이를 임포트하는 CLAUDE.md를 만드는 것입니다. 이렇게 하면 두 파일이 서로 달라지는 대신 동일한 콘텐츠를 읽게 됩니다. 서로 달라지는 두 파일은 가장 전형적인 충돌 문제입니다.

3단계: 규칙뿐만 아니라 결정 사항도 기록하기

2단계를 거치고 나면 진짜 모순되는 몇 가지 항목만 남게 될 것입니다. 두 레이어가 실제로 동일한 사항에 대해 의견이 다르고, 두 작성자 모두 합당한 이유가 있는 경우입니다.

이러한 문제는 레이어의 우선순위를 매기는 것으로는 해결할 수 없습니다. "내부 HTTP 클라이언트 사용" 대 "표준 라이브러리 클라이언트 사용"은 두 개의 명령문으로서 해결이 불가능합니다. 하지만 하나는 내부 클라이언트만 필요한 프록시를 지원하던 시절에 작성되었고, 이후 버전에서 표준 라이브러리도 이를 지원하게 되었다는 사실을 알게 되면 즉시 해결됩니다.

이러한 정보는 CLAUDE.md가 명령문을 적는 곳이기 때문에 두 파일 어디에도 없었습니다. 즉, 오늘 해결한 모든 충돌은 다음에 누군가가 그 원인을 적지 않고 명령문만 작성할 때 다시 발생하게 됩니다. 자동 메모(Auto memory) 기능이 약간의 도움이 됩니다. Claude는 리포지토리별로 학습 및 수정 사항을 자체 저장소에 유지하며, 매 세션마다 문서화된 제한(처음 200줄 또는 25KB)까지 주입됩니다. 하지만 이 저장소는 여러분의 피드백을 바탕으로 Claude가 작성하는 것이지, 팀이 내린 결정과 그 이유를 기록한 것은 아닙니다.

MemoryLake는 모든 지침 파일 외부에서 결정 사항과 그 이유를 보관하며, MCP 또는 API를 통해 이에 대한 질문에 답변합니다. 여러분의 CLAUDE.md 파일은 짧고 명령조로 유지되며 문서에 기재된 대로 정확히 로드됩니다. 두 파일이 충돌할 때, 어떤 레이어가 이겨야 하는지 추측하는 대신 각 파일이 존재하는 이유를 찾아볼 수 있습니다.

1단계: API 키 생성하기

키를 생성하고 약 30초 만에 첫 번째 요청을 보내보세요. 위의 2단계를 진행하기 전에 이 작업을 수행하면, 레이어를 정리하면서 각 충돌을 기록할 공간을 마련할 수 있습니다.

2단계: 첫 번째 메모리 업로드하기

2단계의 충돌 사항과 상속받은 규칙들을 검토하세요. 각 규칙에 대해 무엇이 결정되었고, 무엇이 거부되었으며, 그 이유는 무엇인지 기록하세요. 아무도 이유를 기억하지 못하는 규칙은 가장 가치 있는 항목입니다. 왜냐하면 그것들이 다시 논쟁거리가 될 것이기 때문입니다. 관련 문서와 파일도 같은 위치에 보관합니다.

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

Claude Code, Codex, Devin 및 기타 에이전트에 MCP 또는 API를 통해 액세스 권한을 부여하세요. 규칙이 잘못된 것처럼 보일 때, "이것이 왜 여기에 있는가"에 대한 답변이 더 큰 목소리의 반복이 아닌 논리적인 이유와 함께 제공됩니다.

첫 번째 변화는 파일이 짧아진다는 것입니다. 이유가 다른 곳에 보관되면 CLAUDE.md는 명령문 목록이 되며, 이는 200줄 미만 가이드가 요구하는 사항이자 공식 문서에서 준수율을 높인다고 명시한 부분입니다.

두 번째는 대부분의 충돌이 해결되는 것이 아니라 아예 존재하지 않게 된다는 점입니다. paths 범위가 지정된 규칙과 다른 경로 범위가 지정된 규칙은 결코 동시에 컨텍스트에 존재하지 않습니다. 이는 우선순위를 매기는 것이 아니라 구조적인 해결책입니다.

세 번째는 관리형 정책(managed policy) 레이어가 더 이상 두렵지 않다는 점입니다. 조직 파일이 진정한 조직적 제약 조건만 담고 프로젝트 파일이 프로젝트 사실 정보만 담고 있다면, 병합은 정확히 여러분이 원하는 방식(겹치지 않는 두 개의 문장 세트)으로 작동합니다.

네 번째는 임의의 선택에 관한 문장이 여러분이 신경 쓰는 부분에 더 이상 적용되지 않는다는 점입니다. Claude는 여전히 모순되는 두 규칙 사이에서 임의로 선택할 수 있지만, 여러분이 모순되는 규칙을 제공하는 것 자체를 중단했기 때문입니다. 이것이 Claude Code가 프로젝트 컨텍스트를 잊어버리는 현상 및 에이전트가 지침 파일을 무시하는 현상에 대한 실제 해결책입니다. 지침이 무시된 것이 아니라, 이웃한 지침에 의해 다수결로 밀려난 것입니다.

디버깅을 시작하기 전에 항상 /context를 실행하세요. 로드된 메모리 파일 목록이 실제 기준(ground truth)이며, 대개 예상보다 깁니다.

레이어당 하나의 역할만 부여하세요. 조직적 제약, 개인적 선호, 프로젝트 사실 정보, 조건부 규칙, 작업 절차. 두 레이어가 동일한 주제에 대해 이야기할 수 있다면, 결국 그렇게 될 것입니다.

paths frontmatter를 적극적으로 사용하세요. 범위가 지정된 규칙은 다른 파일에 대한 규칙과 충돌할 수 없습니다. 이는 가장 비용이 적게 드는 충돌 제거 방법입니다.

프로젝트 파일을 권장 크기 이하로 유지하세요. 공식 문서에서는 200줄 미만을 목표로 하며, 파일이 길어지면 준수율이 떨어진다고 지적합니다. 하나의 파일을 키우는 대신 주제별로 분할하여 .claude/rules/에 넣으세요.

프로젝트 사실 정보를 사용자 파일에 절대 넣지 마세요. 이는 팀원의 규칙과 일치하지 않고 검토할 수도 없는 규칙이 발생하는 가장 흔한 원인입니다.

임포트하려는 것이 아니라면 경로를 백틱으로 감싸세요. 임포트 파싱은 코드 스팬을 건너뛰므로, 백틱은 파일을 단순히 언급하는 것과 실제로 로드하는 것의 차이를 만듭니다.

AGENTS.md를 중복 작성하는 대신 임포트하세요. Claude Code는 AGENTS.md가 아니라 CLAUDE.md를 읽으므로, 동일한 컨벤션을 수동으로 유지 관리하는 두 개의 복사본은 결국 서로 달라지게 됩니다.

강력한 제약 조건에는 훅(hook)을 사용하세요. 공식 문서에서는 이 파일들이 강제된 설정이 아니라 컨텍스트임을 명시하고 있으며, Claude의 결정과 관계없이 작업을 차단하는 방법은 PreToolUse 훅을 사용하는 것입니다.

Claude Code는 지침 파일에 대해 솔직하게 문서화하고 있습니다. 발견된 모든 파일은 서로를 덮어쓰는 대신 컨텍스트에 병합되고, paths frontmatter가 없는 규칙은 프로젝트 파일과 동일한 우선순위로 로드되며, 전체 세트는 강제된 설정이 아닌 컨텍스트로 취급되고, 두 규칙이 충돌할 경우 Claude는 임의로 하나를 선택할 수 있습니다. 학습해야 할 숨겨진 우선순위 엔진은 없으며, 이는 두 파일이 충돌할 때 호소할 곳이 없음을 의미하기도 합니다.

그러니 충돌에서 이기려고 애쓰지 말고, 충돌 자체를 배포하지 마세요. 실제로 로드되는 항목을 나열하고, 레이어가 겹치지 않도록 각 레이어에 하나의 주제만 부여하고, 조건부인 모든 항목의 범위를 paths로 지정하고, 지침을 따를 수 있을 만큼 파일을 짧게 유지하세요. 그런 다음 각 규칙이 존재하는 이유를 파일 외부의 어딘가에 기록해 두세요. 충돌을 결정하는 레이어는 파일 경로도, 로드 순서도 아니기 때문입니다. 그것은 바로 그 규칙이 무엇을 위한 것이었는지 여전히 기억하는 사람이 있는지 여부입니다.