Claude Code를 쓰다 보면 매번 같은 설명을 반복하게 됩니다. “이 프로젝트는 이런 구조야”, “톤은 이렇게 써줘”, “이 폴더에 저장해줘”. CLAUDE.md를 쓰면 이런 반복이 사라져요.
CLAUDE.md 사용법은 간단합니다. 프로젝트 폴더에 CLAUDE.md 파일을 하나 만들어두면, Claude Code가 매 대화 시작할 때 이 파일을 자동으로 읽습니다. 한번 써두면 계속 적용돼요.
CLAUDE.md가 뭔가요
CLAUDE.md는 Claude Code에게 주는 프로젝트 설명서입니다. 마크다운(.md) 형식의 텍스트 파일이에요.
이 파일에 프로젝트의 규칙, 구조, 주의사항을 적어두면 Claude Code가 이를 참고해서 작업합니다. 사람으로 치면 “이 프로젝트 투입 전에 읽어야 할 가이드 문서” 같은 거예요.
- 파일 위치: 프로젝트 폴더 최상위에 `CLAUDE.md`로 저장
- 형식: 마크다운 (일반 텍스트도 가능)
- 자동 로딩: Claude Code 실행 시 자동으로 읽힘
- 즉시 반영: 파일을 수정하면 다음 대화부터 반영
CLAUDE.md에 뭘 적으면 되나요
정해진 양식은 없지만, 실전에서 효과가 좋은 항목들이 있어요.
1. 프로젝트 개요
## 프로젝트 개요
- 이 프로젝트는 AI 도구 리뷰 블로그(Tool-LOG)입니다
- 워드프레스 기반, GeneratePress 테마 사용
- 대상 독자: AI에 관심 있는 비개발자프로젝트가 뭔지 한 줄로 알려주면, Claude Code의 답변 방향이 잡힙니다.
2. 파일 구조
## 파일 구조
- contents/ — 블로그 글 HTML 파일
- wp_publish.py — WordPress 자동 발행 스크립트
- config.json — WP 인증 정보 (수정 금지)어떤 파일이 어디에 있는지 알려주면, “이 파일 찾아줘”라고 할 필요가 없어요.
3. 작업 규칙
## 블로그 글 작성 규칙
- 톤: 합니다/해요 혼용. 명령조(~해라) 금지
- SEO: 포커스 키워드를 제목, 첫 문단, H2에 포함
- HTML: meta description 필수, 시맨틱 태그 사용
- 금지: 과장 표현("최고의", "혁명적"), 이모지 사용이 규칙이 있으면 매번 “톤 이렇게 써줘”라고 반복할 필요가 없습니다.
4. 주의사항
## 주의사항
- config.json에 비밀번호가 있으므로 절대 내용을 출력하지 말 것
- 기존 글 파일을 덮어쓰지 말 것 (새 파일로 생성)
- 이미지는 수동 업로드이므로 이미지 관련 자동화 시도하지 말 것실수를 방지하는 규칙도 중요합니다.
CLAUDE.md 실전 예시 — 블로그 프로젝트
실제로 이 블로그에서 쓰고 있는 CLAUDE.md의 핵심 부분을 보여드릴게요.
# Tool-LOG 블로그 — CLAUDE.md
## 프로젝트 개요
- AI 도구 활용법을 다루는 워드프레스 블로그
- 비개발자 관점에서 실사용 경험 기반으로 작성
## 글 작성 규칙
- HTML 형태로 작성 (WP에 업로드하므로)
- <title>에 SEO 키워드 포함
- <meta name="description"> 필수 (Rank Math 자동 파싱)
- 첫 문단에 포커스 키워드 자연스럽게 삽입
- H2에 키워드 1~2회 포함
- 톤: 합니다/해요 혼용, 명령조 금지
- 표와 목록 적극 활용
- 과장 표현 금지
## 출력 위치
- 글 파일: contents/ 폴더에 저장
- 파일명: {주제-영문-kebab}-2026.html
## 발행 방법
- python wp_publish.py "contents/파일.html" --category "카테고리" --focus-keyword "키워드" --status draft이 파일 하나 덕분에 “블로그 글 하나 써줘”라고만 해도 SEO, 톤, 형식이 맞는 글이 나옵니다.
CLAUDE.md 적용 전 vs 후
| 항목 | CLAUDE.md 없을 때 | CLAUDE.md 있을 때 |
|---|---|---|
| 매 대화 시작 | “이 프로젝트는…” 설명 반복 | 자동으로 규칙 적용 |
| 글 품질 | 대화마다 톤/형식이 다름 | 일관된 품질 유지 |
| 파일 저장 | “이 폴더에 저장해줘” 매번 지시 | 자동으로 맞는 위치에 저장 |
| 실수 방지 | 가끔 config 파일 건드림 | 주의사항에 따라 회피 |
| 프롬프트 길이 | 길고 반복적 | 핵심 요청만 짧게 |
CLAUDE.md를 더 잘 쓰는 팁
- 짧게 쓰세요 — 너무 길면 Claude Code가 핵심을 놓칠 수 있어요. 1~2페이지 분량이 적당합니다
- 구체적으로 쓰세요 — “좋은 글을 써줘”보다 “합니다/해요 혼용, 명령조 금지”가 훨씬 효과적이에요
- 예시를 넣으세요 — 원하는 결과물의 예시나 참조 파일을 명시하면 품질이 올라갑니다
- 계속 업데이트하세요 — 작업하면서 “이것도 규칙에 넣어야겠다” 싶으면 바로 추가하세요
- 경로별 CLAUDE.md — 하위 폴더에도 별도 CLAUDE.md를 둘 수 있어요. 해당 폴더 작업 시 자동 적용됩니다
CLAUDE.md가 필요한 사람
| 이런 분이라면 | 효과 |
|---|---|
| 같은 프로젝트를 반복 작업하는 분 | 매번 같은 설명 반복이 사라짐 |
| 여러 프로젝트를 오가는 분 | 프로젝트별 규칙이 자동 적용 |
| 결과물 품질이 들쑥날쑥한 분 | 일관된 품질 유지 |
| 팀에서 Claude Code를 쓰는 경우 | 팀원 모두 같은 규칙으로 작업 |
정리하면
CLAUDE.md 사용법의 핵심은 “규칙을 파일에 적어두는 것”입니다. 한번 만들어두면 매 대화에 자동 적용되고, 결과물 품질이 일관되게 유지돼요.
처음에는 프로젝트 개요 + 작업 규칙 2~3줄이면 충분합니다. 작업하면서 하나씩 추가해가면 자연스럽게 좋은 CLAUDE.md가 만들어져요. AI에게 규칙을 가르치는 가장 효율적인 방법입니다.
※ CLAUDE.md는 Claude Code 전용 기능입니다. claude.ai 웹이나 모바일 앱에서는 프로젝트(Projects) 기능의 커스텀 지시사항이 비슷한 역할을 해요.