9강: CLAUDE.md
AI에게 규칙을 알려주는 설명서
매번 같은 말, 하기 귀찮지 않으세요?
8강에서 첫 프로젝트를 만들었어요. HTML + CSS로 개인 웹페이지를 완성하고, GitHub Pages로 배포까지 했죠. 8강 마지막에 이렇게 말씀드렸어요. "CLAUDE.md에 규칙을 한 번 적어두면, AI가 매번 알아서 그 규칙을 따라요."
바로 오늘 그 이야기를 해볼 거예요.
새로 전학 온 친구에게 매번 같은 설명을 반복하는 상황을 상상해 보세요. "우리 반은 실내화 신어야 해", "점심시간은 12시야", "칠판 지우는 건 3번이 해". 매일 아침마다 이걸 반복하면 피곤하잖아요. 그래서 학교에는 학생 수칙이 있어요. 한 번 적어두면, 새로 오는 사람도 그걸 읽으면 끝이에요.
CLAUDE.md가 바로 그 학생 수칙이에요. AI에게 "이 프로젝트에서는 이렇게 해" 하고 적어두는 프로젝트 규칙서예요. 한 번 적어두면, Claude Code를 실행할 때마다 AI가 자동으로 이 파일을 읽고 규칙을 따라요. 매 번 "한글로 설명해줘", "다크 모드로 해줘", "다른 파일은 건드리지 마" 같은 말을 반복할 필요가 없어요.
우리는 이렇게 쓰고 있어요
지금 여러분이 읽고 있는 이 AI//STUDY 사이트도 CLAUDE.md를 쓰고 있어요. 실제 내용을 보여드릴게요.
프로젝트 CLAUDE.md (프로젝트 루트의 규칙서)
프로젝트 폴더 맨 위에 있는 CLAUDE.md 파일이에요. AI가 이 프로젝트에서 일할 때 따라야 할 규칙이 적혀 있어요.
# ai-study -- D-ONWORKS Knowledge Archive
D-ONWORKS의 AI 지식 아카이브 사이트. 도메인: ai.d-onworks.com.
- 스택: Docusaurus 3.9.2 · React 18 · HOLOGRID 커스텀 테마 (다크 only)
- 배포: git push origin main → Vercel 자동 빌드 (webhook)
- 로컬 개발: npm start (http://localhost:3000/)
## 금지 사항
- static/decks/clauders-4/index.html -- 원본 슬라이드. 임의로 구조 변경 금지.
- static/mockups/style-{2,3,4}-*/ -- 선택되지 않은 목업. 삭제 금지.
여기에 뭐가 적혀 있는지 보세요. 기술 스택(이 프로젝트가 어떤 도구로 만들어졌는지), 배포 방법(어떻게 인터넷에 올리는지), 금지 사항(절대 건드리면 안 되는 파일)이 들어있어요. 이걸 적어두면 AI가 엉뚱한 도구를 추천하거나, 건드리면 안 되는 파일을 수정하는 실수를 막을 수 있어요.
회사 공통 CLAUDE.md (모든 프로젝트에 적용)
디온웍스에서는 여러 프로젝트를 동시에 관리해요. 모든 프로젝트에 공통으로 적용되는 규칙이 있어요.
# D-ONWORKS 회사 공통 규칙
## 언어
- 모든 설명, 주석, 커밋 메시지는 한글 작성.
변수명, 함수명, 파일명만 영어.
## AI 코드 품질
- AI가 추천한 패키지는 반드시 실존 여부 확인
(환각 패키지 19.7% 발생)
- 같은 기능에 서로 다른 라이브러리 혼용 금지
## 코드 구조
- 모든 파일 500줄 초과 금지
"한글로 써라", "AI가 추천하는 패키지가 진짜 있는지 확인해라", "파일 하나가 500줄 넘으면 안 된다." 이런 규칙을 한 번 적어두면, 어떤 프로젝트를 열든 AI가 알아서 따라요.
여기서 눈여겨볼 부분이 있어요. "환각 패키지 19.7% 발생" 이라는 문장이에요. AI가 존재하지 않는 가짜 패키지(다른 사람이 만든 코드 묶음)를 추천하는 경우가 약 5개 중 1개라는 뜻이에요. 그래서 "반드시 확인해라"는 규칙을 넣어둔 거예요. 이렇게 실제 경험에서 얻은 교훈을 CLAUDE.md에 적어두면 같은 실수를 반복하지 않아요.
CLAUDE.md의 3가지 레벨
CLAUDE.md는 적용 범위에 따라 3가지 레벨이 있어요. 학교에 비유하면 이렇게 생각하면 돼요.
| 레벨 | 파일 위치 | 비유 | 적용 범위 |
|---|---|---|---|
| 프로젝트 | 프로젝트 폴더의 CLAUDE.md | 반 규칙 | 이 프로젝트에서만 |
| 글로벌 | ~/.claude/CLAUDE.md | 학교 교칙 | 내 모든 프로젝트 |
| 회사 공통 | 관리자가 설정하는 정책 파일 | 교육부 지침 | 회사 전체 |
~(틸다)는 "내 홈 폴더"를 뜻하는 기호예요. Windows에서는 C:\Users\내이름\ 에 해당해요.
프로젝트 레벨 — "이 프로젝트에서만 적용되는 규칙"
프로젝트 폴더 맨 위에 CLAUDE.md 파일을 만들면 돼요. 그 프로젝트에서 Claude Code를 실행할 때만 적용돼요.
# 내 첫 프로젝트 규칙
- 기술: HTML + CSS (JavaScript 사용하지 마)
- 디자인: 다크 배경(#0a0a0a), 시안 포인트(#00e5ff)
- 파일: index.html과 style.css 2개만 사용
- 한글로 설명해줘
- 코드에 한글 주석 달아줘
8강에서 만든 개인 웹페이지 프로젝트에 이 파일을 넣어두면, 앞으로 이 프로젝트에서 Claude에게 뭘 시키든 위 규칙을 자동으로 따라요.
글로벌 레벨 — "내 모든 프로젝트에 적용되는 규칙"
~/.claude/CLAUDE.md 에 파일을 만들면 돼요. 어떤 프로젝트를 열든 항상 적용돼요.
# 글로벌 지침
## 언어
- 모든 설명은 한글로 작성.
코드 내 변수명, 함수명, 파일명만 영어 허용.
"한글로 설명해줘"를 매 프로젝트마다 적을 필요 없이, 글로벌에 한 번만 적으면 돼요. 디온웍스에서는 이 파일에 "한글 작성", "빌드 규칙", "FTP 관리 규칙" 같은 전사 공통 지침을 넣어두고 있어요.
우선순위 — 프로젝트 규칙이 이긴다
같은 내용이 글로벌과 프로젝트에 둘 다 적혀 있으면 어떻게 될까요? 프로젝트 규칙이 우선이에요. 학교 교칙에 "교복 착용" 이라고 적혀 있어도, 체육 시간에는 "체육복 착용" 규칙이 이기잖아요. 그런 원리예요.
CLAUDE.md에 뭘 적어야 할까요?
처음에는 뭘 적어야 할지 모르겠죠? 이 4가지만 넣으면 충분해요.
1. 기술 스택 — "이 프로젝트는 이걸로 만들어"
## 기술 스택
- HTML + CSS + JavaScript
- 외부 라이브러리 사용하지 마
- 이미지 파일 사용하지 마
AI가 엉뚱한 도구를 쓰는 걸 막아줘요. "React 안 쓰고 HTML만 쓸 거야" 하고 적어두면, AI가 갑자기 React(웹 화면을 만드는 프레임워크) 코드를 생성하는 일이 없어요.
2. 디자인 규칙 — "색상과 스타일은 이렇게"
## 디자인
- 배경: #0a0a0a (거의 검정)
- 글씨: #e0e0e0 (밝은 회색)
- 포인트: #00e5ff (시안, 밝은 파란색)
- 모바일 반응형 필수
7강에서 "구체적인 숫자와 이름을 쓰세요" 라고 했죠? CLAUDE.md에 색상 코드를 적어두면, 새로운 기능을 추가할 때마다 매번 색상을 알려줄 필요가 없어요.
3. 금지 사항 — "이건 절대 하지 마"
## 금지 사항
- index.html의 기본 구조(head, body)는 변경하지 마
- style.css의 색상 변수는 내가 허락할 때만 수정해
- 새로운 파일 추가하지 마
7강에서 "안 할 것"을 말하는 게 중요하다고 했죠? 프롬프트에 매번 적는 대신, CLAUDE.md에 한 번 적어두면 돼요.
4. 작업 스타일 — "이런 식으로 일해줘"
## 작업 방식
- 설명은 한글로 해줘
- 코드에 한글 주석 달아줘
- 한 번에 하나의 기능만 수정해
- 수정 후에는 어떤 파일을 바꿨는지 알려줘
AI의 일하는 방식을 정해주는 거예요. 이걸 적어두면 Claude가 매번 일관된 방식으로 작업해요.
context7 — AI가 최신 공식 문서를 직접 보게 하기
CLAUDE.md가 "프로젝트 규칙서"라면, context7은 AI를 위한 도서관 사서예요.
AI에게 "Docusaurus 설치 방법 알려줘" 하고 물어보면, AI는 자기가 학습한 시점의 정보를 바탕으로 대답해요. 문제는, AI의 학습 데이터가 항상 최신이 아니라는 거예요. 6개월 전에는 npx create-docusaurus@2.0 이었는데 지금은 npx create-docusaurus@3.9 일 수 있어요. AI가 옛날 버전을 알려주면, 설치는 되는데 이상하게 동작하거나 에러가 나요.
context7을 설치하면, AI가 실시간으로 공식 문서를 직접 조회해서 최신 정보를 가져와요. 도서관에서 오래된 교과서 대신, 사서에게 "최신판 가져다주세요" 하는 거예요.
context7 설치하기
Claude Code 대화창에서 딱 한 줄이면 돼요.
클로드 코드 대화창에서
!를 맨 앞에 붙이면 터미널 명령어를 바로 실행할 수 있어요.
# context7 설치 (OAuth 인증 후 자동 설정)
! npx ctx7 setup --claude
이 명령어가 하는 일을 풀어 설명하면 이래요.
npx ctx7— context7 CLI(명령줄 도구)를 실행해요setup— 초기 설정을 시작해요 (인증 + API 키 생성 + 설치를 한 번에)--claude— Claude Code 전용으로 설치해요
명령어를 실행하면 브라우저가 열리면서 인증 화면이 나와요. 로그인하면 자동으로 설정이 완료돼요.
버전 차이 체험해보기
context7이 왜 필요한지, 직접 체험해 볼게요. Claude Code 대화창에서 이렇게 물어보세요.
Docusaurus 최신 안정 버전이 뭐야?
공식 문서를 context7으로 확인해서 알려줘.
AI가 context7을 통해 공식 문서를 직접 조회하고, 최신 버전 정보를 정확하게 알려줄 거예요. context7 없이 물어봤을 때와 비교해 보면, 버전 번호가 다를 수 있어요. 이 차이가 바로 "학습 데이터의 시차" 문제예요. context7은 그 시차를 없애줘요.
settings.json — Claude Code의 행동을 조절하는 설정
CLAUDE.md가 "무엇을 해라/하지 마라"를 적는 규칙서라면, settings.json(설정 파일)은 Claude Code 프로그램 자체의 동작 방식을 조절하는 설정이에요.
리모컨의 버튼이라고 생각하면 돼요. CLAUDE.md는 "이 채널만 봐" 같은 콘텐츠 규칙이고, settings.json은 "볼륨 크기", "화면 밝기" 같은 기계 설정이 에요.
settings.json은 /config 명령어로 편하게 수정할 수 있어요. Claude Code 대화창에서 /config 를 입력하면 설정 화면이 열려요. 초보자가 꼭 알아둘 설정 3가지만 소개할게요.
1. permissions — 자주 쓰는 명령어 자동 허용
Claude Code는 파일을 수정하거나 명령어를 실행할 때마다 "이거 해도 돼?" 하고 물어봐요. 안전장치예요. 그런데 매번 "허용" 버튼을 누르는 게 귀찮을 때가 있어요.
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)"
]
}
}
이렇게 적어두면, npm run lint(코드 스타일 검사)와 npm run test(테스트 실행)는 물어보지 않고 바로 실행해요.
2. language — 응답 언어 설정
{
"language": "korean"
}
이걸 설정해두면 Claude가 항상 한글로 응답해요. CLAUDE.md에 "한글로 써줘"를 적는 것과 비슷하지만, 이건 프로그램 레벨의 설정이라 더 확실해요.
3. model — 사용할 AI 모델 선택
{
"model": "claude-sonnet-4-6"
}
Claude에는 여러 모델이 있어요. Opus(가장 똑똑하고 느린 모델), Sonnet(속도와 성능의 균형), Haiku(가장 빠르고 가벼운 모델). 기본값은 자동 선택이지만, 특정 모델을 고정하고 싶으면 이 설정을 쓰면 돼요.
메모리 시스템 — AI가 나를 기억하게 하기
CLAUDE.md는 "규칙"을 적는 파일이고, 메모리(Memory)는 AI가 대화에서 배운 것을 자동으로 기억하는 시스템이에요.
예를 들어, 여러분이 Claude에게 "나는 커밋하기 전에 항상 확인해줘" 라고 말하면, AI가 그 내용을 자동으로 메모리에 저장해요. 다음에 새 대화를 시작해도, AI는 "아, 이 사람은 커밋 전에 확인을 원하는구나" 하고 기억하고 있어요.
디온웍스의 AI//STUDY 프로젝트 메모리를 살짝 보여드릴게요.
# ai-study 프로젝트 메모리 인덱스
- 프로젝트 정체성: Docusaurus 지식 아카이브, HOLOGRID 테마
- 커밋/푸시는 사용자가 명시적으로 요청할 때만
- 커밋 전 untracked files 확인 필수
- 글감 저장소 위치: docs/.drafts/ideas/
AI가 알아서 "이 프로젝트는 Docusaurus 아카이브구나", "커밋은 함부로 하면 안 되는구나" 같은 걸 기억하고 있어요. 한 번도 직접 파일에 적은 적 없는데, 대화 중에 "커밋은 내가 시킬 때만 해" 라고 말한 걸 AI가 스스로 정리해서 저장한 거예요.
메모리는 대화를 하면서 자동으로 쌓이기 때문에, 지금 당장 뭔가를 설정할 필요는 없어요. Claude Code를 쓰다 보면 자연스럽게 채워져요. /memory 명령어로 현재 저장된 메모 리를 확인할 수 있어요.
실습: 내 프로젝트에 CLAUDE.md 만들기
8강에서 만든 개인 웹페이지 프로젝트에 CLAUDE.md를 직접 만들어 볼게요.
1단계: 프로젝트 폴더로 이동
일반 터미널(Windows 명령 프롬프트 또는 Mac 터미널)에서 8강 프로젝트 폴더로 이동하세요.
# 8강에서 만든 프로젝트 폴더로 이동
cd ~/my-page
# Claude Code 시작
claude
2단계: CLAUDE.md 만들기
Claude Code 대화창에서 이렇게 시키세요.
프로젝트 루트에 CLAUDE.md 파일을 만들어줘.
내용은 아래와 같이:
# my-page 프로젝트 규칙
## 기술 스택
- HTML + CSS만 사용 (JavaScript 쓰지 마)
- 외부 라이브러리 사용 금지
- 파일: index.html, style.css 2개만
## 디자인 규칙
- 배경: #0a0a0a
- 글씨: #e0e0e0
- 포인트: #00e5ff
- 모바일 반응형 필수
## 금지 사항
- 새 파일 추가 금지
- 기존 HTML 구조(head, body 태그) 변경 금지
- 이미지 파일 사용 금지
## 작업 방식
- 설명은 한글로
- 코드에 한글 주석 달기
- 수정 후 바뀐 파일 목록 알려주기
3단계: context7 설치
# context7 설치 (한 번만 하면 모든 프로젝트에서 사용 가능)
! npx ctx7 setup --claude
브라우저가 열리면 로그인하세요. 인증이 완료되면 자동으로 설정돼요.
4단계: 효과 체험하기
CLAUDE.md가 만들어졌으니, 이제 효과를 느껴볼 차례예요.
히어로 섹션에 그라데이션 배경을 추가해줘.
이렇게만 말해도, AI가 CLAUDE.md를 읽고 알아서 이렇게 해줄 거예요.
- style.css만 수정해요 (새 파일 추가 금지 규칙)
- #0a0a0a와 #00e5ff를 활용한 그라데이션을 넣어요 (디자인 규칙)
- JavaScript 없이 CSS만으로 구현해요 (기술 스택 규칙)
- 한글 주석을 달아요 (작업 방식 규칙)
"한글로 해줘", "CSS만 써줘", "새 파일 만들지 마" 같은 말을 하나도 안 했는데, AI가 전부 지켜요. 이게 CLAUDE.md의 힘이에요.
PART 2를 마무리하며
여기까지 오신 분들, 정말 대단해요.
PART 1(1–5강)에서 환경을 세팅하고, PART 2(6–9강)에서 기획부터 첫 프로젝트, 그리고 오늘 프로젝트 규칙서까지 완성했어요. 정리하면 이래요.
| 강 | 한 줄 요약 | 산출물 |
|---|---|---|
| 6강 | 아이디어를 기획서로 | PRD 완성 |
| 7강 | AI에게 잘 시키는 법 | 프롬프트 3요소 |
| 8강 | 첫 프로젝트 완성 | 내 URL |
| 9강 | AI에게 규칙서 만들기 | CLAUDE.md + context7 |
여러분은 이제 기획도 하고, 프롬프트도 쓰고, 프로젝트도 만들고, 규칙서도 세팅한 거예요. 바이브 코딩의 기초 체력이 완성된 셈이에요.
다음 강부터는 PART 3: 본격 개발이에요. 10강에서는 수직 슬라이싱을 배워요. "한 번에 전부 만 들어줘"가 왜 위험한지, "한 입씩 만들기"가 왜 정답인지 알게 될 거예요. PART 3부터는 진짜 서비스를 만들기 시작해요.
이번 강에서 기억할 것
핵심만 정리해 볼게요.
-
CLAUDE.md는 프로젝트 규칙서예요. 기술 스택, 디자인 규칙, 금지 사항, 작업 방식을 적어두면 AI가 매번 자동으로 따라요. 매번 같은 말 반복할 필요 없어요.
-
3가지 레벨이 있어요. 프로젝트(이 프로젝트만) > 글로벌(내 모든 프로젝트) > 회사 공통(회사 전체). 프로젝트 규칙이 가장 우선이에요.
-
context7로 AI에게 최신 문서를 보여주세요. AI의 학습 데이터는 항상 최신이 아니에요. context7을 설치하면 AI가 공식 문서를 실시간으로 조회해요. 설치는 한 줄이면 끝이에요.
-
settings.json은 Claude Code의 리모컨이에요. 자주 쓰는 명령어 자동 허용, 응답 언어, 사용 모델을 설정할 수 있어요.
/config명령어로 편하게 수정해요. -
메모리는 자동이에요. 대화 중에 AI가 중요한 정보를 알아서 기억해요. 따로 설정할 필요 없이, Claude Code를 쓰다 보면 자연스럽게 채워져요.
이런 분께 추천해요
CLAUDE.md는 "AI에게 매번 같은 말 반복하기 귀찮은 분"을 위한 해결책이에요.
- 8강에서 첫 프로젝트를 만들었는데, AI가 매번 다른 스타일로 작업해서 답답한 분 -- CLAUDE.md에 디자인 규칙을 적어두면, 어떤 요청을 해도 일관된 스타일이 나와요.
- 바이브 코딩을 시작했는데, 프로젝트가 커질수록 AI에게 설명할 게 많아지는 분 -- 규칙서를 한 번 세팅해두면, 프로젝트가 아무리 커져도 AI가 맥락을 놓치지 않아요.
- AI가 옛날 버전 코드를 알려줘서 에러가 난 적 있는 분 -- context7을 설치하면 AI가 항상 최신 공식 문서를 참조해요. 버전 문제 걱정이 없어져요.
참고 링크
▸개정 이력1건
- v12026-04-13초판
이 글이 도움이 되었나요?