클로드 코드에 일을 시킬 때마다 “한국어로 답해 줘”, “가격은 지어내지 마”를 다시 적고 있다면 CLAUDE.md를 만들 때입니다. CLAUDE.md는 작업 폴더에 두는 메모 파일이고, 클로드 코드는 대화를 시작할 때마다 이 파일을 먼저 읽습니다. 파일을 만드는 데 돈은 들지 않지만, 클로드 코드를 쓰려면 Pro 이상 구독이나 API 결제가 필요합니다. 이 글은 동네 빵집 소개 페이지를 똑같은 요청으로 두 번 만들게 해 본 기록입니다. 한 번은 CLAUDE.md 없이, 한 번은 규칙 11줄을 넣고 시켰습니다.
세 줄 요약
- 얻는 것: 매번 하던 당부(답하는 말투, 디자인 규칙, 하지 말 것)를 파일 하나에 적어 두면 클로드 코드가 알아서 지킵니다. 제가 실험에 쓴 파일을 템플릿으로 내려받을 수 있습니다.
- 시간: 템플릿을 내 일에 맞게 고치는 데 10분쯤, 효과를 확인하는 요청 한 번에 1분이 채 안 걸립니다.
- 비용: 이번 페이지 만들기 요청은 한 번에 API 요금으로 환산해 약 0.3달러어치 사용량이었습니다.
같은 요청, CLAUDE.md가 있을 때와 없을 때
먼저 결과부터 보여 드립니다. 빈 폴더 두 개를 만들고 한쪽에만 CLAUDE.md를 넣은 뒤, 두 폴더에서 아래 요청을 똑같이 보냈습니다. 빵집 정보는 일부러 하나도 주지 않았습니다.
우리 동네 빵집 '밀밭베이커리' 소개 페이지를 만들어 줘. 대표 메뉴, 영업시간, 오시는 길이 들어가면 돼.
직접 눌러 보기: CLAUDE.md 없이 만든 페이지 · 규칙 11줄을 넣고 만든 페이지. 휴대폰으로 열면 실제 모습 그대로 보입니다.
같은 요청을 폴더마다 두 번씩, 모두 네 번 보냈습니다. 결과는 두 번 모두 같은 방향이었습니다.
| 살펴본 것 | CLAUDE.md 없이 (2회) | CLAUDE.md 넣고 (2회) |
|---|---|---|
| 메뉴 가격 | 두 번 다 빵 6개에 가격을 지어 넣음(통밀 캄파뉴 7,000원 등) | 두 번 다 [가격 입력] 빈칸 |
| 영업시간 | 요일별 시간을 지어 넣음 | [영업시간 입력] 빈칸 |
| 주소·전화번호 | ○○로 123, 000-0000-0000 같은 자리표시(지어내지는 않음) | [주소 입력], [전화번호 입력] 빈칸 |
| 바깥에서 불러오는 것 | 두 번 다 구글 글꼴, 한 번은 가게 이름으로 검색한 구글 지도까지 | 없음 |
| 파일 | HTML 파일 하나에 디자인·동작 코드까지 모두 | index.html과 style.css 두 개 |
| 쓴 색 | 14가지 | 지정한 3가지와 사진 자리 회색 1가지 |
| 휴대폰 전화 버튼 | 화면 아래 고정 없음 | 화면 아래 고정, 높이 56px(규칙은 48px 이상) |
| 끝에 알려 주는 말 | 들어간 내용을 길게 설명 | 파일 목록과 확인 방법을 알려 줌. “3줄 이내”는 두 번 다 넘김 |
솔직히 첫인상은 왼쪽이 더 완성돼 보입니다. 오른쪽은 빈칸투성이입니다. 왼쪽도 끝에 “임시로 채워 넣었다”고 알려 주기는 했습니다. 그래도 실제 가게 정보를 넣을 생각이라면 오른쪽이 훨씬 고치기 쉽습니다. 왼쪽은 그럴듯한 가격과 영업시간을 하나하나 찾아 지워야 합니다. 구글 지도를 넣은 쪽은 이름만 같은 다른 가게를 가리킬 수도 있습니다. CLAUDE.md가 해 준 일은 페이지를 꾸미는 쪽보다 제가 정한 규칙을 지키게 하는 쪽이었습니다.
직접 실행 확인한 날짜 2026-10-14
- 무엇인가
- 클로드 코드가 대화를 시작할 때마다 읽는 메모 파일(마크다운 글)
- 이번에 쓴 것
- Opus 5.5 · 생각 깊이 중간(비교 4회, 프롬프트 시험, /init 모두 같음) · macOS 26.1
- 준비물
- 클로드 코드(설치 방법), 작업 폴더 하나
- 원본
- Claude Code 메모리 문서 (한국어)
복사해 쓰는 프롬프트: 내 프로젝트용 CLAUDE.md 만들기
CLAUDE.md를 처음부터 쓰기 막막하면 클로드 코드에게 맡겨도 됩니다. 작업 폴더에서 클로드 코드를 열고 아래 글을 붙여 넣습니다. <…> 부분만 내 일로 바꿉니다.
[역할] 너는 클로드 코드를 처음 쓰는 사람을 돕는 도우미야.
[맥락] 나는 개발을 잘 모르고, 이 폴더에서 <만들려는 것: 우리 동네 빵집 소개 한 페이지 웹사이트>를 만들려고 해.
[입력] 꼭 지켰으면 하는 것: <휴대폰에서 먼저 보기 좋게, 색은 크림색·갈색 계열, 전화 걸기 버튼>
지난번에 싫었던 것: <가격이랑 전화번호를 마음대로 지어냄, 바깥 글꼴을 불러옴, 파일이 하나에 다 섞임>
[작업] 이 폴더 맨 위에 CLAUDE.md 파일을 만들어 줘.
[제약] 한국어로 쓴다. 20줄 안팎, 길어도 40줄을 넘기지 않는다. 규칙은 "예쁘게" 같은 말 대신 확인할 수 있는 문장으로 쓴다(예: "색은 세 가지만"). CLAUDE.md 말고 다른 파일은 만들거나 고치지 않는다. 이미 CLAUDE.md가 있으면 덮어쓰지 말고 고칠 점만 알려 준다.
[출력] 대화, 파일 구조, 디자인, 하지 말 것 네 묶음으로 나눈다.
[확인] 다 쓰면 줄 수를 세어 알려 주고, 확인할 수 없는 문장이 남아 있으면 고친 뒤에 끝낸다.좋은 답이라면 CLAUDE.md 하나만 생기고, 네 묶음으로 나뉘어 있고, 색 코드나 픽셀 같은 숫자로 된 규칙이 들어 있습니다. 빈 폴더에서 위 글 그대로 시켜 보니 1분이 채 안 걸려 26줄짜리 파일이 나왔습니다. 크림색·갈색은 색 코드 세 개로 바뀌었고, “가격·전화번호를 예시로라도 채우지 않는다”는 줄도 들어갔습니다. 확인 칸의 지시대로 “화면 아래에 늘 보이게”라는 애매한 문장을 “position: fixed로 화면 아래에 고정”으로 고쳤다고 알려 왔습니다.
1단계. 무엇을 적을지 정하기 (약 5분)
이 단계에서는 CLAUDE.md에 넣을 규칙을 고릅니다. 공식 문서는 CLAUDE.md를 “다시 설명해야 할 내용을 기록하는 장소”로 생각하라고 합니다. 클로드가 같은 실수를 두 번째 할 때, 지난번에 한 당부를 또 적고 있을 때가 추가할 때입니다.
제가 넣은 규칙 11줄은 다섯 묶음입니다. 이런 페이지를 시키면 흔히 거슬리는 점(지어낸 가격, 바깥 글꼴, 한 파일에 섞인 코드)을 미리 규칙으로 적었습니다. CLAUDE.md 없이 만든 쪽에서 세 가지 모두 실제로 나왔습니다.
# 밀밭베이커리 소개 페이지
## 대화
- 답은 한국어로 한다. 개발 용어는 처음 나올 때 한 줄로 풀어 쓴다.
- 작업이 끝나면 만든 파일 목록과 확인하는 방법을 3줄 이내로 알려 준다.
## 파일 구조
- index.html(내용)과 style.css(디자인) 두 파일만 만든다. 자바스크립트가 꼭 필요할 때만 script.js 하나를 더 둔다.
- 외부 라이브러리, 외부 글꼴, 외부 이미지 주소를 쓰지 않는다. 사진 자리는 회색 상자에 "사진 넣을 자리"라고 적는다.
## 디자인
- 색은 세 가지만 쓴다: 배경 #FFF8EE, 글자 #3B2A1A, 강조 #C8702A.
- 글꼴은 시스템 기본 글꼴(-apple-system, "Apple SD Gothic Neo", "Noto Sans KR", sans-serif)을 쓴다.
- 이모지를 쓰지 않는다.
## 모바일 우선
- 폭 375px 휴대폰 화면을 먼저 맞추고, 768px 이상에서만 여러 칸으로 펼친다.
- 전화 걸기 버튼은 휴대폰 화면 아래에 고정하고, 누르는 영역은 높이 48px 이상으로 한다.
## 하지 말 것
- 주소, 전화번호, 가격, 손님 후기를 지어내지 않는다. 모르는 값은 [전화번호 입력]처럼 대괄호로 비워 둔다.
- 요청하지 않은 기능(예약, 장바구니, 로그인)을 넣지 않는다.가장 중요한 것은 확인할 수 있는 문장으로 쓰는 것입니다. 공식 문서도 “코드를 적절히 포맷하십시오” 대신 “2칸 들여쓰기 사용”처럼 쓰라고 합니다.
| ❌ 이렇게 쓰면 흐려집니다 | ✅ 이렇게 쓰면 지켰는지 확인할 수 있습니다 |
|---|---|
| 예쁘고 따뜻한 느낌으로 | 색은 세 가지만 쓴다: 배경 #FFF8EE, 글자 #3B2A1A, 강조 #C8702A |
| 가짜 정보 넣지 마 | 모르는 값은 [전화번호 입력]처럼 대괄호로 비워 둔다 |
| 모바일에서도 잘 보이게 | 폭 375px 휴대폰 화면을 먼저 맞추고, 768px 이상에서만 여러 칸으로 펼친다 |
| 깔끔하게 정리해 줘 | index.html과 style.css 두 파일만 만든다 |
길이는 짧을수록 좋습니다. 공식 문서는 파일 하나에 200줄 이하를 권하고, 길수록 컨텍스트(클로드가 한 번에 읽는 분량)를 더 쓰고 덜 지킨다고 설명합니다. 제 파일은 클로드가 읽는 분량으로 635토큰이었습니다.
2단계. 어디에 두나 정하기 (약 1분)
이 단계에서는 파일 위치를 고릅니다. 위치에 따라 적용되는 범위가 다릅니다. 처음에는 작업 폴더 맨 위에 두는 프로젝트 CLAUDE.md 하나면 충분합니다.
| 위치 | 어디에 적용되나 | 이럴 때 고르세요 |
|---|---|---|
작업 폴더의 CLAUDE.md 또는 .claude/CLAUDE.md | 그 폴더에서 일할 때. 저장소를 같이 쓰는 사람 모두 | 이 프로젝트에만 맞는 규칙 |
~/.claude/CLAUDE.md | 내 컴퓨터의 모든 폴더 | “한국어로 답하기”처럼 어디서나 원하는 습관 |
작업 폴더의 CLAUDE.local.md | 그 폴더, 나만 | 남과 공유하지 않을 개인 메모 |
하위 폴더의 CLAUDE.md | 클로드가 그 하위 폴더의 파일을 읽거나 고칠 때 불러옴 | 폴더마다 규칙이 다를 때 |
공식 문서에 따르면 찾은 파일은 서로 덮어쓰지 않고 모두 함께 읽힙니다. 그래서 두 파일의 규칙이 부딪치면 클로드가 아무 쪽이나 고를 수 있습니다. 실제로 제 컴퓨터의 ~/.claude/CLAUDE.md에는 다른 일용 규칙이 들어 있어서, 이번 비교에서는 그 파일이 섞이지 않게 빼고 실행했습니다(아래 실행 기록 상자).
빈 파일에서 시작하기 싫다면 클로드 코드 대화창에서 /init을 입력합니다. 공식 문서에 따르면 폴더를 살펴보고 시작용 CLAUDE.md를 만들어 주고, 이미 있으면 덮어쓰지 않고 고칠 점을 제안합니다. CLAUDE.md 없이 만든 빵집 페이지 폴더에서 해 보니 1분이 채 안 걸렸습니다.
나온 파일은 영어였고, 내용은 페이지 구조 설명이었습니다. 다크 모드 색이 두 군데 정의돼 있다, 주소와 전화번호는 자리표시다 같은 것입니다. “가격을 지어내지 마” 같은 제 취향은 당연히 들어 있지 않았습니다. /init은 코드가 이미 있는 폴더에서 출발점으로 쓰고, 원하는 규칙은 직접 덧붙이는 편이 맞습니다.
파일을 고칠 때는 대화창에서 /memory를 입력합니다. 공식 문서에 따르면 CLAUDE.md 위치 목록이 나오고, 고르면 편집기로 열립니다. 아직 없는 파일을 고르면 새로 만듭니다. 다른 파일 내용을 끌어오려면 CLAUDE.md 안에 @README.md처럼 @경로를 적습니다. 불러온 파일도 처음에 함께 읽히므로 분량을 줄여 주지는 않습니다.
3단계. 파일이 읽혔는지 확인하기 (약 1분)
이 단계에서는 클로드 코드가 내 CLAUDE.md를 실제로 읽었는지 봅니다. 작업 폴더에서 클로드 코드를 열고 대화창에 /context를 입력합니다. 저는 같은 명령을 터미널에서 한 번 묻고 끝나는 방식(claude -p /context)으로 실행해 확인했습니다.
이렇게 나오면 성공 Memory files 아래에 내 CLAUDE.md 경로가 보입니다. claude -p /context로 확인하니 Project | ~/claude-lab/claude-md/after/CLAUDE.md | 635가 나왔습니다. 대화창에서는 표 모양이 조금 다를 수 있습니다.
- 목록에 없으면: 클로드 코드를 연 폴더가 CLAUDE.md가 있는 폴더(또는 그 아래)인지 확인합니다. 공식 문서에 따르면 시작한 폴더와 그 위 폴더의 CLAUDE.md만 처음에 읽습니다.
- 하위 폴더에 둔 CLAUDE.md가 안 보이면: 정상입니다. 하위 폴더 파일은 클로드가 그 폴더의 파일을 읽거나 고칠 때 불러옵니다.
$ cd <작업 폴더>/claude-md/before # after 폴더에서도 똑같이 실행
$ claude -p "우리 동네 빵집 '밀밭베이커리' 소개 페이지를 만들어 줘. 대표 메뉴, 영업시간, 오시는 길이 들어가면 돼." \
--permission-mode acceptEdits \
--setting-sources project,local \
--settings '{"claudeMdExcludes":["/Users/<사용자>/.claude/CLAUDE.md"]}' \
--output-format json
# --permission-mode acceptEdits : 파일 만들기·고치기를 미리 허락(묻는 사람이 없으므로)
# --setting-sources, claudeMdExcludes : 제 개인 설정과 ~/.claude/CLAUDE.md가 섞이지 않게 뺌
# --output-format json : 걸린 시간과 사용량(API 요금 환산)을 함께 받음
# 결과 (duration_ms, total_cost_usd)
before 46832 0.303 index.html
after 33740 0.282 index.html style.css
before-2 48731 0.303 milbat-bakery.html
after-2 46412 0.305 index.html style.css
# 네 번 모두 model claude-opus-5-5, effort medium (세션 기록에서 확인)4단계. 지켜졌는지 보고 고치기 (약 5분)
이 단계에서는 결과물을 규칙과 한 줄씩 맞춰 봅니다. 위 비교 표가 그 결과입니다. 규칙 11줄 중 9줄은 두 번 모두 그대로 지켜졌습니다. 하나는 안 지켜졌고, 하나는 애매했습니다.
- “3줄 이내로 알려 준다”는 두 번 다 넘었습니다. 파일 목록과 확인 방법은 빠짐없이 알려 줬으니, 저는 이 정도면 된다고 보고 그대로 두었습니다. 꼭 지켜야 한다면 “답은 글머리표 3개로만 쓴다”처럼 더 좁게 씁니다.
- “색은 세 가지만”인데 사진 자리에 회색이 하나 더 들어갔습니다. 같은 파일에 “사진 자리는 회색 상자”라고 제가 적었기 때문입니다. 두 규칙이 살짝 부딪친 경우입니다. 고친다면 “사진 자리 상자는 #E5DED3″처럼 색을 정해 줍니다.
공식 문서도 CLAUDE.md는 클로드가 읽고 따르려고 하는 맥락일 뿐, 반드시 지킨다는 보장은 없다고 적고 있습니다. 매번 꼭 실행돼야 하는 일(예: 파일을 고칠 때마다 검사 돌리기)은 훅(hook)이라는 별도 기능으로 겁니다.
CLAUDE.md 템플릿 내려받기
위 실험에 그대로 쓴 파일에 사용 안내를 붙였습니다. CLAUDE.md 템플릿 내려받기(텍스트 파일). 내려받은 뒤 이름을 CLAUDE.md로 바꿔 작업 폴더 맨 위에 둡니다. [대괄호] 부분을 내 일에 맞게 바꾸고, 필요 없는 줄은 지웁니다.
파일 맨 위의 <!-- … --> 안내문은 지우지 않아도 됩니다. 공식 문서에 따르면 이런 주석 블록은 클로드에게 넘기기 전에 빠지므로 사용량을 쓰지 않습니다.
한계와 주의할 점
- 폴더마다 두 번씩, 모두 네 번 해 본 결과입니다. 같은 요청도 다시 시키면 결과가 조금씩 다릅니다.
- 윈도우에서는 해 보지 않았습니다.
대안
| 이름 | 다른 점 | 이럴 때 고르세요 |
|---|---|---|
| 매번 요청에 적기 | 파일 없이 그때그때 당부. 대화가 바뀌면 다시 적어야 함 | 한 번만 할 일 |
| 스킬 | 필요할 때만 불러오는 작업 절차 묶음 | 여러 단계짜리 절차, 가끔 하는 일 |
.claude/rules/ 폴더 | 규칙을 주제별 파일로 나눔. 특정 파일을 다룰 때만 불러오게 할 수도 있음 | 프로젝트가 커져 CLAUDE.md가 길어질 때 |
자주 묻는 질문
CLAUDE.md는 어디에 만드나요?
클로드 코드를 여는 작업 폴더 맨 위에 CLAUDE.md라는 이름으로 만듭니다. 모든 폴더에 적용하고 싶은 습관은 ~/.claude/CLAUDE.md에 둡니다. 위치별 차이는 2단계 표에 정리했습니다.
CLAUDE.md를 만들었는데 클로드가 안 지켜요
먼저 /context로 파일이 읽혔는지 봅니다(3단계). 읽혔는데 안 지킨다면 규칙을 숫자나 파일 이름처럼 확인할 수 있는 문장으로 바꾸고, 다른 CLAUDE.md와 부딪치는 규칙이 없는지 봅니다.
# 으로 메모를 바로 추가하던 기능은 없어졌나요?
공식 문서의 입력 단축 표에는 /, !, @는 있지만 #은 없습니다. 지금 문서는 클로드에게 “이것을 CLAUDE.md에 추가해 줘”라고 말하거나 /memory로 파일을 직접 고치라고 안내합니다.
CLAUDE.md와 AGENTS.md는 뭐가 다른가요?
AGENTS.md는 여러 코딩 도구가 함께 읽는 지침 파일입니다. 공식 문서에 따르면 클로드 코드는 기본 설정에서 CLAUDE.md가 없을 때만 AGENTS.md를 읽습니다. 둘 다 쓰려면 CLAUDE.md 안에 @AGENTS.md를 적어 불러오거나, /config에서 프로젝트 지침을 claude-md-and-agents-md로 바꿉니다.
CLAUDE.md는 얼마나 길게 써야 하나요?
공식 문서는 파일 하나에 200줄 이하를 권합니다. 처음에는 10~20줄로 시작해서, 클로드가 같은 실수를 반복할 때마다 한 줄씩 늘리는 편이 관리하기 쉽습니다.
출처
Claude Code 메모리 문서, Claude Code 대화형 모드 문서 (모두 2026-10-14 확인)