CLAUDE.md 작성법 — Claude가 내 규칙을 따르게 만드는 5원칙
Claude Code에게 분명히 지시했는데도 자꾸 엉뚱하게 답한 적 있나요? 문제는 실력이 아니라 CLAUDE.md입니다. CLAUDE.md 작성법의 핵심 원칙과, Claude가 규칙을 무시하는 진짜 이유를 공식 가이드 기준으로 초보자 눈높이에서 정리했습니다.
결론부터 — 모호하게 쓰면 무시당합니다
CLAUDE.md는 매 세션마다 자동으로 읽히는 프로젝트 지침서입니다. 한 번 잘 써두면 같은 설명을 반복하지 않아도 Claude가 내 프로젝트를 이해하고 일관된 결과를 냅니다.
핵심은 한 줄로 요약됩니다. “깔끔하게”는 무시당하고, “30줄 이하로”는 지켜집니다. Claude가 규칙을 안 따르는 이유 대부분은 지시가 모호하기 때문입니다. 검증 가능한 구체적인 문장으로 쓰는 것, 이것이 CLAUDE.md 작성법의 출발점입니다.
CLAUDE.md가 뭔가요?
CLAUDE.md는 Claude Code(터미널에서 쓰는 AI 코딩 도구)가 작업을 시작할 때 가장 먼저 읽는 규칙 파일입니다. 자동차 시트를 한 번 내 몸에 맞춰두면 탈 때마다 그대로 적용되는 것과 같습니다.
쉽게 비유하면, Claude는 똑똑하지만 우리 팀 사정을 전혀 모르는 신입사원입니다. 결과물이 아쉬운 건 머리가 나빠서가 아니라, 우리 프로젝트의 맥락을 안 알려줬기 때문입니다. CLAUDE.md는 그 신입에게 건네는 업무 매뉴얼인 셈입니다.
비어 있는 파일에서 시작해, Claude가 실수할 때마다 한 줄씩 규칙을 추가해 키워가는 것이 정석입니다. 처음부터 완벽하게 쓰려 애쓸 필요가 없습니다.
CLAUDE.md 작성 5원칙
1. 검증 가능한 구체적 규칙으로 쓰기
가장 효과가 큰 원칙입니다. 사람마다 해석이 갈리는 표현은 피하고, 누가 봐도 참·거짓을 가릴 수 있는 문장으로 적습니다.
# 나쁜 예
✗ 깔끔한 코드를 작성하세요
✗ 테스트를 잘 작성하세요
# 좋은 예
✓ 함수는 30줄 이하로 작성
✓ 새 파일 생성 전 반드시 나에게 확인
✓ 커밋 전 npm test 실행2. 우리 프로젝트 용어 정의하기
같은 단어도 프로젝트마다 뜻이 다릅니다. Claude가 헷갈릴 만한 용어는 미리 정의해줍니다.
## 도메인 용어
- 주문(Order): 고객이 한 번에 결제하는 묶음 전체
- 주문항목(OrderItem): 주문 내 개별 상품 단위3. 스스로 검증하게 만들기
Claude는 “다 된 것처럼 보일 때” 멈추는 습성이 있습니다. 그래서 결과를 스스로 점검하도록 규칙을 넣어줍니다.
## 검증 규칙
- 코드 작성 후 반드시 빌드 실행하고 에러 스스로 수정
- 이미 읽은 파일은 다시 읽지 않음4. 짧게 유지하기 (200줄 이하)
길수록 좋은 게 아닙니다. 규칙이 300줄을 넘으면 정작 중요한 규칙이 잡음에 묻혀 Claude가 무시하기 시작합니다. 공식 권장은 200줄 이하입니다. 분량이 넘치면 세부 규칙은 별도 파일로 빼냅니다.
5. 규칙이 많아지면 조건부로 쪼개기
프로젝트가 커지면 API·테스트·디자인 규칙이 한 파일에 뒤섞입니다. 이때는 .claude/rules/ 폴더로 나누고, “이 규칙은 이런 파일을 만질 때만 읽어라”라고 조건을 겁니다.
# .claude/rules/api-design.md
---
paths:
- "src/api/**/*.ts"
---
- 모든 엔드포인트에 입력값 검증 필수이렇게 하면 화면(프론트엔드) 작업을 할 땐 API 규칙이 끼어들지 않아, Claude가 지금 일에만 집중합니다. 주방 직원에게 배달 매뉴얼을 들이밀지 않는 것과 같은 이치입니다.
좋은 패턴 vs 나쁜 패턴 한눈에
| 구분 | 좋은 패턴 | 나쁜 패턴 |
|---|---|---|
| 표현 | “함수는 30줄 이하” | “깔끔하게 작성” |
| 길이 | 200줄 이하, 핵심만 | 300줄 이상 장문 |
| 구조 | 규칙별로 파일 분리 | 모든 규칙 한 파일에 |
| 용어 | 프로젝트 용어 정의 | 정의 없이 추측 의존 |
| 검증 | 스스로 점검 규칙 포함 | 검증 수단 없음 |
한 가지 더 — 맥락은 많을수록 좋지 않다
의외의 사실이지만, 관련 없는 자료까지 전부 욱여넣으면 Claude가 중요한 걸 놓칩니다. 실제로 어떤 프로젝트는 CLAUDE.md가 4만 단어 넘게 불어나 속도와 규칙 준수가 모두 무너진 사례가 있습니다.
그래서 맥락은 세 층으로 나눠 관리하는 게 좋습니다. 항상 적용할 핵심 원칙은 CLAUDE.md(짧게), 특정 작업에만 필요한 매뉴얼은 참조 문서로, 매번 달라지는 일회성 요청은 그때그때 프롬프트로 전달하는 식입니다.
마무리
CLAUDE.md 작성법의 핵심은 구체적으로, 짧게, 그리고 실수할 때마다 한 줄씩 키우는 것입니다. “왜 Claude가 내 말을 안 듣지?”의 답은 거의 모호한 지시에 있습니다. 오늘 내 CLAUDE.md를 열어 “깔끔하게” 같은 문장을 “30줄 이하”처럼 바꾸는 것부터 시작해보세요. AI 코딩 품질이 눈에 띄게 달라집니다.
