낡은 CLAUDE.md가 Claude Code의 작업 정확도를 떨어뜨리는 이유

빌드 명령어를 바꾼 지 두 달이 지났는데도 Claude Code는 여전히 옛 명령어로 빌드를 시도합니다. 디렉터리를 재편해도 사라진 경로를 자꾸 참조하고, 테스트 명령어가 바뀐 줄도 모른 채 옛 방식으로 돌려보다 실패하죠. 코드는 리팩터링으로 계속 다듬어지는데, CLAUDE.md만 처음 작성한 그대로 박제되어 있는 거예요. 이 글에서는 CLAUDE.md가 시간이 지나며 어떻게 망가지는지, 그리고 Anthropic이 직접 만든 claude-md-management 플러그인으로 어떻게 다시 살려낼 수 있는지 정리합니다. 목차

CLAUDE.md가 낡으면 무슨 일이 벌어지는가 claude-md-improver: CLAUDE.md를 6가지 기준으로 채점한다 /revise-claude-md: 세션이 끝날 때마다 배움을 기록한다 토큰을 먹기만 하는 CLAUDE.md와 일을 시키는 CLAUDE.md 두 도구를 언제 구분해서 써야 하는가

CLAUDE.md가 낡으면 무슨 일이 벌어지는가 CLAUDE.md의 내용은 매 세션 프롬프트의 일부로 전송됩니다. 즉, 거기에 적힌 모든 줄이 Claude에게는 "사실"로 작동해요. 그래서 빌드 명령어가 바뀌었는데 CLAUDE.md에는 옛 명령어가 남아 있다면, Claude는 자신 있게 틀린 명령어를 실행합니다. 부작용은 하나 더 있습니다. CLAUDE.md가 비대해질수록 매 세션 토큰을 더 많이 소모해요. 의미 없는 일반론과 중복 설명이 쌓이면, 컨텍스트 윈도우를 그만큼 헛되이 깎아 먹는 셈입니다.

코드는 리팩터링되는데 CLAUDE.md만 멈춰 있다면, 그건 매 세션 잘못된 정보를 프롬프트에 끼워 넣는 것과 같습니다.

팀에서 운영 중이라면, 지금 당장 최근 3개월 git log를 훑어보고 CLAUDE.md가 그 변경을 반영하고 있는지 확인하세요. 디렉터리 구조, 빌드 스크립트, 테스트 명령어 세 가지만 봐도 절반은 갱신할 거리가 나옵니다. 2. claude-md-improver: CLAUDE.md를 6가지 기준으로 채점한다 claude-md-improver는 정기 건강검진 같은 스킬입니다. 슬래시 명령어를 외울 필요 없이, Claude Code에 자연어로 "CLAUDE.md를 감사해 줘"라고 말하면 발동합니다. 작동 흐름은 단순해요.

리포지토리 내 모든 CLAUDE.md와 CLAUDE.local.md를 찾는다 정해진 6가지 기준으로 각각을 채점한다 A부터 F까지 등급과 보고서, 구체적인 개선 제안을 보여준다 사용자가 승인하면 diff를 적용한다

채점 기준은 다음과 같이 배분되어 있습니다. 기준배점확인 내용Commands / Workflows20build / test / lint / deploy가 갖춰져 있는가Architecture Clarity20디렉터리 구조나 모듈 관계가 드러나는가Non-Obvious Patterns15코드만 봐서는 모를 함정·관례가 적혀 있는가Conciseness15당연한 설명이나 중복으로 부풀려져 있지 않은가Currency15현재 코드베이스와 일치하는가Actionability15명령어를 복사해 바로 실행 가능한가 여기서 눈에 띄는 건 Conciseness(간결함)에 15점이 배정되어 있다는 점입니다. 다 적어두는 게 점수가 아니라 오히려 감점 요인이라는 뜻이죠. CLAUDE.md는 프롬프트의 일부이기 때문에 길이 자체가 비용입니다.

CLAUDE.md를 두껍게 쓰는 것은 미덕이 아닙니다. 매 줄이 토큰이고, 매 줄이 Claude의 주의를 끌어갑니다.

