UX 개발 / Claude Code

Claude Code의 CLAUDE.md를 관리하는 claude-md-management 실전 가이드

Claude CodeCLAUDE.mdclaude-md-managementClaude PluginProject MemoryAI CodingDeveloper Workflow

CLAUDE.md는 Claude Code가 프로젝트를 이해하는 데 사용하는 상시 지침 파일이다. 빌드 명령, 테스트 방법, 아키텍처, 팀 규칙을 적어두면 매 세션마다 같은 설명을 반복하지 않아도 된다. 문제는 코드가 계속 바뀌는 동안 이 문서만 오래된 상태로 남기 쉽다는 점이다.

claude-md-management는 이 문제를 줄이기 위한 Anthropic 공식 플러그인이다. 현재 공식 저장소 기준으로 코드베이스와 문서의 불일치를 감사하는 skill과 현재 세션에서 발견한 지식을 문서에 반영하는 command를 함께 제공한다. 둘 다 파일을 바로 고치지 않고 먼저 보고서나 diff를 보여준 뒤 사용자의 승인을 받는다.

이 글은 2026년 8월 6일 기준 공식 플러그인 소스, Claude Code 플러그인 설치 문서, CLAUDE.md 메모리 문서를 확인해 작성했다.

한눈에 보는 두 가지 도구

도구역할사용 시점결과
claude-md-improver skill현재 코드베이스와 CLAUDE.md 비교구조 변경 후, 정기 점검 전품질 점수, 문제 목록, 개선안
revise-claude-md command현재 세션의 반복 가능한 학습 추출작업을 마치기 직전추가 제안과 승인용 diff

간단히 말하면 claude-md-improver는 정기 건강검진, revise-claude-md는 작업 종료 전 회고에 가깝다. 플러그인이 백그라운드에서 자동 실행되는 것은 아니다. 자연어로 감사를 요청하거나 namespaced command를 직접 실행해야 한다.

설치하기

Claude Code를 대화형으로 한 번 실행했다면 공식 마켓플레이스인 claude-plugins-official은 보통 자동 등록되어 있다. Claude Code 안에서 다음 명령을 실행한다.

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

터미널에서 비대화형으로 설치하려면 다음 명령을 사용할 수 있다. 기본 설치 범위는 사용자 전체 프로젝트에서 쓰는 user다.

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

플러그인을 찾지 못한다면 마켓플레이스를 추가하거나 새로고침한 뒤 다시 설치한다.

/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace update claude-plugins-official
/plugin install claude-md-management@claude-plugins-official

설치 결과에 재로딩 안내가 나오면 다음 명령을 실행한다.

/reload-plugins

/plugin list에서 설치 상태를 확인하고, /help에서 claude-md-management: namespace가 보이는지 확인하면 준비가 끝난다.

활용법 1: CLAUDE.md 전체 감사하기

코드베이스 구조나 빌드 과정이 달라졌다면 다음처럼 자연어로 요청할 수 있다.

Audit my CLAUDE.md files against the current codebase.
Show the quality report and proposed diffs, but do not edit anything until I approve.

명시적으로 skill을 실행하려면 다음 namespaced command를 사용한다.

/claude-md-management:claude-md-improver

공식 skill은 먼저 저장소 안의 CLAUDE.md 파일들을 찾고, 실제 코드와 비교해 다음 여섯 항목을 평가한다.

평가 항목배점확인하는 내용
Commands/workflows20빌드·테스트·lint·개발 명령이 실제로 유효한가
Architecture clarity20주요 디렉터리, 진입점, 모듈 관계가 설명되어 있는가
Non-obvious patterns15함정, 우회법, 특수한 이유가 기록되어 있는가
Conciseness15당연한 설명과 중복 없이 밀도 있게 쓰였는가
Currency15경로, 기술 스택, 명령이 현재 상태와 일치하는가
Actionability15지침과 명령을 그대로 실행할 수 있는가

총점에 따라 A부터 F까지 등급을 표시하고, 파일별 문제와 권장 추가 사항을 정리한다. 그 다음에만 변경 diff를 제시하고 승인을 요청한다.

