CLAUDE.md 완전 정복 - 기본 구문과 섹션 설계

기술 스택·코딩 규약·금지 사항을 AI가 100% 따르게 만드는 템플릿

Mar 20. 2026

CLAUDE.md 작성에 엄격한 포맷 규정은 없습니다. 마크다운으로 작성하면 Claude Code가 내용을 이해합니다. 하지만 구조를 잘 정리해 두면 AI의 이해 정확도가 올라가고, 팀원이 파일을 유지보수할 때도 훨씬 편해집니다.

이 장에서는 실전에서 바로 쓸 수 있는 섹션 구성 패턴을 소개합니다.

섹션의 기본 구조

효과적인 CLAUDE.md는 다음 5가지 섹션으로 구성합니다.

# 프로젝트 개요
（이 프로젝트가 무엇인지, 1~2문장으로）

## 기술 스택
（사용하는 프레임워크·라이브러리·버전）

## 코딩 규약
（코드 작성 방식의 규칙）

## 커맨드
（빌드·테스트·배포 실행 방법）

## 금지 사항
（해서는 안 되는 것）

각 섹션을 순서대로 살펴보겠습니다.

프로젝트 개요

첫 번째 섹션은 이 프로젝트가 무엇을 하는지를 AI에게 전달하는 곳입니다.

# 쇼핑몰 판매자 관리 대시보드

Next.js 15 + Supabase로 구축한 중소 쇼핑몰 판매자용 관리 화면.
상품 관리, 주문 관리, 고객 관리, 매출 분석 4가지 기능을 제공한다.

여기서 핵심은 비즈니스 컨텍스트를 포함하는 것입니다. "쇼핑몰 판매자 관리 화면"이라고 한 줄 써두는 것만으로, Claude Code는 "상품에는 SKU가 있다" "주문에는 처리 상태가 있다" "배송비 계산 로직이 있을 것이다"와 같은 업무 지식을 스스로 전제로 동작합니다.

기술 스택만 나열하고 비즈니스 맥락을 생략하면, AI는 단순히 코드를 생성하는 수준에 머물고 맙니다. 프로젝트가 해결하려는 문제와 사용자를 명시해 두면 AI의 제안 품질이 눈에 띄게 달라집니다.

기술 스택

사용하는 프레임워크와 버전을 명시합니다.

## 기술 스택

- 프레임워크: Next.js 15 (App Router)
- 언어: TypeScript 5.x (strict mode)
- DB: Supabase (PostgreSQL)
- 인증: Supabase Auth
- 스타일링: Tailwind CSS v4
- 테스트: Vitest + Testing Library
- 패키지 매니저: pnpm

버전 번호를 반드시 기재하세요. Claude Code가 오래된 API나 deprecated된 패턴을 사용하는 실수를 막을 수 있습니다. 예를 들어 "Next.js 15"라고 쓰면 App Router 기반 코드를 생성하지만, 버전을 생략하면 구버전 Pages Router 패턴이 섞여 나오는 경우가 생깁니다.

국내 서비스 환경에서 자주 추가되는 항목들:

## 기술 스택 (국내 서비스 추가 예시)

- 소셜 로그인: 카카오 로그인 SDK, 네이버 로그인 API
- 결제: 토스페이먼츠 v2 SDK
- 알림: 카카오 알림톡 (알리고 API)
- 지도: 카카오맵 SDK
- 전화번호 인증: 솔라피(Solapi) SMS API
- 배포: Vercel (프론트) + AWS ECS (API 서버)

코딩 규약

프로젝트 고유의 코딩 규칙을 목록으로 열거합니다.

## 코딩 규약

- 컴포넌트는 함수 컴포넌트로 작성한다. 클래스 컴포넌트는 사용하지 않는다
- 상태 관리는 React Server Components를 기본으로 하되, 클라이언트 상태가 필요한 경우에만 `'use client'`를 사용한다
- API 라우트는 `app/api/` 이하에 RESTful하게 배치한다
- 데이터베이스 접근은 `lib/db/`에 쿼리 함수로 모은다. 컴포넌트에서 직접 SQL을 작성하지 않는다
- 에러 핸들링은 `lib/errors.ts`의 커스텀 에러 클래스를 사용한다
- 날짜·시간은 Day.js 대신 표준 `Intl` API와 `Date` 객체를 사용한다. 단, 타임존 처리가 필요한 경우 `date-fns-tz`를 사용한다
- 서버 저장은 UTC, 화면 표시는 KST(Asia/Seoul)로 변환한다

포인트는 "왜 그렇게 하는가"보다 "무엇을 해야 하는가"를 명확히 작성하는 것입니다. AI는 배경 이유보다 명확한 지시를 더 잘 따릅니다. 단, 팀원이 나중에 읽었을 때 이해하기 어려운 규칙에는 간단한 이유를 괄호로 추가하면 유지보수에 도움이 됩니다.

커맨드

빌드, 테스트, 배포 커맨드를 기술합니다.

## 커맨드

- 개발 서버 시작: `pnpm dev`
- 프로덕션 빌드: `pnpm build`
- 전체 테스트 실행: `pnpm test`
- 단일 파일 테스트: `pnpm test -- path/to/file.test.ts`
- 린트 검사: `pnpm lint`
- 타입 체크: `pnpm typecheck`
- DB 마이그레이션 생성: `pnpm supabase migration new <마이그레이션명>`
- DB 마이그레이션 적용: `pnpm supabase db push`
- Storybook 실행: `pnpm storybook`

