Anthropic 공식 claude-md-management 플러그인으로 CLAUDE.md를 키워 나가자

CLAUDE.md, 마지막으로 확인한 게 언제인가요? 프로젝트 빌드 명령어가 바뀌었거나, 테스트 실행 방법이 달라졌거나, 디렉터리 구조를 정리했을 때, 매번 제대로 반영하고 계신가요? 솔직히 저는 게을러지기 일쑤입니다. 그러다 보면 어느새 Claude Code가 낡은 정보에 의존해 엉뚱한 짓을 시작하는 '흔한 상황'이 발생하곤 하죠.

이 고민에 정면으로 답해주는 것이 Anthropic 공식 claude-md-management 플러그인입니다. Claude Code를 만드는 Anthropic이 직접 개발하고 유지보수하는 플러그인으로, CLAUDE.md의 품질을 채점해 주는 스킬과 세션 중 배운 내용을 CLAUDE.md에 반영하는 명령어가 세트로 구성되어 있습니다. 말하자면 'CLAUDE.md 청소 담당' 같은 플러그인입니다.

이번에는 이 플러그인의 내용, 설치 방법, 실제 사용법, 그리고 CLAUDE.md를 어떻게 관리해야 하는지에 대한 베스트 프랙티스까지 정리해서 소개해 드립니다.

왜 CLAUDE.md의 최신 상태가 중요한가

CLAUDE.md는 Claude Code가 매 세션마다 읽어들이는 '프로젝트 취급 설명서'입니다. 빌드 명령어, 아키텍처, 빠지기 쉬운 함정 등 코드만 봐서는 알기 어려운 정보를 여기에 적어두면, Claude가 처음부터 프로젝트의 '분위기'를 이해한 상태로 작업을 시작할 수 있습니다.

하지만 여기에는 부작용도 있습니다. CLAUDE.md의 내용은 프롬프트의 일부로 매번 전송되므로, 낡은 정보나 중복된 정보가 있으면 그대로 Claude를 잘못 인도하거나 토큰을 낭비하게 됩니다. 코드 본체는 리팩터링을 통해 항상 세련되게 다듬어지는데, CLAUDE.md만 몇 달 전 모습 그대로 방치되는 것은 흔한 일입니다.

claude-md-management는 이러한 '방치 문제'를 시스템적으로 해결하기 위한 플러그인입니다.

두 가지 도구: 점검과 기록

이 플러그인에는 역할이 다른 두 가지 도구가 들어 있습니다. 혼동하기 쉬우니 먼저 정리해 보겠습니다.

**claude-md-improver**는 코드베이스 전체를 훑어보며 "이 CLAUDE.md가 현재 코드를 제대로 반영하고 있는가?"를 점검하는 스킬입니다. 정기 건강검진이라고 할 수 있죠.

반면 **/revise-claude-md**는 좀 더 일상적인 도구로, "오늘 세션에서 발견한 명령어와 주의사항"을 그 자리에서 CLAUDE.md에 기록하기 위한 명령어입니다. '기록 담당'이라고 부르면 이해하기 쉬울 것입니다.

두 도구 모두 최종적으로 편집을 적용하기 전에 사용자의 승인을 구하므로, CLAUDE.md가 멋대로 수정될 걱정은 없습니다.

설치

claude-plugins-official 마켓플레이스는 Claude Code를 실행할 때 자동으로 활성화되므로 추가 준비는 필요 없습니다. Claude Code 내에서 다음을 실행하는 것만으로 설치할 수 있습니다.

/plugin install claude-md-management@claude-plugins-official

"어떤 플러그인이 있을까?" 하고 둘러보며 선택하고 싶다면, /plugin을 입력하고 Discover 탭을 열어 카탈로그에서 검색하여 설치할 수 있습니다.

설치 후에는 잊지 말고 /reload-plugins를 실행해 주세요. 그래야 스킬과 명령어가 현재 세션에 반영됩니다.

사용법 1: claude-md-improver로 점검하기

claude-md-improver는 스킬이므로 슬래시 명령어를 따로 외울 필요가 없습니다. Claude에게 자연스러운 언어로 요청하기만 하면 실행됩니다.

CLAUDE.md를 감사해 주세요
check if my CLAUDE.md is up to date

이런 식의 한 문장이면 충분합니다. 스킬이 작동하면 다음과 같은 워크플로가 진행됩니다.

1. 리포지토리 내의 모든 CLAUDE.md와 CLAUDE.local.md를 찾습니다.
2. 각각을 6가지 관점에서 채점하여 A~F 등급을 매깁니다.
3. 보고서를 제시하고 구체적인 개선 제안을 나열합니다.
4. 승인을 받은 후 실제로 차이점(diff)을 적용합니다.