개발자라면 처음 채점에서 A가 나오리라 기대하지 않는 편이 좋습니다. 직접 돌려보면 B나 C가 흔하게 나옵니다. 점수 자체보다 "왜 깎였는지"를 읽는 게 핵심이에요. 그동안 어떤 기준으로 낡아 있었는지가 그대로 드러납니다. 3. /revise-claude-md: 세션이 끝날 때마다 배움을 기록한다 /revise-claude-md는 좀 더 일상적인 도구입니다. 오늘 세션 도중 "아, 이 명령어 처음 알았네", "이 폴더 구조는 처음 보면 못 알아채겠다"라고 느낀 순간이 있을 거예요. 그 감각을 다음 세션의 Claude에게 넘기는 명령어입니다. 플러그인 명령어는 네임스페이스와 함께 호출합니다. /claude-md-management:revise-claude-md /claude-md-management:까지만 치면 Tab으로 자동완성됩니다. 실행하면 Claude는 그 세션을 되돌아보며 다음을 추출합니다.

직접 쓰거나 발견한 Bash 명령어 지킨 코드 스타일 패턴 잘 통한 테스트 기법 환경이나 설정의 특이점 빠질 뻔한 함정과 경고

추가로, 어느 파일에 기록할지까지 판단합니다. 팀이 공유해야 하면 CLAUDE.md, 개인 환경에만 해당하면 CLAUDE.local.md로 분류해 제안하죠. 모든 제안은 diff로 미리 보여주고, 거절하면 파일은 그대로 둡니다.

세션이 끝나는 시점은, 이번 작업에서 얻은 정보가 가장 신선한 시점이기도 합니다.

팀에서 운영 중이라면 이 명령어를 PR 만들기 직전 워크플로에 끼워 넣는 것을 추천합니다. PR 본문을 쓰는 시점이 곧 "이번에 뭐가 새로 정해졌는가"를 정리하는 시점이라, CLAUDE.md 갱신도 같은 흐름에 자연스럽게 붙습니다. 4. 토큰을 먹기만 하는 CLAUDE.md와 일을 시키는 CLAUDE.md 플러그인의 가이드라인을 보면 CLAUDE.md에 "무엇을 적을 것인가"보다 "무엇을 적지 않을 것인가"를 더 강하게 잡고 있습니다. 이유는 똑같아요 — 모든 줄이 매 세션 프롬프트에 실립니다. 적어야 할 것

발견한 명령어 (npm run build:prod처럼 그 자리에서 찾은 것) 비자명한 패턴 ("테스트는 --runInBand로 직렬 실행 필수" 같은 제약) 패키지 간 관계 ("auth 모듈은 crypto 초기화 이후에 import" 같은 의존성) 검증된 테스트 기법 ("API 테스트는 supertest 사용") 설정의 특이점 ("Redis 연결에 ?family=0 필수")

적지 말아야 할 것

코드 읽으면 보이는 것: "UserService는 사용자 관련 작업을 처리합니다" 같은 자명한 설명 일반론: "테스트를 꼼꼼히 작성합시다" 류의 프로젝트 무관 격언 일회성 수정: "커밋 abc123에서 버그 픽스" — 다음에 재발하지 않으면 기록할 필요가 없습니다 장황한 해설: JWT를 RFC부터 설명하지 말고, Auth: JWT HS256, Authorization: Bearer <token> 한 줄로 끝냅니다

CLAUDE.md의 한 줄 한 줄에 "이게 정말 Claude가 알아야 하는가"라고 묻는 습관을 들이면, 평균 절반은 사라집니다.

개발자라면 새 CLAUDE.md를 쓸 때 "코드를 처음 보는 사람에게 입으로 설명해야 하는 것"만 적는 기준으로 시작해 보세요. 코드를 열면 알 수 있는 것은 적지 않습니다. 이 한 가지 기준만으로도 Conciseness 점수가 크게 올라갑니다. 5. 두 도구를 언제 구분해서 써야 하는가 claude-md-improver와 /revise-claude-md는 기능이 비슷해 보여 헷갈리기 쉽습니다. 실은 트리거가 완전히 다릅니다. 도구트리거성격claude-md-improver (스킬)코드베이스가 바뀐 후정기 건강검진/revise-claude-md (명령어)세션이 끝나갈 때일상적 메모 큰 리팩터링이나 디렉터리 재편 직후라면 claude-md-improver로 전체를 훑습니다. 새 도구나 설정을 도입한 직후도 마찬가지로 improver입니다. 반면, 세션 중에 "아, 이거 처음 알았네" 싶은 순간에는 /revise-claude-md로 그 자리에서 기록합니다.

