# Claude 설정 최적화 계획

**날짜**: 2026-02-03
**목적**: 토큰 효율성 개선 + 규칙 분리 + 자동화 강화

---

## 배경 (왜 이 작업을 하는가?)

### 문제 발견
- `~/.claude/` 에 **16개 MD 파일 (3,549줄, ~119KB)** 가 매 대화마다 전부 로드됨
- SAM 프로젝트 전용 규칙이 글로벌에 있어 다른 프로젝트에도 불필요하게 전파
- 비즈니스 분석용 파일(BUSINESS_PANEL, RESEARCH_CONFIG 등)이 일상 개발에도 로드
- type-check 같은 프로세스가 MD 규칙으로만 존재 → 강제성 없음

### 기대 효과
- 매 대화 토큰 사용량 감소 (불필요한 ~1,500줄 절약)
- SAM 규칙과 범용 규칙의 명확한 분리
- type-check 자동화로 실수 방지 강화

---

## 작업 계획

### 1단계: 프로젝트 CLAUDE.md 분리
**상태**: 🔄 진행 중

**작업 내용**:
- `~/.claude/RULES.md`에서 SAM 전용 규칙 추출
- 프로젝트 루트에 `CLAUDE.md` 생성 (SAM 전용 규칙)
- 글로벌 `RULES.md`는 범용 규칙만 남김

**SAM 전용으로 분류된 규칙들** (프로젝트 CLAUDE.md로 이동):
| 섹션 | 이유 |
|------|------|
| Common Table Standards | SAM ERP 테이블 패턴 |
| Document Table Merging | SAM 성적서/보고서 전용 |
| Page Layout Standards | SAM AuthenticatedLayout 구조 |
| Design Popup Policy | SAM Radix UI 스택 |
| Build Policy | SAM 빌드 정책 |
| Client Component 사용 원칙 | SAM 폐쇄형 ERP 특성 |
| SAM Project Structure | SAM 경로 구조 |
| Backend API Analysis Policy | SAM 백엔드 연동 |
| Test URL Documentation Rules | SAM 테스트 URL |
| User Environment Knowledge | 사용자 환경 특화 |
| HttpOnly Cookie API Communication | SAM 인증 패턴 |
| Radix UI Select Bug | SAM 기술 스택 이슈 |
| React → Next.js Migration | SAM 마이그레이션 |
| Large File Migration Workflow | SAM 마이그레이션 |
| Component Pattern Reuse | SAM 컴포넌트 패턴 |
| 기획서/스크린샷 기반 UI 구현 | SAM 기획서 프로세스 |

**글로벌에 남는 규칙들** (범용):
| 섹션 | 이유 |
|------|------|
| Priority System | 모든 프로젝트 공통 |
| Scope Discipline (일반 부분) | 모든 프로젝트 공통 |
| Implementation Completeness | 모든 프로젝트 공통 |
| Failure Investigation | 모든 프로젝트 공통 |
| Professional Honesty | 모든 프로젝트 공통 |
| Safety Rules | 모든 프로젝트 공통 |
| Workflow & Session | 모든 프로젝트 공통 |
| File & Code Organization | 모든 프로젝트 공통 |
| Workspace Hygiene | 모든 프로젝트 공통 |
| Git Rules | 모든 프로젝트 공통 |
| Claude-Specific Rules | 모든 프로젝트 공통 |
| Quick Reference | 모든 프로젝트 공통 |

---

### 2단계: 가끔 쓰는 MD 파일 임포트 해제
**상태**: ⏳ 대기

**작업 내용**:
- `~/.claude/CLAUDE.md`에서 `@` 임포트 줄 제거 (파일 자체는 유지)

