클로드 코드를 쓰다 보면 비슷한 설명을 반복하게 됩니다. 어떤 테스트를 먼저 돌려야 하는지, 코드 스타일은 어떻게 맞추는지, 이 프로젝트에서 조심해야 할 점은 무엇인지 계속 다시 말하게 되는 식입니다. 이런 반복을 줄일 때 핵심이 되는 파일이 CLAUDE.md입니다.
이 글은 CLAUDE.md 작성법을 중심으로, 어디에 두는 파일인지, 어떤 내용을 적는 편이 좋은지, 팀 공유 규칙과 개인 취향을 어떻게 나눌지 정리했습니다.
Table of Contents
CLAUDE.md는 무엇을 담는 파일인가
공식 메모리 문서 기준으로 프로젝트 메모리는 ./CLAUDE.md에 둡니다. 이 파일은 프로젝트 구조, 코딩 규칙, 공통 작업 흐름처럼 팀이 같이 알아야 하는 맥락을 담는 용도에 가깝습니다.
즉 설정 파일이 동작을 바꾸는 쪽이라면, CLAUDE.md는 일하는 기준을 전달하는 쪽에 더 가깝습니다.
어떤 내용을 적으면 좋은가
- 프로젝트 구조와 주요 디렉터리 설명
- 테스트 실행 순서
- 코드 스타일 규칙
- 배포 전 점검 항목
- 자주 쓰는 명령
핵심은 추상적인 문장보다 실제 행동 기준을 적는 것입니다. “코드를 깔끔하게 유지한다”보다 “테스트는 어떤 순서로 돌린다”가 훨씬 유용합니다.
개인 취향과 팀 규칙은 분리하는 편이 좋다
공식 문서는 프로젝트 메모리 외에 사용자 메모리 ~/.claude/CLAUDE.md도 설명합니다. 따라서 팀 전체 규칙은 프로젝트 메모리에 두고, 개인 취향은 사용자 메모리로 분리하는 편이 충돌이 적습니다.
import 문법도 알아두면 편하다
공식 메모리 문서에는 @path/to/file 형태의 import 문법도 안내되어 있습니다. 프로젝트 전체 설명은 README에 있고, 세부 규칙은 별도 문서에 있다면 필요한 파일만 가져오는 방식이 관리에 유리합니다.
정리
CLAUDE.md는 단순 소개문이 아니라, 프로젝트에서 반복 설명되는 규칙을 안정적으로 모아두는 파일입니다. 팀 규칙은 프로젝트 메모리에, 개인 취향은 사용자 메모리에 나누는 기준만 잡아도 훨씬 덜 흔들립니다.
참고한 공식 문서
- Anthropic Manage Claude’s memory
