Claude Guide

Claude Code 설정 구조를 안내하고, 프로젝트별 CLAUDE.md를 리뷰합니다.

설정 유형 선택 가이드

Claude Code는 다양한 설정 방식을 제공합니다. 컨텍스트 소비 최소화를 위해 적절한 유형을 선택하세요.

어디에 넣을까?

CLAUDE.md: 커밋 규칙, 테스트 정책, 금지 사항 (항상 적용되어야 할 것) rules/: 상세 규칙 (20줄+), 영역별 분리 (frontend/, backend/) commands/: 반복 워크플로우 (/review, /deploy, /docs) skills/: 특정 주제 전문 지식 (항상 필요하지 않은 것) agents/: 독립 컨텍스트 필요한 작업 (코드 리뷰, 탐색)

CLAUDE.md 리뷰

프로젝트별 CLAUDE.md를 리뷰하고 정리합니다.

핵심 목표:

• 프로젝트 고유 정보만 유지 (50-100줄)
• 범용 패턴은 Skills로 분리
• 필수 항목 누락 방지

Instructions

워크플로우: 기존 claude.md 리뷰

1. 파일 확인

# 현재 디렉토리 확인
pwd

# claude.md 찾기
ls claude.md 2>/dev/null || ls CLAUDE.md 2>/dev/null

있으면: 리뷰 시작 없으면: 생성 제안 (templates/ 참조)

2. Read 및 분석

Read claude.md (또는 CLAUDE.md)

분석 항목:

1. 길이 체크

   • 50-100줄: ✅ 적절
   • 100-200줄: ⚠️ 약간 김
   • 200줄 이상: ❌ Skills 분리 필요

2. Skills로 분리할 내용 감지

   키워드 패턴으로 감지:

   • "TypeScript", "타입", "컨벤션", "린팅" → patterns-typescript
   • "React", "컴포넌트", "hooks", "상태 관리" → patterns-react
   • "API 설계", "엔드포인트", "RESTful" → patterns-api
   • "테스트", "유닛", "E2E", "mocking" → test-guidelines
   • "에러 핸들링", "try-catch", "로깅" → patterns-error-handling

   판단 기준:

   • 해당 섹션이 20줄 이상
   • 프로젝트 독립적인 범용 내용
   • 다른 프로젝트에도 적용 가능

3. 필수 항목 체크

   • 프로젝트 개요 (1-2줄 설명)
   • 퀵 커맨드 (build, test, dev, deploy 등)
   • 서비스 엔드포인트/포트
   • 환경변수 필수 항목
   • 프로젝트 특이사항/주의사항

3. 리포트 생성

사용자에게 분석 결과 요약:

## 📊 claude.md 리뷰 결과

### 전체 현황
- 총 라인: XXX줄 (권장: 50-100줄)
- 상태: ✅ 적절 / ⚠️ 약간 김 / ❌ 분리 필요

### Skills로 분리 권장 (총 YYY줄)
1. TypeScript 컨벤션 (50줄) → patterns-typescript
2. React 패턴 (80줄) → patterns-react
3. 테스트 가이드 (40줄) → test-guidelines

### 필수 항목 누락
- [ ] 퀵 커맨드
- [ ] 서비스 엔드포인트

### 적절한 내용
- [x] 프로젝트별 quirks
- [x] 특정 서비스 설정

4. 사용자 확인

개선 방향 선택지 제시:

[1] Skills 분리 + 정리

• 범용 내용을 skills로 분리
• 프로젝트 고유 정보만 남김
• 누락된 필수 항목 추가

[2] 정리만 (분리 없이)

• 현재 구조 유지
• 포맷만 정리

[3] 새로 작성

• 기존 내용 참고하여 템플릿 기반 재작성

5. 개선 실행

[1] Skills 분리 선택 시:

1. 각 분리 대상마다 확인:

   Copy

   "TypeScript 컨벤션(50줄)을 patterns-typescript skill로 분리하시겠습니까?"
   → Yes: 새 skill 생성
   → No: claude.md에 유지
   

2. 새 skill 생성:

   bashCopy

   mkdir -p skills/patterns-{name}/
   Write skills/patterns-{name}/SKILL.md
   

3. claude.md에서 해당 섹션 제거

