claude-md-management 플러그인 리뷰: 클로드 코드 CLAUDE.md 점검·고치기, 플러그인 없이 한 것과 비교

클로드 코드는 프로젝트의 CLAUDE.md를 매번 읽고 일을 시작하는데, 이 파일은 한 번 써 두고 잊기 쉬워 코드가 바뀐 뒤에도 없는 명령이나 지운 폴더를 계속 알려 주곤 합니다. claude-md-management는 Anthropic 공식 플러그인으로, CLAUDE.md를 실제 코드와 대조해 점수를 매기고 고쳐 주는 스킬과 대화에서 알게 된 것을 CLAUDE.md에 보태는 명령을 담고 있습니다. 일부러 낡게 쓴 CLAUDE.md가 든 예제 프로젝트를 만들고, 같은 요청을 플러그인 없이 두 번, 플러그인으로 세 번 보내 결과를 채점했습니다. 플러그인은 무료이고 쓸 때 Claude 사용량이 듭니다.

결과부터 보기: 같은 요청, 세 파일 나란히

왼쪽이 손대기 전 CLAUDE.md, 가운데가 플러그인 없이 고친 것, 오른쪽이 플러그인으로 고친 것입니다. 아래쪽 목록은 채점 10개 결과입니다.

직접 눌러 보기: 다섯 번의 결과 파일 전체 비교(탭을 누르면 실행마다 고친 CLAUDE.md와 채점 결과가 나옴)

따라 해 보기: 요청문과 실습 재료

CLAUDE.md가 있는 프로젝트 폴더에서 클로드 코드를 열고 아래 문장을 보내면 이번 실험과 같습니다. 플러그인이 없어도 됩니다. CLAUDE.md를 처음 만드는 단계라면 CLAUDE.md 작성법 글을, 클로드 코드가 처음이라면 클로드 코드 설치 방법을 먼저 보세요. 실습 재료(zip)에는 예제 프로젝트, 요청문, 채점 기준과 채점 스크립트, 다섯 번의 결과 파일을 넣었습니다.

이 프로젝트의 CLAUDE.md를 점검하고 고쳐 줘. 확인은 묻지 말고 바로 고쳐 줘.

좋은 답이라면 무엇이 실제와 달랐는지(명령·버전·폴더), 무엇을 새로 넣고 뺐는지를 나눠 알려 주고, 적은 명령을 직접 돌려 본 결과까지 말해 줍니다.

예제 프로젝트의 원래 CLAUDE.md는 아래와 같습니다. npm start라는 명령은 없고, 노드는 20 이상이 필요하며, src/·public/ 폴더도 없습니다. 빌드에는 CAFE_NAME 환경 변수가 있어야 하는데 그 말도 빠져 있습니다.

# 카페 메뉴 프로젝트

우리 카페 메뉴 웹사이트를 만드는 프로젝트입니다. 자바스크립트로 만들었습니다. 자바스크립트는 브라우저와 Node.js 서버에서 돌아가는 프로그래밍 언어입니다.

## 설치와 실행
Node 16이 필요합니다.
`npm install` 후 `npm start`로 서버를 켭니다.

## 폴더 구조
- src/ : 소스 코드
- src/legacy/ : 예전 템플릿 (건드리지 말 것)
- public/ : 정적 파일

## 규칙
- 항상 깔끔한 코드를 작성하세요.
- 의미 있는 변수 이름을 쓰세요.
- 새 기능에는 테스트를 작성하세요.
- TODO: 배포 방법 정리하기

1단계. 플러그인 깔기 (약 1분)

플러그인은 스킬·명령·훅을 묶어 클로드 코드에 넣는 꾸러미입니다. claude-md-management에는 CLAUDE.md를 점검하는 스킬(claude-md-improver) 하나와 /revise-claude-md 명령 하나가 들어 있습니다. 둘 다 Claude가 읽는 지시 문서이고, 컴퓨터에서 따로 돌아가는 프로그램은 없습니다. 스킬이 무엇인지는 클로드 스킬 글에 정리했습니다.

쓰려는 프로젝트 폴더에서 터미널에 아래 명령을 실행합니다. --scope local은 이 폴더에서만 켜는 옵션입니다.

claude plugin install claude-md-management@claude-plugins-official --scope local

이렇게 나오면 성공 ✔ Successfully installed plugin: claude-md-management@claude-plugins-official (scope: local). 폴더 안 .claude/settings.local.json에 이 플러그인이 켜짐으로 적힙니다.

• --scope를 빼면 내 컴퓨터의 모든 프로젝트에 켜집니다. CLAUDE.md를 여러 프로젝트에서 관리한다면 그렇게 깔아도 됩니다.
• 클로드 코드를 대화형으로 한 번도 켜지 않은 컴퓨터에서 설치가 실패하면 claude plugin marketplace add anthropics/claude-plugins-official를 먼저 실행합니다(공식 플러그인 문서 기준).