**제거 대상 임포트** (일상 SAM 개발에 불필요):
| 파일 | 줄 수 | 용도 |
|------|-------|------|
| @BUSINESS_PANEL_EXAMPLES.md | 278줄 | /sc:business-panel 전용 |
| @BUSINESS_SYMBOLS.md | 211줄 | /sc:business-panel 전용 |
| @MODE_Business_Panel.md | 334줄 | /sc:business-panel 전용 |
| @RESEARCH_CONFIG.md | 445줄 | /sc:research 전용 |
| @MODE_DeepResearch.md | 57줄 | /sc:research 전용 |
| @MODE_Brainstorming.md | 43줄 | 가끔 사용 |
| @MODE_Introspection.md | 38줄 | 거의 안 씀 |
| @MODE_Token_Efficiency.md | 74줄 | 컨텍스트 압박 시만 |
| **합계** | **~1,480줄** | **절약** |

**유지 대상 임포트**:
| 파일 | 이유 |
|------|------|
| @PRINCIPLES.md | 핵심 엔지니어링 원칙 |
| @RULES.md | 범용 행동 규칙 |
| @GIT_POLICY.md | Git 워크플로우 |
| @FLAGS.md | 모드 활성화 플래그 |
| @MODE_Task_Management.md | 멀티스텝 작업 관리 |
| @MODE_Orchestration.md | 도구 선택 최적화 |

---

### 3단계: Hooks 추가
**상태**: ⏳ 대기

**작업 내용**:
- `.claude/settings.local.json`에 PostToolUse hook 추가
- Write/Edit 후 자동 `npx tsc --noEmit` 실행

---

### 4단계: 중복 제거
**상태**: ⏳ 대기

**작업 내용**:
- RULES.md의 "Git Rules" 섹션과 GIT_POLICY.md 간 중복 정리
- RULES.md에는 "git 올려줘" 단축 명령 + 기본 원칙만 남김
- 상세 브랜치 전략/커밋 규칙은 GIT_POLICY.md로 통합
- COMPLEX_TASK_PROTOCOL.md는 RULES.md의 Checklist-Driven Development와 중복 → 정리

---

## 진행 기록

| 단계 | 상태 | 완료일 | 비고 |
|------|------|--------|------|
| 1단계: 프로젝트 CLAUDE.md 분리 | ✅ | 2026-02-03 | SAM 전용 16개 섹션 이동 |
| 2단계: MD 임포트 해제 | ✅ | 2026-02-03 | 9개 파일 임포트 해제 (~1,759줄) |
| 3단계: Hooks 추가 | ✅ | 2026-02-03 | PostToolUse typecheck hook |
| 4단계: 중복 제거 | ✅ | 2026-02-03 | GIT_POLICY.md에서 87줄 중복 제거 |

---

## 최종 결과

### 토큰 절약 수치
```
변경 전: 3,549줄 (전부 글로벌, 매 대화 로드)
변경 후: 1,193줄 (글로벌 916 + 프로젝트 277)
절약량:  2,356줄 (~66% 감소)
```

### 다른 프로젝트에서의 효과
```
변경 전: 3,549줄 (SAM 규칙 포함)
변경 후:   916줄 (범용 규칙만)
절약량:  2,633줄 (~74% 감소)
```

### 변경된 파일 목록
| 파일 | 작업 |
|------|------|
| `프로젝트/CLAUDE.md` | 신규 생성 (SAM 전용 규칙) |
| `~/.claude/CLAUDE.md` | 임포트 9개 해제 |
| `~/.claude/RULES.md` | SAM 규칙 제거 (1017→258줄) |
| `~/.claude/GIT_POLICY.md` | 중복 섹션 제거 (394→307줄) |
| `.claude/hooks/typecheck-after-edit.sh` | 신규 생성 |
| `.claude/settings.local.json` | hooks 설정 추가 |

### Hook 동작 방식
- **트리거**: Write/Edit 도구 사용 후
- **대상**: .ts/.tsx 파일만
- **실행**: `npx tsc --noEmit` (30초 타임아웃)
- **에러 시**: Claude에 타입 에러 피드백 → 자동 수정 시도