Claude Code가 CLAUDE.md를 무시하는 것은 종종 버그가 아니라, 더 이상 존재하지 않는 모델을 위해 작성된 파일이기 때문입니다. Anthropic은 모델별로 삭제해야 할 스캐폴딩 (scaffolding) 목록을 담은 프롬프팅 페이지를 제공하며, 최신 프론티어 모델 (frontier models)조차 지침을 500개 이상 작성하면 그중 68%만 따릅니다. 출시일에 맞춰 정리하십시오.

내가 이를 진단한 방법, 그리고 측정하지 않은 것들

이 포스트는 5가지 측정 연구와 Anthropic 자체의 모델별 프롬프팅 페이지를 바탕으로 작성되었습니다. 20개 모델과 7개 제공업체를 대상으로 한 지침 밀도 벤치마크인 IFScale 연구 (2025-07). 1,925개의 리포지토리에서 추출한 2,303개의 에이전트 컨텍스트 파일에 대한 대규모 연구 (2025-11). ETH Zurich의 AGENTS.md와 LogicStar를 활용하여 개발자가 작성한 컨텍스트 파일과 생성된 컨텍스트 파일을 대상으로 4개의 에이전트를 평가한 연구 (2026-02). SWE-bench Verified 상에서의 리포지토리 가이드에 대한 탐색 및 정제 (probe-and-refine) 연구 (2026-06). 그리고 238개의 공개된 SKILL.md 파일에 대한 스멜 분석 (smell analysis) (2026-07). 아래 인용된 모든 벤더의 문장은 2026-07-25에 실시간으로 다시 가져왔습니다. 이 연구들 중 그 어느 것도 나의 리포지토리나 당신의 리포지토리를 테스트하지 않았습니다.

검증하려는 주장은 좁은 범위입니다. Claude Code가 CLAUDE.md를 무시하는 데에는 한 가지 이상의 그럴듯한 원인이 있으며, 모델 업데이트 직후 에이전트의 성능이 눈에 띄게 저하된다면 당신이 이전 모델을 위해 작성한 지침은 무고한 방관자가 아니라 유력한 용의자입니다.

내가 의도적으로 건너뛴 것은 내 자신의 지침 파일에 대한 전후 비교입니다. 한 명의 저자가 작성한 하나의 리포지토리는 차트를 그려 넣은 일화에 불과합니다. 내가 찾을 수 있었던 실무자 증거인 두 개의 종료된 GitHub 이슈와 하나의 Hacker News 스레드는 데이터라기보다는 참고용 색채로 취급하기에 충분할 만큼 희박합니다.

Anthropic은 모델을 출시할 때마다 삭제 목록을 함께 제공합니다

새로운 모델 출시로 인해 요구되는 프롬프트 변경 사항(prompt changes)은 해당 모델의 이름을 가진 페이지에 게시됩니다. Anthropic의 프롬프트 엔지니어링 허브(prompt-engineering hub)는 모델별 가이드를 가장 먼저 배치하여 Claude Fable 5, Claude Sonnet 5, Claude Opus 5 및 Claude Opus 4.8이 어떻게 다르게 동작하는지와 무엇을 변경해야 하는지를 다루며, 이전 세대에서 넘어오는 프롬프트를 위한 마이그레이션(migration) 고려 사항은 가장 마지막에 배치합니다. 이는 이미 귀하의 저장소(repo)에 체크인된 파일에 대한 변경 로그(changelog)인 셈입니다.

대부분의 개발자는 이 페이지들을 플랫폼에서 제품을 출시하는 사람들을 위한 API 튜닝 노트로 읽습니다. 하지만 이 내용들은 글자 그대로, 귀하의 프로젝트 루트에 있는 마크다운(markdown) 파일을 위한 유지보수 목록이기도 합니다. 아무도 이를 그런 방식으로 정의하지 않기에, 파일은 조용히 노후화됩니다.

Opus 4.8 페이지의 한 단락은 나머지 전체 말뭉치(corpus)를 합친 것보다 더 많은 역할을 수행합니다. Claude Opus 4.8 프롬프팅 페이지는 "만약 귀하의 코드 리뷰 하네스(code-review harness)가 이전 모델에 맞춰 튜닝되었다면, 초기에는 재현율(recall)이 낮게 나타날 수 있습니다. 이는 모델의 성능 퇴보(capability regression)가 아니라 하네스 효과(harness effect)일 가능성이 높습니다"라고 경고합니다.

How a model release ages the file you never touched

