CLAUDE.md로 프로젝트 설계

동작하는 코드

프로젝트 루트에 CLAUDE.md 파일을 만들어보세요:

> 이 프로젝트를 분석해서 CLAUDE.md 파일을 만들어줘.
> 프로젝트 구조, 기술 스택, 개발 컨벤션을 포함해줘.

Claude가 프로젝트를 분석하고 CLAUDE.md를 생성합니다. 이제 새 세션을 시작하면 Claude가 이 파일을 자동으로 읽습니다:

claude

> 이 프로젝트에서 새 API 엔드포인트를 추가하려면 어떻게 해야 해?

CLAUDE.md에 정의된 컨벤션에 맞춰서 안내해줍니다.

직접 수정하기

Claude가 만든 CLAUDE.md를 열어서 직접 수정해보세요. 좋은 CLAUDE.md의 구조:

# 프로젝트 이름

## 기술 스택

- 프레임워크: Next.js 14
- 언어: TypeScript (strict mode)
- DB: PostgreSQL + Prisma
- 테스트: Jest + React Testing Library

## 개발 명령어

- `npm run dev` — 개발 서버
- `npm run build` — 빌드
- `npm test` — 테스트 실행
- `npm run lint` — 린팅

## 코딩 컨벤션

- 커밋 메시지: Conventional Commits
- 함수명: camelCase
- 컴포넌트: PascalCase
- 파일명: kebab-case
- 에러 처리: 커스텀 에러 클래스 사용 (src/errors/)

## 프로젝트 구조

- src/app/ — 페이지 라우팅
- src/components/ — 재사용 컴포넌트
- src/lib/ — 유틸리티, DB 클라이언트
- src/api/ — API 라우트 핸들러

## 주의사항

- .env 파일은 절대 커밋하지 않는다
- DB 마이그레이션은 반드시 PR 리뷰 후 적용
- 외부 API 키는 환경 변수로만 관리

팀의 실제 규칙을 여기에 담으세요.

"왜?" — CLAUDE.md는 AI의 메모리

Claude Code는 매 세션마다 새로 시작합니다. 이전 대화를 기억하지 못합니다. CLAUDE.md는 이 문제를 해결합니다. 세션이 시작될 때 자동으로 읽히기 때문에, 매번 같은 규칙을 반복 설명할 필요가 없습니다.

CLAUDE.md의 계층 구조

| 위치 | 범위 | 용도 | | ------------------------------ | ------------- | ---------------------------------- | | ~/.claude/CLAUDE.md | 모든 프로젝트 | 개인 선호도 (에디터 설정, 언어 등) | | 프로젝트 루트 /CLAUDE.md | 현재 프로젝트 | 프로젝트 규칙, 기술 스택 | | 하위 디렉토리 /src/CLAUDE.md | 해당 디렉토리 | 디렉토리별 특수 규칙 |

Claude는 현재 작업 디렉토리에서 상위로 올라가며 모든 CLAUDE.md를 읽습니다. 더 구체적인 규칙이 상위 규칙보다 우선합니다.

좋은 CLAUDE.md 작성 원칙

1. 구체적으로 — "깨끗한 코드를 작성해" 대신 "함수는 20줄을 넘지 않는다"
2. 예시 포함 — 추상적인 규칙보다 구체적인 코드 예시가 효과적
3. 갱신 유지 — 프로젝트가 변할 때 CLAUDE.md도 업데이트

심화 학습