.claude/ 폴더 구조 완벽 가이드: 프로젝트 설정부터 고급 활용까지 알아보기

이 글은 해당 링크를 참고하여 학습용도로 정리한 포스팅입니다. Claude Code의 핵심이라 할 수 있는 .claude/ 폴더의 구조와 활용법을 상세히 다루며 각 구성 요소의 역할과 실제 사용 방법을 단계별로 살펴봅시다.

이미지 출처: Daily Dose of Data Science

 

들어가며: 왜 .claude/ 폴더가 중요한가?

Claude Code를 사용하다 보면 매번 같은 지시사항을 반복해서 입력하는 것이 번거로울 수 있습니다. "TypeScript를 사용해줘", "테스트 코드도 작성해줘", "우리 팀의 코딩 컨벤션을 따라줘" 같은 요청들 말입니다.

매 대화 세션마다 이런 기본적인 규칙들을 반복해서 설명하는 것은 시간 낭비일 뿐만 아니라, 중요한 세부사항을 놓치거나 팀원 간 일관성이 깨질 위험도 있습니다. .claude/ 폴더는 바로 이런 문제를 해결하기 위한 Claude Code의 설정 시스템입니다.

이 폴더 시스템을 통해 우리는 Claude에게 프로젝트의 컨텍스트를 한 번만 설명하면 되고, 이후에는 Claude가 자동으로 이러한 규칙과 설정을 기억하고 따르게 됩니다. 마치 새로운 팀원이 합류했을 때 온보딩 문서를 제공하는 것처럼, Claude에게도 프로젝트에 대한 명확한 가이드라인을 제공할 수 있는 것입니다.

두 가지 레벨의 디렉토리 구조 이해하기

Claude Code는 설정 관리를 위해 두 가지 레벨의 .claude 디렉토리를 사용합니다. 이는 마치 Git의 로컬 설정과 글로벌 설정처럼, 프로젝트별 설정과 사용자 전역 설정을 분리하여 관리하는 구조입니다.

이미지 출처: Daily Dose of Data Science

 

프로젝트 레벨 디렉토리 (.claude/)

프로젝트 루트에 위치하는 .claude/ 폴더는 해당 프로젝트에만 적용되는 설정을 담고 있습니다. 이 폴더의 가장 큰 특징은 Git에 커밋되어 팀원들과 공유된다는 점입니다.

예를 들어, 여러분의 팀이 React와 TypeScript를 사용하고 있고, 특정한 코딩 컨벤션을 따르고 있다면, 이러한 정보를 프로젝트 레벨 .claude/ 폴더에 저장합니다. 새로운 팀원이 프로젝트를 클론받으면 자동으로 이 설정들을 받게 되고, Claude Code는 즉시 팀의 규칙을 인식하고 따르게 됩니다.

프로젝트 레벨 디렉토리에 포함되는 주요 내용들:

• 프로젝트의 기술 스택 정보
• 팀의 코딩 컨벤션
• 빌드 및 테스트 명령어
• 프로젝트 구조 설명
• 공통 워크플로우 및 자동화 스크립트

 

글로벌 레벨 디렉토리 (~/.claude/)

홈 디렉토리에 위치하는 ~/.claude/ 폴더는 사용자의 모든 프로젝트에 공통으로 적용되는 개인 설정을 담고 있습니다. 이 폴더는 로컬 머신에만 존재하며 Git에 커밋되지 않습니다.

개인 개발 환경의 특성이나 선호하는 작업 스타일, 자주 사용하는 개인 명령어 등을 이곳에 저장할 수 있습니다. 예를 들어, 특정 IDE를 사용한다거나, 개인적으로 선호하는 디버깅 방법이 있다면 글로벌 설정에 포함시킬 수 있습니다.

글로벌 레벨 디렉토리에 포함되는 주요 내용들:

• 개인 개발 환경 설정
• 자주 사용하는 개인 명령어
• 개인 작업 스타일 및 선호사항
• 프로젝트별 세션 기록 및 메모리

이미지 출처: Daily Dose of Data Science

 

핵심 구성 요소 상세 분석

이제 .claude/ 폴더의 각 구성 요소를 하나씩 자세히 살펴보겠습니다. 각 요소가 어떤 역할을 하는지, 어떻게 작성하는지, 그리고 실제로 어떻게 활용되는지 구체적인 예시와 함께 설명하겠습니다.

1. CLAUDE.md - 프로젝트의 두뇌

CLAUDE.md 파일은 .claude/ 폴더의 가장 중요한 파일입니다. 이 파일은 Claude의 시스템 프롬프트에 직접 로드되어, Claude가 프로젝트를 이해하고 적절하게 동작하도록 만드는 핵심 지침서 역할을 합니다.

CLAUDE.md의 중요성

