2026.04.14

CLAUDE.md 작성 가이드

Claude Code 에이전트가 매 세션마다 가장 먼저 읽는 파일. 이 파일 하나로 에이전트의 성능이 완전히 달라집니다.

CLAUDE.md가 뭔가요?

CLAUDE.md는 Claude Code의 기억 장치입니다. 사람으로 치면 "업무 매뉴얼"이에요. 이 파일에 프로젝트 규칙, 코딩 스타일, 자주 쓰는 명령어 등을 적어두면, 에이전트가 세션을 열 때마다 자동으로 읽고 그에 맞게 행동합니다.

CLAUDE.md가 없으면? 에이전트는 매번 백지 상태에서 시작합니다. "이건 React 프로젝트야", "TypeScript를 써야 해" 같은 걸 매번 알려줘야 하죠.

어디에 만드나요?

CLAUDE.md는 위치에 따라 적용 범위가 달라집니다.

읽는 순서: ~/.claude/ → ./CLAUDE.md → 하위폴더 → .local.md
나중에 읽힌 것이 우선합니다.

가장 쉽게 만드는 법

Claude Code에서 /init 명령어를 실행하면 프로젝트를 분석해서 자동으로 초안을 만들어줍니다.

claude > /init
✓ Analyzed project structure
✓ Created CLAUDE.md
  → Build system: npm detected
  → Framework: React + TypeScript
  → Test runner: vitest

이 초안에서 불필요한 부분을 삭제하고, 중요한 규칙만 남기세요. 500줄 이하가 이상적입니다. 너무 길면 에이전트가 핵심을 놓칩니다.

실전 템플릿

# 프로젝트 개요
사내 업무 자동화 대시보드
React + TypeScript + Supabase

# 명령어
- 개발 서버: npm run dev
- 테스트: npm run test
- 빌드: npm run build

# 코딩 규칙
- TypeScript strict 모드 사용
- 함수형 컴포넌트만 (class 금지)
- CSS는 Tailwind만, 인라인 금지
- 한글 주석 필수

# 에이전트 행동 규칙
- 파일 삭제 전 반드시 확인 요청
- main 브랜치에 직접 push 금지
- 테스트 코드 없이 PR 생성 금지

잘 쓰는 팁

1. 명령어부터 쓰세요

에이전트가 가장 자주 쓰는 건 빌드·테스트·배포 명령어입니다. 이것만 정확히 적어도 생산성이 크게 올라갑니다.

2. 금지 사항을 명확히

"좋은 코드를 써줘"는 의미 없습니다. "eval() 사용 금지", "any 타입 금지"처럼 구체적으로 써야 에이전트가 지킵니다.

3. 너무 길게 쓰지 마세요

300~500줄이 적정선입니다. 에이전트가 이미 알 수 있는 것(package.json에 나와있는 의존성 등)은 빼세요.

4. 살아있는 문서로 유지

에이전트가 반복적으로 틀리는 패턴이 보이면 그때마다 CLAUDE.md에 추가하세요. 점점 정확해집니다.