필요 없어지면 같은 폴더에서 아래 명령으로 지웁니다.

claude plugin uninstall claude-md-management@claude-plugins-official --scope local

2단계. “CLAUDE.md 점검하고 고쳐 줘” 보내기 (약 1분)

스킬 이름을 부를 필요는 없습니다. 플러그인을 깐 세 번 모두 Claude가 요청을 보고 첫 동작으로 claude-md-improver 스킬을 불렀습니다. 스킬 문서에 적힌 순서는 이렇습니다. 폴더 안의 CLAUDE.md를 모두 찾고, 6개 항목(명령 20점, 구조 20점, 숨은 함정 15점, 간결함 15점, 최신 상태 15점, 바로 실행할 수 있는지 15점)으로 점수를 매겨 보고한 뒤, 고칠 내용을 보여 주고 허락을 받아 고칩니다.

이번에는 다섯 번 모두 코드 파일을 읽고 npm test와 npm run check를 실제로 돌려 본 다음 파일을 고쳤습니다. 플러그인 쪽은 답에 점수를 붙였습니다. 1회차와 2회차는 고치기 전 파일을 25/100점(F 등급)으로 매겼습니다. 플러그인 1회차 답의 첫 부분을 옮깁니다.

실행 기록 · 작업 폴더 · 플러그인 1회차 답에서 옮김

CLAUDE.md를 점검하고 다시 썼습니다. 실제 코드와 맞지 않는 내용이 많아서 일부만 고치기보다 새로 쓰는 쪽을 택했습니다. 고치기 전 점수는 25/100(F 등급) 정도입니다.

| 기존 내용 | 실제 | 조치 |
| Node 16 필요 | package.json에는 >=20 | Node 20 이상으로 수정 |
| npm start로 실행 | start 스크립트가 없고 dev가 있음 | 명령 4개(build, dev, test, check)로 교체 |
| src/, src/legacy/, public/ | 셋 다 없는 폴더 | 실제 구조(data/, scripts/, test/)로 교체 |

스킬 문서는 “고칠 내용을 diff(바뀐 줄)로 보여 주고 허락을 받은 뒤 고친다”고 적고 있습니다. 이번에는 다섯 번 모두 파일을 통째로 다시 썼고, 바뀐 줄을 따로 보여 주지 않았습니다. “확인은 묻지 말고 바로 고쳐 줘”를 뺀 플러그인 3회차도 허락을 묻지 않고 바로 고쳤습니다. 다만 이 컴퓨터의 개인 설정 문서(CLAUDE.md)에 “지시한 작업은 묻지 말고 끝까지 진행”이라는 규칙이 있어 그 영향일 수 있습니다. 대화창에서 쓸 때 고치기 전에 보고만 받고 싶다면 “먼저 점수와 고칠 곳만 보여 줘”라고 요청하면 됩니다.

플러그인 없이·있이 채점 결과

채점 기준은 실행 전에 이 플러그인의 채점표(quality-criteria)와 고칠 때 지침(update-guidelines)에서 뽑아 고정했고, 요청문에는 넣지 않았습니다. 예제에 일부러 심은 문제 8개와 결과 조건 2개를 채점 스크립트로 판정했습니다.

검사	플러그인 없음 (1·2)	플러그인 있음 (1·2)	플러그인 있음 ③ 기본 요청
없는 npm start → npm run dev	✅ ✅	✅ ✅	❌ (아래 설명)
Node 16 → 20 이상	✅ ✅	✅ ✅	✅
없는 폴더(src/·public/) 언급 지움	✅ ✅	✅ ✅	✅
build·test·check 명령 적음	✅ ✅	✅ ✅	✅
CAFE_NAME 환경 변수 필요하다고 적음	✅ ✅	✅ ✅	✅
dist/ 폴더는 빌드마다 지워지니 직접 고치지 말 것	✅ ✅	✅ ✅	✅
“깔끔한 코드를 작성하세요” 같은 일반론 지움	✅ ✅	✅ ✅	✅
“자바스크립트는 … 언어입니다” 설명 지움	✅ ✅	✅ ✅	✅
40줄 이하	✅ ✅	✅ ✅	✅
코드 파일은 그대로	✅ ✅	✅ ✅	✅
합계(10개 중)	10 · 10	10 · 10	9
고친 파일 길이	19줄 · 19줄	24줄 · 30줄	27줄
점수 매기기	없음	25/100(F) · 약 25/100(F)	고친 뒤 예상 약 85(B)
사용량(API 단가)	0.33 · 0.32달러	0.36 · 0.36달러	0.40달러

