elle510/claudemd-review

Skill: CLAUDE.md 리뷰

발동 조건

사용자가 다음을 요청할 때 이 skill을 사용:

• "CLAUDE.md 검토해줘 / 확인해줘 / 리뷰해줘"
• "CLAUDE.md 원칙 지키고 있는지 체크해줘"
• /claudemd-review

체크 원칙 (Claude Code 공식 문서 기준)

원칙 1: 크기

• 파일당 200줄 이하 권장
• 초과 시 @path import 또는 .claude/rules/ 파일 분리 권장

원칙 2: 구체성

검증 가능한 수준으로 구체적이어야 함:

| ❌ 모호 | ✅ 구체 | | -------------------- | ------------------------------------ | | "코드를 깔끔하게 써" | "2칸 들여쓰기 사용" | | "변경사항 테스트해" | "커밋 전 npm test 실행" | | "파일을 잘 정리해" | "API 핸들러는 src/api/handlers/에" |

원칙 3: 비자명성

• Claude가 코드에서 스스로 추론할 수 있는 내용은 제외
• 일반적인 모범사례(clean code, SOLID 등) 제외
• 넣어야 할 것: 비자명한 제약, 버전 고정 이유, 프로젝트별 컨벤션, 금지 행동

원칙 4: 일관성

• 같은 주제에 대해 서로 모순되는 지시가 없어야 함
• 여러 CLAUDE.md 파일 간 충돌 없어야 함

원칙 5: 계층 적합성

| 위치 | 담아야 할 내용 | | --------------------- | ------------------------------------------------ | | 루트 CLAUDE.md | 전체 프로젝트 공통 (패키지 매니저, 버전 제약 등) | | 패키지/앱 CLAUDE.md | 해당 패키지에만 적용되는 규칙 | | ~/.claude/CLAUDE.md | 개인 선호도 (팀 공유 불필요한 것) |

원칙 6: @ 참조 활용

• 관련 파일은 텍스트 설명 대신 @path/to/file 문법으로 직접 연결
• 상세 규칙은 .claude/rules/ 파일로 분리 후 참조

리뷰 절차

1단계: 파일 목록 수집

프로젝트 내 모든 CLAUDE.md 파일을 찾는다.

2단계: 각 파일 검토

각 파일에 대해 6가지 원칙을 순서대로 체크한다.

3단계: 결과 출력

아래 형식으로 출력한다:

## CLAUDE.md 리뷰 결과

### 파일: {경로}
- 줄 수: N줄 (✅ / ⚠️ 200줄 초과)

#### ✅ 원칙 준수
- ...

#### 🚫 위반
1. [원칙명] 문제 설명
   해결: 구체적인 수정 방법

#### ⚠️ 개선 권장
- ...

---

### 총평
위반 N건 / 권장 N건

자동 수정 여부

• 내용 수정 (모호한 표현 → 구체적 표현): 사용자 확인 후 자동 수정 가능
• 파일 분리 (.claude/rules/ 이동): 계획 먼저 제시 후 사용자 승인
• @ 참조 변환: 사용자 확인 후 자동 수정 가능

Gotchas

• 전체 프로젝트 스캔 필수: 루트 CLAUDE.md만 보지 말고 모든 패키지/앱의 CLAUDE.md를 찾아서 검토한다.
• 위반 vs 권장 구분: 명백한 원칙 위반은 🚫, 개선하면 좋은 수준은 ⚠️로 구분한다. 둘을 섞으면 우선순위가 불명확해진다.
• 자동 수정 전 확인 필수: 파일 분리처럼 구조를 바꾸는 작업은 반드시 사용자 승인 후 실행한다.