CLAUDE.md는 AI 페어 개발의 설계도 — 프로젝트 구조·코딩 규칙·금지 사항을 담아 세션마다 같은 결과를 내는 방법.
CLAUDE.md — AI 파트너에게 주는 설계도
새 개발자가 팀에 합류하면 프로젝트를 이해시키는 데 몇 주가 걸립니다. Claude Code는 매 세션마다 새로 시작하는 새 개발자와 같습니다. CLAUDE.md는 이 문제를 해결합니다 — 프로젝트 루트에 두면 Claude가 모든 세션 시작 시 자동으로 읽고 프로젝트 컨텍스트를 복원합니다. 잘 만든 CLAUDE.md 하나가 매 세션의 온보딩 시간을 90% 줄여줍니다.
CLAUDE.md가 없을 때 벌어지는 일
# CLAUDE.md 없는 세션
you: "로그인 API에 rate limiting 추가해줘"
claude: "어떤 프레임워크를 쓰나요? Express인가요 Fastify인가요?"
you: "Next.js App Router야"
claude: "인증은 어떤 방식인가요? JWT인가요?"
you: "Supabase Auth 써"
claude: "rate limiting 라이브러리는 뭐 선호하세요?"
... (매번 반복)# CLAUDE.md 있는 세션
you: "로그인 API에 rate limiting 추가해줘"
claude: "app/actions/auth.ts 확인했습니다. upstash/ratelimit 사용해서
Supabase 세션 기반으로 분당 5회 제한 추가하겠습니다." (바로 실행)CLAUDE.md 핵심 구성 요소
# [프로젝트명] 마스터 컨텍스트
## 프로젝트 한 줄 요약
Next.js 16 App Router + Supabase + TypeScript 채용 플랫폼
## 기술 스택
- Frontend: Next.js 16, TypeScript, Tailwind CSS
- Backend: Supabase (PostgreSQL + Auth + Storage + Realtime)
- 패키지 관리: npm
- 배포: Vercel (main → 자동 배포)
## 핵심 경로
app/ ← 모든 페이지
app/actions/ ← Server Actions (서버 전용 로직)
components/ ← 재사용 컴포넌트
utils/ ← 유틸리티 함수
supabase/migrations/ ← DB 변경 이력 (필수 생성)
messages/ ← i18n 번역 파일 (ko/en/ja)
types/supabase.ts ← DB 타입 자동생성 (수정 금지!)
## 코딩 규칙
- TypeScript strict 모드 — any 사용 금지 (Supabase Admin은 예외)
- Server Action은 반드시 getAdminInfo()로 관리자 인증
- DB 변경 시 supabase/migrations/ 파일 필수 생성
- 컴포넌트는 'use client' 최소화 — 서버 컴포넌트 우선
## 절대 하지 말 것
- types/supabase.ts 직접 수정
- middleware.ts 삭제 또는 수정
- .env.local git 커밋
- git push origin main (hotfix 제외)섹션별 설계 원칙
1. 한 줄 요약은 진짜 한 줄로
Claude가 가장 먼저 읽는 부분입니다. "Next.js + Supabase 채용 플랫폼"처럼 기술 스택과 도메인을 함께 담으세요. 이 한 줄이 모든 판단의 기준이 됩니다.
2. 핵심 경로는 파일 트리 형식으로
Claude가 파일을 찾아야 할 때 CLAUDE.md의 경로 정보를 먼저 참조합니다. 실제 디렉토리 구조와 일치하게 유지하세요. 어긋나면 오히려 방해가 됩니다.
3. 규칙보다 금지 사항이 더 중요
"TypeScript를 써라"보다 "types/supabase.ts를 수정하지 마라"가 훨씬 구체적이고 효과적입니다. Claude가 실수할 수 있는 지점을 금지 목록으로 명시하세요.
4. 현재 작업 상태 섹션 추가
장기 프로젝트라면 현재 진행 상황을 적어두면 세션 복원이 빠릅니다.
## 현재 작업 상태 (2026-06-17 기준)
- Phase 1 (채용 플랫폼) 진행 중
- 완료: 회원가입·로그인·공고 등록·지원 흐름
- 진행 중: 알림 시스템 개선
- 다음: 결제 모듈 (Toss Payments)여러 CLAUDE.md 계층 구조
Claude는 CLAUDE.md를 계층적으로 읽습니다. 루트의 전체 규칙 + 서브디렉토리의 세부 규칙을 조합합니다.
프로젝트루트/CLAUDE.md ← 전체 프로젝트 규칙
app/admin/CLAUDE.md ← 어드민 전용 규칙
supabase/migrations/CLAUDE.md ← 마이그레이션 작성 규칙# app/admin/CLAUDE.md 예시
# 어드민 전용 규칙
모든 Server Action은 utils/admin-auth.ts의 getAdminInfo() 호출 필수.
RLS를 우회하는 createAdminClient()는 어드민 영역에서만 사용.
어드민 페이지는 app/admin/(protected)/ 아래에만 위치.CLAUDE.md 유지보수 전략
- 코딩 규칙 변경 시: 코드와 동시에 CLAUDE.md 업데이트. 코드만 바꾸면 Claude가 구버전 패턴을 계속 사용.
- 새 패키지 추가 시: 기술 스택 섹션에 추가. "왜 이 패키지를 쓰는가"를 한 줄 코멘트로.
- 오류 패턴 발견 시: "절대 하지 말 것" 섹션에 즉시 추가. Claude가 같은 실수를 반복하면 규칙이 부족한 것.
- 정기 검토: 월 1회 CLAUDE.md와 실제 코드베이스 일치 여부 확인.
CLAUDE.md는 팀의 집단 지식을 코드화한 문서입니다. "왜 이렇게 결정했는지"를 잊어버리기 전에 기록하고, Claude가 그 판단을 따르도록 만드세요. 6개월 후의 나 자신에게 보내는 메모이기도 합니다.
핵심 정리
- CLAUDE.md 없으면 매 세션 온보딩 반복 — 프로젝트 루트에 두면 Claude가 자동 로드, 세션 시작 시간 90% 단축
- 규칙보다 금지 사항이 효과적 — "수정 금지" "삭제 금지" 같은 구체적 제약이 모호한 원칙보다 실수를 막는 데 유리
- 계층 구조 활용 — 루트 CLAUDE.md(전체 규칙) + 서브디렉토리 CLAUDE.md(세부 규칙)로 구역별 특수 규칙 관리
관련 검색어 · CLAUDE.md 작성법 · 클로드 코드 프로젝트 설정 · Claude Code 온보딩 · AI 개발 컨텍스트 · 클로드 코드 완벽 마스터 · 프로젝트 AI 설정