Claude Guide

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

설정 유형 선택 가이드

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

| 유형 | 로드 시점 | 용도 | |------|----------|------| | CLAUDE.md | 항상 | 핵심 규칙, 필수 설정 | | rules/ | 자동 로드 (paths 지정 시 해당 경로만) | 상세 규칙 분리 (20줄+ 시) | | hooks/ | 이벤트 시 | 도구 호출 전후 자동 실행 | | commands/ | 호출 시만 | 반복 작업 템플릿 (/auto-dev) | | skills/ | 필요 시만 | 전문 지식 패키지 (drawio) | | agents/ | 위임 시만 | 독립 컨텍스트 작업 (code-review) |

어디에 넣을까?

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

Memory 계층 구조

Claude Code는 여러 위치에서 메모리를 로드합니다. 위에서 아래로 우선순위가 높습니다.

| 우선순위 | 유형 | 위치 | 공유 범위 | |:---:|------|------|----------| | 1 | Enterprise policy | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md<br>Linux: /etc/claude-code/CLAUDE.md<br>Windows: C:\Program Files\ClaudeCode\CLAUDE.md | 조직 전체 | | 2 | User memory | ~/.claude/CLAUDE.md | 개인 (모든 프로젝트) | | 3 | Project memory | ./CLAUDE.md 또는 ./.claude/CLAUDE.md | 팀 (소스 컨트롤) | | 4 | Project rules | ./.claude/rules/*.md | 팀 (소스 컨트롤) | | 5 | Project local | ./CLAUDE.local.md | 개인 (현재 프로젝트만) |

동작 방식: cwd에서 루트까지 재귀적으로 탐색하며 모든 CLAUDE.md, CLAUDE.local.md 로드

CLAUDE.local.md는 자동으로 .gitignore에 추가됨

@ Import 문법

다른 파일을 import할 수 있습니다:

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md
- 개인 설정 @~/.claude/my-project-instructions.md

상대/절대 경로 모두 지원
최대 5단계 재귀 import
코드 블록 내에서는 평가되지 않음

Path-Specific Rules

.claude/rules/ 내 파일에 YAML frontmatter로 특정 경로에만 적용:

---
paths: src/api/**/*.ts
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

Glob 패턴 예시:

**/*.ts: 모든 TypeScript 파일
src/**/*: src/ 하위 모든 파일
src/components/*.tsx: 특정 디렉토리만
{src,lib}/**/*.ts: 여러 디렉토리

Memory 명령어

/init    # CLAUDE.md 생성
/memory  # 로드된 memory 파일 확인

공식 문서: https://code.claude.com/docs/en/memory

CLAUDE.md 리뷰

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

핵심 목표:

프로젝트 고유 정보만 간결하게 유지 (토큰 효율성 우선)
범용 패턴은 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)

분석 항목:

컨텍스트 효율성 체크
- 간결하고 핵심만: ✅ 적절
- 다소 장황함: ⚠️ 약간 김
- 범용 내용 많음: ❌ Skills 분리 필요
Skills로 분리할 내용 감지

키워드 패턴으로 감지:
- "TypeScript", "타입", "컨벤션", "린팅" → patterns-typescript
- "React", "컴포넌트", "hooks", "상태 관리" → patterns-react
- "API 설계", "엔드포인트", "RESTful" → patterns-api
- "테스트", "유닛", "E2E", "mocking" → test-guidelines
- "에러 핸들링", "try-catch", "로깅" → patterns-error-handling
판단 기준:
- 해당 섹션이 20줄 이상
- 프로젝트 독립적인 범용 내용
- 다른 프로젝트에도 적용 가능
필수 항목 체크
- [ ] 프로젝트 개요 (1-2줄 설명)
- [ ] 퀵 커맨드 (build, test, dev, deploy 등)
- [ ] 서비스 엔드포인트/포트
- [ ] 환경변수 필수 항목
- [ ] 프로젝트 특이사항/주의사항

3. 리포트 생성

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

## 📊 claude.md 리뷰 결과

### 전체 현황
- 총 라인: XXX줄
- 상태: ✅ 간결하고 적절 / ⚠️ 약간 김 / ❌ 분리 필요

### 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 분리 선택 시:

