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. 승인을 요청한 후 실제로 차이를 적용한다

참고로 저는 /claude-md까지 입력하면 claude-md-improver가 후보로 표시되므로, 그에 맞춰 탭 키를 누르면 /claude-md-management:claude-md-improver라는 커맨드가 되어 그것을 실행하고 있습니다.

6가지 채점 기준

채점은 제대로 된 루브릭에 기반합니다. 합계 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:까지 입력하면 탭 완성도 작동하므로 생각보다 편합니다.

이 커맨드를 실행하면 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를 사용한다"와 같이 확립된 패턴
• **설정의 특