CLAUDE.md를 작성하는 것은 마치 새로운 개발자를 위한 온보딩 문서를 작성하는 것과 같습니다. 하지만 인간 개발자와 달리, Claude는 이 문서를 한 번에 완벽하게 읽고 기억하며, 모든 지시사항을 정확하게 따릅니다.

이 파일이 시스템 프롬프트에 직접 로드된다는 것은 Claude가 대화를 시작하기 전에 이미 프로젝트의 모든 컨텍스트를 알고 있다는 의미입니다. 따라서 매번 "우리는 TypeScript를 사용해"라고 말할 필요 없이, Claude는 자동으로 TypeScript 코드를 생성합니다.

효과적인 CLAUDE.md 작성 원칙

1. 간결성 유지 (200줄 이하)
Claude의 컨텍스트 윈도우는 제한적이므로, CLAUDE.md는 가능한 한 간결해야 합니다. 200줄을 넘어가면 성능이 저하되고 중요한 정보가 무시될 수 있습니다. 핵심 정보만 포함시키고, 상세한 내용은 rules/ 폴더로 분리하는 것이 좋습니다.

2. 구체적이고 명확한 지시
모호한 표현보다는 구체적인 예시와 명확한 지시를 사용합니다. "좋은 코드를 작성해줘"보다는 "모든 함수에 JSDoc 주석을 포함하고, 에러 처리는 try-catch 블록을 사용해줘"가 더 효과적입니다.

3. 우선순위 명시
여러 규칙이 충돌할 수 있는 경우, 명확한 우선순위를 제시합니다. 예를 들어, "성능보다 가독성을 우선시" 또는 "보안이 최우선"과 같은 지침을 포함시킵니다.

실전 CLAUDE.md 예시

# 프로젝트 개요
이 프로젝트는 전자상거래 플랫폼의 백엔드 API입니다.
Node.js 18과 TypeScript 5를 사용하며, Express.js 프레임워크 기반입니다.

# 핵심 기술 스택
- Runtime: Node.js 18 LTS
- Language: TypeScript 5 (strict mode enabled)
- Framework: Express.js 4.x
- Database: PostgreSQL 15 with Prisma ORM
- Testing: Jest + Supertest
- Package Manager: npm (not yarn or pnpm)

# 프로젝트 구조
src/
├── controllers/    # HTTP 요청 처리 로직
├── services/       # 비즈니스 로직
├── repositories/   # 데이터베이스 접근 로직
├── middlewares/    # Express 미들웨어
├── utils/         # 유틸리티 함수
├── types/         # TypeScript 타입 정의
└── config/        # 설정 파일

# 개발 규칙
1. 모든 코드는 TypeScript로 작성
2. 함수는 단일 책임 원칙을 따름 (하나의 함수는 하나의 일만)
3. 에러 처리는 centralized error handler 사용
4. 모든 엔드포인트는 입력 검증 필수
5. 데이터베이스 쿼리는 반드시 Prisma ORM 사용

# 네이밍 컨벤션
- 파일명: kebab-case (user-controller.ts)
- 클래스명: PascalCase (UserController)
- 함수/변수명: camelCase (getUserById)
- 상수: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- 인터페이스: I 접두사 사용 (IUserService)

# 테스트 규칙
- 모든 새 기능은 테스트 코드 포함
- 테스트 파일은 *.test.ts 또는 *.spec.ts
- 테스트 커버리지 목표: 80% 이상
- E2E 테스트는 주요 사용자 시나리오 커버

# 자주 사용하는 명령어
- 개발 서버 실행: npm run dev
- 테스트 실행: npm test
- 빌드: npm run build
- 린트 검사: npm run lint
- 타입 체크: npm run type-check

# 중요 보안 규칙
- 절대 비밀 키를 하드코딩하지 않음
- 모든 사용자 입력은 검증 및 sanitize
- SQL 인젝션 방지를 위해 raw query 금지
- JWT secret은 환경 변수로 관리

CLAUDE.local.md - 개인 설정 오버라이드

CLAUDE.local.md 파일은 CLAUDE.md를 개인적으로 커스터마이징할 수 있는 파일입니다. 이 파일은 자동으로 .gitignore에 포함되어 Git에 커밋되지 않으므로, 팀 설정을 변경하지 않고도 개인 환경에 맞는 설정을 추가할 수 있습니다.

이미지 출처: Daily Dose of Data Science

예를 들어, 팀은 npm을 사용하지만 개인적으로 더 빠른 pnpm을 선호한다면, CLAUDE.local.md에 이를 명시할 수 있습니다:

# 개인 개발 환경 설정
- Package Manager: pnpm (개인 선호)
- IDE: VS Code with Vim extension
- 로컬 데이터베이스: Docker PostgreSQL on port 5433

