CLAUDE.md 작성법: AI가 내 코드 컨벤션을 기억하게 만드는 프로젝트 규칙 파일 가이드

CLAUDE.md는 AI용 온보딩 문서다

Claude Code를 프로젝트에 붙이면 처음에는 저장소를 읽고 패턴을 추론합니다. 하지만 패키지 매니저, 폴더 규칙, 테스트 명령, 선호하는 코드 스타일처럼 매번 반복해서 설명해야 하는 내용이 생깁니다. CLAUDE.md는 이 반복 설명을 줄이는 프로젝트 규칙 파일에 가깝습니다.

사람에게 README가 “이 프로젝트가 무엇인지” 알려준다면, CLAUDE.md는 AI에게 “이 프로젝트에서 어떻게 일해야 하는지”를 알려줍니다. 1인 개발자에게 특히 유용한 이유는 간단합니다. 내가 어제 정한 규칙을 오늘의 AI 세션이 잊지 않게 만드는 최소한의 장치이기 때문입니다.

먼저 적어야 할 5가지

처음부터 거창하게 쓰기보다, AI가 실수하면 비용이 커지는 항목부터 적는 편이 좋습니다.

예를 들어 “이 프로젝트는 pnpm을 사용한다. npm install을 실행하지 않는다”처럼 짧고 단정한 문장이 좋습니다. “가능하면 예쁘게 작성” 같은 취향 표현보다 “서버 액션은 app/actions에 둔다”처럼 확인 가능한 규칙이 AI에게 더 잘 전달됩니다.

실전 템플릿

아래 구조를 복사한 뒤 프로젝트에 맞게 줄이면 됩니다. 핵심은 길이가 아니라 판단 기준입니다.

# CLAUDE.md

## 프로젝트 개요
- 한국어 사용자를 위한 B2C 웹 서비스
- Next.js App Router 기반

## 명령어
- 설치: pnpm install
- 개발: pnpm dev
- 빌드: pnpm build
- 린트: pnpm lint

## 구조
- app/: 라우트와 페이지
- components/: 재사용 UI
- lib/: 공통 유틸과 서버 헬퍼
- messages/: 다국어 문구

## 코딩 규칙
- TypeScript를 사용한다.
- 새 UI는 기존 컴포넌트 스타일을 우선 따른다.
- 서버 로직은 클라이언트 컴포넌트에 직접 넣지 않는다.
- 에러는 조용히 무시하지 말고 호출부에서 처리한다.

## 금지사항
- 패키지 매니저를 임의로 바꾸지 않는다.
- 환경변수 이름을 변경하지 않는다.
- 기존 마이그레이션 파일을 수정하지 않는다.

이 정도만 있어도 AI가 “무엇을 실행해야 하는지”, “어디에 코드를 둬야 하는지”, “무엇을 피해야 하는지”를 훨씬 빨리 파악합니다.

너무 길게 쓰면 오히려 약해진다

CLAUDE.md를 사내 위키처럼 만들고 싶은 유혹이 있습니다. 하지만 길어진 규칙 파일은 실제 작업에서 덜 읽히고, 오래된 내용이 섞이기 쉽습니다. AI에게도 긴 문서는 우선순위가 흐려질 수 있습니다.

좋은 기준은 “새로 합류한 동료에게 첫 작업 전 5분 안에 설명할 내용인가?”입니다. 세부 구현 설명, 과거 의사결정 기록, 긴 회고는 별도 문서로 빼고 CLAUDE.md에는 현재 작업 규칙만 남기는 편이 실용적입니다.

체크리스트로 줄이면 이렇습니다.

• 실행 명령이 실제로 동작하는가
• 폴더 설명이 현재 구조와 맞는가
• 금지사항이 구체적인가
• 오래된 라이브러리 이름이 남아 있지 않은가
• 한 화면 안에서 대략 훑을 수 있는가

갱신 습관이 성능을 만든다

CLAUDE.md는 한 번 쓰고 끝나는 문서가 아닙니다. AI가 반복해서 같은 실수를 할 때마다 규칙을 한 줄 추가하는 방식이 좋습니다. 예를 들어 매번 잘못된 테스트 명령을 실행한다면 명령어 섹션을 고치고, 새 파일 위치를 자주 틀린다면 구조 섹션을 보강합니다.

다만 실수 하나마다 문서를 길게 늘리기보다, 반복되는 패턴만 남기세요. “이번에는 이 파일을 수정하지 마”는 프롬프트에 적고, “마이그레이션 파일은 생성 후 수정하지 않는다”처럼 앞으로도 적용될 규칙은 CLAUDE.md에 넣는 식입니다.

1인 빌더를 위한 작성 원칙

혼자 만드는 프로젝트일수록 문서화가 뒤로 밀립니다. 하지만 CLAUDE.md는 남을 위한 문서라기보다, 미래의 나와 AI 세션을 위한 작업 메모입니다.

처음에는 30줄 안팎으로 시작하세요. 패키지 매니저, 명령어, 폴더 구조, 금지사항만 있어도 충분합니다. 이후 AI와 작업하면서 “이건 매번 설명하네” 싶은 문장만 추가하면 됩니다. 잘 쓴 CLAUDE.md는 AI를 똑똑하게 만드는 마법 파일은 아니지만, 같은 실수를 줄이고 코드베이스의 방향을 유지하는 현실적인 안전장치가 됩니다.