여러분 이거 경험 있죠?
AI한테 뭘 시켰는데 “아 그거 아니고…” 하면서 다시 설명하는 거.
매번 똑같은 지시 반복하고, 또 까먹고, 또 설명하고.
“아… 이거 어디 적어놓고 쓰면 안돼?” 하신 적 있죠?
있어요. 진짜로. 바로 CLAUDE.md입니다.
여기서 잠깐, 이게 뭔데요?
CLAUDE.md는 Claude AI가 모든 대화 세션에서 기본적으로 참조하는 규칙 파일입니다. 2026년 1월 기준, Claude Code 시스템에서 프로젝트별 custom instructions를 정의하는 표준 방식으로 자리잡았습니다.
쉽게 말할게요.
“AI한테 출근 첫날 나눠주는 업무 매뉴얼”
끝. 이게 전부예요.
근데 이게 왜 필요하냐면요.
왜 “출근 첫 지시서”라고 부를까요?
ChatGPT나 Claude 써보신 분 다 아실 거예요.
매번 대화 시작할 때마다 “너는 ~한 역할이야”, “이렇게 답해줘” 반복하잖아요?
프로젝트 규칙 설명하고. 파일 구조 설명하고. 코딩 스타일 설명하고.
이거 한 프로젝트에서 10번, 20번 반복하면 진짜 짜증나죠.
그래서 나온 게 CLAUDE.md입니다.
.claude/ ├── CLAUDE.md ← 이 파일! (출근 첫 지시서) ├── docs/ │ ├── skills/ │ │ └── skill-structure.md ← 스킬 생성 가이드 │ └── agents/ │ └── agent-structure.md ← 에이전트 생성 가이드 ├── skills/ ← 실제 스킬들 └── agents/ ← 실제 에이전트들
Claude가 프로젝트 열면 .claude/CLAUDE.md 파일을 자동으로 읽어요.
그 안에 적힌 규칙을 모든 대화에서 따릅니다.
매번 말 안 해도 되는 거죠.
실제로 뭐가 들어가나요?
제가 6개월간 블로그 자동화 시스템 만들면서 실제로 사용하는 CLAUDE.md를 보여드릴게요.
1) 절대 규칙 (CRITICAL RULES)
“이건 절대 지켜!”라는 규칙들이 들어갑니다.
## 🚨 CRITICAL RULES (절대 규칙) ### ⚠️ Rule #1: 스킬/에이전트 생성 시 MANDATORY **새로운 스킬이나 에이전트를 만들어달라는 요청을 받으면:** MUST DO: 1. 명시적으로 확인 메시지 출력 2. .claude/docs/skills/skill-structure.md 읽기 (스킬인 경우) 3. .claude/docs/agents/agent-structure.md 읽기 (에이전트인 경우) 4. 공식 예시를 템플릿으로 사용 5. 50-100줄 범위로 작성 NEVER DO: ❌ .claude/docs/ 참조 없이 직접 생성 ❌ 마음대로 구조 변경 ❌ 장황하게 200줄+ 작성
이거 왜 이렇게 디테일하냐면요.
초반에 Claude한테 “스킬 만들어줘” 했더니 마음대로 구조 바꾸고, 200줄씩 써대고, 템플릿 무시하더라고요.
그래서 “이렇게 하지 마!”까지 명시한 겁니다.
솔직히 AI도 잔소리 들어야 제대로 일해요 ㅋㅋ
2) 워크플로우 강제
“이 순서대로 해!”라는 단계별 지시도 넣습니다.
## 🎯 Agent/Skill Creation Workflow
STEP 1: 트리거 인식
사용자: "XXX 스킬 만들어줘"
↓
트리거 감지 ✅
STEP 2: 명시적 선언
"[확인] XXX 스킬을 생성하겠습니다"
"[읽기] .claude/docs/skills/skill-structure.md 참조"
STEP 3: 공식 가이드 읽기
if 스킬:
read_file(".claude/docs/skills/skill-structure.md")
elif 에이전트:
read_file(".claude/docs/agents/agent-structure.md")
STEP 4: 템플릿 기반 생성
STEP 5: 검증
이거 없으면 Claude가 “아 맞다, 가이드 읽어야지” 하고 까먹어요.
진짜예요.
3) 자가 검증 체크리스트
AI가 스스로 “내가 잘했나?” 확인하는 섹션도 있어요.
## 🧪 Self-Check (자가 검증) 스킬/에이전트 생성 후 자가 질문: Q1: .claude/docs/ 가이드를 읽었는가? A: Yes ✅ / No ❌ Q2: 공식 예시 구조를 템플릿으로 사용했는가? A: Yes ✅ / No ❌ Q3: 50-100줄 범위인가? A: Yes ✅ / No ❌ Q4: description이 한 문장인가? A: Yes ✅ / No ❌ 모두 ✅ → 성공 하나라도 ❌ → 재작성
이거 넣고 나서 실수가 90% 줄었어요.
AI도 체크리스트 주면 더 정확하게 일합니다.
진짜 효과 있나요? (솔직 후기)
6개월 써본 저의 솔직한 의견 말씀드릴게요.
✅ 좋았던 점
1. 반복 설명 90% 감소
예전엔 대화 시작할 때마다:
사용자: "블로그 글 써줘.
근데 OREO 구조로,
팩트 체크 필수,
경험 중심으로..."
이제는:
사용자: "블로그 글 써줘" Claude: [CLAUDE.md 규칙 자동 적용]
말 안 해도 알아서 합니다.
진짜 편함.
2. 일관성 유지
32개 스킬 만들었는데 전부 구조가 똑같아요.
나중에 봐도 바로 이해됨.
팀 프로젝트면 더 좋겠죠.
3. 실수 방지
“웹 검색 필수” 규칙 넣어놨더니 Claude가 한 번도 안 까먹었어요.
CLAUDE.md 없을 때는 10번 중 3번은 웹 검색 생략하더라고요.
⚠️ 아쉬운 점
1. 100% 준수는 아님
가끔 규칙 무시하고 마음대로 할 때 있어요.
그럴 땐 “CLAUDE.md 규칙 확인해” 하면 바로 수정함.
2. 너무 길면 역효과
초반에 CLAUDE.md를 500줄로 만들었다가 Claude가 헷갈려하더라고요.
200줄 이하로 핵심만 담는 게 좋습니다.
3. 업데이트 필요
프로젝트 진행하면서 규칙 바뀌잖아요?
CLAUDE.md도 같이 업데이트해줘야 함.
한 달에 한 번 정도 점검 필요.
실제 사용 예시: Before/After
제 블로그 자동화 시스템으로 보여드릴게요.
❌ Before (CLAUDE.md 없을 때)
사용자: "블로그 통계 스킬 만들어줘" Claude: "네! 만들어드리겠습니다" ↓ [마음대로 구조 작성] [200줄짜리 장황한 문서] [템플릿 무시] ↓ 사용자: "아니 이거 아니고..." ↓ 3번 재작성 😭
시간 낭비 30분.
✅ After (CLAUDE.md 사용)
사용자: "블로그 통계 스킬 만들어줘" Claude: "[확인] .claude/docs/skills/skill-structure.md 읽기" ↓ [공식 가이드 읽음] ↓ [템플릿 기반 생성] ↓ [50-80줄, 명확한 구조] ↓ 사용자: "오 딱 이거야!" ✅
한 방에 끝.
5분 걸림.
차이 느껴지시죠?
여러분도 만들 수 있나요?
당연하죠!
최소 템플릿 (30초면 만듦)
--- title: My Project Rules version: 1.0.0 --- # My Project Rules ## 🚨 절대 규칙 1. 절대 지켜야 할 규칙1 2. 절대 지켜야 할 규칙2 3. 절대 지켜야 할 규칙3 ## 📋 워크플로우 STEP 1: ~ STEP 2: ~ STEP 3: ~ ## ✅ 필수 사항 - 필수1 - 필수2 ## ❌ 금지 사항 - 금지1 - 금지2
이거 .claude/CLAUDE.md로 저장하면 끝.
진짜 이게 전부예요.
어떤 규칙을 넣어야 할까요?
제가 6개월 써보니까 이런 것들이 효과 좋더라고요:
1. 반복해서 말하는 것들
❌ "매번 팩트 체크 해줘" ✅ CLAUDE.md에 "팩트 체크 필수" 규칙 추가
2. 자주 실수하는 것들
❌ "아 또 웹 검색 안 했네..." ✅ CLAUDE.md에 "웹 검색 생략 금지" 규칙 추가
3. 파일 구조 / 네이밍 규칙
❌ "파일명은 kebab-case로!" ✅ CLAUDE.md에 "네이밍 규칙: kebab-case" 추가
4. 출력 형식
❌ "체크리스트 형식으로 보여줘" ✅ CLAUDE.md에 "출력 형식: 체크리스트 필수" 추가
근데 진짜 웃긴 게요
이거 쓰고 나서 제가 느낀 건데요.
AI한테 규칙 정리하는 게 사람 관리보다 쉬워요.
사람한테 “이렇게 해줘” 하면:
- “왜요?”
- “다른 방법 없나요?”
- “전에는 안 그랬는데요?”
AI한테 CLAUDE.md로 규칙 주면:
- 묻지도 따지지도 않음
- 그냥 함
- 일관되게 함
물론 AI는 창의성 없고, 사람은 융통성 있죠.
근데 **”정해진 규칙 지키기”**에서만큼은 AI가 훨씬 낫더라고요.
이게 2026년 AI 시대의 아이러니인 것 같아요.
다른 AI 도구에서도 되나요?
네, 개념은 같습니다.
| 도구 | 규칙 파일 위치 | 비고 |
|---|---|---|
| Claude Code | .claude/CLAUDE.md | 가장 명확한 구조 |
| Cursor | .cursorrules | 1개 파일에 모든 규칙 |
| Windsurf | project_context.md | 이름만 다름 |
| Cline | cline_docs/ 폴더 | 여러 파일로 분산 가능 |
| ChatGPT Projects | Custom Instructions | UI에서 직접 입력 |
핵심은 같습니다:
“AI한테 프로젝트 규칙을 미리 알려주는 파일”
이름이 CLAUDE.md든, .cursorrules든, 개념은 동일해요.
실전 팁 (6개월 경험담)
1. 짧게 시작하세요
❌ 처음부터 500줄 규칙서 만들기 ✅ 10줄짜리 간단한 규칙 → 필요할 때 추가
제 CLAUDE.md도 처음엔 20줄이었어요.
6개월 쓰면서 지금 285줄 됨.
한 번에 완벽하게 만들 필요 없어요.
2. 구체적으로 쓰세요
❌ “좋은 코드 작성해줘” ✅ “함수는 최대 50줄, 주석 필수, 에러 처리 포함”
AI는 “좋은 코드”가 뭔지 몰라요.
숫자와 예시로 말해야 합니다.
3. 금지 사항도 명시하세요
❌ “이렇게 해줘” (only) ✅ “이렇게 해줘 + 이건 하지 마”
AI는 착한 학생이 아니에요.
“하지 마”를 안 말하면 마음대로 합니다.
4. 체크리스트 추가하세요
## 작업 전 필수 확인 [ ] 웹 검색 완료? [ ] 팩트 체크 완료? [ ] 템플릿 사용?
이거 넣으니까 실수가 진짜 줄었어요.
AI도 체크리스트 좋아하더라고요.
5. 버전 관리 하세요
--- version: 1.2.0 last_updated: 2026-01-09 ---
나중에 “어? 이거 언제 바뀌었지?” 할 때 유용함.
FAQ (자주 묻는 질문)
Q1. CLAUDE.md가 너무 길어지면 어떡하죠?
A: 200줄 넘어가면 분리하세요.
.claude/ ├── CLAUDE.md ← 핵심 규칙만 (200줄 이하) ├── docs/ │ ├── coding-style.md ← 코딩 스타일 상세 │ ├── naming-rules.md ← 네이밍 규칙 상세 │ └── workflows/ ← 워크플로우 상세
CLAUDE.md에는 “상세는 docs/ 참조” 링크만 넣으면 됨.
Q2. 여러 프로젝트에서 공통으로 쓸 수 있나요?
A: 네, 템플릿 만들어두세요.
저는 claude-template/ 폴더에 기본 CLAUDE.md 만들어놨어요.
새 프로젝트 시작할 때 복사해서 씁니다.
Q3. Claude가 규칙 안 지킬 때는?
A: “CLAUDE.md 규칙 확인해” 한마디면 됨.
그럼 파일 다시 읽고 수정해줘요.
Q4. 팀 프로젝트에서도 유용한가요?
A: 엄청 유용합니다!
신입 개발자한테 “CLAUDE.md 읽어봐” 하면 프로젝트 규칙 파악 끝.
AI도 사람도 같은 규칙서 보는 거죠.
Q5. 업데이트 주기는?
A: 저는 한 달에 한 번 점검해요.
“자주 반복하는 지시 있나?” “새로 생긴 실수 패턴 있나?”
체크하고 CLAUDE.md 업데이트.
마무리하며
CLAUDE.md는 그냥 텍스트 파일이에요.
근데 이게 있고 없고 차이가 엄청 큽니다.
있으면:
- 매번 지시 반복 안 해도 됨
- AI가 일관되게 일함
- 실수 90% 감소
- 시간 절약 (하루 30분)
없으면:
- 같은 말 10번 반복
- AI가 매번 다르게 일함
- 자잘한 실수 많음
- 스트레스 ↑
6개월 써본 제 솔직한 결론:
“AI 쓰려면 CLAUDE.md부터 만들어라”
10분 투자로 앞으로 몇 달 편하게 쓸 수 있어요.
지금 바로 .claude/ 폴더 만들고, CLAUDE.md 파일 하나 만들어보세요.
20줄이면 충분합니다.