CLAUDE.md는 프로젝트 루트에 있는 일반 마크다운 파일입니다. Claude는 모든 세션에서 이 파일을 자동으로 읽습니다. 프로젝트 수준: ./CLAUDE.md. 전역(모든 프로젝트): ~/.claude/CLAUDE.md. 프로젝트가 전역을 재정의합니다. 전역 파일은 기본값을, 프로젝트 파일은 이 저장소의 세부 정보를 담습니다.
이 파일을 프로젝트에 대해 아무것도 모르는 고도로 숙련된 계약자에게 제공하는 온보딩 문서라고 생각하십시오. 이 파일이 없으면 모든 세션은 Claude가 스택, 명명 규칙 및 과거 결정을 추측하는 것으로 시작됩니다. 추측은 코드가 되고, 코드는 버그가 됩니다. CLAUDE.md는 이러한 연쇄를 단축시킵니다. 파일은 기억하든 안 하든 작동하기 때문에 영리한 프롬프트보다 낫습니다.
제 역할을 하는 다섯 가지 섹션. 각 섹션은 3~6개의 글머리 기호로 구성됩니다.
1. 스택: 프레임워크, DB, 인증, 이메일, 버전 포함. "Next.js 16, Neon의 Postgres, 이메일은 Resend, 결제는 Stripe, 인증은 Supabase."
2. 경로: 파일 위치. "/app에 앱, /actions에 서버 액션, /app/api/v2 아래에 API, /components/ui에 공유 컴포넌트."
3. 규칙: 당신에게는 명백하지만 Claude에게는 보이지 않는 규칙. "금액은 센트(정수), 날짜는 UTC, 파일 이름은 케밥 케이스, ID는 UUID v4."
4. 보안 규칙: 절대 발생해서는 안 되는 일. "API 키를 절대 로깅하지 마십시오. 모든 SQL을 매개변수화하십시오. 모든 공개 엔드포인트에 속도 제한을 적용하십시오."
5. 하지 마십시오: 이미 빠졌던 함정. "묻지 않고 종속성을 추가하지 마십시오. 로컬에서 프로덕션에 대해 마이그레이션을 실행하지 마십시오."
작업된 템플릿입니다. 실제 프로젝트 세부 정보로 교체하십시오.
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth with Google OAuth
## Routes
- App in /app, actions in /actions, API under /app/api/v2
## Conventions
- Money in cents (int), dates UTC, filenames kebab-case
- IDs: UUID v4. Boolean columns: is_ or has_ prefix
## Security Rules
- Never log secrets, parameterize SQL
- Rate-limit all POST/PUT/DELETE endpoints (10/min per IP)
- New Supabase tables ship with RLS policies in same commit
## Don't Do This
- Don't add deps without asking
- Don't run migrations from local against prod
- Don't use select(*)구체성에 주목하십시오. "IP당 10회/분"은 실행 가능합니다. "속도 제한 사용"은 그렇지 않습니다.
가장 비싼 실수: 구체적으로 들리지만 모호한 규칙.
약함: "돈을 신중하게 다루십시오." Claude는 최선이라고 생각하는 방식으로 돈을 처리할 것이며, 이는 시스템과 일치하지 않을 수 있습니다.
강함: "모든 금액은 정수 센트입니다. 부동 소수점은 절대 사용하지 마십시오. 원시 센트를 표시하지 마십시오. 100으로 나누고 통화 기호로 서식을 지정하십시오." 저장 유형, 처리 규칙, 표시 규칙. 모호함이 없습니다.
두 번째 실수: 제약 대신 열망을 작성하는 것. "우리는 깨끗하고 읽기 쉬운 코드를 중요하게 생각합니다"는 열망입니다. "200줄이 넘는 파일은 모듈로 분할됩니다"는 제약입니다. 열망은 판단을 요구하고, 제약은 일관된 동작을 생성합니다. CLAUDE.md를 제약으로 채우십시오.
CLAUDE.md는 살아있는 문서입니다. 업데이트가 필요하다는 세 가지 신호:
동일한 컨텍스트를 두 번째로 프롬프트에 붙여넣습니다. 다시 말하고 있다면 CLAUDE.md에 속합니다.
Claude가 규칙으로 방지할 수 있었던 실수를 합니다. 실수가 규칙입니다. 다음 세션 전에 작성하십시오.
동료에게 규칙을 설명합니다. 소리 내어 말할 가치가 있다면 자동으로 로드할 가치가 있습니다.
길이 규율: 섹션당 3~6개의 글머리 기호; 8개를 넘으면 섹션을 분할하십시오. 너무 길어서 훑어볼 수 없는 CLAUDE.md는 중요한 규칙이 묻히기 때문에 작동을 멈춥니다. 올바른 6줄은 60줄의 채우기보다 낫습니다.
약 300줄을 넘어서 확장: @filename 포함을 사용하여 주제 파일로 분할:
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.md각 주제 파일은 집중된 상태를 유지하고, 루트는 짧게 유지됩니다.
CLAUDE.md를 버전 제어에 커밋하십시오. 규칙은 PR에서 검토 가능해지고, 새로운 팀원은 Claude가 이미 구성된 상태로 저장소를 복제합니다. 각 Don't Do This 규칙을 해당 버그 수정과 동일한 커밋에 추가하십시오. 한 가지 주의할 점: 커밋하기 전에 머신별 경로를 일반화하십시오.
CLAUDE.md와 프롬프트 중 어디에 속하는가? 폭발 반경. 규칙이 수정하는 데 1시간 이상 걸리는 종류의 실수를 방지한다면 CLAUDE.md에 들어갑니다. 세션별 지침은 프롬프트에 남아 있습니다.
10분 안에 첫 CLAUDE.md를 만드십시오. Claude에게 이 프롬프트를 제공하십시오.
"저는 이 스택으로 프로젝트를 위해 Claude Code를 설정하고 있습니다: [스택]. 새로운 사람이 모를 주요 규칙: [규칙]. 절대 위반해서는 안 되는 보안 규칙: [규칙]. 이전에 버그를 일으킨 것: [함정]. 스택, 경로, 규칙, 보안 규칙, 하지 마십시오의 다섯 가지 섹션으로 CLAUDE.md 초안을 작성하십시오."
첫 번째 초안은 80%를 제공합니다. Claude가 놓친 부분으로 다듬으십시오. 나머지 20%는 프로젝트에 대한 실제 경험에 특정한 것입니다.
프로젝트 루트의 CLAUDE.md는 스택, 경로, 규칙, 보안 규칙 및 함정을 모든 세션에 로드합니다. 교차 프로젝트 기본값을 위한 전역 파일, 재정의를 위한 프로젝트 파일. 열망이 아닌 제약. 올바른 6줄은 60줄보다 낫습니다. Claude가 작성된 규칙으로 방지할 수 있었던 실수를 할 때마다 업데이트하십시오.