> AI_Lab
CLAUDE.md도 리팩토링이 필요하다
Claude Code를 쓰다 보면 프로젝트 루트에 CLAUDE.md라는 파일을 하나씩 두게 됩니다. 빌드 명령어, 아키텍처 개요, 코딩 컨벤션 같은 걸 적어두면 세션을 새로 열 때마다 Claude가 그걸 읽고 시작하는 구조입니다. 문제는 이 파일이 딱 처음 만들 때만 정성을 들이고, 그 뒤로는 잘 안 들여다본다는 점입니다. 코드는 계속 바뀌는데 설명서는 그 자리에 멈춰 있으니 시간이 지날수록 둘 사이 거리가 벌어집니다.
그러다 GitHub에서 claude-md-management라는 공식 플러그인을 보게 됐습니다. 이름 그대로 CLAUDE.md 자체를 관리해주는 도구입니다.
스킬 하나, 커맨드 하나
플러그인 구성은 단순합니다.
claude-md-improver (스킬) | /revise-claude-md (커맨드) | |
|---|---|---|
| 목적 | CLAUDE.md를 코드 현재 상태와 맞추기 | 이번 세션에서 배운 걸 기록하기 |
| 트리거 | 코드베이스가 바뀌었을 때 | 세션 끝에 |
| 쓰는 시점 | 주기적인 점검 | 세션 중 뭔가 문서에 없어서 헤맸을 때 |
전자는 “지금 문서가 코드랑 맞는지” 감사하는 쪽이고, 후자는 “이번에 겪은 시행착오를 다음 세션을 위해 남겨두는” 쪽입니다. 둘이 서로 반대 방향으로 CLAUDE.md를 갱신하는 셈입니다.
마켓플레이스를 추가하고 플러그인을 설치하는 두 단계입니다.
/plugin marketplace add anthropics/claude-plugins-official
/plugin install claude-md-management감사는 6개 기준으로
설치 후 스킬을 실제 프로젝트의 CLAUDE.md에 돌려보면 다음 순서로 진행됩니다.
- 탐색: 저장소 안의
CLAUDE.md,.claude.local.md등을 전부 찾습니다. - 평가: 각 파일을 6개 기준(커맨드/워크플로, 아키텍처 명확성, 비직관적 패턴, 간결성, 최신성, 실행 가능성)으로 채점합니다. 배점은 20/20/15/15/15/15로 총 100점이고, A~F 등급이 매겨집니다.
- 리포트 출력: 점수와 근거를 먼저 보여줍니다. 이 단계에서는 아직 아무것도 고치지 않습니다.
- 개선안 제시: 파일을 실제로 고치기 전에, 어떤 줄을 왜 추가·수정하는지 diff 형태로 먼저 보여줍니다.
- 승인 후 반영: 사용자가 승인한 항목만 Edit으로 실제 반영합니다.
여기서 특별한 부분은 3번과 4번 사이에 항상 사람의 승인을 끼워 넣는다는 겁니다. 점수만 매기고 끝내는 게 아니라, “이걸 왜 바꾸는지”를 근거와 함께 먼저 보여주고 나서야 파일에 손을 댑니다.
실제로 돌려본 결과
제 프로젝트 CLAUDE.md에 돌려봤더니 이런 리포트가 나왔습니다.
Score: 71/100 (Grade: B)
| Criterion | Score | Notes |
|---|---|---|
| Commands/workflows | 12/20 | 검증 루프(compile→lint→test) 태스크명은 있지만 ./gradlew 접두사, 앱 실행/설치 명령, 단일 테스트 실행법 없음 |
| Architecture clarity | 18/20 | Dual DB, TimeBlock 도메인, 하네스 파이프라인 등 구조 설명이 탄탄함 |
| Non-obvious patterns | 8/15 | Realm 스레드 안전성 등 일부 있으나, 실제 코드 검증 결과 중요한 gotcha 2개가 누락됨 (아래 참조) |
| Conciseness | 14/15 | 군더더기 없이 밀도 높음 |
| Currency | 8/15 | 버전 정보 여러 개가 실제 코드와 불일치 (아래 참조) |
| Actionability | 11/15 | 대부분 실행 가능하나 ./gradlew 누락으로 바로 복붙은 안 됨 |
아키텍처 설명이나 간결성 쪽은 점수가 높았는데, 최신성과 비직관적 패턴 항목에서 감점이 컸습니다.
구체적으로는 이런 식이었습니다.
- 문서에 적힌 라이브러리·SDK 버전 정보 몇 개는 실제 빌드 설정 파일과 대조해보니 이미 몇 단계 지난 값으로 남아 있었습니다. 문서를 쓴 시점 이후로 의존성을 업그레이드하면서 CLAUDE.md는 그대로 뒀던 겁니다.
- 특정 UI 속성에 쓰는 단위 컨벤션(예: 어떤 단위를 써야 하는지)도 이전에 여러 번 지적받았던 규칙인데, 정작 CLAUDE.md에는 빠져 있었습니다.
grep 몇 번으로 이 세 가지를 다 코드와 대조해서 확인한 다음, 리포트에 근거로 붙여서 보여주고 승인을 받고 나서야 diff를 반영했습니다. 반영 후 다시 채점하니 A등급 근처까지 올라갔습니다.
느낀 점
CLAUDE.md는 매 세션 프롬프트에 그대로 실리는 파일인데도, 정작 “이게 지금도 맞는 얘기인가”를 검증하는 절차는 따로 없었습니다. 코드는 리뷰를 거치지만 코드에 대한 설명서는 아무도 리뷰하지 않는 셈입니다.
제가 이미 알고 있던 사실(로깅이 죽어 있다는 것)조차 문서화가 안 되면 아무 소용이 없다는 거였습니다. 사람의 기억 속에만 있는 지식은 그 사람이 없는 세션에서는 없는 지식과 같습니다. AI에게 프로젝트를 설명하는 문서를, 다시 AI에게 시켜서 코드와 대조하고 감사하게 한다는 발상 자체가 묘하게 재귀적이면서도 실용적이라고 느꼈습니다. 무엇보다 Anthropic에서 직접 이런 플러그인을 제시한 것이라 더 자주 사용하게 될 것 같네요.
Comments