이 메커니즘을 천천히 읽어보십시오. 왜냐하면 이는 명백한 결론을 뒤집기 때문입니다. 귀하의 리뷰 프롬프트가 "보수적으로 행동하라" 또는 "사소한 것은 지적하지 마라"라고 말한다면, 새 모델은 이전 모델보다 그 명령을 더 충실히 따릅니다. 따라서 모델은 똑같이 철저하게 조사하여 버그를 찾아내지만, 귀하가 설정한 기준 미만의 버그에 대해서는 보고를 거부합니다. 그러면 귀하의 대시보드에는 재현율(recall)이 떨어지는 것으로 표시되고, 귀하는 모델에 대해 버그 리포트를 제출하게 됩니다.

같은 페이지에서는 근본적인 행동 변화를 명확하게 기술하고 있습니다. Claude Opus 4.8은 "특히 낮은 노력 수준(lower effort levels)에서 프롬프트를 문자 그대로, 그리고 명시적으로 해석합니다. 하나의 항목에서 다른 항목으로 지침을 암묵적으로 일반화하지 않으며, 귀하가 요청하지 않은 사항을 추론하지도 않습니다."라고 명시합니다.

이 문장으로부터 세 가지 결과가 도출되며, 각각은 이미 귀하의 파일에 있는 라인 카테고리에 대응됩니다.

• 완곡한 검토 필터(Hedged review filters)가 이제 구속력을 갖습니다. 귀하가 부드러운 힌트로 작성했던 질적 기준이 엄격한 기준으로 강제 적용됩니다.
• 범위가 지정되지 않은 규칙(Unscoped rules)은 여전히 범위가 지정되지 않은 상태로 남습니다. Anthropic 자체의 해결책은 범위를 명시하는 것입니다. 예를 들어 "첫 번째 섹션뿐만 아니라 모든 섹션에 이 서식을 적용하세요"와 같이 작성하는 것입니다.
• 보완용 스캐폴딩(Compensating scaffolding)은 이제 불필요한 짐이 됩니다. 이전 모델의 습관을 우회하기 위해 존재했던 지침들이 여전히 중요한 규칙들과 주의력을 다투게 됩니다.

언급된 항목 중 두 가지는 이례적일 정도로 직설적입니다. 해당 페이지는 만약 중간 상태 메시지를 강제하기 위해 스캐폴딩(예: "도구 호출(tool calls)을 3번 할 때마다 진행 상황을 요약하세요"라는 전형적인 문구)을 추가했다면, 이를 제거해 보라고 말합니다. 또한, 이전 모델들은 프론트엔드 디자인(frontend-design) 기술을 위해 더 긴 프롬프트 스니펫(prompt snippet)이 필요했지만, Opus 4.8은 더 최소한의 가이드만으로도 독특한 프론트엔드를 생성한다는 점을 언급하며 Anthropic 자체의 권장 사항을 폐기합니다.

마지막 항목은 보기보다 더 중요합니다. 벤더(Vendor)가 벤더 스스로가 귀하에게 주었던 조언을 삭제하고 있는 것입니다. 모델을 훈련시킨 사람들조차 그 모델을 위해 작성된 지침이 모델의 수명보다 오래 지속되도록 작성하지 못한다면, 귀하가 작년에 급하게 작성한 지침 역시 마찬가지일 것입니다.

파일은 계속 커지기만 하고, 모델은 읽을 수 있는 양이 정해져 있다

지침 파일은 설정 코드(configuration code)처럼 유지 관리됩니다. 2,303개의 에이전트 컨텍스트 파일에 대한 연구에 따르면, 이 파일들은 "빈번하고 작은 추가"를 통해 진화하는 것으로 나타났으며, 삭제 측면도 측정되었습니다. Claude Code 파일은 커밋당 중앙값 57단어가 추가되는 반면, 세 가지 도구 전체에서 삭제 중앙값은 15단어 미만입니다.

순성장(Net growth), 모든 커밋, 영원히. 아무도 삭제를 계획하지 않습니다. 세 번의 릴리스(release) 전에 출시된 모델을 대상으로 작성한 규칙이 여전히 그곳에 남아, 여전히 주의(attention)를 소모하며, 오늘 아침에 추가한 규칙과 여전히 비교되고 있습니다.

이제 이 규칙들이 맞닥뜨리게 될 천장에 숫자를 매겨보십시오. IFScale은 7개의 제공업체에 걸쳐 20개의 최첨단(state-of-the-art) 모델을 평가했으며, "가장 뛰어난 프론티어 모델(frontier models)조차 최대 밀도인 500개의 지시사항(instructions)에서는 68%의 정확도만을 달성한다"는 사실을 발견했습니다.

지시 밀도가 높아질수록 지시 준수율(Instruction adherence)은 하락합니다

