CLAUDE.md 작성 가이드와 복붙용 템플릿

CLAUDE.md는 Claude Code가 프로젝트 시작 시 자동으로 읽는 컨텍스트 파일입니다. 잘 쓴 CLAUDE.md 한 장이 매번 같은 설명을 반복하는 수고를 없애고, 결과 품질을 크게 끌어올립니다. 이 가이드는 작성 원칙·필수 섹션·복붙 템플릿·자주 하는 실수를 정리합니다.

CLAUDE.md란 무엇인가

Claude Code가 프로젝트 루트에서 자동으로 인식하는 마크다운 파일입니다. 새 세션이 시작될 때마다 이 파일이 시스템 프롬프트에 포함되어, 모델이 프로젝트의 맥락·관례·금기를 미리 알게 됩니다. 비유하자면 새 팀원에게 건네는 온보딩 문서입니다.

위치: 프로젝트 루트의 CLAUDE.md (필수). 추가로 서브디렉토리에도 둘 수 있음 (해당 폴더 작업 시 우선 적용)
크기 권장: 너무 길면 컨텍스트 낭비. 300~800줄 정도가 균형점. 1,000줄 넘으면 분리 고려
형식: 마크다운. 모델이 잘 읽도록 헤더·리스트·코드 블록 적극 활용

꼭 넣어야 할 6개 섹션

1. 프로젝트 개요

"이게 무슨 프로젝트인가"를 한두 문단으로. 너무 길게 쓰지 않습니다 — 정체성과 목적만.

# 프로젝트
이 레포는 [용도]를 위한 [언어] 기반 [형태]입니다.
주요 사용자는 [대상]이며, 가장 중요한 제약은 [제약]입니다.

2. 기술 스택

모델이 어떤 도구를 가정해도 되는지 명확히. 버전까지 적으면 베스트.

## 스택
- Next.js 16 (App Router, Turbopack)
- TypeScript 5, Tailwind 4, shadcn/ui
- Supabase (PostgreSQL)
- 패키지매니저: pnpm

3. 디렉토리 구조

주요 폴더의 역할을 1줄씩. 모델이 "어디에 새 파일을 둘지" 정확히 알게 됩니다.

## 구조
- src/app/[locale] — 다국어 라우트
- src/lib/uc — 비즈니스 로직 (articles, categories)
- src/components/uc — 도메인 컴포넌트

4. 코딩 컨벤션

모델이 자주 어기는 부분을 명시적으로. "~하지 마" 식의 금지 규칙이 효과가 좋습니다.

## 규칙
- 새 컴포넌트는 항상 TypeScript + named export
- Server Component 우선, Client Component는 "use client" 필수
- 절대 inline style 쓰지 말기 (Tailwind만)
- 외부 라이브러리 추가는 사전에 묻기

5. 데이터 모델·API 패턴

DB 테이블 이름과 주요 필드, API 라우트 패턴을 한 곳에. 매번 schema 파일 찾는 수고를 없앱니다.

6. 자주 쓰는 명령

## 명령
- 개발 서버: pnpm dev
- 타입 체크: pnpm type-check
- 빌드: pnpm build
- 배포: git push origin main → Railway 자동

고급 활용 패턴

금지 규칙은 적극적으로

모델은 "권장"보다 "금지"에 더 잘 반응합니다. 회피해야 할 것을 명확히 적으세요.

## 금지
- console.log를 production 코드에 남기지 않기
- any 타입 절대 금지 (unknown 사용)
- 빈 catch 블록 금지 (반드시 logging 또는 rethrow)

"왜"를 같이 적기

규칙만 적으면 모델이 비슷한 상황에서 일반화하지 못합니다. 이유를 함께 적으세요.

- await createClient() 대신 createPublicClient() 사용
  이유: cookies()를 부르면 페이지가 dynamic 강제돼 ISR 캐싱이 깨짐

예시 코드 넣기

한 줄의 좋은 예시가 열 줄의 설명보다 강력합니다.

## 새 API 라우트 패턴
\`\`\`ts
// src/app/api/community/example/route.ts
import { createClient } from "@/lib/supabase/server";

export async function POST(req: Request) {
  const supabase = await createClient();
  const { data: { user } } = await supabase.auth.getUser();
  if (!user) return new Response("Unauthorized", { status: 401 });
  // ...
}
\`\`\`

자주 하는 실수

너무 길게 작성: 1,000줄 넘는 CLAUDE.md는 컨텍스트만 잡아먹고 효과가 떨어집니다. 필요한 핵심만 남기세요.
중복: 같은 규칙을 여러 섹션에서 반복하면 모델이 우선순위를 혼동합니다.
설명 없는 예시: 코드 예시만 던지지 말고 "이게 권장 패턴인 이유"를 한 줄 같이 적기.
업데이트 안 함: 프로젝트 구조 바뀌었는데 CLAUDE.md가 오래되면 모델이 잘못된 가정으로 작업합니다. 큰 리팩토링 후 함께 갱신.
비밀 정보 넣기: API 키·비밀번호 절대 금지. CLAUDE.md는 git에 들어가는 공유 문서입니다.

복붙용 미니 템플릿

# 프로젝트
[1~2문단 — 이 프로젝트가 무엇이고 누구를 위한 것인가]

## 스택
[버전 포함 5~10줄]

## 구조
[주요 폴더 5~10개와 한 줄 설명]

## 규칙
- [코딩 컨벤션 5~10개]

## 금지
- [절대 하면 안 되는 것 3~5개]

## 명령
- 개발: [...]
- 빌드: [...]
- 배포: [...]

## 자주 쓰는 패턴
[코드 예시 2~3개]

## 알아두면 좋은 도메인 지식
[프로젝트 특수 사항 — 회사·서비스·법령 등]