부록 D. CLAUDE.md 잘 쓰는 법

CLAUDE.md 세 종류

CLAUDE.md는 한 종류가 아닙니다. 위치에 따라 세 가지로 나뉩니다.

파일	위치	적용 범위	Git 공유
글로벌	~/.claude/CLAUDE.md	내 모든 프로젝트	아니오
프로젝트	./CLAUDE.md	현재 프로젝트	예
로컬	./CLAUDE.local.md	현재 프로젝트	아니오

여러 파일이 있으면 모두 로드됩니다. 작업 폴더에 가까울수록 우선 적용됩니다.

글로벌 vs 프로젝트 구분하는 법

글로벌 (~/.claude/CLAUDE.md)에는 어느 프로젝트에서나 적용되어야 하는 것들을 씁니다.

# 응답 규칙
- 한국어로 답변
- 이모지 사용 금지
- 코드 설명은 비개발자 기준으로

프로젝트 (./CLAUDE.md)에는 이 프로젝트에만 필요한 것들을 씁니다.

# 이 프로젝트 규칙
- 블로그 글은 status: 초안으로 시작
- 커밋 메시지는 "content: " 접두사
- 로컬 서버: npm run dev (포트 4321)

---

효과적으로 쓰는 법

200줄 이내 목표

CLAUDE.md가 길어질수록 지시 준수율이 낮아집니다. 200줄을 넘기지 않는 것을 목표로 합니다.

긴 내용이 있다면 @파일경로로 별도 파일에서 불러올 수 있습니다.

# CLAUDE.md
@docs/conventions.md
@docs/project-structure.md

# 핵심 규칙 (짧게)
- 커밋 메시지는 영어

구체적으로 쓰기

추상적인 지시는 Claude가 자의적으로 해석합니다.

나쁜 예	좋은 예
”코드 잘 써줘"	"들여쓰기는 2칸 스페이스"
"친절하게 대답해줘"	"전문 용어 쓸 때 괄호 안에 설명 추가"
"변경 전에 확인해줘"	"파일 삭제 전에 반드시 먼저 물어봐줘”

경로별 규칙 분리

특정 폴더에만 적용할 규칙은 .claude/rules/ 폴더에 분리할 수 있습니다.

.claude/rules/
└── content.md    ← src/content/**에만 적용되는 규칙

---
globs: src/content/**/*.md
---

마크다운 파일 규칙:
- frontmatter에 status 필드 필수
- 코드 블록에 언어 명시

CLAUDE.md에 모든 규칙을 넣으면 길어집니다. 규칙이 많아지면 rules/ 폴더로 분리하는 것이 좋습니다.

---

현재 이 튜토리얼의 CLAUDE.md

4장에서 수정한 CLAUDE.md를 다시 열어보면, 지금 배운 내용이 그대로 담겨 있습니다.

현재 CLAUDE.md 내용 확인해줘.

글로벌 CLAUDE.md가 있다면 이렇게 확인합니다.

~/.claude/CLAUDE.md 내용 보여줘.