Claude Code가 CLAUDE.md를 무시할 때? 컨텍스트에 무엇이 포함되어 있는지 확인하기

Claude Code가 규칙을 무시하는 경우, 일반적인 해결책은 문구를 수정하는 것입니다. 동사로 시작하고, 리터럴(literals)에는 백틱(")을 사용하며, 주변 산문에서 높은 초점을 유지하고 싶은 부분은 굵게 처리하는 식입니다. 하지만 이 모든 것을 시도하기 전에, 더 저렴하면서도 광범위하게 제기되는 질문이 있습니다. 즉, 그 규칙이 애전트(agent)의 컨텍스트에 아예 포함되었었는지 여부입니다.

이것은 두 가지 다른 실패 사례를 의미합니다. 로드되었으나 여전히 지켜지지 않은 규칙은 문구상의 문제 또는 강제 실행(enforcement) 문제입니다. 반면, 애전트에게 로드되지 않은 규칙은 배관(plumbing) 문제입니다. 아무리 문구를 수정해도 해결되지 않습니다. 종종 첫 번째 유형인 경우가 많습니다. 즉, 파일은 로드되고 애전트는 그 내용을 인용할 수 있지만, 여전히 이탈하는 것입니다. 이 두 가지를 구별하는 것이 어떤 수정이 필요한지 결정합니다.

그래서 저는 Claude Code에서 오래된 프로젝트를 열어 실제로 애전트에게 전달되는 내용이 무엇인지 살펴보았습니다.

프로젝트: SageCompass

SageCompass는 지난 겨울에 진행했던 저의 LangGraph 프로젝트입니다. Reporails가 존재하기 이전에 수동으로 지침 파일을 작성했으며, 마지막 커밋은 2026년 1월 21일자입니다. 아무도 이것을 위해 조정하지 않았습니다.

Drupal core 폴더 외부에 포함된 내용은 다음과 같습니다:

langgraph/app/ 아래의 모든 폴더에는 자체 CLAUDE.md가 있습니다. app/graphs/에 있는 파일의 경우 다음과 같이 열립니다:

# Local scope: app/graphs

이 파일은 `app/graphs/**`를 편집할 때 **주요** 지침 표면(primary instruction surface)입니다.

세션

어제 저는 Claude Code 2.1.311을 사용하여 sagecompass/langgraph에서 10개월 만에 처음으로 열었고, 주변을 둘러보라고 요청했습니다: “프로젝트를 한번 살펴봅시다. 저희가 10개월 동안 열지 않았네요.” 애전트는 시스템 맵을 읽고, 그래프 코드를 탐색했으며, 품질 게이트(quality gates)와 테스트를 실행한 후 모든 것이 여전히 통과한다고 보고했습니다. 그런 다음 저는 매 턴 끝에서 계속 보던 오류에 대해 물었고, 그것까지 수정해 주었습니다.

두 개의 프롬프트에 걸쳐 18개의 셸 명령어(shell command)를 실행했습니다. 그런 다음 세션을 열었습니다:

npx @reporails/cli xray

fails xray는 127.0.0.1에서 페이지를 제공하며, Claude Code가 이미 ~/.claude/projects/ 아래에 보관하고 있는 세션 기록(session transcript)을 읽습니다. Graph 탭은 에이전트에게 타임라인을 보여주며, 모든 지침 파일(instruction file), 규칙(rule), 스킬(skill), 메모리 파일(memory file), 그리고 MCP 서버가 처음 로드된 시점에 왼쪽 패널에 표시됩니다.

두 개의 지침 파일이 로드되었으며, 모두 시작 시점에 로드되었습니다: 루트의 CLAUDE.md와 langgraph/CLAUDE.md입니다. 나머지 세션 동안 다른 지침 파일은 에이전트의 컨텍스트(context)에 진입하지 않았습니다. 최대 컨텍스트는 65k 토큰이었습니다. 두 파일이 차지하는 비중은 약 2.3k 토큰이었고 (루트 파일 기준 약 771, langgraph/CLAUDE.md 기준 약 1.5k), 도구 호출(tool calls) 및 결과가 약 22k, 도구 정의(tool definitions)가 약 14k를 차지했습니다.

로드됨 또는 로드되지 않음 (Loaded, or never loaded)

Sources 목록은 세션이 로드할 수 있었던 내용과 각 항목에 어떤 일이 일어났는지를 보여줍니다: 로드됨(loaded), 나열되었으나 로드되지 않음(listed but never loaded), 디스크에 있으나 로드되지 않음(on disk but never loaded), 또는 이 세션에 기록되지 않음(not recorded in this session).

이번 세션에서 Sources 목록은 langgraph/의 세션이 로드할 수 있는 11개의 지침 파일을 계산합니다. 두 개가 로드되었습니다. 나머지 아홉 개(app/ 아래 각 폴더별 하나와 tests/ 폴더)는 '로드되지 않음(not loaded)'으로 표시되었습니다.

아홉 개 중 하나는 에이전트가 코드를 읽은 폴더의 자체 선언된 주요 지침 파일인 app/graphs/CLAUDE.md입니다. 0:13에 이 파일은 sed -n 1,200p app/graphs/graph.py를 실행했습니다. 세션 내 모든 읽기 작업(read)은 셸을 거쳤고, app/graphs/CLAUDE.md는 로드되지 않았습니다.

에이전트가 graph.py를 같은 방식으로 편집했다면, 그래프 모듈을 어떻게 작성해야 하는지 설명하는 파일 없이도 작동했을 것입니다. 그 파일은 어떤 문구 수정보다 로딩(loading) 수정이 필요했습니다.

'Tool calls' 탭에서 해당 호출을 클릭하면 에이전트가 그 순간 가지고 있던 내용(컨텍스트)을 페이지에서 보여줍니다: 40k 토큰의 컨텍스트와 두 개의 지침 파일, 즉 루트 CLAUDE.md와 langgraph/CLAUDE.md입니다.

이번 세션에서 발견된 CLAUDE.md 모범 사례(best practices)가 지적하는 내용

• 규칙을 재작성하기 전에 세션을 확인하세요. X-ray가 파일이 로드된 것을 보여주면, 다음으로 문구(wording) 또는 강제 적용(enforcement)을 확인합니다. 만약 로드가 전혀 되지 않았다면, 먼저 로딩 문제를 수정해야 합니다.
• 반드시 지켜야 할 규칙에 대해 중첩된 파일(nested file)에 의존하지 마세요. 폴더의 CLAUDE.md는 에이전트가 해당 폴더에 도달하는 방식에 따라 달라지며, 이번 세션에서는 로드되지 않았습니다. 모든 변경 사항에서 유효해야 하는 규칙은 시작 시 로드되는 파일이나 이를 확인하는 훅(hook) 뒤에 위치해야 합니다.
• 존재하는 파일을 가리키세요. langgraph/CLAUDE.md의 128번째 줄에는 'See .shared/rules/testing.md'라고 적혀 있습니다. 이 파일은 몇 달 전에 다섯 개의 testing-*.md 파일로 분할되었는데, 포인터는 이전 이름을 유지하고 있었습니다. 깨진 포인터는 조용히 실패하며, 에이전트가 보내는 유일한 신호는 읽기 실패(failed read)입니다.

X-ray가 다루는 범위

X-ray는 Claude Code 세션을 읽습니다. SageCompass의 11개 AGENTS.md 파일은 Codex, Copilot, Cursor에 의해 읽히지만, x-ray는 해당 에이전트들의 세션은 보여주지 않습니다. Team 또는 Enterprise 장치에서는 조직에서 claude.ai 관리 콘솔(admin console)에 설정한 설정을 읽기 때문에, 정책이 생성한 컨텍스트를 보여줍니다.

이는 로컬에서 실행됩니다. 페이지는 127.0.0.1에서 서비스되며, 이미 사용자의 장치에 있는 세션 파일을 읽습니다. 'Check' 및 'Fix' 버튼만이 Reporails 서버에 도달하는 유일한 부분입니다.

본인의 세션으로 시도해 보기

Claude Code를 시작했던 폴더에서 실행하세요:

npx @reporails/cli xray

Reporails 플러그인이 설치된 상태에서 에이전트에게 /reporails:ails xray를 요청하면 현재 세션이 열립니다. Reporails CLI는 에이전트가 실제로 어떤 컨텍스트(context)를 가지고 있었는지 보여주며, fails check는 그 컨텍스트에 포함된 지침 파일(instruction files)들을 점수화합니다.