3회차의 ❌ 하나는 실수가 아닙니다. 새 파일에 “npm start는 없음”이라는 안내 줄을 남겼고, 채점 스크립트가 npm start 글자가 남았는지만 봐서 걸렸습니다. npm run dev는 제대로 적었습니다.

다섯 파일의 차이는 크지 않았습니다. 넷은 “배포 방법 정리하기” TODO를 코드에 배포 근거가 없다며 지웠고, 플러그인 2회차만 “배포 방법 미정”으로 남겼습니다. 플러그인 쪽은 명령을 코드 상자에 모으고 파일마다 역할을 한 줄씩 적어서 더 길어졌습니다. 다섯 번 모두 코드에서 확인한 가격 규칙(100원 단위, 1,000원 이상)과 가격 표시 함수 won()도 주의 사항에 넣었습니다.

플러그인 없이 1회차가 고친 파일입니다.

# 카페 메뉴 프로젝트

`data/menu.json`을 읽어 정적 메뉴 페이지 `dist/index.html`을 만드는 프로젝트. Node 20 이상, ES 모듈(`.mjs`), 외부 의존성 없음.

## 명령
- `CAFE_NAME="달빛 카페" npm run build` : `dist/index.html` 생성. `CAFE_NAME`이 없으면 실패함
- `npm run dev` : `dist/`를 http://localhost:5173 에 띄움 (먼저 build 필요)
- `npm test` : `node --test` (테스트는 `test/*.test.mjs`)
- `npm run check` : 메뉴 가격 규칙 검사

## 구조
- `data/menu.json` : 메뉴 원본 (`categories[].items[]`의 `name`, `price`)
- `scripts/render.mjs` : HTML 렌더링 (`renderMenu`, `won`)
- `scripts/build.mjs`, `scripts/serve.mjs`, `scripts/check-prices.mjs` : 위 명령들의 실행 파일

## 주의
- `dist/`는 빌드마다 통째로 지우고 다시 만든다. `dist/` 안 파일을 직접 고치지 말고 `data/`나 `scripts/`를 고칠 것.
- 가격은 원 단위 정수, 100원 단위, 1,000원 이상. 쉼표·"원"은 표시할 때 `won()`으로만 붙인다. 메뉴를 고친 뒤 `npm run check` 실행.
- 새 기능에는 `test/`에 테스트 추가.

기본 명령 /doctor prompt-audit 와 비교

공식 메모리 문서에는 플러그인 없이 쓰는 점검 명령이 하나 있습니다. /doctor prompt-audit는 CLAUDE.md 같은 지시 파일에서 낡은 지시, 없는 파일·명령 언급, 서로 부딪치는 규칙을 찾아 보고서와 수정안을 냅니다. 사용자가 고치라고 하기 전에는 파일을 바꾸지 않고, 클로드 코드 2.1.283 이상에서 됩니다.

같은 예제 프로젝트 복사본에서 한 번 돌려 봤습니다. Node 16, 없는 npm start, 없는 폴더 세 개, 빠진 CAFE_NAME·dist/·가격 규칙, 일반론 문장, 자바스크립트 설명까지 채점 항목에 든 문제를 모두 표로 짚었고, 파일은 그대로였습니다. 프로젝트 CLAUDE.md뿐 아니라 이 컴퓨터의 개인 설정 문서(~/.claude/CLAUDE.md)까지 함께 검사해 그쪽 문장도 고치자고 제안했습니다. 1분 반쯤 걸렸고 1.12달러어치로, 플러그인 점검의 세 배 가까이 들었습니다.

정리하면 보고서만 받고 직접 고치려면 /doctor prompt-audit, 점검과 고치기를 한 번에 맡기려면 이 플러그인이나 그냥 “점검하고 고쳐 줘” 요청이 맞습니다.

3단계. 작업이 끝나면 /revise-claude-md (선택, 약 1분)

이 명령은 방금 대화에서 알게 된 것(쓴 명령, 겪은 오류, 코드 규칙) 중 CLAUDE.md에 없는 것을 찾아 보태자고 제안합니다. 명령 문서에 따르면 한 줄짜리로 짧게 쓰고, 넣을 내용을 보여 준 뒤 허락받은 것만 고칩니다.

플러그인 1회차 대화를 이어서 이 명령을 보내 봤습니다. 방금 CLAUDE.md를 고친 대화라 “새로 넣을 내용이 없다”며 파일을 바꾸지 않았고, 넣지 않은 이유(권한 거부는 이 컴퓨터 설정 문제라 팀 문서에 맞지 않음)까지 표로 정리했습니다. 한 번에 0.41달러어치였습니다. 한 번에 묻고 끝내는 방식(claude -p)으로 보낼 때는 짧은 이름 /revise-claude-md가 오류를 냈고, 정식 이름 /claude-md-management:revise-claude-md로 보내야 돌았습니다.

