앤트로픽이 Claude Code용 claude-md-management 플러그인을 내놨다. 프로젝트 규칙 파일인 CLAUDE.md를 여섯 가지 기준으로 채점해 100점 만점 점수와 A~F 등급을 돌려주는 도구다. 채점표를 받아 이 블로그를 굴리는 저장소의 CLAUDE.md에 그대로 대 봤더니, 줄 수는 공식 권고선인 200줄 아래였는데(117줄) 절 하나가 파일 글자의 43%를 먹고 있었다(2026년 8월 5일 직접 확인).
규칙 파일은 눈에 잘 안 띈다. 코드처럼 실행되지도 않고 테스트도 안 걸린다. 그런데 세션을 열 때마다 통째로 읽히니까, 여기가 어긋나면 그 대화 전체가 어긋난 채로 간다.
이 플러그인은 정확히 무엇을 해 주나
두 가지를 한다. 하나는 규칙 파일을 채점하는 것이고, 다른 하나는 방금 끝난 작업에서 배운 것을 규칙 파일에 붙일 한 줄로 뽑아 주는 것이다.
채점 쪽은 claude-md-improver라는 스킬이다. “내 CLAUDE.md를 점검해 줘”처럼 부르면 저장소를 훑어 CLAUDE.md·.claude.local.md 를 전부 찾고, 파일마다 점수와 등급을 매긴 표를 먼저 보여 준다. 고치는 건 그다음이다. 스킬 문서에 “수정하기 전에 언제나 품질 보고서를 먼저 출력하라”고 대문자로 적혀 있고, 실제 수정은 diff를 보여 준 뒤 사용자가 승인한 것만 반영한다.
다른 하나는 /revise-claude-md 명령이다. 이건 방향이 반대다. 점검이 아니라 수집이다. 그 세션에서 새로 알게 된 것을 돌아보고 규칙 파일에 남길 만한 한 줄을 제안한다. 명령 정의 파일에 이런 문장이 있다. “간결하게, 개념 하나당 한 줄. CLAUDE.md는 프롬프트의 일부라서 짧은 게 중요하다.”
설치는 한 줄이다.
/plugin install claude-md-management@claude-plugins-official공식 문서 기준으로 claude-plugins-official 마켓플레이스는 Claude Code를 처음 켤 때 자동으로 등록된다. 못 찾겠다고 나오면 /plugin marketplace add anthropics/claude-plugins-official 을 먼저 하면 된다. 카탈로그는 claude.com/plugins 에서도 볼 수 있다.
무엇을 기준으로 채점하나
여섯 가지다. 채점표 원문에 배점까지 적혀 있어서 합이 정확히 100점이 된다.
| 기준 | 배점 | 묻는 것 |
|---|---|---|
| 명령어·작업 흐름 | 20 | 빌드·테스트·배포 명령이 적혀 있나 |
| 구조 설명 | 20 | 코드베이스 생김새가 파악되나 |
| 숨은 함정 | 15 | 이 프로젝트만의 별난 점이 적혀 있나 |
| 간결성 | 15 | 뻔한 말과 군더더기가 없나 |
| 최신성 | 15 | 지금 코드 상태와 맞나 |
| 실행 가능성 | 15 | 그대로 따라 할 수 있게 적혔나 |
등급은 90점 이상 A, 70점대 B, 50점대 C, 30점대 D, 29점 이하 F로 갈린다. 채점표에는 감점 신호 목록도 따로 있는데 읽어 볼 만하다. 실행하면 실패할 명령, 지워진 파일을 가리키는 경로, 낡은 버전 표기, 템플릿을 손 안 대고 붙여 넣은 흔적, 이 프로젝트와 상관없는 일반론, 끝내지 않은 TODO, 그리고 여러 규칙 파일에 같은 내용이 중복된 것.
짧게 쓰는 게 제일 중요한가
아니다. 적어도 이 도구의 배점은 그렇게 말하지 않는다. 20점짜리 두 개는 간결성이 아니라 명령어와 구조 설명이다. 곧 “무엇이 안 적혀 있나”를 먼저 본다. 간결성은 15점이고, 스킬 문서의 가중치 칸에서도 여섯 중 둘뿐인 Medium에 들어 있다.
이게 뜻밖이었다. 규칙 파일 이야기가 나오면 대체로 “너무 길다”로 흘러가는데, 정작 앤트로픽이 만든 채점표는 길이만으로는 만점의 15%까지만 움직인다. 파일을 반으로 줄여도 명령어가 없으면 20점이 그대로 빈다.
길이가 상관없다는 말은 아니다. CLAUDE.md 공식 문서는 이렇게 적어 뒀다. “파일당 200줄 이하를 목표로 하라. 파일이 길수록 컨텍스트를 더 먹고 지시 준수율이 떨어진다.” 바로 옆 항목은 이거다. “두 규칙이 서로 모순되면 클로드가 그중 하나를 임의로 고를 수 있다.” 길이와 충돌이 실제로 문제라는 건 1차 문서가 직접 적어 둔 셈이다. 다만 그게 채점의 중심은 아니라는 것.
우리 규칙 파일에 대 보니
숫자부터 적는다. 이 블로그 저장소의 CLAUDE.md는 117줄, 12,921자, 21,854바이트였다(2026년 8월 5일 기준).
| 잰 것 | 값 |
|---|---|
| 줄 수 | 117줄 (권고선 200줄 이내) |
| 글자 수 | 12,921자 |
| 제일 큰 절 하나 | 5,602자 = 파일의 43% |
| 파일이 가리키는 실제 경로 | 30개 |
| 그중 살아 있는 것 | 30개 |
줄 수 기준으로는 통과다. 117줄이면 200줄 권고에 한참 못 미친다. 그런데 한 줄이 평균 110자다. 줄 수가 길이를 대변하지 못한다는 뜻이고, 200줄이라는 기준을 우리 파일에 그대로 대면 실제보다 후하게 나온다.
경로 쪽은 기대보다 깨끗했다. 파일 안에서 백틱으로 감싼 경로를 뽑아 하나씩 존재를 확인했는데, 자리표시자를 뺀 실제 경로 30개가 전부 살아 있었다. 감점 신호 목록의 “지워진 파일을 가리키는 경로”에는 안 걸린다.
그럼 무엇이 틀려 있었나
손으로 관리하던 숫자였다. 이 파일의 “현재 상태” 절에 한동안 게시글이 5편이라고 적혀 있었는데, 그걸 발견한 2026년 7월 30일에 실제로는 23편이었다. 18편이 어긋난 채로 방치돼 있었던 것이다.
여기가 재미있는 지점이다. 기계가 셀 수 있는 것(경로 30개)은 전부 맞았고, 기계가 세러 가지 않는 것(글 편수 하나)이 틀렸다. 파일 경로는 존재하거나 안 하거나 둘 중 하나라 확인이 쉽다. 반면 “게시글 5편” 같은 문장은 문법적으로 멀쩡하고 파일 어디에도 모순이 없다. 실제 세상이 조용히 앞서갈 뿐이다.
고친 방식은 숫자를 정확히 갱신하는 게 아니었다. 그 줄에서 숫자를 아예 뺐다. 지금 그 자리엔 “게시글 목록과 편수는 content/post_YYYYMM.md 참조”라고만 적혀 있다. 손으로 관리하는 카운터는 반드시 어긋나니까, 두 곳에 적지 않고 한 곳만 정본으로 두는 쪽을 골랐다. 문장 하나를 어떻게 재느냐는 요구사항 정의서 작성법에서 다룬 자와 결이 같다. 셀 수 있게 적었나, 재 볼 수 있게 적었나.
규칙 파일을 이렇게 관리한다
바뀌는 숫자는 규칙 파일에 두지 않는다. 편수·버전·비용처럼 움직이는 값은 그 값이 실제로 사는 파일을 가리키게만 한다. 이게 앞의 사고에서 얻은 결론이고, 지금도 그렇게 쓰고 있다.
대신 규칙 파일에는 채점표가 20점씩 매긴 쪽을 채운다. 실제로 치는 명령, 폴더 구조, 그리고 이 프로젝트에서만 걸리는 함정. 우리 파일에서 제일 값이 나가는 부분도 서버 쪽 함정 네 가지를 적어 둔 자리다. 그건 코드를 읽어서는 절대 안 나온다.
중복은 여전히 남아 있다. 43%를 먹고 있는 그 절은 다른 문서에 이미 있는 규칙을 다시 쓴 것이라 감점 신호 목록의 마지막 항목에 정확히 걸린다. 알고도 두고 있다. 정리하는 데 드는 품과 잘못 지웠을 때의 손해를 재 보고 그렇게 정했는데, 채점을 해 보고 나니 그 판단을 한 번 더 들여다볼 생각이 든다. 도구가 준 값은 점수가 아니라 그 계기였다.
비싼 모델을 쓰는 것과 읽히는 규칙을 정돈하는 것 중에 뒤쪽이 싸고 효과가 빠르다. 규칙 파일은 세션마다 통째로 읽히니까, 거기 적힌 틀린 문장 하나는 한 번이 아니라 매번 틀린다. 바이브 코딩으로 주사위 게임을 만들었을 때도 막힌 자리는 모델이 아니라 요구가 흐릿한 자리였다.
솔직히 밝혀 둘 것
이 글은 플러그인을 설치해 돌린 후기가 아니다. 저장소에서 채점 기준 문서를 받아 우리 파일에 손으로 대 본 것이다. 점수를 숫자로 매기지 않은 것도 그래서다. 도구가 내는 등급은 도구가 매겨야 의미가 있다.
수정 제안 단계도 돌리지 않았다. 이 파일의 중복은 남겨 두기로 정해 둔 것이라, 고쳐 주겠다는 제안을 받아 봐야 반영할 데가 없다.
그리고 플러그인은 종류를 가려서 깔아야 한다. 같은 공식 문서에 이런 경고가 붙어 있다. 앤트로픽은 플러그인에 어떤 MCP 서버나 파일이 들어 있는지 통제하지 않고, 의도대로 동작하는지도 보증하지 않는다. 이 플러그인은 앤트로픽이 직접 만들어 저장소의 내부 플러그인 폴더에 둔 것이지만, 같은 목록에 외부 제출분도 섞여 있다. AI 도구 이름이 늘어나는 속도는 요즘 AI 용어를 정리하면서도 느꼈는데, 이름이 늘어난 만큼 설치 전에 한 번 보는 습관도 같이 늘어야 한다.
여기 적은 배점표와 설치 명령어는 2026년 8월 5일에 저장소와 공식 문서에서 직접 확인한 것이다. 도구 쪽 문서는 자주 바뀐다.