Claude Guide

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

설정 유형 선택 가이드

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

어디에 넣을까?

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

Skill Frontmatter 레퍼런스

skills/{name}/SKILL.md의 YAML frontmatter 공식 필드.

기본 필드

name — 슬래시 커맨드 이름. 소문자+숫자+하이픈, 최대 64자. 생략 시 디렉토리명.

name: fix-issue    # → /fix-issue 로 호출

description — Claude가 자동 호출 여부를 판단하는 기준 + / 메뉴 설명. What + When 형식 필수. 생략 시 마크다운 첫 문단.

description: Resolves Git rebase conflicts. Use when encountering merge conflicts during rebase.

argument-hint — / 자동완성 시 표시되는 인자 힌트.

argument-hint: "[issue-number]"
# /fix-issue [issue-number] 로 표시

스킬 본문에서 $ARGUMENTS (전체), $0, $1 (개별)로 참조:

Fix GitHub issue $ARGUMENTS following our coding standards.

호출 제어

disable-model-invocation — true 설정 시 Claude가 자동으로 호출하지 못함. 사용자만 /로 수동 호출. description이 컨텍스트에 로드되지 않아 토큰도 절약.

# 배포처럼 부작용이 큰 작업에 적합
disable-model-invocation: true

user-invocable — false 설정 시 / 메뉴에서 숨김. Claude만 자동 호출. description은 컨텍스트에 로드됨.

# Claude용 배경 지식에 적합 (사용자가 직접 호출할 이유 없음)
user-invocable: false

조합 효과:

도구/모델 제어

allowed-tools — skill 실행 중 사용 가능한 도구 제한. 와일드카드 지원.

# 읽기 전용 skill
allowed-tools: Read, Grep, Glob

# Git 명령만 허용
allowed-tools: Bash(git *), Read, Grep, Glob

model — skill 실행 시 사용할 모델. 종료 후 원래 모델로 복귀.

# 간단한 포매팅은 저비용 모델로
model: claude-haiku-4-5-20251001

# 복잡한 분석은 고성능 모델로
model: claude-opus-4-6

격리 실행

context: fork + agent — 독립 서브에이전트에서 실행. 메인 대화 이력에 접근 불가, 컨텍스트 보호.

context: fork
agent: Explore          # Explore, Plan, general-purpose, 또는 커스텀
allowed-tools: Glob, Grep, Read

Skill-scoped Hooks

hooks — skill 실행 중에만 활성화되는 훅. 종료 시 해제.

hooks:
  - matcher: Bash
    hooks:
      - type: command
        command: "~/.claude/hooks/check-secrets.sh"
        timeout: 30

동적 컨텍스트 주입

본문에서 !`command` 문법으로 셸 명령을 전처리 (Claude 이전 실행, 출력 삽입):

## PR context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`

Memory 계층 구조

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

동작 방식: 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)

분석 항목:

1. 컨텍스트 효율성 체크

   • 간결하고 핵심만: ✅ 적절
   • 다소 장황함: ⚠️ 약간 김
   • 범용 내용 많음: ❌ 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줄
- 상태: ✅ 간결하고 적절 / ⚠️ 약간 김 / ❌ 분리 필요

### 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. 검증

정리 후 재확인:

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

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: 모노레포
• enterprise.md: 엔터프라이즈 프로젝트 (DDD, 규제 준수)