4. claude.md에 skill 참조 추가:

   markdownCopy

   ## 코딩 가이드
   - TypeScript: `patterns-typescript` skill 참조
   - React: `patterns-react` skill 참조
   

[2] 정리만 선택 시:

• 포맷 정리
• 섹션 재배치
• 필수 항목 추가

[3] 새로 작성 선택 시:

1. 프로젝트 유형 확인:

   • Web App (Next.js, React 등)
   • API Server (Express, Fastify 등)
   • Monorepo (Turborepo, Nx 등)
   • Minimal (기본)

2. 적절한 템플릿 선택 (templates/{유형}.md)

3. 사용자와 대화하며 커스터마이징:

   • "프로젝트명은?"
   • "빌드 명령어는?"
   • "개발 서버 포트는?"
   • "특별한 주의사항은?"

4. claude.md 생성

6. 검증

정리 후 재확인:

• 길이: 50-100줄 이내?
• 필수 항목 모두 포함?
• Skills 참조 명확?

포함/제외 기준

✅ claude.md에 포함할 것

프로젝트 고유 정보:

• 프로젝트 개요 및 목적
• 빌드/테스트/배포 명령어
• 서비스 엔드포인트 및 포트
• 환경변수 필수 항목
• 인증/테스팅 워크플로우 (프로젝트 특화)
• 프로젝트별 quirks 및 주의사항
• 특정 서비스 설정 (Redis, DB 등)
• 프로젝트 특화 트러블슈팅

예시:

# MyApp

웹 기반 사용자 관리 시스템

## 퀵 커맨드
- Build: `npm run build`
- Dev: `npm run dev` (http://localhost:3000)
- Test: `npm test`
- Deploy: `./scripts/deploy.sh`

## 서비스
- API: http://localhost:3000/api
- Admin: http://localhost:3001
- Redis: localhost:6379

## 환경변수 필수
- DATABASE_URL
- REDIS_URL
- JWT_SECRET

## 주의사항
- DB 마이그레이션은 항상 백업 후 실행
- Redis는 개발 시 docker compose로 자동 실행

❌ Skills로 분리할 것

범용 패턴 및 가이드:

• 언어별 컨벤션 (TypeScript, Python 등)
• 프레임워크 패턴 (React, Vue, Express 등)
• API 설계 원칙 (RESTful, GraphQL)
• 테스트 작성 가이드
• 에러 핸들링 패턴
• 데이터베이스 설계 원칙
• 성능 최적화 기법

분리 대상 skill 매핑:

• TypeScript 컨벤션 → patterns-typescript
• React 패턴 → patterns-react
• Backend 아키텍처 → patterns-backend
• API 설계 → patterns-api
• 테스트 가이드 → test-guidelines
• 에러 핸들링 → patterns-error-handling
• 보안 → review-security

체크리스트

필수 항목

• 프로젝트 개요 (1-2줄)
• 퀵 커맨드 (build, test, dev)
• 서비스 엔드포인트/포트
• 환경변수 필수 항목

품질

• 50-100줄 이내
• Skills 참조 명확
• 프로젝트 고유 정보만
• 섹션 구조 명확

Skills 분리

• 코딩 컨벤션 (> 20줄) 분리
• 프레임워크 패턴 분리
• 범용 가이드 분리

예시

예시 1: 리뷰 후 Skills 분리

User: "claude.md 리뷰해줘" Assistant:

1. Read claude.md (250줄)
2. 분석:
   • TypeScript 컨벤션 (60줄) → patterns-typescript
   • React 패턴 (70줄) → patterns-react
   • 퀵 커맨드 누락
3. 리포트 제시
4. 사용자 승인
5. 실행:
   • skills/patterns-typescript/ 생성
   • skills/patterns-react/ 생성
   • claude.md에서 해당 섹션 제거
   • 퀵 커맨드 추가
6. 결과: 80줄의 깔끔한 claude.md

예시 2: 새로 작성

User: "claude.md 만들어줘" Assistant:

1. 프로젝트 유형 확인
2. templates/web-app.md 선택
3. 커스터마이징
4. claude.md 생성

Technical Details

템플릿은 templates/ 디렉토리 참조:

• minimal.md: 최소 구성
• web-app.md: 웹앱 프로젝트
• api-server.md: API 서버
• monorepo.md: 모노레포