CLAUDE.md란

• 세션 시작 시 Claude가 자동으로 읽는 마크다운
• 프로젝트, 사용자 또는 조직과 같은 범위로 Claude에 지속적인 지침을 제공할 수 있음
  • Claude는 이전 세션에 대한 기억 없이 세션을 시작함
• 컨벤션, 워크 플로우, 스타일을 정의해서 반복적으로 클로드에게 같은 지시를 내리지 않아도 됨

/init

(하위 내용은 /init 후 수행한 작업에 대해 Claude가 설명해준것. 아티클과 무관.)

미래의 Claude 인스턴스가 이 레포에서 빠르게 생산적으로 일할 수 있도록, 코드를 여러 파일 읽어야만 알 수 있는 맥락을 미리 요약

1. 코드베이스 탐색 — 파일 트리를 순회하며 전체 구조 파악
2. 핵심 파일 읽기 — 아키텍처 이해에 필요한 파일들을 직접 읽음
3. 기존 문서 확인 — README.md, .cursor/rules/, .github/copilot-instructions.md 등 이미 있는 문서에서 중요 내용 추출
4. CLAUDE.md 작성 — 수집한 정보를 바탕으로 아래 항목에 집중해서 작성
   - Commands: build·dev·lint 등 자주 쓰는 명령어
   - Architecture: 파일 하나만 봐서는 알기 어려운 "큰 그림" (데이터 흐름, 모듈 간 관계, 패턴 등)

포함하지 않는 것

• 쉽게 유추 가능한 파일 목록이나 구조 나열
• 일반적인 개발 관행 (테스트 작성, 에러 처리 등)
• 코드 내용과 중복되는 설명

/init을 통해 생성된 내용 중에 중요하지 않은 것들은 제거 필요.

CLADE.md에 포함시켜야 할 내용

• 프로젝트 컨텍스트
  • 어떤 성격의 프로젝트인지 설명
• 코드 스타일
  • 구체적으로 선호하는 서식 및 패턴
• 명령어
  • 테스트 실행, 빌드, 린트, 배포 방법 관련 명령어
• 주의 사항
  • 프로젝트별 주의 사항. 수정하면 안 되는 파일 등

# 프로젝트: ShopFront
App Router, Stripe 결제, Prisma ORM을 사용하는 Next.js 14 전자상거래 애플리케이션입니다.

## 코드 스타일

- TypeScript strict 모드 사용, `any` 타입 금지
- default export 대신 named export 사용
- CSS: Tailwind 유틸리티 클래스 사용, 커스텀 CSS 파일 금지

## 명령어

- `npm run dev`: 개발 서버 시작 (포트 3000)
- `npm run test`: Jest 테스트 실행
- `npm run test:e2e`: Playwright end-to-end 테스트 실행
- `npm run lint`: ESLint 검사
- `npm run db:migrate`: Prisma 마이그레이션 실행

## 아키텍처

- `/app`: Next.js App Router 페이지 및 레이아웃
- `/components/ui`: 재사용 가능한 UI 컴포넌트
- `/lib`: 유틸리티 및 공유 로직
- `/prisma`: 데이터베이스 스키마 및 마이그레이션
- `/app/api`: API 라우트

## 중요 사항

- .env 파일은 절대 커밋하지 마세요
- /app/api/webhooks/stripe의 Stripe webhook 핸들러는 반드시 서명을 검증해야 합니다
- 제품 이미지는 로컬이 아닌 Cloudinary에 저장됩니다
- 인증 플로우에 대한 자세한 내용은 @docs/authentication.md를 참고하세요

CLAUDE.md 작성 주의 사항

• 300줄 미만 권장. 컨텍스트 토큰 소모.
  • 코드베이스에 복잡한 규칙이 있는 경우 예외
• 특정 상황에서만 중요한 정보는 별도의 파일에 저장해 두고 참조
  • See @README.md for project overview
• 핵심 내용은 CLAUDE.md 에 유지
• 주제별 상세 지침은 별도의 파일로 옮겨 @imports

.claude/rules/

your-project/
├── .claude/
│   ├── CLAUDE.md           # 주요 프로젝트 지침
│   └── rules/
│       ├── code-style.md   # 코드 스타일 가이드라인
│       ├── testing.md      # 테스트 컨벤션
│       └── security.md     # 보안 요구사항

• 디렉터리에 있는 모든 마크다운 파일은 메인 CLAUDE.md 파일과 동일한 우선순위로 자동 로드
• 도메인이 명확하게 구분된 대규모 팀 적합

모듈 특성별로 컨텍스트 관리

• 작업 위치에 따라 관련 컨텍스트 로드
• api, components 등 폴더 별로  CLAUDE.md 를 두어 모듈 특성별로 다른 규칙 적용 가능
• 모노레포나 모듈이 명확하게 구분된 프로젝트에 유용

CLAUDE.md 관리법

• PR에서 패턴 위반을 발견하면 CLAUDE.md에 규칙을 추가해서 관리

GitHub Action에서 CLAUDE.md 관리 자동화 (아티클 인용)

Claude Code GitHub 액션( /install-github-action 로 설치)을 사용하고 있다면, PR 댓글에 _@claude를 직접 태그하여 이러한 업데이트를 요청할 수 있습니다. 예를 들어 "@_claude CLAUDE.md에 다음 내용을 추가해 주세요: enum은 절대 사용하지 말고, 항상 문자열 리터럴 유니온을 선호하세요."와 같이 작성하면 됩니다. 클로드는 파일을 업데이트하고 PR의 일부로 변경 사항을 커밋합니다. Boris Cherny가 이 워크플로를 공유해 주었고 , 저는 이 워크플로를 CLAUDE.md 유지 관리 방식의 일부로 활용하고 있습니다.

모범 사례

• 프로젝트가 무엇인지 한 줄로 설명하는 것으로 시작하세요.
• 코드 스타일 선호 사항을 구체적이고 실행 가능하게 만드세요.
• 주요 명령어(테스트, 빌드, 린트, 배포)를 포함하세요.
• 실수를 방지할 수 있도록 주의 사항을 충분히 자세히 알려주세요.
• 300줄 이하로 유지하거나, 모든 줄이 그 자리에 있을 만한 가치가 있도록 하세요.
• 자세한 안내를 @import한 파일로 옮기세요.
• 오래되었거나 최신 지침과 충돌하는 내용은 모두 제거하십시오.
• 정말 중요한 규칙만 강조 표시하세요.
• 작업 시작 전에만 지침을 추가하지 말고, 작업하면서 동시에 지침을 추가하세요.
• PR 리뷰에서 규칙(컨벤션)이 발견되면 업데이트하세요.
• 오래되었거나 상충되는 규칙이 있는지 정기적으로 검토하십시오.

규모가 큰 프로젝트의 경우:

• 서로 다른 규칙을 가진 하위 디렉터리에는 별도의 CLAUDE.md 이 필요할 수 있습니다.
• 규칙을 .claude/rules/ 파일로 분리하면 팀 간 소유권을 더 명확하게 할 수 있습니다.

참고 아티클

# CLAUDE.md 완벽 가이드