참고로 저는 /claude-md까지 입력하면 claude-md-improver가 후보로 표시되므로, 탭 키를 눌러 /claude-md-management:claude-md-improver 명령어를 완성해 실행하곤 합니다.

6가지 채점 기준

채점은 정해진 루브릭(rubric)에 근거하며, 총 100점 만점입니다.

흥미로운 점은 **Conciseness(간결함)**에 점수가 배정되어 있다는 것입니다. "일단 다 적고 보자"는 오히려 감점 대상이라는 뜻이죠. CLAUDE.md는 매번 프롬프트의 일부로 읽히기 때문에 양을 늘리는 것이 능사가 아닙니다.

채점 결과는 A(90100)부터 F(029)까지 5단계로 표시됩니다. 제가 이 스킬을 실행해 봐도 의외로 B나 C가 많아, 그동안 얼마나 품질이 낮은 CLAUDE.md를 사용해 왔는지 통감하게 됨과 동시에 이 플러그인의 고마움을 실감하게 됩니다.

사용법 2: /revise-claude-md로 배움 반영하기

코딩 세션을 마친 후, "오늘은 이 명령어를 몰랐었네", "이 디렉터리 구조는 언뜻 봐서는 이해하기 어렵네"라고 느낀 적 없으신가요? 그 감각을 다음 세션의 Claude에게 전달하기 위한 명령어가 /revise-claude-md입니다.

/claude-md-management:revise-claude-md

플러그인 스킬은 모두 네임스페이스와 함께 호출됩니다. /claude-md-management:까지 입력하면 Tab 보완이 작동하므로 생각보다 간편합니다.

이 명령어를 실행하면 Claude는 현재 세션을 되돌아보고 다음과 같은 관점에서 '추가해야 할 내용'을 찾습니다.

• 사용했거나 발견한 Bash 명령어
• 준수한 코드 스타일 패턴
• 성공적이었던 테스트 기법
• 환경이나 설정의 특이점
• 마주친 함정이나 경고

그다음 어느 CLAUDE.md에 작성해야 할지까지 판단해 줍니다. 팀 공유용이라면 CLAUDE.md, 개인용이라면 CLAUDE.local.md와 같은 식입니다.

제안은 diff 형식으로 표시되며, 승인하기 전까지 실제 파일은 변경되지 않습니다. "이건 좀 불필요하다" 싶은 것은 거절하면 되므로 정보가 너무 많이 쌓일 걱정도 없습니다.

CLAUDE.md의 4가지 위치

이 플러그인을 사용하다 보면 CLAUDE.md라고 해도 몇 가지 종류가 있다는 것을 알게 됩니다. 정리해 보겠습니다.

Claude Code는 상위 디렉터리의 CLAUDE.md도 자동으로 찾아 합산해 주므로, 모노레포(하나의 리포지토리에 여러 패키지를 모으는 구성)에서 패키지마다 CLAUDE.md를 두어도 문제없이 작동합니다. 이 플러그인 역시 각각의 CLAUDE.md를 개별적으로 감사해 줍니다.

베스트 프랙티스: 어떻게 키워나갈 것인가

이 플러그인의 update-guidelines.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-md-improver로 전체 점검
• 새로운 도구나 설정을 도입한 직후 → claude-md-improver로 누락된 반영 사항 확인
• 세션 중에 "아, 이거 몰랐네"라고 느꼈을 때 → /revise-claude-md로 그 자리에서 반영

정기적인 건강검진(improver)과 일상의 작은 기록(revise)을 병행하는 것을 추천합니다.

마치며

claude-md-management는 "CLAUDE.md는 한 번 쓰고 끝내는 것이 아니라 키워나가는 것"이라는 발상을 구체화한 플러그인입니다. Anthropic에서 공식적으로 내놓은 만큼 Claude Code 본체와의 궁합도 좋고 도입 비용도 거의 제로에 가깝습니다.

저도 실제로 사용해 보면서 생각보다 CLAUDE.md가 낡아 있었다는 사실을 깨닫곤 합니다. Claude Code를 일상적으로 사용하고 계신다면 꼭 한번 설치해 보세요. CLAUDE.md를 감사받는 것만으로도 자신의 프로젝트를 바라보는 관점이 조금 달라질 것입니다.

참고 링크

• CLAUDE.md Management (Claude Plugins 카탈로그)
• claude-plugins-official 리포지토리
• Discover and install plugins (공식 문서)