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 평가 체크리스트

□ 필수 섹션 포함 여부
  - [ ] 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 - 전체 구현 가이드
• Template - 복사 가능한 템플릿
• Design Patterns - 고급 패턴 모음

---

Step 3: 최적화 (Optimization)

컨텍스트 압축 기법

Before (72 tokens):

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):

### Data Access - Use Service Layer

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

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

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

테이블 vs 산문

산문 (비효율적):

users.center_id 필드는 존재하지 않습니다. 대신 center_users 조인 테이블을 사용해야 합니다. 또한 students.name은 잘못된 필드명입니다. 올바른 필드명은 students.full_name입니다.

테이블 (효율적):

| ❌ 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만으로 정확한 답변

유지보수 체크리스트

## 업데이트 트리거
- [ ] 같은 패턴 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 - CLAUDE.md 구현 전체 가이드
• template.md - 복사 가능한 템플릿
• patterns.md - 고급 디자인 패턴 모음