Claude Guide

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. 각 분리 대상마다 확인:

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

2. 새 skill 생성:

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

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

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

   ## 코딩 가이드
   - 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: 모노레포