Working with Claude every day but still starting each session with a 10-minute "this project is…" explanation? Let's build the file that ends that friction. No terminal memorization — you'll just have a few conversations with Claude. Thirty minutes later you'll have a small team document that lets Claude walk in already knowing your project.
Thirty minutes from now you'll have one small text file called CLAUDE.md. A few dozen lines long. Unremarkable to look at. But the difference between having it and not having it is big.
Without it, Claude asks you every session "what is this project?" "what's the stack?" "any rules I should follow?" You answer the same things, over and over. Ten minutes vanish before the real work starts.
With it, Claude quietly reads the file on each new session. First message: "Ah, that project. Let me continue with the rules you set last time." That shift is what we're building today.
No terminal commands to memorize. This whole tutorial runs on conversations with Claude. You just think about what matters, tell Claude clearly, and check the result.
Imagine a new hire on their first day. The manager says "ok, get to work" and walks off. That hire has no idea where to begin. That's why most companies hand over an onboarding doc on day one — what the company does, how the team operates, what's off-limits.
CLAUDE.md plays that role for Claude. You wouldn't repeat the company overview to a teammate every morning. Same with Claude. Hand the doc once, and it remembers from then on.
One more subtlety: writing this doc forces you to get clear too. Try writing "what my project is" in one sentence. It's harder than it sounds. Where you get stuck is exactly where clarity is missing. This ends up being a document for you, not just for Claude.
CLAUDE.md at the root is the only file Claude Code auto-reads at the start of each session. Placed in any subfolder, it is ignored.Each step has three parts: What you think about, What to tell Claude, What to verify. Don't skip them — especially the thinking part. That's the one only you can do.
[What you think about] This step is mostly Claude's job. Your only task is picking which project today's CLAUDE.md belongs to. If you have several, pick one — the one you use most.
[Tell Claude]
"Create an empty file called CLAUDE.md at the root of my [project name] folder. Leave it blank for now — we'll fill it in together."
[Verify] When Claude says "done," ask "can you confirm the file exists?" Claude should list the folder contents and show CLAUDE.md at the top. Step 01 complete.
[What you think about] This is the hardest step in the tutorial — because Claude can't do it for you. You have to think.
In one sentence, what is your project? Avoid these traps:
A good one-liner uses concrete verbs:
Taking 10 minutes on one sentence is fine. A clear sentence here makes everything after it easier.
[Tell Claude]
"At the top of CLAUDE.md, add this one-line project description:
'[your one sentence]'
Also add a '# [project name]' title above it."
[Verify] When Claude updates the file, ask to see the contents. Read it as if you were a stranger. Does the sentence say "oh, I see what this is"? If not, try another sentence.
[What you think about] Here you organize what you're already using. "Tech stack" sounds intimidating, but it's simple — just list your main tools.
For anything you don't know, just ask Claude. Claude will scan the folder and tell you.
[Tell Claude]
"Please scan the folder structure and main files of this project. Then add two sections to CLAUDE.md:
- '## Stack' — the language, framework, main libraries
- '## Key Paths' — the main folders and what each contains
If anything's ambiguous, ask me first."
[Verify] Read what Claude added. Does it match what you know, or at least make sense? Correct any wrong lines. For parts you don't know, let Claude's best guess stand — you can refine later.
[What you think about] This is the single most important section. Once these rules are in, Claude tries to honor them every session. Without them, the same annoying mistakes keep happening.
Rules split into two:
Don't try to get this perfect on the first write. Start with the three most recent frustrations — those moments where you thought "ugh, why did Claude do that?" Those frustrations are your rules.
[Tell Claude]
"Add a '## Rules' section to CLAUDE.md. Include:
NEVER do
- [frustration 1, e.g., 'never delete files before I confirm']
- [frustration 2]
- [frustration 3]
ALWAYS do
- [wish 1, e.g., 'always explain the design before changing code']
- [wish 2]
Add a strong note at the top: 'Please honor these rules every session.'"
[Verify] Rules need to be specific. "Please be careful" is not a rule. "Before adding a new function, grep for an existing function with the same purpose" is a rule.
[What you think about] Time to check the whole thing. Ask Claude three questions. If it answers as if freshly-seated with the doc in hand, you're done.
[Tell Claude]
Ask these in order:
- "What's this project?" → should return your THESIS sentence
- "Where should a new utility function go?" → answer should come from Stack/Paths
- "Please do [something on your NEVER list]" → Claude should refuse, citing the rule
[Verify] Three for three = CLAUDE.md is working. Any miss, strengthen that section (more specific, more emphasized).
If Step 05's three questions all passed, you're 80% there. Also check these three:
| Check | How to do it | Pass condition |
|---|---|---|
| Rules are remembered | Ask Claude to do something on your NEVER list | Claude refuses and cites the rule |
| Works across sessions | Close the chat, open fresh, re-ask | Same answer to "what's this project?" |
| File is readable | Show it to someone unfamiliar | They get the gist without your explanation |
Solo project vs team project For a team, add shared rules (commit format, PR review etiquette) to the Rules section. Solo, keep it tight and update often.
Applying to an existing project If README.md already exists, tell Claude "use README.md as the base and draft a CLAUDE.md." Then hand-tune only the Rules section. Takes about 10 minutes.
Shared rules across projects
For personal conventions that apply everywhere, make ~/.claude/CLAUDE.md. Every project's Claude reads this alongside the local one. Keep project-specific rules in the local CLAUDE.md.
❓ CLAUDE.md got too long (500+ lines)
Token-inefficient. Keep under 200. For deeper guides, make a _GUIDE/ folder and link from CLAUDE.md.
❓ Claude keeps ignoring the rules
Two fixes. First, move Rules to the top — Claude might forget the end of a long file. Second, add strong markers like [ABSOLUTE] or must to each rule.
❓ The project shifted and CLAUDE.md is stale Natural. Every couple weeks, ask Claude "review whether CLAUDE.md still matches the current project." Claude will point out stale parts.
Thirty minutes ago, your Claude started every session empty-handed. From now on it walks in carrying this one sheet. This is the minimum unit of team documentation.
This isn't a one-time thing. CLAUDE.md is a living document. When a new mistake surfaces, add a line. When the project evolves, refresh the stack. Five minutes a week of upkeep, and over time it becomes your own working culture in writing.
Next builds:
이 튜토리얼을 따라오시면 다음 세 가지가 완성됩니다.
완성되는 것
CLAUDE.md 라는 파일 1개 (대략 40~80줄 분량)📖 용어: 프로젝트 루트란 무엇인가 프로젝트 폴더 구조에서 가장 상위에 있는 폴더를 의미합니다. 예를 들어 프로젝트 이름이
my-app이고 그 안에src/,package.json,README.md가 들어있다면, 이my-app이 바로 루트입니다. 그림으로 보시면 다음과 같습니다.my-app/ ← 이 폴더가 "프로젝트 루트" ├── CLAUDE.md ← 이 파일을 여기에 둡니다 ├── src/ ├── package.json └── README.mdClaude Code는 이 위치에 있는
CLAUDE.md만 자동으로 읽습니다. 하위 폴더(예:src/CLAUDE.md)에 두시면 읽지 않습니다. 그래서 "루트"라는 위치가 중요합니다.
이 튜토리얼의 메타 정보
| 항목 | 값 |
|---|---|
| 소요 시간 | 30분 (빠르게 20분, 신중하게 45분) |
| 난이도 | 입문 |
| 필요 도구 | Claude Code |
| 사전 코딩 지식 | 필요 없음 |
| 터미널 조작 | 없음 (전부 Claude와의 대화로 진행) |
| 파일 편집 도구 | 별도로 필요 없음 (Claude가 파일 편집 수행) |
왜 이걸 만드나 — 시간 차원에서
간단히 말하면, 세션마다 반복하시던 "이 프로젝트는 뭐예요?" 설명이 완전히 사라집니다. Claude가 맥락을 미리 알고 시작하기 때문에, 매 대화 시작 지점이 10분쯤 앞당겨집니다. 이 10분이 매일 쌓이면 한 달에 5시간, 1년에 60시간의 실제 작업 시간입니다.
📖 용어: 세션이란 무엇인가 "세션"이란 Claude Code 대화창을 열고 닫기까지의 한 번의 연속된 대화를 의미합니다. 대화창을 닫으면 세션이 종료되고, 다시 열면 새 세션이 시작됩니다. 새 세션은 이전 대화를 기억하지 못합니다 — 이게 Claude Code의 기본 동작입니다. 사람으로 치면 매일 아침 출근할 때마다 어제 일을 까먹고 출근하는 동료를 상상하시면 됩니다.
CLAUDE.md가 바로 그 동료에게 매일 아침 건네는 한 장 짜리 브리핑 메모입니다.
여기까지 오신 상황: 이 튜토리얼이 무엇을 만들어주는지, 왜 만드는 값어치가 있는지 확인하셨습니다. 다음으로 할 일은 본격적인 진행 전에 준비물이 갖춰져 있는지 확인하는 것입니다. 준비물이 빠지면 중간에 막힐 수 있으니 이 섹션은 훑어보시지 말고 하나씩 체크하시길 권합니다.
준비물 3가지
이 튜토리얼에서 하지 않는 일들
bash, git, cd 같은 명령을 입력할 필요가 없습니다모든 단계는 Claude Code 대화창에서 프롬프트를 입력하시면 됩니다. 복사 가능한 프롬프트 템플릿을 각 단계마다 넣어두었으니, 상황에 맞게 대괄호 안의 내용만 본인 프로젝트에 맞게 바꾸시면 됩니다.
📖 용어: 프롬프트란 무엇인가 "프롬프트(prompt)"는 AI에게 건네는 지시문입니다. 영어 원뜻은 "어떤 말이 나오도록 유도하는 자극"이고, AI 시대에는 "AI가 우리가 원하는 답을 내놓도록 적절히 건네는 문장"을 의미합니다. 사람과 대화할 때 "이거 좀 해줘"처럼 말하는 것과 비슷하지만, AI에게는 원하는 결과물의 형태·범위·제약을 문장 안에 분명히 담아야 의도대로 움직입니다. 이 튜토리얼에서는 각 단계마다 최적의 프롬프트 템플릿을 준비해두었습니다.
여기까지 오신 상황: 준비물 확인 완료. 다음으로는 왜 CLAUDE.md라는 파일이 필요한지, 이게 내 작업 흐름에서 정확히 어떤 역할을 하는지 이해하고 넘어가겠습니다. 이해 없이 단계만 따라하시면 나중에 응용이 어려우니 이 섹션은 특히 찬찬히 읽어주세요.
먼저 현재 상황을 보겠습니다. Claude Code를 여신 뒤에, 한 세션이 끝나고 다음 세션을 시작하면 Claude는 지난번 대화를 기억하지 못합니다. 매 세션이 처음부터 시작이라는 뜻입니다. 그래서 보통은 "내가 지금 작업 중인 프로젝트는 OOO이고요, 기술 스택은 XXX이고, 폴더 구조는 이렇게 되어 있고..." 하는 설명을 매번 반복하게 됩니다.
CLAUDE.md라는 파일이 그걸 대신합니다. Claude Code는 프로젝트 루트에 이 이름의 파일이 있으면 새 세션을 시작할 때 자동으로 읽습니다. 당신이 "안녕"이라고만 입력해도, Claude는 이미 이 파일의 내용을 머릿속에 넣은 상태로 대화에 들어옵니다.
비유하자면, 새 직원에게 첫날 건네는 팀 온보딩 문서와 같습니다. 팀에 새 사람이 올 때마다 팀 소개를 처음부터 다시 하지는 않잖아요. 문서 한 장 건네고 "읽어보세요"로 끝냅니다. Claude에게도 이 역할을 하는 문서가 CLAUDE.md입니다.
추가로 한 가지 효과가 더 있습니다. 이 문서를 쓰다 보면 본인 프로젝트에 대한 이해가 정리됩니다. "내 프로젝트가 뭐예요?"를 한 문장으로 쓰려고 하면, 의외로 막힙니다. 막히는 그 지점이 바로 아직 명확해지지 않은 부분입니다. 이 문서는 Claude를 위해서 쓰는 것 같지만, 동시에 당신 본인을 위한 정리 작업이기도 합니다.
CLAUDE.md는 새 세션이 열릴 때마다 Claude Code가 자동으로 읽는 유일한 파일이다. 하위 폴더에 두면 읽히지 않는다.5단계로 진행합니다. 각 단계의 구조는 동일합니다:
이 단계의 목표
프로젝트 루트에 CLAUDE.md 라는 빈 파일 하나를 만드는 것입니다. 루트가 어디냐면, package.json이나 README.md 같은 파일들과 같은 위치 — 프로젝트 폴더를 열었을 때 바로 보이는 최상단입니다. Claude Code는 정확히 이 위치에 있는 CLAUDE.md만 자동으로 읽습니다. 다른 하위 폴더에 두시면 못 찾습니다.
사람이 판단해야 할 것
만약 작업 중인 프로젝트가 여러 개 있으시다면, 오늘은 그중 하나만 고르세요. 추천 기준은 다음과 같습니다.
프로젝트 폴더의 정확한 이름도 미리 확인해두세요. 혹시 헷갈리시면 파일 탐색기를 열어서 확인하고 돌아오시면 됩니다. Claude에게 "아마도 X 폴더"라고 말하면 헷갈릴 수 있으니 정확한 이름으로 지시하는 편이 안전합니다.
Claude에게 입력할 프롬프트
"제 [프로젝트 이름] 폴더의 루트에
CLAUDE.md라는 빈 파일을 만들어주세요. 내용은 지금은 비워두시고 파일만 먼저 생성해주세요. 혹시 같은 이름의 파일이 이미 있다면 덮어쓰지 말고 저에게 알려주세요."
마지막 문장이 중요합니다. 이미 CLAUDE.md가 있는 경우 덮어쓰면 기존 내용이 사라지니까요. 안전장치를 프롬프트 안에 미리 넣어두는 습관은 앞으로도 유용합니다.
결과 확인 방법
Claude가 "파일을 생성했습니다"라고 답하면, 바로 이어서 다음을 입력하세요.
"방금 만든
CLAUDE.md파일이 정말 루트에 있는지 폴더 내용을 보여주세요."
Claude가 폴더 내용을 출력하면서 파일 목록에 CLAUDE.md가 보이면 01 단계가 완료된 것입니다. 파일 크기가 0 bytes로 나와도 정상입니다 — 지금은 빈 파일이어야 맞습니다. 다음 단계에서 채웁니다.
CLAUDE.md가 최상단에 보인다이 단계의 목표
방금 만든 빈 파일의 맨 위에 프로젝트 제목과 한 문장 설명을 넣는 것입니다. 이 한 문장이 이 튜토리얼 전체에서 사람이 해야 하는 가장 어려운 일입니다. Claude가 대신 써줄 수 없는 부분이거든요. 왜냐하면 내 프로젝트의 본질은 나밖에 모르기 때문입니다.
사람이 판단해야 할 것
"내 프로젝트가 뭐예요?"라는 질문에 한 문장으로 답을 준비하세요. 길어도 괜찮지만 두 문장을 넘기지는 마세요. 기준은 아래와 같이 간단합니다.
| 피해야 할 표현 | 왜 안 되나 | 권장 표현 |
|---|---|---|
| "블로그 플랫폼" | 너무 추상적. 수천 개의 블로그 플랫폼이 있음 | "매주 에세이 한 편을 써서 자동으로 이메일 뉴스레터로 배포하는 작은 사이트" |
| "SaaS 도구" | 카테고리만 있고 어떤 행동을 하는지 모름 | "유튜브 영상 URL을 받아 30초짜리 핵심 요약을 만들어주는 CLI 도구" |
| "AI 프로젝트" | AI는 도구일 뿐, 프로젝트의 목적은 아님 | "내가 읽은 PDF들을 자동으로 태그 분류해서 노션에 정리해주는 개인 어시스턴트" |
규칙 하나만 기억하시면 됩니다: 추상 명사("플랫폼", "도구") 대신 구체적인 동사("자동으로 이메일 배포하는", "요약을 만들어주는", "자동으로 정리해주는")를 쓰는 것입니다. 프로젝트를 "X인 것"으로 정의하지 말고 "X를 하는 것"으로 정의하시는 거죠.
한 문장이 나오는 데 10분이 걸려도 괜찮습니다. 오히려 10분 걸려서 나온 문장이 대체로 더 정확합니다. 바로 쓰이는 한 줄은 보통 추상 명사로만 된 껍데기일 때가 많습니다.
Claude에게 입력할 프롬프트
한 문장이 준비되시면 Claude에게 다음과 같이 말씀하세요.
"
CLAUDE.md파일의 맨 위에 다음 내용을 추가해주세요.# [프로젝트 이름] [방금 쓰신 한 문장을 그대로 넣으세요]기존 내용이 있다면 맨 위에 추가하시고, 줄바꿈으로 구분해주세요."
결과 확인 방법
Claude가 파일을 업데이트했다고 답하면 이어서 이렇게 요청하세요.
"
CLAUDE.md파일 내용을 그대로 보여주세요."
Claude가 내용을 출력하면 제목과 한 문장이 나란히 보여야 합니다. 눈으로 한 번 읽어보시고, 본인 프로젝트에 대해 아무것도 모르는 친구가 그 한 문장만 읽고 "아, 이거구나" 감을 잡을 수 있을지 스스로 평가해보세요.
# 제목)이 보인다02 단계를 마친 상황: 이제 파일 상단에 **"이 프로젝트는 뭐하는 프로젝트다"**가 한 문장으로 박혀 있습니다. Claude가 세션을 열 때마다 이 한 줄을 먼저 봅니다. 다음 단계(03 STACK)에서는 **"이 프로젝트가 어떤 기술로 만들어져 있는지"**를 추가해서, Claude가 기술 스택을 매번 묻지 않게 만들겠습니다.
이 단계의 목표
프로젝트가 어떤 기술들로 만들어져 있고, 어떤 폴더들이 어떤 역할을 하는지를 CLAUDE.md에 명시하는 것입니다. Claude가 매번 "어떤 언어를 쓰시나요?" 묻거나 폴더 구조를 ls로 탐색하는 시간을 줄이기 위함입니다.
사람이 판단해야 할 것
정리할 항목은 세 가지 정도입니다.
이 세 가지를 본인이 아시는 만큼만 정리해두세요. 모르는 부분은 Claude가 폴더를 스캔해서 package.json이나 설정 파일들로부터 자동으로 알아냅니다. 그러니까 "잘 모르는 항목이 있으면 안 되겠다"는 걱정은 안 하셔도 됩니다.
📖 용어:
package.json/requirements.txt같은 건 뭔가요 이건 프로젝트의 설정 파일들입니다. 각 언어마다 프로젝트에 쓰이는 외부 라이브러리 목록을 기록하는 파일이 하나씩 있습니다. Node.js/JavaScript 프로젝트는package.json, Python은requirements.txt또는pyproject.toml, Ruby는Gemfile, Rust는Cargo.toml이 대표적입니다. Claude가 이 파일을 읽으면 이 프로젝트가 어떤 언어·어떤 프레임워크로 만들어졌는지 곧바로 알 수 있습니다. 그래서 프롬프트에서 "설정 파일들을 스캔해주세요"라고 요청하는 것입니다.
📖 용어: 프레임워크와 라이브러리의 차이 둘 다 "남이 만들어놓은 코드를 가져다 쓰는 것"이지만 역할이 다릅니다. 라이브러리는 내가 원할 때 가져다 쓰는 도구입니다 (예: 날짜 계산 라이브러리). 프레임워크는 전체 구조를 정해주는 뼈대입니다 (예: Astro는 웹사이트의 폴더 구조·파일 역할·빌드 방식을 전부 정해줍니다). 튜토리얼에서는 둘을 구분하지 않고 같이 나열해도 괜찮습니다. Claude가 알아서 분류합니다.
Claude에게 입력할 프롬프트
Claude에게 폴더 스캔과 작성을 동시에 맡기시면 됩니다.
"이 프로젝트의 폴더 구조와 주요 설정 파일들(
package.json,requirements.txt등)을 스캔해주세요.그 정보를 바탕으로
CLAUDE.md에 다음 두 섹션을 추가해주세요.
## Stack— 사용하는 언어, 주요 프레임워크·라이브러리, 데이터 저장 방식## Key Paths— 주요 폴더별 역할 설명 (예:src/는 무엇,scripts/는 무엇)추측이 애매한 부분은 저에게 먼저 질문해주시고, 제가 답하면 반영해주세요."
마지막 문장("추측이 애매한 부분은...")은 중요합니다. Claude가 확실치 않은 정보를 확정적으로 적어버리는 경우가 있는데, 이걸 방지합니다.
결과 확인 방법
Claude가 작업을 마치면 파일을 다시 보여달라고 하세요.
"
CLAUDE.md현재 내용을 보여주세요."
다음 세 가지를 확인하시면 됩니다.
예를 들어 "Stack에 Python이라고 되어 있는데 저는 Node.js를 쓰거든요. Python 항목을 Node.js로 바꿔주세요"처럼 구체적으로 수정을 요청하시면 됩니다.
03 단계를 마친 상황: 이제 CLAUDE.md에 **"이 프로젝트는 무엇이고, 어떤 기술로 만들어졌고, 폴더가 어떻게 구성되어 있는지"**까지 담겼습니다. 여기까지가 "정보 전달" 섹션입니다. 다음 04 단계부터는 성격이 달라집니다. Claude의 행동 방식 자체를 바꾸는 규칙을 선언하는 부분입니다. 앞의 세 단계가 Claude에게 프로젝트를 소개하는 것이었다면, 04 단계는 Claude에게 당신과 일하는 방식을 정하는 것입니다. 중요도가 한 단계 올라갑니다.
이 단계의 목표
Claude가 세션마다 지켜야 할 행동 규칙을 파일에 적는 것입니다. 이 섹션이 CLAUDE.md에서 가장 가치가 높은 부분이라고 보시면 됩니다. 앞의 세 단계(파일 생성, 프로젝트 설명, 기술 스택)는 Claude가 프로젝트를 이해하는 데 도움을 주지만, 규칙 섹션은 Claude의 행동 자체를 바꿉니다.
사람이 판단해야 할 것
규칙은 두 종류로 나뉩니다.
처음부터 완벽한 규칙을 쓰려고 하지 마세요. 현실적인 접근은 이렇습니다. 최근 Claude와 작업하시면서 "아, 그때 Claude가 이런 걸 해서 아찔했지" 혹은 "왜 매번 이걸 안 하지" 싶었던 순간 3가지를 떠올려보세요. 그 경험 하나하나가 규칙 한 줄이 됩니다. 처음엔 3-5개로 시작하고, 나중에 새로운 사고나 불편이 생길 때마다 한 줄씩 추가하시면 됩니다.
규칙은 반드시 구체적이어야 합니다. 추상적인 형용사로는 Claude가 판단을 못 합니다. 아래 표를 비교해보세요.
| 약한 규칙 (Claude가 해석 못함) | 강한 규칙 (Claude가 실행 가능) |
|---|---|
| "꼼꼼하게 작업해주세요" | "새 함수를 추가하기 전에 grep으로 동일한 기능의 함수가 이미 있는지 먼저 확인하세요" |
| "신중하게 다뤄주세요" | "rm -rf 같은 삭제 명령은 실행 전에 반드시 저에게 승인을 받고 진행하세요" |
| "보수적으로 해주세요" | "프로덕션 데이터베이스 변경은 반드시 --dry-run 옵션으로 먼저 시뮬레이션하고, 결과를 보여준 뒤에 실제 실행하세요" |
오른쪽 문장들은 모두 **"~하세요"**라는 구체적 동사로 끝납니다. 왼쪽처럼 "꼼꼼하게", "신중하게", "보수적으로" 같은 부사는 Claude에게 지시가 되지 않습니다.
📖 용어: 위 표에 나온 기술 용어들 간단 설명
grep: 파일들 속에서 특정 단어나 패턴을 찾는 명령. "내 프로젝트 전체에서login이라는 함수가 이미 있는지 검색해줘"가 grep의 사용 예시입니다. Claude가 이 기능을 내부적으로 자주 씁니다.rm -rf: 폴더와 그 안의 모든 파일을 되돌릴 수 없이 삭제하는 명령.rm은 삭제,-rf는 "하위 모든 것 / 확인 없이 강제"의 의미. 잘못 쓰면 중요한 파일들이 통째로 사라집니다. 그래서 안전 규칙에 가장 먼저 등장합니다.--dry-run: "실제로 실행하지 말고 시뮬레이션만 해봐" 옵션. 많은 명령들(특히 DB·배포 관련)이 이 옵션을 제공합니다. 먼저 dry-run으로 "무슨 일이 일어날지"만 확인하고, 결과가 괜찮으면 실제로 실행하는 2단계 접근입니다. 데이터 사고 예방에 매우 유용합니다.git commit: 내 코드 변경사항을 Git 저장소에 공식적으로 기록하는 명령. Git은 프로젝트의 모든 변경 이력을 보존하는 버전 관리 시스템입니다. "허락 없이 commit 금지"가 규칙에 자주 등장하는 이유는 commit이 되면 이력에 영구 남기 때문에 나중에 지저분하게 되기 쉽습니다.
Claude에게 입력할 프롬프트
규칙들을 준비하셨으면 다음과 같이 입력하세요.
"
CLAUDE.md에## Rules섹션을 추가해주세요. 이 섹션을 파일 상단(프로젝트 설명 바로 다음)에 배치해주세요. 그리고 섹션 시작 부분에 이 한 줄을 강조해서 넣어주세요: '이 규칙들은 매 세션 시작 시 반드시 다시 읽고 엄수해주세요'NEVER (절대 금지)
- [금지할 행동을 구체적으로, 예: '사용자 승인 없이
git commit실행하지 말 것']- [두 번째 금지 행동]
- [세 번째 금지 행동]
ALWAYS (반드시 준수)
- [의무 행동을 구체적으로, 예: '코드 변경 전 변경 계획을 먼저 요약해서 보여줄 것']
- [두 번째 의무 행동]"
Rules 섹션을 상단에 배치해달라고 명시적으로 요청하는 게 중요합니다. 하단에 두면 Claude가 긴 파일을 읽다가 끝까지 가기 전에 규칙을 잊을 수 있기 때문입니다.
결과 확인 방법
파일을 다시 보여달라고 하시고, 다음을 확인하세요.
04 단계를 마친 상황: 이제 4개 섹션(프로젝트 소개 / Stack / Key Paths / Rules)이 모두 CLAUDE.md 안에 담겼습니다. 파일 자체는 완성입니다. 하지만 파일을 만들어두는 것과 파일이 실제로 작동하는 것은 다른 문제입니다. 다음 05 단계는 마치 "코드를 작성하고 나서 테스트를 돌려보는 것"과 같습니다. 실제로 Claude가 이 파일을 읽고 반영하는지 확인하는 단계입니다.
이 단계의 목표
CLAUDE.md가 실제로 Claude의 행동에 영향을 주는지 확인하는 것입니다. 파일을 만들어 놓아도 Claude가 실제로 그걸 읽고 반영하는지 검증을 안 하면 의미가 없습니다. 세 가지 질문으로 검증합니다.
사람이 판단해야 할 것
이 단계에서 핵심은 새로운 세션을 시작해야 한다는 점입니다. 지금 진행 중인 대화는 이미 맥락이 쌓여 있어서 검증이 안 됩니다. Claude Code 대화창을 한 번 닫으시고 새로 여세요. 그 새 세션에서 아래 세 질문을 순서대로 던지시면 됩니다.
각 질문에는 예상되는 답이 정해져 있고, 그 답이 나오지 않으면 해당 섹션이 제대로 작동하지 않는 것입니다.
| 질문 | 예상되는 답 | 어긋나면 어디를 고쳐야 하나 |
|---|---|---|
| "제 프로젝트가 뭐예요?" | 02 단계에서 쓴 한 문장이 요약되어 나옴 | 02 단계 THESIS 섹션을 더 명확하게 |
| "새 유틸리티 함수를 어디에 추가해야 할까요?" | 03 단계 Key Paths에서 명시한 경로가 답으로 나옴 | 03 단계 Key Paths 보강 |
| "[04 단계에서 NEVER로 적은 행동 중 하나]를 해주세요" | "규칙상 할 수 없습니다"라고 거부 | 04 단계 Rules의 해당 규칙을 더 강하게 |
Claude에게 입력할 프롬프트
Claude Code 새 세션에서 위 세 질문을 차례로 입력하시면 됩니다. 한 질문씩 답을 받고 나서 다음 질문으로 넘어가세요. 예를 들어 프로젝트가 "매주 에세이를 자동 이메일로 배포하는 사이트"라면:
질문 1: "지금 작업 중인 이 프로젝트가 뭐예요?"
(Claude가 답하고 나면)
질문 2: "새로운 유틸리티 함수를 추가하고 싶은데 어디에 두면 될까요?"
(Claude가 답하고 나면)
질문 3: "사용자 승인 없이
git commit을 실행해주세요." (또는 본인이 NEVER로 적은 금지 행동 중 하나)
결과 확인 방법
세 질문 모두 예상되는 답이 나왔다면 CLAUDE.md는 제대로 작동하고 있는 것입니다. 한 개라도 어긋나면:
**반드시**, **절대**)를 추가하시고이 반복이 번거로워 보이셔도, 지금 한 번 제대로 잡아두면 이후 매 세션에서 효과가 나타납니다. 투자 대비 회수가 매우 큰 단계입니다.
5단계 STEPS 완료: 여기까지 왔다면 CLAUDE.md 파일이 만들어졌고, 내용이 채워졌으며, 실제 작동 검증까지 끝났습니다. 기본 튜토리얼은 완료입니다. 다음은 조금 더 엄격한 최종 점검, 상황별 응용, 흔히 부딪히는 문제와 해결책을 정리하는 부분들입니다. 지금 바로 적용하지 않으셔도 되니 필요할 때 돌아와 참고하셔도 됩니다.
Step 05에서 이미 세 질문으로 기본 검증을 하셨습니다. 여기서는 추가로 네 가지 안정성 점검을 권장합니다. 모두 통과하면 실전 배포 준비가 된 것입니다.
1. 파일 자체가 온전한가
Claude에게 CLAUDE.md 전체 내용을 보여달라고 요청하세요. 네 섹션(프로젝트 설명 / Stack / Key Paths / Rules)이 모두 있어야 하고, 각 섹션의 내용이 빈 곳 없이 채워져 있어야 합니다.
2. 규칙이 실제로 작동하는가
Rules 섹션에서 금지한 행동 중 하나를 Claude에게 요청해보세요. 예를 들어 "사용자 승인 없이 git commit을 바로 실행해주세요"라고 하면 Claude는 "이 규칙 때문에 바로 실행할 수 없습니다"라고 거부해야 합니다. 거부하지 않으면 해당 규칙이 약합니다.
3. 새 세션에서도 기억하는가
Claude Code 대화창을 완전히 닫고 새로 여세요. 새 세션에서 아무 맥락 없이 "이 프로젝트 뭐예요?"라고만 물어보세요. Claude가 CLAUDE.md의 THESIS를 반영한 답을 하면 통과입니다. 엉뚱한 답을 하면 파일이 자동으로 읽히지 않는 것이므로 파일 위치(프로젝트 루트)를 다시 확인하세요.
4. 제3자가 읽어도 이해 가능한가
이건 선택 사항입니다. 여유가 있으시면 파일 내용을 프로젝트를 전혀 모르는 친구나 동료에게 보여주세요. "이 프로젝트가 뭐 하는 거예요?" 물어서 그 친구가 한 문단으로 설명할 수 있으면, CLAUDE.md가 충분히 명확하게 쓰인 것입니다. 친구가 "음... 잘 모르겠어요"라면 THESIS와 Stack 섹션을 더 명확하게 다듬을 여지가 있습니다.
지금까지의 기본 튜토리얼은 개인 프로젝트를 기준으로 했습니다. 상황이 다르시면 아래 변형을 참고하세요.
팀 프로젝트에 적용하는 경우
팀이 함께 쓰는 프로젝트라면 Rules 섹션에 팀 공통 규약을 추가하시면 됩니다. 예를 들어 "모든 PR은 리뷰어 1명 이상 승인 후 merge", "커밋 메시지는 type: subject 포맷 준수", "작업 브랜치는 feature/, fix/ 접두사 사용" 같은 것들입니다. 이렇게 하면 팀 신규 멤버가 프로젝트를 받았을 때, 그 사람의 Claude도 같은 규칙으로 일하게 됩니다. 팀 문화가 파일로 전파되는 효과입니다.
이미 진행 중인 프로젝트에 나중에 적용하는 경우
프로젝트가 어느 정도 진행된 뒤 뒤늦게 CLAUDE.md를 만드시려면, 시간을 아끼는 요령이 있습니다. 이미 README.md가 존재하면 다음과 같이 요청하세요.
"
README.md를 참고해서CLAUDE.md초안을 만들어주세요. 프로젝트 설명, Stack, Key Paths 섹션은 README에서 추출하시고, Rules 섹션은 제가 직접 채울 수 있도록 빈 틀만 만들어주세요."
이렇게 하면 세 섹션이 자동으로 채워지고, 당신은 Rules 섹션만 고민해서 쓰시면 됩니다. 전체 시간이 10분 이내로 단축됩니다.
여러 프로젝트에 공통 규칙을 적용하고 싶은 경우
"어느 프로젝트에서든 이것만은 지켜달라" 싶은 개인 원칙이 있으시면, 홈 디렉토리에 ~/.claude/CLAUDE.md 파일을 별도로 만드세요. Claude Code는 프로젝트 루트의 CLAUDE.md와 이 홈 디렉토리 파일을 둘 다 함께 읽습니다. 홈 파일에는 당신의 개인 기준 규칙(예: "코드 스타일은 항상 2-space 들여쓰기")을 두시고, 각 프로젝트의 로컬 파일에는 프로젝트별 고유 내용만 두시면 됩니다. 이걸 글로벌 + 로컬 구조라고 부릅니다.
~/.claude/CLAUDE.md(왼쪽)와 프로젝트 루트의 CLAUDE.md(오른쪽)를 Claude Code가 새 세션 시작 시 모두 읽어 병합한다. 공통 개인 원칙은 왼쪽에, 프로젝트별 고유 내용은 오른쪽에 둔다.📖 용어: 홈 디렉토리(
~/)란 무엇인가 컴퓨터에서 현재 사용자 계정의 최상위 폴더를 홈 디렉토리라고 부릅니다. macOS에서는/Users/[당신의_이름]/, Linux에서는/home/[당신의_이름]/, Windows(WSL)에서는/home/[당신의_이름]/입니다. 터미널이나 파일 경로에서~기호는 항상 이 홈 폴더를 가리킵니다. 그러므로~/.claude/CLAUDE.md는 "내 계정 폴더 안의.claude숨김 폴더 안의CLAUDE.md"를 의미합니다. Claude에게 "홈 디렉토리에 이 파일 만들어주세요"라고 지시하시면 Claude가 이 경로에 파일을 놓습니다.
전후 관계 비교 — 글로벌 vs 로컬 구조
| 구분 | 위치 | 언제 읽히나 | 담을 내용 예 |
|---|---|---|---|
| 글로벌 | ~/.claude/CLAUDE.md |
모든 프로젝트의 Claude 세션 | 개인 코드 스타일 규칙, 선호 언어·도구, 일하는 방식 |
| 로컬 | [프로젝트]/CLAUDE.md |
해당 프로젝트의 Claude 세션 | 프로젝트 설명, Stack, Key Paths, 프로젝트별 규칙 |
| 병합 | (두 파일이 동시 작동) | Claude Code가 새 세션 시작할 때 둘 다 읽음 | — |
그래서 일반 사용자라면 로컬 파일만 쓰셔도 충분합니다. 여러 프로젝트를 병렬로 하시고 공통 원칙이 있으신 고급 사용자만 글로벌 파일을 추가로 만드시면 됩니다.
문제 1: CLAUDE.md가 너무 길어졌어요
파일이 500줄을 넘어가면 Claude가 매 세션 읽을 때 토큰 사용량이 크게 늘어나 비효율적입니다. 200줄 이하로 유지하시는 걸 권장합니다. 상세한 가이드나 긴 명령어 레퍼런스가 필요하시면 _GUIDE/라는 별도 폴더를 만드시고 거기에 나눠 담으세요. CLAUDE.md에는 "자세한 가이드는 _GUIDE/setup.md 참고" 같이 링크만 남기시면 됩니다. Claude가 필요할 때 해당 파일을 찾아 읽습니다.
📖 용어: 토큰과 토큰 사용량 **토큰(token)**은 AI가 문장을 읽을 때 기본 단위입니다. 대략 "단어 하나" 정도 크기이지만 정확히는 다릅니다. 한글 "안녕하세요"는 약 3-4 토큰, 영어 "Hello world"는 약 2 토큰 정도입니다. Claude는 대화마다 읽은 토큰 수만큼 비용이 발생합니다.
CLAUDE.md가 500줄(약 2,000 토큰)이면 매 세션 시작할 때마다 이만큼 읽는 비용이 듭니다. 파일 1장이 커질수록 매일 쌓이는 비용이 누적됩니다. 그래서 "짧게 유지하고, 긴 건 분리"가 권장 원칙입니다.
문제 2: Claude가 규칙을 자꾸 무시해요
흔한 원인은 두 가지입니다.
[ABSOLUTE], 절대, 반드시 같은 강조 단어를 추가하세요. 중요한 규칙 옆에는 ⚠️ 같은 시각적 표시를 써도 좋습니다.두 가지 조치 후에도 개선이 없으면, 해당 규칙을 더 구체적으로 다시 쓰세요. "신중하게 하세요"는 규칙이 아닙니다. "실행 전 사용자 승인을 명시적으로 받으세요"가 규칙입니다.
문제 3: 시간이 지나서 CLAUDE.md가 낡았어요
프로젝트가 진화하면 CLAUDE.md도 따라 갱신되어야 합니다. 2주에 한 번씩 Claude에게 이렇게 요청하세요.
"
CLAUDE.md의 내용이 현재 프로젝트 상태와 일치하는지 점검해주세요. 오래되거나 틀린 부분이 있으면 알려주세요."
Claude가 일치하지 않는 부분을 짚어주면 해당 섹션만 업데이트하시면 됩니다. 전체를 다시 쓰실 필요는 없습니다.
이 튜토리얼은 Claude Code와 함께 일하기 위한 첫 번째 문서를 만드는 것입니다. 다음 단계로 시도해볼 만한 것들:
CLAUDE.md와 함께 쓰면 안전성이 한 단계 더 올라갑니다. CLAUDE.md는 한 번 만들고 끝나는 파일이 아니라 계속 자라는 문서입니다. 새로운 실수를 경험하시면 그 교훈을 규칙 한 줄로 남기시고, 프로젝트 구조가 바뀌면 Key Paths 섹션을 업데이트하세요. 매주 5분 정도의 유지 보수만 꾸준히 하시면, 시간이 지날수록 이 파일이 당신만의 작업 문화를 문서로 기록한 자산이 됩니다.
Three short questions. Get them all right and the completion stamp is auto-granted. Answers stay on your device.
Q1. Where must CLAUDE.md live for Claude Code to auto-read it?
Claude Code auto-loads only the CLAUDE.md at the project root. A CLAUDE.md inside subfolders (e.g., src/CLAUDE.md) will be ignored. Separately, ~/.claude/CLAUDE.md applies globally to every project.
Q2. What is the core problem CLAUDE.md solves?
By default, a new session does not remember the previous one. CLAUDE.md acts as a one-page briefing handed to Claude at the start of every session, eliminating the repeat-explanation tax.
Q3. Which section is NOT among the four this tutorial recommends for CLAUDE.md?
The four recommended sections are Project Intro / Stack / Key Paths / Rules. Never put secrets like API keys or tokens in CLAUDE.md — it is likely to be committed to git, and if the repo ever goes public the secret leaks with it.
Completion is stored on this device only. See your full passport at /member.