---
name: claudemd-review
description: 사용자가 CLAUDE.md 파일 검토/확인/리뷰를 요청할 때, 또는 /claudemd-review를 입력할 때 사용한다. Claude Code 공식 원칙 6가지 기준으로 프로젝트 내 모든 CLAUDE.md를 감사한다.
---

# 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 권장 구분**: 명백한 원칙 위반은 🚫, 개선하면 좋은 수준은 ⚠️로 구분한다. 둘을 섞으면 우선순위가 불명확해진다.
- **자동 수정 전 확인 필수**: 파일 분리처럼 구조를 바꾸는 작업은 반드시 사용자 승인 후 실행한다.