sam-react-prod/claudedocs/dev/[PLAN-2026-02-03] claude-config-optimization.md

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에 타입 에러 피드백 → 자동 수정 시도