# 개인 작업 스타일
- 커밋 전 항상 로컬에서 전체 테스트 실행
- 디버깅 시 console.log 대신 VS Code debugger 사용
- 브랜치명: feature/이름-기능 형식 사용

2. rules/ 폴더 - 모듈화된 지침 관리

프로젝트가 성장하면서 CLAUDE.md 파일이 너무 커지는 문제가 발생할 수 있습니다. 이때 rules/ 폴더를 사용하여 지침을 주제별로 분리하고 모듈화할 수 있습니다.

rules/ 폴더의 장점

1. 관심사의 분리: API 규칙, 테스팅 규칙, 보안 규칙 등을 별도 파일로 관리하여 유지보수가 쉬워집니다.
2. 경로별 적용: 특정 디렉토리에만 적용되는 규칙을 정의할 수 있습니다.
3. 팀 협업 향상: 각 팀원이 자신의 전문 영역에 해당하는 규칙을 관리할 수 있습니다.

실제 rules/ 폴더 구조 예시

.claude/rules/
├── api-conventions.md      # REST API 설계 규칙
├── testing-strategy.md     # 테스트 작성 가이드
├── security-checklist.md   # 보안 체크리스트
├── database-patterns.md    # 데이터베이스 패턴
├── error-handling.md       # 에러 처리 규칙
└── performance-guide.md    # 성능 최적화 가이드

경로별 규칙 적용 (Path Scoping)

YAML frontmatter를 사용하여 특정 경로에만 규칙을 적용할 수 있습니다. 이는 대규모 프로젝트에서 특히 유용합니다.