Claude Code는 이 섹션을 참고해 테스트 실행이나 빌드 확인을 자동으로 수행합니다. 패키지 매니저가 pnpm인데 npm 커맨드를 쓰는 실수도 이 섹션 하나로 방지됩니다.

팁: 커맨드 섹션에 자주 쓰는 DB 조작, 코드 생성 스크립트, 환경 초기화 커맨드도 함께 적어두면 AI가 적절한 시점에 자동으로 실행해줍니다.

금지 사항

AI에게 시켜서는 안 되는 것을 명시합니다. 이 섹션은 예기치 않은 트러블을 방지하기 위해 특히 중요합니다.

## 금지 사항

- `main` 브랜치에 직접 커밋하지 않는다. 반드시 feature 브랜치를 생성한다
- `.env` 파일 및 `.env.local` 파일을 커밋에 포함하지 않는다
- `node_modules/`나 `dist/` 안의 파일을 직접 변경하지 않는다
- 기존 DB 마이그레이션 파일을 수정하지 않는다 (새로운 마이그레이션을 추가한다)
- `package.json`의 의존성을 무단으로 업그레이드하지 않는다
- 결제 관련 금액 계산을 클라이언트에서 수행하지 않는다 (서버에서 검증한다)
- 개인정보(이름, 전화번호, 이메일 등)를 로그에 출력하지 않는다

국내 서비스에서 특히 민감한 항목인 결제 금액의 클라이언트 계산과 개인정보 로그 출력 금지는 처음부터 명시해 두는 것을 권장합니다. AI가 의도치 않게 이를 위반하는 코드를 생성하는 경우가 실제로 자주 발생합니다.

잘 쓰는 팁

목록을 사용한다

긴 산문보다 목록이 AI의 이해 정확도를 높입니다.

# 좋지 않은 예
이 프로젝트에서는 TypeScript를 사용하며, strict 모드를 활성화하고 있습니다.
테스트는 Vitest로 작성하며, 커버리지는 80% 이상을 목표로 합니다.
커밋 메시지는 한국어로, Conventional Commits 형식에 따라 작성해 주세요.

# 좋은 예
- TypeScript strict mode 사용
- 테스트: Vitest, 커버리지 80% 이상 유지
- 커밋 메시지: 한국어, Conventional Commits 형식

산문은 사람이 읽기엔 자연스럽지만, AI는 항목이 명확히 구분된 목록을 더 정확하게 파싱합니다.

구체적인 예시를 함께 제시한다

규칙만 적는 것보다 예시를 함께 쓰면 AI의 출력 품질이 눈에 띄게 안정됩니다.

## 파일 명명 규칙

- 컴포넌트: PascalCase (예: `UserProfile.tsx`)
- 유틸리티 함수: camelCase (예: `formatDate.ts`)
- 상수 파일: SCREAMING_SNAKE_CASE (예: `API_ENDPOINTS.ts`)
- 테스트 파일: 대상 파일과 동일한 이름 + `.test` (예: `formatDate.test.ts`)
- 타입 정의 파일: camelCase + `.types` (예: `order.types.ts`)

IMPORTANT 키워드 활용

특히 중요한 규칙에는 IMPORTANT:를 붙이면 Claude Code가 더 확실하게 따릅니다.

IMPORTANT: 프로덕션 데이터베이스에 DELETE 문을 직접 실행하지 않는다.
반드시 논리 삭제(deleted_at 컬럼 업데이트)를 사용한다.

IMPORTANT: 토스페이먼츠 결제 금액은 반드시 서버에서 DB 기준으로 재계산한다.
클라이언트가 전달한 금액을 그대로 사용하지 않는다.

IMPORTANT는 남발하면 효과가 떨어집니다. 보안 사고나 데이터 손실로 직결되는 규칙에만 사용하세요.

섹션 설계의 안티패턴

정보 과다

CLAUDE.md에 수백 행을 작성하면 우선순위가 모호해집니다. AI는 전체를 읽지만, 어디에 집중해야 할지를 판단하는 데 어려움을 겪습니다. 정말 중요한 규칙에만 집중하세요. 기준은 50~100행입니다.

어쩔 수 없이 내용이 많아진다면, @임포트를 활용해 파일을 분리하는 것이 좋습니다. 메인 CLAUDE.md에는 핵심 규칙만 남기고, 세부 사항은 @./docs/coding-standards.md처럼 별도 파일로 분리합니다.

모순되는 규칙

"간결하게 쓴다"와 "상세한 주석을 작성한다"처럼 서로 충돌하는 지시가 있으면 AI의 출력이 불안정해집니다. 규칙을 추가할 때마다 기존 규칙과 모순되지 않는지 확인하세요. 특히 코딩 규약을 점진적으로 추가하다 보면 이런 모순이 생기기 쉽습니다.

오래된 정보

CLAUDE.md가 현실과 괴리되면 AI가 잘못된 규칙을 충실히 따르게 됩니다. 라이브러리 업그레이드, 디렉토리 구성 변경, 팀 컨벤션 변경이 있을 때마다 CLAUDE.md도 함께 업데이트하세요. 코드베이스 변경 PR에 CLAUDE.md 업데이트를 포함하는 것을 팀 규칙으로 정해두는 것을 권장합니다.