refactoring

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'