---
paths:
  - src/api/**
  - src/controllers/**
---

# API 엔드포인트 규칙

## RESTful 원칙
1. 명사형 리소스 이름 사용 (/users, /products)
2. HTTP 메서드 의미 준수
   - GET: 조회 (부작용 없음)
   - POST: 생성
   - PUT: 전체 수정
   - PATCH: 부분 수정
   - DELETE: 삭제

## 응답 형식
모든 API 응답은 다음 형식을 따름:
```json
{
  "success": boolean,
  "data": object | array | null,
  "error": {
    "code": string,
    "message": string,
    "details": object
  } | null,
  "meta": {
    "timestamp": string,
    "version": string
  }
}

## 에러 코드 체계
- 4xx: 클라이언트 에러
  - 400: 잘못된 요청
  - 401: 인증 필요
  - 403: 권한 없음
  - 404: 리소스 없음
- 5xx: 서버 에러
  - 500: 내부 서버 오류
  - 503: 서비스 이용 불가

3. commands/ 폴더 - 커스텀 슬래시 명령어

반복적인 작업을 자동화하고 싶다면 commands/ 폴더를 활용할 수 있습니다. 여기에 정의된 마크다운 파일들은 슬래시 명령어로 변환되어 간단한 명령으로 복잡한 작업을 실행할 수 있게 해줍니다.

이미지 출처: Daily Dose of Data Science

명령어 생성 규칙

파일명이 곧 명령어명이 됩니다:

• 프로젝트 레벨: .claude/commands/review.md → /project:review
• 글로벌 레벨: ~/.claude/commands/deploy.md → /user:deploy

실전 명령어 예시

1. 코드 리뷰 자동화 (.claude/commands/review.md)

# 코드 리뷰 수행

현재 브랜치의 변경사항을 메인 브랜치와 비교하여 리뷰합니다.

## 변경 내용 확인
!`git diff main...HEAD --stat`

## 상세 diff
!`git diff main...HEAD`

위의 변경사항을 기반으로 다음 관점에서 코드를 리뷰해주세요:

1. **코드 품질**
   - 가독성과 유지보수성
   - 중복 코드 여부
   - 복잡도

2. **보안**
   - 입력 검증
   - 인증/인가 처리
   - 민감 정보 노출

3. **성능**
   - 불필요한 데이터베이스 쿼리
   - N+1 문제
   - 메모리 누수 가능성

4. **테스트**
   - 테스트 커버리지
   - 엣지 케이스 처리
   - 테스트 가능한 설계

개선이 필요한 부분을 구체적으로 지적하고, 수정 방안을 제시해주세요.

2. GitHub 이슈 처리 (.claude/commands/fix-issue.md)

# GitHub 이슈 #$ARGUMENTS 해결

## 이슈 내용 가져오기
!`gh issue view $ARGUMENTS --json title,body,labels -q '{title: .title, body: .body, labels: .labels[].name}'`

## 관련 PR 확인
!`gh issue view $ARGUMENTS --json linkedPullRequests -q .linkedPullRequests`

위 이슈를 해결하기 위한 코드를 작성해주세요. 다음 사항을 고려하세요:

1. 이슈에서 요구하는 기능/버그 수정을 정확히 구현
2. 기존 코드와의 일관성 유지
3. 적절한 테스트 코드 포함
4. 필요한 경우 문서 업데이트

작업 완료 후 커밋 메시지는 다음 형식으로:
`fix: #$ARGUMENTS [이슈 제목]`

3. 성능 프로파일링 (.claude/commands/profile.md)

# 성능 프로파일링 실행

## Node.js 프로파일링 시작
!`node --prof app.js & sleep 10 && kill $!`

## 프로파일 결과 처리
!`node --prof-process isolate-*.log > profile.txt`

## 주요 병목 지점 확인
!`head -50 profile.txt`

프로파일링 결과를 분석하고 다음을 제공해주세요:

1. 성능 병목 지점 Top 5
2. 각 병목 지점의 원인 분석
3. 구체적인 개선 방안
4. 예상 성능 향상 효과

추가로 다음 도구를 사용한 분석도 고려해주세요:
- Chrome DevTools
- Artillery (부하 테스트)
- Clinic.js (Node.js 성능 분석)

4. skills/ 폴더 - 자동 실행 워크플로우

commands/가 수동으로 실행하는 명령어라면, skills/는 컨텍스트에 따라 자동으로 활성화되는 워크플로우입니다. 특정 패턴이나 키워드가 감지되면 자동으로 실행되어, 반복적인 작업을 더욱 효율적으로 처리할 수 있습니다.

이미지 출처: Daily Dose of Data Science

skills/와 commands/의 차이점

• commands/: 사용자가 명시적으로 실행 (/review 입력)
• skills/: Claude가 자동으로 판단하여 실행 (코드 변경 감지 시 자동 리뷰)

실전 스킬 예시

보안 자동 검토 스킬 (.claude/skills/security-audit/SKILL.md)

---
name: Security Audit
description: 보안 관련 코드 변경 시 자동으로 보안 검토 수행
auto_invoke: true
triggers:
  keywords:
    - auth
    - password
    - token
    - secret
    - encrypt
    - decrypt
    - login
  patterns:
    - "*.auth.*"
    - "**/security/**"
  files:
    - "src/auth/**"
    - "src/middleware/auth.ts"
---

# 자동 보안 검토 체크리스트

코드에서 보안 관련 변경이 감지되었습니다. 다음 항목을 자동으로 검토합니다:

## 인증/인가
- [ ] 적절한 인증 메커니즘 사용 (JWT, OAuth)
- [ ] 세션 관리 및 타임아웃 설정
- [ ] 권한 체크 누락 여부

## 데이터 보호
- [ ] 민감 정보 암호화 여부
- [ ] 환경 변수 사용 (하드코딩 금지)
- [ ] 로그에 민감 정보 노출 여부

## 입력 검증
- [ ] 모든 사용자 입력 검증
- [ ] SQL 인젝션 방지
- [ ] XSS 방지
- [ ] CSRF 토큰 사용

## 보안 헤더
- [ ] Content-Security-Policy
- [ ] X-Frame-Options
- [ ] X-Content-Type-Options
- [ ] Strict-Transport-Security

보안 이슈가 발견되면 즉시 수정 제안을 제공합니다.

데이터베이스 마이그레이션 스킬 (.claude/skills/db-migration/SKILL.md)

---
name: Database Migration Helper
description: 데이터베이스 스키마 변경 감지 시 마이그레이션 지원
auto_invoke: true
triggers:
  files:
    - "prisma/schema.prisma"
    - "src/entities/**"
    - "migrations/**"
---

# 데이터베이스 마이그레이션 도우미

스키마 변경이 감지되었습니다. 다음 작업을 수행합니다:

1. **변경 사항 분석**
   - 새로운 테이블/컬럼 추가
   - 기존 스키마 수정
   - 인덱스 변경

2. **마이그레이션 파일 생성**
   ```bash
   npx prisma migrate dev --name [description]

3. **롤백 계획 수립**
   - 이전 버전으로 되돌리기 위한 스크립트 준비
   - 데이터 백업 확인

4. **성능 영향 평가**
   - 인덱스 추가/제거의 영향
   - 대용량 테이블 변경 시 다운타임 예상

5. **테스트 데이터 업데이트**
   - Seed 데이터 수정
   - 테스트 케이스 업데이트

 

5. agents/ 폴더 - 특화된 서브에이전트

agents/ 폴더를 통해 특정 작업에 특화된 AI 에이전트를 정의할 수 있습니다. 각 에이전트는 고유한 페르소나, 제한된 도구 접근 권한, 그리고 특정 모델을 사용할 수 있습니다.

에이전트 시스템의 장점

1. 작업 특화: 각 에이전트가 특정 작업에만 집중하여 더 나은 결과 도출
2. 리소스 최적화: 간단한 작업은 경량 모델, 복잡한 작업은 고성능 모델 사용
3. 보안 강화: 각 에이전트별로 필요한 최소한의 권한만 부여

실전 에이전트 예시

코드 리뷰 전문가 (.claude/agents/reviewer.yaml)

---
name: Code Review Expert
model: claude-3-5-haiku  # 빠른 응답을 위한 경량 모델
tools: [Read, Grep, Glob]  # 읽기 전용 권한
temperature: 0.3  # 일관성 있는 리뷰를 위한 낮은 temperature
---

당신은 10년 경력의 시니어 코드 리뷰어입니다.
코드 품질, 보안, 성능, 유지보수성을 꼼꼼히 검토합니다.

## 리뷰 원칙
1. 건설적이고 구체적인 피드백 제공
2. 문제점 지적 시 항상 개선 방안 제시
3. 작은 스타일 이슈보다 중요한 로직 문제에 집중
4. 칭찬할 점도 함께 언급

## 중점 검토 영역
### 코드 품질
- SOLID 원칙 준수 여부
- DRY (Don't Repeat Yourself) 위반
- 함수/클래스의 단일 책임 원칙
- 네이밍과 가독성

### 보안
- OWASP Top 10 취약점
- 입력 검증 및 sanitization
- 민감 정보 처리

### 성능
- 시간/공간 복잡도
- 불필요한 리렌더링 (React)
- 데이터베이스 쿼리 최적화

### 테스트
- 테스트 커버리지
- 엣지 케이스 처리
- 테스트 가능한 설계

## 리뷰 형식
```markdown
## 요약
[전반적인 코드 품질과 주요 발견사항]

## 우수한 점
- [잘 작성된 부분들]

## 필수 수정 사항 
- [반드시 수정해야 할 치명적 문제]

## 권장 개선 사항
- [개선하면 좋을 부분들]

## 제안 사항 💡
- [고려해볼 만한 아이디어]

성능 최적화 전문가 (.claude/agents/optimizer.yaml)

---
name: Performance Optimizer
model: claude-3-5-sonnet  # 복잡한 분석을 위한 고성능 모델
tools: [Read, Write, Edit, Bash]  # 코드 수정 권한 포함
---

당신은 성능 최적화 전문가입니다.
코드의 병목 지점을 찾아 개선하는 것이 주 임무입니다.

## 분석 도구
- Node.js: node --prof, clinic.js
- React: React DevTools Profiler
- 데이터베이스: EXPLAIN ANALYZE

## 최적화 전략
1. **측정 우선**: 추측하지 말고 프로파일링
2. **80/20 규칙**: 가장 영향이 큰 부분부터
3. **트레이드오프 고려**: 가독성 vs 성능

## 일반적인 최적화 패턴
### React
- memo, useMemo, useCallback 활용
- 가상화 (react-window)
- 코드 스플리팅
- 번들 크기 최적화

### Node.js
- 스트림 활용
- 클러스터링
- 캐싱 전략
- 비동기 처리 최적화

### 데이터베이스
- 인덱스 최적화
- 쿼리 튜닝
- 커넥션 풀링
- 배치 처리

## 보고서 형식
1. 현재 성능 측정 결과
2. 병목 지점 분석
3. 개선 방안 (코드 포함)
4. 예상 개선 효과
5. 부작용 및 주의사항

6. settings.json - 권한과 보안 설정

settings.json 파일은 Claude Code가 시스템에서 수행할 수 있는 작업을 세밀하게 제어합니다. 이는 보안과 안전성을 보장하는 중요한 파일입니다.

권한 설정의 세 가지 모드

1. allow: 항상 허용되는 작업
2. deny: 항상 금지되는 작업
3. ask: 실행 전 사용자 확인이 필요한 작업

실전 settings.json 예시

{
  "$schema": "https://cdn.jsdelivr.net/gh/anthropics/claude-code@main/schema/settings.schema.json",

  "allow": [
    // 개발 관련 명령어
    "Bash(npm run *)",
    "Bash(npm test*)",
    "Bash(npm run build)",

    // Git 작업
    "Bash(git status)",
    "Bash(git diff*)",
    "Bash(git log*)",
    "Bash(git branch*)",
    "Bash(git checkout*)",
    "Bash(git add*)",
    "Bash(git commit*)",

    // Docker 개발 환경
    "Bash(docker-compose up*)",
    "Bash(docker-compose down)",
    "Bash(docker ps*)",
    "Bash(docker logs*)",

    // 파일 작업
    "Read",
    "Write(src/**)",  // src 폴더 내부만 쓰기 허용
    "Write(tests/**)",
    "Edit"
  ],

  "deny": [
    // 위험한 명령어
    "Bash(rm -rf *)",
    "Bash(sudo *)",
    "Bash(chmod 777 *)",

    // 민감한 파일 접근 차단
    "Read(.env)",
    "Read(.env.*)",
    "Read(**/*.pem)",
    "Read(**/*.key)",
    "Read(secrets/**)",

    // 시스템 파일 수정 차단
    "Write(/etc/**)",
    "Write(/usr/**)",
    "Write(/bin/**)",

    // 프로덕션 배포 차단
    "Bash(npm run deploy:prod)",
    "Bash(kubectl apply*)",

    // 데이터베이스 위험 작업
    "Bash(*DROP DATABASE*)",
    "Bash(*DROP TABLE*)",
    "Bash(*TRUNCATE*)"
  ],

  "ask": [
    // 패키지 설치 (보안 검토 필요)
    "Bash(npm install *)",
    "Bash(npm uninstall *)",
    "Bash(pip install *)",

    // Git 원격 작업
    "Bash(git push*)",
    "Bash(git pull*)",
    "Bash(git fetch*)",
    "Bash(git merge*)",
    "Bash(git rebase*)",

    // 데이터베이스 마이그레이션
    "Bash(*migrate*)",
    "Bash(*seed*)",

    // 환경 변수 파일 생성
    "Write(.env*)",

    // 설정 파일 수정
    "Write(*.config.js)",
    "Write(*.json)",
    "Write(Dockerfile*)",
    "Write(docker-compose*)"
  ],

  "commands": {
    // 커스텀 명령어별 권한 설정
    "project:deploy": {
      "allow": ["Bash(docker build*)", "Bash(docker push*)"],
      "deny": ["Bash(kubectl delete*)"]
    }
  }
}

