CLAUDE.md는 어떻게 써야하는가?

CLAUDE.md

CLAUDE.md란?

CLAUDE.mdsms 클로드 코드에게 주는 지시서이다. 프로젝트 폴더에 해당 파일을 두면, Claude는 대화를 시작할때 마다 해당 문서를 읽는다.

코드 스타일, 폴더 구조, 금지 사항 같은 것을 적어두면 된다.

 

왜 필요한가?

클로드에게 매번 "우리 프로젝트는 이렇게 해" 라고 말하는 건 비효율적이다. CLAUDE.me에 한 번 써두면, 다음 대화부터 다시 설명하지 않아도 된다.

프로젝트가 클수록 이 차이가 커진다.

 

어떻게 작성하나

핵심 규직 짧게, 중요한 것만 적는다.

시스템 프롬프트 (AI에게 주는 초기 지시)에 정보가 너무 많으면 AI가 헷갈린다.

CLAUDE.md도 마찬가지다. 길게 쓸수록 클로드는 중요한 것을 놓친다.

 

구조는 아래와 같이 나누는 것을 권장한다.

프로젝트 루트/
├── CLAUDE.md          ← 전체 규칙 요약 + 하위 파일 연결
├── src/
│   └── CLAUDE.md      ← 소스 코드 관련 규칙만
└── docs/
    └── CLAUDE.md      ← 문서 관련 규칙만

 

루트 CLAUDE.md는 목차 역할만 한다.

세부 규칙은 기능별 폴더 안에 각각 둔다.

나는 어떻게 했는가

처음엔 다 적으려고 했다

처음 CLAUDE.md를 썼을 때, 모든 것을 넣으려고 했다. 코드 스타일, 변수명 규칙, 주석 형식, 폴더 구조, 예외 처리 방법. 개발 팀의 컨벤션, 기본 규칙 등등..

파일이 200줄이 넘어갔다.

 

결과는 반대였다. 클로드가 규칙을 절반도 따르지 않는 것으로 보였다.

너무 많은 지시는 없는 것보다 못했다.

 

실수하면서 한 줄씩 고쳤다

지금 방식은 단순하다.

클로드가 실수하면, 그때 CLAUDE.me에 한 줄 추가한다.

 

예를 들어, 클로드가 자꾸 한국어 주석을 영어로 바꾸면, 이렇게 적는다.

# 규칙
- 주석은 반드시 한국어로 작성한다.

 

처음부터 완벽하게 쓰려고 하지 않는다. 쓰다 보면 어떤 규칙이 필요한지 자연스럽게 보인다.

 

마치며

CLAUDE.md는 짧게, 기능별로, 실수하면서 고쳐가는 것이다.

처음에는 루트에 5줄짜리 CLAUDE.md 하나로 시작해도 충분하다.

그리고 실수할때 마다 한줄씩, 명확하게 추가한다.