감사 결과를 검토하는 방법

점수를 올리는 것 자체보다 제안이 실제 프로젝트에 맞는지 확인하는 일이 중요하다.

  • 제시된 명령을 로컬에서 직접 실행할 수 있는가?
  • 삭제되거나 이동한 경로가 남아 있지 않은가?
  • 코드에서 쉽게 알 수 있는 내용을 장황하게 복사하지 않았는가?
  • 일회성 장애 대응을 영구 규칙으로 만들고 있지 않은가?
  • 팀 공통 규칙과 개인 설정이 섞이지 않았는가?

품질 점수는 테스트 결과가 아니라 플러그인의 휴리스틱 평가다. 점수가 높더라도 잘못된 명령이 하나 들어가면 다음 세션을 계속 잘못된 방향으로 이끌 수 있으므로 diff 리뷰는 생략하지 않는다.

활용법 2: 세션 학습을 바로 반영하기

작업 중에 숨겨진 전제나 반복될 만한 해결법을 발견했다면 세션이 끝나기 전에 다음 command를 실행한다.

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

이 command는 현재 대화를 돌아보며 다음 정보를 찾는다.

  • 새로 발견한 build, test, lint 명령
  • 실제로 사용한 코드 스타일이나 패턴
  • 성공한 테스트 방법과 필요한 선행 조건
  • 환경변수나 로컬 설정의 특이점
  • 다음 세션에서도 마주칠 가능성이 큰 함정

좋은 추가 제안은 짧고 재사용 가능하다.

## Testing
+ `npm run test:integration` requires Docker and a local Redis on port 6379.

반대로 다음과 같은 내용은 넣지 않는 편이 좋다.

- Today we fixed a difficult Redis problem after trying several approaches.
- Always write clean code and follow best practices.

첫 문장은 한 번의 작업 일지에 가깝고, 두 번째 문장은 구체적인 행동을 정하지 못한다. CLAUDE.md에는 다음 세션이 즉시 사용할 수 있는 명령, 경로, 제약, 이유만 남긴다.

가장 실용적인 운영 루틴

새 프로젝트

  1. Claude Code의 /init으로 초안 CLAUDE.md를 만든다.
  2. 사람이 프로젝트 목적, 금지 사항, 배포 제약을 보완한다.
  3. claude-md-improver로 실제 코드와 초안을 비교한다.
  4. 필요한 제안만 승인하고 git diff -- CLAUDE.md로 최종 검토한다.

일반 개발 세션

  1. 평소처럼 기능 구현이나 버그 수정을 진행한다.
  2. 재사용 가능한 명령이나 함정을 발견했는지 판단한다.
  3. 발견했다면 종료 전에 revise-claude-md를 실행한다.
  4. 한 줄로 줄일 수 있고 다시 발생할 내용만 승인한다.

구조 변경이나 릴리스 전

  1. package script, 디렉터리, 테스트 환경의 변경을 마친다.
  2. 전체 CLAUDE.md 감사를 실행한다.
  3. 제안된 명령을 실제로 검증한다.
  4. 코드 변경과 문서 변경을 같은 PR에서 리뷰한다.

규모가 작은 팀은 큰 구조 변경 뒤와 월 1회 정도 전체 감사를 하고, 중요한 학습이 생긴 세션에서만 revise-claude-md를 실행하는 것으로 충분하다. 매 세션마다 억지로 업데이트하면 문서가 작업 일지처럼 비대해진다.

CLAUDE.md에는 무엇을 남겨야 할까?

남기기 좋은 정보다른 곳이 더 적합한 정보
실제 build·test·lint 명령README에 이미 충분히 설명된 설치 튜토리얼
기본값과 다른 프로젝트 규칙일반적인 언어·프레임워크 상식
위험한 작업과 필수 승인 절차한 번만 발생한 오류의 긴 해결 과정
코드만 보고 알기 어려운 아키텍처 이유상세 API 명세와 전체 데이터 모델
반복되는 환경·테스트 함정개인 URL, 개인 테스트 계정, 비밀 값