오래 작업한 대화 끝에 쓰면 쓸모가 더 큽니다. 다만 이번에는 그런 대화로 시험하지 않았습니다.

이런 사람에게 권합니다

• ✅ 여러 프로젝트의 CLAUDE.md를 같은 기준으로 정기 점검하려는 사람. 매번 같은 6개 항목으로 점수를 매겨 주니 어느 파일부터 손볼지 고르기 쉽습니다.
• ✅ 한 저장소에 CLAUDE.md가 여러 개인 사람(폴더마다 둔 경우). 스킬 문서에 따르면 첫 단계에서 모든 CLAUDE.md를 찾아 하나씩 평가합니다(이번 예제는 파일 하나라 시험하지 않았습니다).
• ❌ CLAUDE.md 하나를 가끔 손보는 사람. 이번에는 “점검하고 고쳐 줘”라는 요청만으로 결과가 같았고, 사용량은 조금 적었습니다.

한계와 주의할 점

• 노드 프로젝트 하나, 문제를 일부러 심은 CLAUDE.md 하나로만 시험했습니다. 큰 저장소나 폴더별 CLAUDE.md에서는 결과가 다를 수 있습니다.
• 조건마다 두세 번씩만 돌렸습니다. 시간·사용량 차이는 참고용입니다.
• 점수는 Claude가 채점표를 보고 매기는 값이라 실행마다 조금씩 다를 수 있습니다. 같은 파일을 두 번 매긴 이번에는 둘 다 25점 안팎이었습니다.
• 스킬 문서는 개인용 파일을 .claude.local.md라는 이름으로 찾습니다. 공식 문서의 이름은 CLAUDE.local.md라서, 스킬 문서에 적힌 찾기 명령으로는 이 파일이 안 잡힐 수 있습니다(문서 기준, 이번 예제에는 개인용 파일이 없어 시험하지 않았습니다).
• 고친 파일은 꼭 직접 읽어 보세요. 이번 다섯 번은 지어낸 명령이 없었지만, 배포 방법처럼 코드에 근거가 없는 항목을 지울지 남길지는 실행마다 달랐습니다.

대안

방법	다른 점	이럴 때 고르세요
claude-md-management(이 글)	6개 항목 점수 + 고치기, 대화 끝에 배운 것 보태기	여러 CLAUDE.md를 같은 기준으로 관리할 때
플러그인 없이 “점검하고 고쳐 줘”	점수 없이 바로 고침, 결과 파일이 조금 짧음	CLAUDE.md 하나를 가끔 손볼 때
/doctor prompt-audit	기본 명령. 보고서와 수정안만, 개인 설정 문서까지 검사	고치기 전에 보고서를 받아 직접 고를 때
/init 명령	기본 명령. 코드를 읽어 CLAUDE.md를 만들고, 이미 있으면 덮어쓰지 않고 개선을 제안(공식 문서 기준, 이번에 시험하지 않음)	CLAUDE.md가 아직 없을 때
hookify 플러그인	CLAUDE.md 같은 말로 된 규칙 대신 훅으로 실제로 막음	“이 명령은 절대 안 돼”처럼 꼭 지켜야 할 규칙일 때

자주 묻는 질문

claude-md-management는 무료인가요?

플러그인 자체는 무료(Apache-2.0)입니다. 점검할 때 Claude 사용량이 들고, 이번에는 한 번에 API 단가로 0.4달러 안팎이었습니다. 구독 요금제라면 그만큼 사용량 한도에서 빠집니다.

스킬을 직접 불러야 하나요?

아닙니다. “CLAUDE.md 점검해 줘”, “CLAUDE.md 고쳐 줘”처럼 한국어로 보내도 세 번 모두 스킬이 저절로 불렸습니다. 직접 부르려면 /claude-md-management:claude-md-improver를 입력합니다.

CLAUDE.md를 고친 뒤 클로드 코드를 다시 켜야 하나요?

공식 메모리 문서에 따르면 CLAUDE.md는 대화를 시작할 때 읽습니다. 고친 내용을 확실히 반영하려면 새 대화를 여세요.

팀이 같이 쓰는 CLAUDE.md도 고쳐도 되나요?

고친 파일은 git 변경으로 남으니 커밋 전에 바뀐 부분을 확인하면 됩니다. 이번 다섯 번도 커밋은 하지 않고 “커밋은 하지 않았다”고 알렸습니다. 나만 쓰는 설정은 공식 문서대로 프로젝트 맨 위 CLAUDE.local.md에 두고 .gitignore에 넣으세요.

출처

claude-md-management 플러그인 README·스킬·명령 문서, anthropics/claude-plugins-official 저장소, 클로드 코드 메모리(CLAUDE.md) 문서, 클로드 코드 플러그인 문서 (모두 2026-10-15 확인, 저장소 별 38,350개)