settings.local.json - 개인 권한 오버라이드

개인 개발 환경에서 추가 권한이 필요한 경우, settings.local.json을 사용합니다:

{
  "allow": [
    // 개인 개발 도구
    "Bash(yarn *)",  // 팀은 npm, 개인은 yarn 사용
    "Bash(bun *)",   // 실험적 도구 사용

    // 로컬 개발 서버
    "Bash(ngrok *)",
    "Bash(localtunnel *)"
  ],

  "deny": [
    // 개인적으로 추가 보안
    "Bash(curl *)",
    "Bash(wget *)"
  ]
}

7. 글로벌 ~/.claude/ 디렉토리 구조

글로벌 디렉토리는 모든 프로젝트에 공통으로 적용되는 설정과 개인 워크플로우를 관리합니다.

글로벌 디렉토리 구성

~/.claude/
├── CLAUDE.md              # 모든 프로젝트 공통 지침
├── settings.json          # 글로벌 권한 설정
├── projects/              # 프로젝트별 세션 기록
│   ├── project-abc123/    # 프로젝트 해시별 폴더
│   │   ├── memory.json    # 프로젝트 컨텍스트 기억
│   │   └── sessions/      # 대화 기록
│   └── project-def456/
├── commands/              # 개인 글로벌 명령어
│   ├── daily.md           # 일일 루틴
│   ├── report.md          # 보고서 생성
│   └── cleanup.md         # 정리 작업
├── skills/                # 개인 스킬 라이브러리
│   └── code-formatter/    # 개인 코드 포맷팅 규칙
└── templates/             # 자주 사용하는 템플릿
    ├── react-component.md
    └── express-api.md

 

