rungchan2 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)
필수 섹션 순서
- Header - 프로젝트명 + 1-2문장 설명
- Technical Stack & Conventions - 프레임워크, UI, 상태관리
- Path Aliases -
@/경로 매핑 - Database Schema Overview - 테이블 요약 + 주의사항
- Critical Development Rules - ✅/❌ 패턴
- Architecture Patterns - 레이어 다이어그램
- Workflow Notes - 작업 전 체크리스트
- NOT TO DOs - 금지 사항 목록
- 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 품질 검증 질문:
- "**[자주 틀리는 필드명]**의 올바른 이름은?" → 즉시 답변 가능해야 함
- "Supabase 쿼리는 어디에 작성해야 하나요?" → 정확한 경로 응답
- "사용자 권한은 어떻게 확인하나요?" → 정확한 패턴 응답
- "**[타입명]**은 어디서 import하나요?" → 정확한 경로 응답
성공 기준: 코드베이스 탐색 없이 CLAUDE.md만으로 정확한 답변
유지보수 체크리스트
## 업데이트 트리거
- [ ] 같은 패턴 3회 이상 위반 시
- [ ] 새 아키텍처 결정 시
- [ ] 데이터베이스 스키마 변경 시
- [ ] 새 규칙/패턴 확립 시
## 버전 추적
**Last Updated**: YYYY-MM-DD
**Major Changes**:
- YYYY-MM-DD: [변경 사항] due to [이유]
Quick Reference
필수 포함 항목 ✅
- 자주 발생하는 실수 (필드명 오류)
- 비직관적인 컨벤션 (파일 명명 규칙)
- 아키텍처 가드레일 (레이어 분리)
- 타입 시스템 패턴 (중앙화된 import)
- 도메인별 규칙 (역할 계층)
제외 항목 ❌
- 일반 언어 문서 (Claude는 JS/TS 알고 있음)
- 라이브러리 API 레퍼런스
- 자주 변경되는 코드
- 당연한 베스트 프랙티스
- 기능 백로그 (이슈 트래커 사용)
Resources
references/
- guide.md - CLAUDE.md 구현 전체 가이드
- template.md - 복사 가능한 템플릿
- patterns.md - 고급 디자인 패턴 모음