개인 프로젝트 설정은 Git에 올리지 않는 CLAUDE.local.md에, 파일 경로별 규칙은 .claude/rules/에, 길고 반복 가능한 절차는 skill에 두는 편이 낫다. 반드시 특정 시점에 실행되어야 하는 검사나 차단은 지침이 아니라 hook으로 구현한다.

또한 @docs/testing.md처럼 파일을 import하면 문서를 나누어 관리하기는 편하지만, import된 내용도 시작 시 함께 로드되므로 context 비용을 줄이지는 않는다. 큰 저장소라면 하위 디렉터리의 CLAUDE.md나 path-scoped rules를 사용해 필요한 시점에만 규칙을 불러오는 편이 효과적이다.

꼭 알아둘 제한과 주의점

1. 문서는 강제 정책이 아니다

Claude Code 공식 문서에 따르면 CLAUDE.md는 system prompt가 아니라 사용자 context로 전달된다. 구체적이고 짧을수록 잘 따르지만, 실행을 100% 보장하지 않는다. 배포 전 검사처럼 반드시 실행되어야 하는 규칙은 hook이나 CI로 강제한다.

2. 너무 긴 CLAUDE.md는 오히려 불리하다

Root CLAUDE.md는 세션 시작과 compaction 이후 다시 읽힌다. 공식 가이드는 200줄 아래를 권장하며, 긴 파일은 context를 더 사용하고 지침 준수율을 낮출 수 있다고 설명한다. 플러그인 제안도 추가만 승인하지 말고 중복과 오래된 항목을 함께 제거해야 한다.

3. 로컬 파일명 표기를 직접 확인한다

현재 claude-md-management 1.0.0 소스는 일부 검색 예시에서 .claude.local.md라는 소문자 점 파일을 사용한다. 그러나 최신 Claude Code 공식 문서가 정의하는 로컬 프로젝트 지침 파일은 CLAUDE.local.md다. 로컬 지침을 관리할 때는 공식 파일명을 사용하고 /context의 Memory files 목록에서 실제 로드 여부를 확인한다.

4. 비밀 값은 기록하지 않는다

CLAUDE.md는 보통 Git으로 팀과 공유된다. API 키, 토큰, 실제 고객 데이터, 개인용 URL은 넣지 않는다. 로컬 파일에도 Secret 자체보다 환경변수 이름과 설정 방법만 기록하는 편이 안전하다.

문제가 생겼을 때 확인할 것

증상확인 방법
/plugin 명령이 없음claude --version 확인 후 Claude Code 업데이트
플러그인을 찾지 못함공식 marketplace를 추가하거나 update 후 재설치
설치했지만 command가 안 보임/reload-plugins, /plugin list, /help 순서로 확인
CLAUDE.md를 따르지 않음/context에서 Memory files 로드 여부와 충돌 지침 확인
제안이 너무 많음반복 가능성, 프로젝트 특수성, 실행 가능성을 기준으로 거절

최종 체크리스트

  • 공식 claude-plugins-official marketplace에서 설치했다.
  • 전체 점검은 claude-md-improver, 세션 회고는 revise-claude-md로 구분한다.
  • 보고서와 diff를 읽은 뒤 필요한 변경만 승인한다.
  • 새로 적는 명령과 경로를 실제 코드베이스에서 검증한다.
  • 팀 규칙, 개인 설정, path-scoped rules, skills, hooks를 역할별로 나눈다.
  • CLAUDE.md를 짧고 프로젝트 특화된 상태로 유지한다.
  • CLAUDE.local.md가 /context에 실제로 로드되는지 확인한다.
  • 비밀 값과 일회성 작업 일지는 기록하지 않는다.

claude-md-management의 가장 큰 장점은 문서를 대신 써주는 데 있지 않다. 코드가 바뀐 뒤 문서를 다시 살펴보는 계기와, 세션에서 얻은 지식을 검토 가능한 diff로 남기는 습관을 만들어 준다는 점이 핵심이다.

Related