글로벌 CLAUDE.md 예시

# 개인 개발 환경 설정

## 선호 사항
- 언어: 한국어 우선 (기술 용어는 영어 유지)
- 설명 스타일: 구체적이고 실용적인 예시 포함
- 코드 스타일: 명확성 > 간결성

## 개발 환경
- OS: macOS Sonoma
- 터미널: iTerm2 + Oh My Zsh
- 에디터: VS Code
- 주 언어: TypeScript, Python, Go

## 공통 개발 원칙
1. 테스트 작성을 기본으로
2. 문서화는 필수 (특히 복잡한 로직)
3. 성급한 최적화보다 명확한 코드
4. 에러 처리는 명시적으로

## 자주 사용하는 도구
- 버전 관리: Git + GitHub
- 이슈 트래킹: GitHub Issues + Linear
- CI/CD: GitHub Actions
- 컨테이너: Docker + Kubernetes
- 모니터링: Datadog, Sentry

## 선호하는 라이브러리
### JavaScript/TypeScript
- 테스팅: Jest, Playwright
- 빌드: Vite, esbuild
- 상태 관리: Zustand, TanStack Query

### Python
- 웹: FastAPI
- 테스팅: pytest
- 타입 체킹: mypy

## 디버깅 접근법
1. 로그 기반 디버깅 선호
2. 단계별 재현 가능한 테스트 케이스 작성
3. 이분 탐색으로 문제 범위 좁히기

 

실전 활용 시나리오

이제 실제 개발 상황에서 .claude/ 폴더를 어떻게 활용하는지 구체적인 시나리오를 통해 알아보겠습니다.

시나리오 1: 새 프로젝트 시작하기