출처, IFScale Table 1, 2025-07 측정. https://arxiv.org/html/2507.11538v1

이 그래프의 형태가 바로 논거입니다. claude-opus-4는 10개와 50개의 지시사항에서 100%의 준수율을 유지하고, 100개에서도 94.6%를 유지하지만, 250개에서 67.9%, 500개에서는 44.6%로 떨어집니다. 벤치마크에서 가장 강력한 선인 gemini-2.5-pro-preview조차 하락 폭이 68.9%로 완화될 뿐입니다.

지시사항이 100개에서 250개 사이가 되는 지점에서 파일의 3분의 1이 무시되기 시작하며, 500개에 이르면 절반이 무시됩니다. 어떤 3분의 1이 무시되는지는 알려주지 않습니다.

이 지점에서 CLAUDE.md의 200행 제한은 더 이상 설화(folklore)가 아닙니다. Anthropic의 메모리 문서들은 200행 미만을 목표로 하며, 준수율 저하를 그 증상으로 지목하고 있고, IFScale은 그 조언의 근간이 되는 곡선입니다. 이것이 바로 측정을 직접 해본 적 없는 사람들이 이 숫자를 계속해서 반복하는 이유입니다.

IFScale은 또한 보편적 초두 효과(universal primacy effect), 즉 가장 초기에 나타나는 지시사항에 편향되는 현상을 발견했으며, 저자들은 이를 주의(attention)의 한계로 해석했습니다. 이를 '추가만 가능한(append-only)' 유지보수 방식과 결합하면 부식(rot)의 실제 메커니즘이 드러납니다. 모든 새로운 규칙은 모델이 가장 적게 주의를 기울이는 영역에 배치되는 반면, 은퇴한 모델을 위해 작성했던 보완용 해킹(compensating hack)은 상단에 편안하게 자리 잡고 있습니다.

그 두 논문은 각각 별도로, 그리고 지속적으로 다루어지며, 서로 대조하여 읽히는 경우는 드뭅니다. 하지만 이 둘을 함께 살펴보면, 왜 특정 동작을 수정하기 위해 코드 한 줄을 추가하는 것이 종종 아무런 효과도 내지 못하는지 설명할 수 있습니다.

기술(Skills)은 검토 없이 동일한 부채를 축적한다

기술(Skills)은 당신의 지침 파일(instruction file) 위에 쌓입니다. 기술의 지침 또한 동일한 밀도의 예산(density budget)을 소비하며, 모델별로 할당된 동일한 페이지 수에 맞춰 노후화됩니다.

저는 모델이 출시되는 날에 기술 파일(skill file)을 단 한 번도 열어본 적이 없습니다. 이는 사람들이 일하는 방식에 대한 가정이 아니라, 측정된 사실입니다. 이 코퍼스(corpus) 내의 그 어떤 것도 누가 무엇을 유지 관리하는지에 대해서는 집계하지 않습니다.

238개의 공개된 SKILL.md 파일에 대한 냄새 분석(smell analysis) 결과, '코드 스멜(smell)'이 전혀 없는 파일은 단 하나뿐이었습니다. 파일당 평균 개수는 10.5개였습니다. 에이전트가 규칙에서 벗어나 논리적으로 빠져나갈 수 있게 해주는 탈출 조항(escape clause)인 '합리화 루프홀(The Rationalization Loophole)'은 파일의 94%에서 나타났습니다.

이 수치를 읽을 때 주의하십시오. 이는 단일 스냅샷에서 얻은 유병률(prevalence) 수치이므로, 특정 스멜이 시간이 지남에 따라 수정되는지 아니면 몇 달 동안 지속되는지에 대해서는 말해주지 않습니다. 이 코퍼스는 동일한 파일을 두 번 측정하지 않았습니다.

따라서 기술(skills)에 대한 논거는 종단적(longitudinal)이라기보다 구조적입니다. 모델이 규칙 주변에서 느슨하게 일반화(generalize)될 때는 탈출 조항이 생존 가능했습니다. 하지만 프롬프트를 문자 그대로, 그리고 명시적으로 해석하는 모델 앞에서는 탈출 조항은 곧 탈출하라는 지침이 됩니다.

기술(skill)에 대해 출시 당일에 던져야 할 질문은 좁고 명확합니다. 프로젝트에 대한 지식이 아니라 모델의 동작에 대한 임시방편(workaround)을 인코딩하는 파일들을 여십시오. 왜냐하면 바로 그런 것들이 새로운 모델에 의해 무효화되기 때문입니다. 저장소(Repo)에 대한 사실은 천천히 노후화되지만, 임시방편은 벤더(vendor)의 일정에 맞춰 노후화됩니다.

