CLAUDE.md 작성법 — AI 코딩 어시스턴트에게 프로젝트를 가르치는 기술

1. CLAUDE.md란 무엇인가

CLAUDE.md는 Claude Code(Anthropic의 AI 코딩 CLI)가 프로젝트를 처음 열었을 때 자동으로 읽는 프로젝트 지침 파일입니다. 마치 새 팀원에게 전달하는 온보딩 문서와 같습니다.

AI는 이 파일을 통해 프로젝트의 기술 스택, 코딩 컨벤션, 금지 패턴, 비즈니스 컨텍스트를 이해합니다. 잘 작성된 CLAUDE.md는 AI의 코드 품질과 작업 효율을 크게 높여줍니다.

2. 효과적인 문서 구조

# PROJECT_NAME

## 프로젝트 개요
회사/제품 설명 1~3문장. AI가 맥락을 파악할 수 있도록.

## 기술 스택
- Backend: Laravel 11 (PHP 8.2)
- Frontend: Vue 3 (Blade 인라인)
- DB: MySQL (직접 SQL 관리, Migration/Model 미사용)
- Build: Vite + SCSS

## 코딩 스타일
### 명명 규칙
- 모든 코드: snake_case (변수, 함수, DB 컬럼)
- Laravel 파일명: PascalCase 유지

### 금지 패턴
- Bootstrap 유틸리티 단독 사용 금지 (mb-4, d-flex 등)
- Vue data에 _/$  접두사 금지
- console.log를 프로덕션 코드에 남기지 않을 것

## 디렉토리 구조
app/Http/Controllers/  ← 컨트롤러
resources/scss/        ← SCSS (app.scss가 진입점)
resources/views/       ← Blade 템플릿

## 중요 원칙
- DB 접근은 가능하면 APIController 통해 처리
- 모달 닫기: 외부 클릭 금지, [x] 버튼만 허용

3. 코딩 컨벤션 명시

AI에게 가장 중요한 것은 구체적이고 명확한 금지 / 허용 패턴입니다. 모호한 "좋은 코드를 작성하라" 같은 지침은 효과가 없습니다.

## 원칙
- 클린 코드 작성
- 재사용 가능한 컴포넌트
- 좋은 변수명 사용

## 원칙
- 변수명: snake_case 필수
  Bad: userName / Good: user_name
- Bootstrap mb-4 등 유틸리티 클래스
  단독 사용 금지
- Vue data 프로퍼티: _ 접두사 금지

4. 프로젝트 컨텍스트 전달

AI가 프로젝트의 왜를 이해하면 더 적절한 결정을 내립니다. 특히 비표준 패턴을 사용하는 이유를 설명하세요.

## 데이터베이스 구조

### 왜 Eloquent/Migration을 사용하지 않는가
이 프로젝트는 레거시 WordPress DB와 신규 테이블이 혼재합니다.
Migration 사용 시 기존 테이블 충돌 위험이 있어
직접 SQL로 관리하는 방식을 채택했습니다.

DB 접근: DB::table() 또는 APIController를 통해
절대 금지: Eloquent Model 생성, Migration 파일 생성

5. Override 규칙 활용

CLAUDE.md에 IMPORTANT, CRITICAL, NEVER 같은 강조 키워드를 사용하면 AI가 더 엄격하게 준수합니다.

## 중요 원칙 (CRITICAL)

IMPORTANT: "20년 이상 경력" 같은 문구 절대 사용 금지
  → 2023년 설립 스타트업이므로 AI 혁신 내러티브만 사용

NEVER: php artisan make:model / make:migration 실행 금지

ALWAYS: SCSS 스타일은 반드시 _showcase.scss 등
  해당 페이지 파일에 작성 (app.scss 직접 수정 금지)

6. 실제 예시 패턴

동지커뮤니케이션이 실제로 사용 중인 CLAUDE.md에서 가장 효과적인 섹션은 코딩 예시 비교입니다.

## API CRUD 패턴

// INSERT (id 없음)
fetch('/api/contact/save', {
  method: 'POST',
  headers: {'Content-Type':'application/json'},
  body: JSON.stringify({ name: '홍길동', email: 'test@test.com' })
});

// UPDATE (id 있음)
fetch('/api/post/save', {
  method: 'POST',
  body: JSON.stringify({ id: 10, title: '수정된 제목' })
});

## 모달 닫기 패턴
// 외부 클릭으로 닫기 금지 (정책)
// [x] 버튼으로만 닫기
<button @click="show_modal = false"><i class="fa fa-xmark"></i></button>