건강검진(improver)은 한 달에 한 번, 일기(revise)는 세션마다 — 정도의 빈도가 적당합니다.

팀에서 운영 중이라면, improver는 스프린트 회고나 릴리스 직전에 정기 일정으로 박아두는 게 효과적입니다. revise는 그때그때라 강제하기 어렵지만, 팀 컨벤션으로 "PR 만들기 전 /revise-claude-md 한 번씩"을 정해두면 자연스럽게 굴러갑니다. 설치는 Claude Code 안에서 한 줄이면 끝납니다. /plugin install claude-md-management@claude-plugins-official 설치 후 /reload-plugins로 현재 세션에 반영하는 것만 잊지 마세요. FAQ Q. claude-md-management는 어디에서 설치하나요? A. Claude Code 내부에서 /plugin install claude-md-management@claude-plugins-official을 실행합니다. claude-plugins-official 마켓플레이스는 Claude Code 실행 시 자동 활성화되므로 별도 등록은 필요 없습니다. 설치 후 /reload-plugins를 실행해야 현재 세션에 스킬과 명령어가 반영됩니다. Q. CLAUDE.md와 CLAUDE.local.md는 어떻게 다른가요? A. CLAUDE.md는 팀이 공유하는 파일로 git에 커밋합니다. CLAUDE.local.md는 개인 환경 전용으로 .gitignore에 넣어 본인 머신에만 두는 파일입니다. 글로벌 개인 설정은 ~/.claude/CLAUDE.md, 모노레포의 모듈별 정보는 각 패키지 디렉터리의 CLAUDE.md에 두면 Claude Code가 상위 디렉터리 분까지 합산해 인식합니다. Q. 플러그인이 CLAUDE.md를 멋대로 고치지는 않나요? A. 두 도구 모두 최종 편집은 사용자 승인을 거친 후에만 적용됩니다. 변경 사항은 diff로 미리 보여주므로, 마음에 들지 않는 항목만 골라서 거절할 수 있습니다. Q. 채점에서 B나 C가 나왔습니다. 심각한가요? A. 처음 실행하면 흔히 나오는 점수입니다. 점수 자체보다 어느 기준에서 깎였는지를 보세요. Currency(현재성)에서 깎였다면 코드와 문서의 괴리가 크다는 뜻이고, Conciseness에서 깎였다면 불필요한 설명이 많다는 뜻입니다. 한 번에 다 고치려 하지 말고 한 카테고리씩 개선해 가는 편이 현실적입니다. 정리 지금 당장 할 수 있는 세 가지입니다.

Claude Code에서 /plugin install claude-md-management@claude-plugins-official로 플러그인을 설치합니다. claude-md-improver를 실행해 현재 CLAUDE.md 점수를 확인하고, 가장 점수가 낮은 카테고리부터 손봅니다. 세션이 끝나갈 때 /revise-claude-md를 호출하는 습관을 팀 워크플로에 끼워 넣습니다.

CLAUDE.md는 한 번 쓰고 끝나는 문서가 아니라, 코드와 같이 자라야 하는 문서입니다. 코드를 리팩터링하듯 CLAUDE.md도 정기적으로 리팩터링한다는 감각이 자리 잡으면, Claude Code의 작업 정확도 자체가 한 단계 올라갑니다. 관련 글 더 보기

TanStack Query 안티패턴 — 성능이 갑자기 떨어지는 이유 (블로그 내 링크) React에서 인라인 스타일을 쓰면 안 되는 4가지 근거 (블로그 내 링크) Anthropic Claude Code 메모리 공식 문서: https://docs.claude.com/en/docs/claude-code/memory

참고 링크

Anthropic Claude Code 공식 문서: https://docs.claude.com/en/docs/claude-code claude-md-management 플러그인 카탈로그 (Claude Plugins) claude-plugins-official 리포지토리