---
name: claude-refactoring
description: "CLAUDE.md 메모리 파일 리팩토링 및 정리 스킬. 기존 CLAUDE.md 분석, 구조 개선, 컨텍스트 효율성 최적화를 수행합니다. 트리거: CLAUDE.md 리팩토링, CLAUDE.md 정리, 메모리 파일 개선, 프로젝트 가이드 최적화, CLAUDE.md 분석, 클로드 가이드 작성, CLAUDE.md 작성 도와줘."
---

# CLAUDE.md Refactoring Skill

CLAUDE.md 파일 분석, 구조화, 최적화를 통해 Claude Code의 프로젝트 이해도와 작업 효율성을 극대화합니다.

## Workflow Decision Tree

```
사용자 요청 분석
├─ 새 CLAUDE.md 작성
│   └─ 템플릿 기반 생성 → references/template.md 참조
├─ 기존 CLAUDE.md 리팩토링
│   ├─ 1단계: 현재 파일 분석
│   ├─ 2단계: 문제점 식별
│   ├─ 3단계: 구조 재설계
│   └─ 4단계: 컨텍스트 최적화
└─ CLAUDE.md 검토/평가
    └─ 품질 메트릭 기반 분석
```

---

## Step 1: 분석 (Analysis)

### 현재 CLAUDE.md 평가 체크리스트

```markdown
□ 필수 섹션 포함 여부
  - [ ] Header (프로젝트명 + 설명)
  - [ ] Technical Stack & Conventions
  - [ ] Path Aliases
  - [ ] Critical Development Rules
  - [ ] NOT TO DOs

□ 컨텍스트 효율성
  - [ ] 토큰 예산 효율적 사용
  - [ ] 중복 정보 없음
  - [ ] 코드 예제 > 장황한 설명

□ 오류 방지 패턴
  - [ ] ✅/❌ 패턴 사용
  - [ ] Common Mistakes 테이블
  - [ ] 구체적 필드명/경로명

□ 아키텍처 문서화
  - [ ] 레이어 구조 다이어그램
  - [ ] Forbidden Patterns
  - [ ] 파일/디렉토리 구조
```

### 문제점 식별 패턴

| 문제 유형 | 증상 | 해결책 |
|----------|------|--------|
| **정보 부족** | Claude가 스키마/타입을 자주 물어봄 | Database Schema 섹션 추가 |
| **모호한 규칙** | 같은 실수 반복 | ✅/❌ 코드 예제로 구체화 |
| **과도한 정보** | 토큰 낭비, 핵심 놓침 | 테이블/코드로 압축 |
| **구조 혼란** | 필요 정보 찾기 어려움 | 섹션 재구성, 목차 추가 |

---

## Step 2: 구조화 (Structure)

### 필수 섹션 순서

1. **Header** - 프로젝트명 + 1-2문장 설명
2. **Technical Stack & Conventions** - 프레임워크, UI, 상태관리
3. **Path Aliases** - `@/` 경로 매핑
4. **Database Schema Overview** - 테이블 요약 + 주의사항
5. **Critical Development Rules** - ✅/❌ 패턴
6. **Architecture Patterns** - 레이어 다이어그램
7. **Workflow Notes** - 작업 전 체크리스트
8. **NOT TO DOs** - 금지 사항 목록
9. **Reference Documentation** - 상세 문서 링크

### 상세 가이드

- **[Implementation Guide](references/guide.md)** - 전체 구현 가이드
- **[Template](references/template.md)** - 복사 가능한 템플릿
- **[Design Patterns](references/patterns.md)** - 고급 패턴 모음

---

## Step 3: 최적화 (Optimization)

### 컨텍스트 압축 기법

**Before (72 tokens):**
```markdown
When you need to get students from the database, you should always use the service layer functions that are located in the /lib/services directory. Never import the Supabase client directly into your components.
```

**After (28 tokens):**
```markdown
### Data Access - Use Service Layer

// ✅ CORRECT
import { getStudents } from '@/lib/services/students'

// ❌ WRONG
import { createClient } from '@/lib/supabase/client'
```

**61% 토큰 절감, 정보 밀도 증가**

### 테이블 vs 산문

**산문 (비효율적):**
```markdown
users.center_id 필드는 존재하지 않습니다. 대신 center_users 조인 테이블을 사용해야 합니다. 또한 students.name은 잘못된 필드명입니다. 올바른 필드명은 students.full_name입니다.
```

**테이블 (효율적):**
```markdown
| ❌ Mistake | ✅ Correct |
|------------|-----------|
| `users.center_id` | `center_users` junction table |
| `students.name` | `students.full_name` |
```

---

## Step 4: 검증 (Validation)

### 품질 메트릭

CLAUDE.md 품질 검증 질문:

1. "**[자주 틀리는 필드명]**의 올바른 이름은?" → 즉시 답변 가능해야 함
2. "Supabase 쿼리는 어디에 작성해야 하나요?" → 정확한 경로 응답
3. "사용자 권한은 어떻게 확인하나요?" → 정확한 패턴 응답
4. "**[타입명]**은 어디서 import하나요?" → 정확한 경로 응답

**성공 기준:** 코드베이스 탐색 없이 CLAUDE.md만으로 정확한 답변

### 유지보수 체크리스트

```markdown
## 업데이트 트리거
- [ ] 같은 패턴 3회 이상 위반 시
- [ ] 새 아키텍처 결정 시
- [ ] 데이터베이스 스키마 변경 시
- [ ] 새 규칙/패턴 확립 시

## 버전 추적
**Last Updated**: YYYY-MM-DD
**Major Changes**:
- YYYY-MM-DD: [변경 사항] due to [이유]
```

---

## Quick Reference

### 필수 포함 항목 ✅
1. 자주 발생하는 실수 (필드명 오류)
2. 비직관적인 컨벤션 (파일 명명 규칙)
3. 아키텍처 가드레일 (레이어 분리)
4. 타입 시스템 패턴 (중앙화된 import)
5. 도메인별 규칙 (역할 계층)

### 제외 항목 ❌
1. 일반 언어 문서 (Claude는 JS/TS 알고 있음)
2. 라이브러리 API 레퍼런스
3. 자주 변경되는 코드
4. 당연한 베스트 프랙티스
5. 기능 백로그 (이슈 트래커 사용)

---

## Resources

### references/
- **[guide.md](references/guide.md)** - CLAUDE.md 구현 전체 가이드
- **[template.md](references/template.md)** - 복사 가능한 템플릿
- **[patterns.md](references/patterns.md)** - 고급 디자인 패턴 모음