각 분리 대상마다 확인:

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

새 skill 생성:

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

claude.md에서 해당 섹션 제거

claude.md에 skill 참조 추가:

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

[2] 정리만 선택 시:

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

[3] 새로 작성 선택 시:

프로젝트 유형 확인:
- Web App (Next.js, React 등)
- API Server (Express, Fastify 등)
- Monorepo (Turborepo, Nx 등)
- Minimal (기본)
적절한 템플릿 선택 (templates/{유형}.md)
사용자와 대화하며 커스터마이징:
- "프로젝트명은?"
- "빌드 명령어는?"
- "개발 서버 포트는?"
- "특별한 주의사항은?"
claude.md 생성

6. 검증

정리 후 재확인:

간결한가?
필수 항목 모두 포함?
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

대규모 프로젝트 CLAUDE.md

대규모 엔터프라이즈 프로젝트는 일반 권장 범위를 초과할 수 있습니다.

언제 200줄+ CLAUDE.md가 필요한가?

프로젝트 고유 규칙이 많은 경우 (REST API 표준, 로깅 표준, i18n 등)
DDD 같은 복잡한 아키텍처를 사용하는 경우
규제 준수 요구사항이 있는 경우 (금융, 의료 등)
체크리스트가 필요한 경우 (새 Controller, 새 Service 등)

대규모 프로젝트 권장 섹션

1. Project Overview        # 프로젝트 개요
2. Quick Commands          # 개발 명령어
3. Services                # 서비스 엔드포인트
4. Environment Variables   # 환경변수
5. Architecture            # 아키텍처 가이드라인 (패키지 구조, 계층 의존성)
6. REST API Standards      # API 응답 패턴, 로깅 표준
7. Internationalization    # i18n 메시지 사용법
8. Swagger Documentation   # API 문서화 규칙
9. Checklists              # 체크리스트 (새 컨트롤러, 새 서비스, PR)
10. Testing Strategy       # 테스트 전략, 디렉토리 구조
11. Troubleshooting        # 자주 발생하는 문제 해결
12. References             # 상세 문서 링크

코드 예시 패턴 (✅/❌)

올바른 방법과 잘못된 방법을 대비하여 명확하게 가이드:

// ✅ 올바른 패턴: ApiResult 래퍼 사용
@PostMapping
public ResponseEntity<ApiResult<UserResponse>> createUser(...) {
    return ResponseEntity.status(HttpStatus.CREATED)
        .body(ApiResult.success(response, message));
}

// ❌ 잘못된 패턴: ApiResult 없이 직접 반환
@GetMapping
public ResponseEntity<List<UserResponse>> getUsers() {
    return ResponseEntity.ok(service.getAll());  // 이렇게 하지 마세요
}

효과: AI가 명확한 패턴을 학습하여 일관된 코드 생성

체크리스트 패턴

새 기능 구현 시 빠뜨리기 쉬운 사항을 명시적으로 나열:

### New Controller Checklist

- [ ] **ApiResult 패턴 적용**: 모든 엔드포인트가 `ResponseEntity<ApiResult<T>>` 반환
- [ ] **MessageSourceService 주입**: 다국어 메시지 처리를 위해 필수
- [ ] **Swagger 문서화**: `@Tag`, `@Operation`, `@ApiResponses` 어노테이션 추가
- [ ] **로깅 표준 준수**: GET은 `debug`, POST/PUT/DELETE는 `info` 레벨
- [ ] **메시지 파일 업데이트**: messages_ko.properties에 메시지 키 추가

효과: AI가 코드 생성 후 자체 검증 가능

템플릿

대규모 프로젝트용 템플릿: templates/enterprise.md

체크리스트

필수 항목

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

품질

[ ] 간결하게 유지
[ ] Skills 참조 명확
[ ] 프로젝트 고유 정보만
[ ] 섹션 구조 명확

Skills 분리

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

예시

예시 1: 리뷰 후 Skills 분리

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

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

예시 2: 새로 작성

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

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

Technical Details

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

minimal.md: 최소 구성
web-app.md: 웹앱 프로젝트
api-server.md: API 서버
monorepo.md: 모노레포
enterprise.md: 엔터프라이즈 프로젝트 (DDD, 규제 준수)