만약 기술을 감사(auditing)하는 것이 아니라 작성하고 있다면, 트리거 설명(trigger description)이 이 모든 것이 의미가 있는지 여부를 결정하는 부분입니다. 이에 대해서는 실제로 작동하는 기술을 작성하는 방법에서 별도로 다루었습니다. 노후화(Aging)는 동일한 업무의 나머지 절반입니다.

한계(Limits)

노후화(Vintage) 문제는 여기서 가장 큰 허점이므로 가장 먼저 다루겠습니다. IFScale의 밀도 곡선(density curve)은 이 논의의 대상이 되는 모델보다 한 세대 앞선 claude-opus-4를 대상으로 2025년 7월에 측정되었으며, 해당 벤치마크는 현재 모델들을 대상으로 다시 실행되지 않았습니다.

일관된 서사를 구성하는 데 있어 더 나쁜 점은, 준수성(adherence)이 출시 날짜에 따라 단조롭게(monotonically) 개선되지 않는다는 것입니다. 동일한 표에서 claude-3.7-sonnet은 최대 밀도에서 52.7%를 기록하며 claude-opus-4의 44.6%를 앞섭니다. 더 최신 모델이라고 해서 더 순종적인 것은 아니며, 그 이후로 곡선이 수정되었다고 말하는 사람은 누구든 추측을 하고 있는 것입니다.

해당 곡선을 당신의 파일에 적용할 때 발생하는 두 번째 문제는 따로 있습니다. IFScale은 하나의 프롬프트 내에 있는 독립적이고 개별적으로 확인 가능한 지시 사항(instructions)을 계산하는 반면, CLAUDE.md는 대부분 선언적 문맥(declarative context)이며 그 사이에 명령형(imperatives)이 섞여 있습니다. 산문 형태의 파일(prose file)이 해당 x축에 어떻게 매핑되는지는 아무도 측정하지 않았습니다.

저는 이 곡선을 좌표가 아닌 방향성으로 사용합니다. 규칙이 더 많아질수록 상황은 악화됩니다. 저는 당신의 파일이 그 곡선의 어디에 위치하는지 말씀드릴 수 없습니다.

그 외의 모든 것은 SWE-bench 스타일의 작업 세트(task suites)에서 측정되었습니다. 벤치마크 하네스(benchmark harness)에서의 문맥 파일(context file) 효과성과 당신의 모노레포(monorepo)에서의 효과성은 서로 다른 양이며, 논문들도 이를 다르게 취급합니다. 두 개의 닫힌 GitHub 이슈와 하나의 Hacker News 스레드가 실무자 측면의 데이터 전부인데, 이는 측정이 아닙니다.

다음으로 저자성(authorship) 문제가 있으며, 여기서 증거에 대한 대중적인 해석은 양방향 모두 틀렸습니다. ETH Zurich 및 LogicStar 연구는 온라인상에서 "문맥 파일이 성공률을 3% 감소시킨다"라고 요약되었는데, 이는 실험의 절반을 조용히 누락시킨 것입니다.

다음은 전체 결과입니다. 개발자가 작성한 문맥 파일은 파일이 전혀 없는 경우와 비교했을 때 에이전트 성능을 평균 4% 향상시킨 반면, LLM이 생성한 파일은 평균 3%의 손실을 초래했습니다. 논문은 테스트된 네 가지 에이전트 모두에서 개발자가 제공한 파일이 생성된 파일보다 성능이 뛰어났다고 명시하고 있습니다.

한 가지 예외는 언급할 가치가 있는데, 바로 이 포스트의 주제인 에이전트입니다. 테스트된 모든 에이전트에서 개발자가 작성한 파일이 파일이 없는 경우보다 성능이 뛰어났으나, Claude Code는 예외였습니다. 또 다른 설정인 모든 다른 문서가 제거된 저장소(repository)에서는 순위가 뒤바뀌어, 생성된 파일이 성능을 2.7% 향상시키며 개발자가 작성한 문서보다 더 나은 결과를 보였습니다.

가이드라인이 생성된 방식에 비하면 두 저작 방식(authorship arms) 모두 미미한 수준입니다. 반복적으로 개선된 가이드라인(Iteratively refined guidance)은 SWE-bench Verified에서 33.0%를 기록한 반면, 초기화에 사용된 수동 큐레이션 지식 베이스(hand-curated knowledge base)는 28.3%를 기록하여 p < 0.001 수준에서 4.7포인트의 격차를 보였습니다. 개선(Refinement)은 저작(authorship)을 큰 차이로 앞서지만, 저작의 영향력이 여전히 0은 아닙니다.