Claude Code를 켤 때마다 “이 프로젝트의 테스트는 pnpm test로 실행해 줘”라고 다시 설명하고 있나요? 이런 프로젝트 규칙을 적어 두는 파일이 CLAUDE.md입니다. Claude Code는 새 대화를 시작할 때 이 파일을 읽고 작업에 참고합니다.
마크다운 형식으로 작성하므로 특별한 설정 문법을 외울 필요는 없습니다. 자주 쓰는 명령, 파일을 배치하는 위치, 팀이 지키는 규칙처럼 대화가 바뀌어도 필요한 내용을 적으면 됩니다.
파일은 어디에 만들까요?
프로젝트의 가장 바깥 폴더에 CLAUDE.md를 만들거나, .claude/CLAUDE.md에 저장하면 됩니다. 팀원이 함께 사용할 규칙이라면 Git으로 관리해 공유하세요.
본인만 사용할 프로젝트 메모는 CLAUDE.local.md에 작성하고, Git 공유 대상에서 제외하는 .gitignore에 추가합니다. 여러 프로젝트에 공통으로 적용할 개인 규칙은 ~/.claude/CLAUDE.md에 둘 수 있습니다.
초안부터 직접 쓰기 어렵다면 Claude Code에서 /init을 실행해 보세요. 프로젝트를 살펴보고 초안을 만드는 데 사용할 수 있습니다. 초안이 나오면 불필요한 설명이나 잘못된 명령을 정리하세요.
코드만 보고는 알기 어려운 내용을 적으세요
다음 네 가지부터 시작하면 충분합니다.
- 실행 명령: 개발 서버, 테스트, 타입 검사, 빌드를 어떻게 실행하는지
- 파일 위치: 화면 구성 요소와 서버 코드를 어디에 두는지
- 팀의 규칙: 들여쓰기, 오류 처리처럼 프로젝트에서 일관되게 지킬 사항
- 완료 기준: 코드를 수정한 뒤 무엇을 확인해야 작업이 끝난 것인지
“깔끔하게 작성해 줘”보다 “들여쓰기는 공백 두 칸을 사용해 줘”처럼 확인할 수 있는 문장이 좋습니다. 테스트 역시 “잘 확인해 줘” 대신 실행할 명령과 확인할 동작을 적으세요.
할 일 관리 앱의 작성 예시
아래는 예시입니다. 명령과 경로는 실제 프로젝트에 맞게 바꿔 사용하세요.
# 할 일 관리 앱의 작업 규칙
## 실행 명령
- 패키지 설치: `pnpm install`
- 개발 서버 시작: `pnpm dev`
- 테스트 실행: `pnpm test`
- 타입 검사: `pnpm check`
## 파일 위치
- 화면 구성 요소는 `src/components/`에 둡니다.
- 서버 요청을 처리하는 코드는 `src/api/`에 둡니다.
## 오류 처리
- API 오류는 `{ error, code }` 형식의 JSON과 알맞은 HTTP 상태 코드로 반환합니다.
- 네트워크 요청이 실패하면 사용자에게 오류 상태를 보여 줍니다.
## 작업 완료 전에 확인할 것
- 할 일이 없을 때, 불러오는 중일 때, 오류가 났을 때의 화면이 모두 표시되어야 합니다.
- `pnpm test`와 `pnpm check`가 통과해야 합니다.이 예시는 “어떻게 실행하는가”, “어디에 코드를 두는가”, “무엇을 확인하는가”를 한 파일에 모은 것입니다. Claude가 같은 실수를 반복한다면 해당 부분에 구체적인 규칙을 한 줄 더해 보세요.
파일을 짧게 유지하는 이유
CLAUDE.md는 대화가 시작될 때 읽는 자료입니다. 너무 길면 AI가 한 번에 참고하는 정보가 많아지고, 중요한 지시가 다른 설명에 묻힐 수 있습니다. 공식 문서는 파일마다 200줄 이내를 목표로 작성하도록 권장합니다.
여러 단계로 반복하는 작업은 별도의 스킬 파일인 SKILL.md로 옮길 수 있습니다. 예를 들어 매번 필요한 테스트 명령은 CLAUDE.md에, 배포할 때만 필요한 긴 점검 절차는 스킬에 두는 식입니다.
다른 도구용 AGENTS.md에 같은 규칙이 이미 있다면 CLAUDE.md에 아래 한 줄을 적어 내용을 불러올 수 있습니다. Claude Code는 AGENTS.md를 자동으로 읽지 않으므로 이 연결을 명시해야 합니다.
@AGENTS.mdCLAUDE.md의 지시는 Claude가 읽고 따르도록 전달하는 내용이며, 특정 동작을 확실히 차단하는 설정은 아닙니다. 실행을 막아야 하는 명령은 /permissions의 거부 규칙이나 도구 실행 전에 호출을 차단할 수 있는 PreToolUse 훅으로 관리합니다.