새로운 React 프로젝트를 시작한다고 가정해봅시다. 팀은 이미 기술 스택과 규칙을 정했고, 이를 Claude Code와 공유하려고 합니다.

Step 1: 프로젝트 초기화

npx create-react-app my-app --template typescript
cd my-app
git init

Step 2: .claude/ 폴더 생성 및 기본 설정

mkdir .claude
mkdir .claude/{rules,commands,skills,agents}

Step 3: CLAUDE.md 작성

# My App - E-commerce Platform Frontend

## Tech Stack
- React 18 with TypeScript
- State: Redux Toolkit + RTK Query
- Styling: Tailwind CSS
- Testing: Jest + React Testing Library
- Build: Create React App

## Project Structure
src/
├── components/     # Reusable UI components
├── features/       # Feature-based modules
├── pages/         # Page components
├── services/      # API services
├── store/         # Redux store
├── hooks/         # Custom hooks
└── utils/         # Utilities

## Key Conventions
- Functional components only
- Props interfaces end with "Props"
- Custom hooks start with "use"
- API calls through RTK Query
- Component files: ComponentName.tsx
- Test files: ComponentName.test.tsx

## Commands
- Start: npm start
- Test: npm test
- Build: npm run build
- Lint: npm run lint

Step 4: 팀 공통 명령어 추가
.claude/commands/component.md:

# Create new React component

Create a new React component with the following structure:

1. Component file: src/components/$ARGUMENTS/$ARGUMENTS.tsx
2. Test file: src/components/$ARGUMENTS/$ARGUMENTS.test.tsx
3. Styles file: src/components/$ARGUMENTS/$ARGUMENTS.module.css
4. Index file: src/components/$ARGUMENTS/index.ts

Include:
- TypeScript props interface
- JSDoc documentation
- Basic unit tests
- Storybook story (if applicable)

Step 5: Git에 커밋

git add .claude/
git commit -m "chore: add Claude Code configuration"

시나리오 2: 버그 수정 워크플로우

프로덕션에서 버그가 발생했고, 이를 신속하게 수정해야 하는 상황입니다.

Step 1: 버그 재현 명령어 실행

/project:reproduce-bug "Users cannot login with email"

Step 2: Claude가 자동으로 실행하는 작업들

1. 관련 코드 검색 (skills/bug-hunter 활성화)
2. 최근 변경 사항 확인
3. 에러 로그 분석
4. 테스트 케이스 실행

Step 3: 수정 제안 받기
Claude가 문제를 파악하고 수정 방안을 제시:

// 문제: 이메일 정규식이 일부 도메인을 거부
// 수정 전:
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

// 수정 후:
const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;

Step 4: 테스트 및 검증

npm test -- --testPathPattern=auth
npm run e2e:auth

시나리오 3: 코드 리뷰 자동화

팀원이 PR을 올렸고, 코드 리뷰가 필요한 상황입니다.

Step 1: PR 체크아웃

gh pr checkout 123

Step 2: 자동 리뷰 실행

/project:review-pr

Step 3: 다중 에이전트 리뷰
Claude가 여러 전문 에이전트를 동시에 실행:

• Security Reviewer: 보안 취약점 검사
• Performance Analyzer: 성능 이슈 확인
• Test Coverage Checker: 테스트 커버리지 검증
• Style Validator: 코딩 컨벤션 준수 확인

Step 4: 종합 리뷰 보고서

## PR #123 Review Summary

### ✅ Approved with suggestions

**Security**: No critical issues found
- Minor: Consider using parameterized queries in UserService

**Performance**: Good
- Suggestion: Add pagination to user list endpoint

**Test Coverage**: 85% (Target: 80%) ✓

**Code Style**: Compliant

### Detailed Feedback
[구체적인 코드 라인별 피드백...]

 

Base Practice

1. CLAUDE.md 작성 팁

DO

• 구체적인 예시 포함
• 우선순위 명확히 명시
• 정기적으로 업데이트
• 팀과 함께 리뷰

DON'T

• 너무 장황하게 작성 (200줄 초과)
• 모호한 표현 사용
• 자주 변경되는 내용 포함
• 민감한 정보 노출

 

2. 성능 최적화

컨텍스트 사용 최적화

• CLAUDE.md는 간결하게
• 자주 사용하지 않는 규칙은 rules/로 분리
• 대용량 참고 자료는 링크로 대체

응답 속도 개선

• 간단한 작업은 경량 모델 사용
• 병렬 처리 가능한 작업 분리
• 캐싱 가능한 정보는 재사용

 

3. 보안 강화

권한 최소화 원칙

{
  // 구체적인 경로와 명령어만 허용
  "allow": [
    "Bash(npm test)",  // "Bash(*)" 대신
    "Write(src/**)",   // "Write" 대신
    "Read(docs/**)"    // 필요한 경로만
  ]
}

