CLAUDE.md Slimming Plan
### 파일별 줄 수 (2026-04-01 기준)
guide docs/guide/CLAUDE_SLIMMING_PLAN.md
목표: 글로벌 CLAUDE.md 1,308줄 → 150줄 이하 (핵심 규칙만 인라인, 나머지 Skills로 분리)
현황 분석
파일별 줄 수 (2026-04-01 기준)
| 파일 | 줄 수 | 성격 | 처리 방향 |
|---|---|---|---|
| 00-identity.md | 51 | 항상 필요 (우선순위, 언어, 레이블) | 핵심 10줄만 인라인 |
| 01-git.md | 89 | CRITICAL 금지 목록 필수 | 금지 명령어만 인라인, 상세 → skill |
| 02-code.md | 60 | Hard Ban 목록 필수 | Ban 목록만 인라인 |
| 03-security.md | 44 | 보안 필수 — 짧아서 전체 인라인 가능 | 전체 인라인 (44줄) |
| 04-workflow.md | 172 | Plan Mode 기준 필수, 나머지 상세 | Plan Mode 기준만 인라인 |
| 05-responses.md | 55 | 형식 가이드 — 참조성 | Skills로 분리 |
| 06-session.md | 78 | 세션 절차 — 참조성 | Skills로 분리 |
| 07-db.md | 233 | DB 안전 — 상황별로만 필요 | Skills로 분리 |
| 08-local-env.md | 241 | 신규 세팅 시만 필요 | Skills로 분리 |
| 08-ui-first.md | 60 | 프론트엔드 작업 시만 필요 | Skills로 분리 |
| 09-hooks-guide.md | 122 | 구성 참조용 | Skills로 분리 |
| 10-subagent-patterns.md | 103 | 참조용 | Skills로 분리 |
핵심/상세 분리 근거
- 항상 필요한 것: 모든 작업에 앞서 AI가 즉시 알아야 할 "하지 말 것" 목록
- 상황별로 필요한 것: 특정 작업(DB 변경, UI 구현, 신규 세팅) 시에만 참조
- 형식/절차 가이드: 작업 중 필요할 때 호출 (
@skill-db,@skill-session)
슬림 CLAUDE.md 구조 (목표: 150줄)
# CLAUDE.md — Global Rules
> Generated by ai-rules. Edit in ai-rules/core/.
## 규칙 우선순위
1. 03-security (보안 최우선)
2. 01-git (되돌리기 불가 작업)
3. 04-workflow (Plan Mode, 사람 승인)
4. 나머지
## 언어 규칙
- 사용자: 한국어 / 코드·커밋: 영어
- 답변 레이블 필수: [검증됨] / [추론] / [모름]
## Git 금지 명령 (CRITICAL)
❌ rebase, merge (ff-only 제외), push -f/--force, conflict 자동 해결
- 보호 브랜치(main/master/develop) 직접 커밋 금지
- ff-only 실패 시: 즉시 멈추고 사용자 보고 (rebase 시도 금지)
## Code Hard Bans
### Frontend
- 컴포넌트에서 fetch/axios 직접 사용 금지 → hooks + React Query
- dangerouslySetInnerHTML → DOMPurify.sanitize() 필수
- console.log → import.meta.env.DEV 조건 필수
- 하드코딩 색상·임의 간격값 금지 → CSS 변수·Tailwind 표준
### Backend
- DB in Controller 금지 → Controller → Service → Repository
- 모든 엔드포인트에 인증 미들웨어 필수
- 카운터 컬럼(count += 1) 금지 → 이벤트 테이블
## 보안 금지
- 하드코딩 시크릿·PII 로그·스택 트레이스 API 노출 금지
- SQL Injection·XSS 방지 필수
- 인증/결제/권한 변경 → security 에이전트 소환
## Plan Mode 기준
- 오류 수정·기능 구현 요청 → Plan Mode 필수 (EnterPlanMode)
- DB 스키마 변경 / 인증·결제 로직은 긴급 시에도 Plan Mode 생략 불가
- AI 단독 실행 가능: 조회·분석·단순 버그 수정(1파일·10줄 이하)·문서
## 커밋 프로세스
0. 브랜치 확인 (main/master/develop이면 커밋 금지)
1. tsc --noEmit + backend imports 검증 후 커밋
2. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> 필수
3. 기본 모드 auto — 커밋+푸시 전 사용자 승인
## Skills 참조
상세 규칙은 상황에 맞는 skill을 호출:
- DB 작업 시: @skill-db
- 신규 프로젝트 세팅 시: @skill-local-env
- UI/프론트엔드 구현 시: @skill-ui-first
- 응답 형식 확인 시: @skill-responses
- 세션 관리 절차: @skill-session
- Hooks 설정 시: @skill-hooks
- Subagent 위임 시: @skill-subagent
Skills 시스템 설계
디렉토리 구조
~/.claude/
CLAUDE.md ← 슬림 버전 (150줄 이하)
skills/
db.md ← 07-db.md 전체 내용
local-env.md ← 08-local-env.md 전체 내용
ui-first.md ← 08-ui-first.md 전체 내용
responses.md ← 05-responses.md 전체 내용
session.md ← 06-session.md 전체 내용
hooks.md ← 09-hooks-guide.md 전체 내용
subagent.md ← 10-subagent-patterns.md 전체 내용
git-detail.md ← 01-git.md 상세 (브랜치 규칙, 프로세스 등)
workflow-detail.md ← 04-workflow.md 상세 (게이트, backlog, WORKLOG 등)
Skill 호출 방식
Claude Code의 /skills/ 참조 패턴을 활용:
# CLAUDE.md에서 참조 선언
Skills 참조: 상황에 맞는 skill을 @skill-{name} 형태로 호출
# 사용자 또는 AI가 필요 시 명시적 호출
"DB 마이그레이션 작업 시작 → @skill-db 적용"
"신규 프로젝트 세팅 → @skill-local-env 체크리스트 실행"
자동 트리거 조건
슬림 CLAUDE.md에 트리거 매핑 테이블 포함:
| 감지 키워드/상황 | 자동 로드 Skill |
|---|---|
prisma migrate, alembic, DROP, CREATE TABLE |
@skill-db |
新규 프로젝트, 포트 확인, DB 세팅 |
@skill-local-env |
*.html 목업, 페이지 컴포넌트 구현 |
@skill-ui-first |
| 세션 시작, SESSION.md, HANDOFF | @skill-session |
adapters/claude-code.mjs 수정 설계
slim 모드 지원
// profile.yaml에서 slim 모드 활성화
// tools.claude-code.slim: true
export function generate(blocks, toolConfig, profile) {
const isSlim = toolConfig.slim === true
if (isSlim) {
// 슬림 CLAUDE.md 생성
const coreBlocks = getCoreBlocks(blocks, toolConfig.core_inline)
// core_inline 목록에 있는 파일만 인라인, 나머지는 skills/ 로 분리
const mainContent = generateSlimMain(coreBlocks, profile)
const skillFiles = generateSkillFiles(blocks, toolConfig.core_inline)
return [
{ path: toolConfig.output, content: mainContent },
...skillFiles.map(sf => ({ path: `skills/${sf.name}.md`, content: sf.content }))
]
}
// 기존 방식 (slim: false 또는 미설정)
return [{ path: toolConfig.output, content: header + blocks.join('\n\n---\n\n') }]
}
global.yaml 수정 예시
tools:
claude-code:
enabled: true
output: CLAUDE.md
slim: true
core_inline: # 항상 CLAUDE.md 인라인 포함
- 00-identity # 규칙 우선순위, 언어, 레이블
- 01-git # 금지 명령어만 (excerpt 지원 필요)
- 02-code # Hard Ban 목록
- 03-security # 전체 (44줄)
- 04-workflow # Plan Mode 기준만
core_skills: # skills/ 로 분리
- 05-responses
- 06-session
- 07-db
- 08-local-env
- 08-ui-first
- 09-hooks-guide
- 10-subagent-patterns
마이그레이션 경로
Phase 1 — Skills 파일 생성 (현재 코어 그대로 복사)
core/*.md→~/.claude/skills/*.md자동 복사- 기존 CLAUDE.md는 변경 없음
Phase 2 — slim 모드 adapter 구현
adapters/claude-code.mjs에isSlim분기 추가profiles/global.yaml에slim: true+core_inline목록 추가- 테스트: slim 모드로 생성된 CLAUDE.md 검토
Phase 3 — 핵심 요약 추출 (excerpt 지원)
- 각 core 파일에
<!-- excerpt:start -->/<!-- excerpt:end -->마커 추가 - adapter가 slim 모드에서 excerpt만 인라인
Phase 4 — 운영 전환
- 글로벌 CLAUDE.md를 slim 버전으로 교체
- 기존 CLAUDE.md는
CLAUDE.md.full.bak으로 보관
예상 줄 수 절감
| 항목 | 현재 | 슬림 후 |
|---|---|---|
| 인라인 핵심 내용 | 1,308줄 | ~140줄 |
| skills/ 총합 | 0줄 | ~1,100줄 (분리) |
| 컨텍스트 소비 (기본) | 1,308줄 | ~140줄 |
| 컨텍스트 소비 (DB 작업) | 1,308줄 | ~140 + 233 = ~373줄 |
대부분의 작업에서 컨텍스트 소비를 89% 절감. 필요한 skill만 로드하므로 실제 작업과 무관한 규칙이 컨텍스트를 차지하지 않음.