민감 정보 보호

• .env 파일은 항상 deny 목록에
• API 키는 환경 변수로
• 개인 정보는 .local 파일에

 

4. 팀 협업 개선

문서화

• 각 규칙의 이유 설명
• 예외 상황 명시
• 변경 이력 기록

리뷰 프로세스

• .claude/ 변경도 PR 리뷰 대상
• 정기적인 규칙 회고
• 피드백 반영 프로세스

 

트러블슈팅 가이드

문제 1: Claude가 규칙을 무시함

증상: CLAUDE.md에 명시한 규칙을 따르지 않음

원인과 해결책

1. 파일이 너무 김 → 200줄 이하로 줄이기
2. 규칙이 상충됨 → 우선순위 명확히
3. 오타나 문법 오류 → YAML frontmatter 검증
4. 캐시 문제 → 세션 재시작

 

문제 2: 명령어가 실행되지 않음

증상: /project:command 입력해도 반응 없음

체크리스트

• 파일 경로 확인 (.claude/commands/command.md)
• 파일명과 명령어명 일치 확인
• 권한 설정 확인 (settings.json)
• 셸 명령어 문법 확인

 

문제 3: 성능 저하

증상: Claude의 응답이 느려짐

최적화 방법

1. 불필요한 규칙 제거
2. 큰 파일은 참조 링크로 대체
3. 복잡한 작업은 단계별로 분리
4. 적절한 모델 선택 (haiku/sonnet/opus)

 

고급 기법과 패턴

1. 다중 에이전트 협업 패턴

복잡한 작업을 여러 전문 에이전트가 협력하여 처리

# .claude/agents/orchestrator.yaml
---
name: Task Orchestrator
model: claude-3-5-opus
---

당신은 작업 조정자입니다.
복잡한 작업을 분석하여 적절한 전문 에이전트에게 할당합니다.

## 에이전트 매핑
- UI 작업 → frontend-expert
- API 작업 → backend-expert
- DB 작업 → database-expert
- 배포 작업 → devops-expert

## 워크플로우
1. 작업 요구사항 분석
2. 하위 작업으로 분해
3. 각 에이전트에게 할당
4. 결과 통합 및 검증

2. 조건부 스킬 실행

특정 조건에서만 실행되는 스킬 정의

# .claude/skills/large-pr-review/SKILL.md
---
name: Large PR Review
description: 대규모 PR 특별 리뷰 프로세스
auto_invoke: true
conditions:
  - files_changed: "> 20"
  - lines_changed: "> 500"
---

대규모 변경이 감지되었습니다.
추가 검토 프로세스를 시작합니다:

1. 아키텍처 영향 분석
2. 성능 영향 평가
3. 단계적 배포 계획 수립
4. 롤백 전략 준비

3. 프로젝트 템플릿 시스템

자주 사용하는 프로젝트 구조를 템플릿화

# ~/.claude/templates/init-react-project.sh
#!/bin/bash

# 프로젝트 생성
npx create-react-app $1 --template typescript
cd $1

# .claude 폴더 복사
cp -r ~/.claude/templates/react-claude/ .claude/

# 프로젝트명 치환
sed -i "s/PROJECT_NAME/$1/g" .claude/CLAUDE.md

# Git 초기화
git init
git add .
git commit -m "chore: initialize project with Claude Code config"

echo "프로젝트 초기화 완료!"

 

마무리

.claude/ 폴더는 단순한 설정 디렉토리가 아니라, Claude Code와의 효과적인 협업을 위한 커뮤니케이션 프로토콜입니다. 잘 구성된 .claude/ 폴더는 다음과 같은 이점을 제공합니다.

1. 일관성: 팀 전체가 동일한 규칙과 패턴 따르기
2. 자동화: 반복적인 작업의 자동 처리
3. 품질: 자동 검증과 리뷰로 코드 품질 향상
4. 생산성: 컨텍스트 전환 비용 감소
5. 지식 공유: 베스트 프랙티스의 문서화와 전파

문서를 참고하면 처음에는 기본적인 CLAUDE.md와 몇 가지 명령어로 시작하여, 프로젝트가 성장함에 따라 점진적으로 더 정교한 설정을 추가해 나가는 것을 권장하고 있습니다.

가장 중요한 것은 .claude/ 폴더가 살아있는 문서라는 점입니다. 프로젝트가 진화함에 따라 지속적으로 업데이트하고, 팀의 피드백을 반영하여 개선해 나가야 합니다. 이를 통해 Claude Code는 단순한 AI 도구가 아닌, 진정한 팀원으로서 프로젝트에 기여할 수 있게 됩니다.

---

참고 문서

• Daily Dose of Data Science - Anatomy of the .claude/ Folder
• Claude Code Official Documentation
• GitHub - Anthropics Claude Code