# 2026년 CLAUDE.md 설정 방법: 템플릿과 6가지 규칙
> 바로 사용할 수 있는 CLAUDE.md 템플릿, 파일을 계속 관리하기 위한 6가지 규칙, 실제 운영 중인 비즈니스에서 사용되는 파일 분석을 소개합니다. Anthropic의 공식 인용문이 포함되어 있습니다.
Source: https://ailoot.ai/blog/ko/claude-md-template/
Canonical: https://ailoot.ai/blog/ko/claude-md-template/
Language: ko
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-126
Revision: sha256-e58ebf7aa358f476dd5cb5ffb76cd8a4ba309286400c23621d6005157b980043
핵심 요점
CLAUDE.md는 프로젝트 루트에 두는 텍스트 파일로, Claude Code가 매 세션 시작 시 읽습니다. 이 파일이 없으면 에이전트는 매번 처음부터 시작합니다. “안녕, 이 프로젝트를 하고 있어. 이게 내 독자층이고, 이게 내 스타일이야”라고 설명하는 데 5-10분을 쓰게 됩니다. 간결한 시작 파일은 보통 100-200줄을 목표로 하지만 이는 검토 지침이지 기술적 상한이 아닙니다. 템플릿은 6개 섹션(설명, 도구, 구조, 파일 경로 안내, 규칙, 언어)으로 구성되고 Claude가 실수할 때마다 업데이트됩니다. 이 글에는 바로 쓸 수 있는 템플릿, 6가지 규칙, 실제 운영 중인 비즈니스의 파일 분석, 12개 항목 점검표가 담겨 있습니다.
바이브 코딩 자료: 도구, 사례 연구, 실수. [Ailoot 가이드](https://ailoot.ai/docs/).
[Ailoot 가이드](https://ailoot.ai/docs/)
## CLAUDE.md가 왜 필요하고, 없으면 Claude가 프로젝트를 왜 잊을까요?
핵심 요점
Claude Code에서는 새 채팅을 시작할 때마다 컨텍스트가 비어 있습니다. CLAUDE.md는 Claude가 새 세션마다 자동으로 불러오는 유일한 파일입니다. 없으면 에이전트는 첫 출근 날의 인턴처럼 일합니다. 당신의 비즈니스, 스타일, 규칙에 대해 아무것도 모릅니다. 파일이 있으면 2년 차 직원처럼 일합니다.
화요일에 Claude Code를 열고 이렇게 설명합니다. “이 프로젝트를 하고 있고, 도구는 이거야. 이건 하지 마.” 잘 작동합니다.
목요일에는 그 채팅이 이미 끝났으니 모든 걸 반복합니다. 토요일에도, 월요일에도 또 한 번 반복합니다.
이게 CLAUDE.md 없이 에이전트와 일하는 모습입니다. 새 창을 열 때마다 백지 상태의 인턴에게 같은 말을 계속 되풀이해야 합니다. 예전에는 매 세션마다 이런 사전 설명을 입력하는 데 5-10분을 썼습니다. 모든 맥락을 직접 전달해야 해서 프롬프트가 길어졌습니다. 그런데도 결과는 여전히 평범했습니다. 에이전트는 내 독자층, 경제성, 원칙을 몰랐습니다.
참고
이것은 모델의 기억력 문제가 아닙니다. 아키텍처의 문제입니다. Claude Code는 일부러 각 세션을 깨끗한 컨텍스트로 시작합니다. 그렇지 않으면 같은 컴퓨터에 있는 서로 다른 프로젝트의 내용이 뒤섞일 수 있습니다. CLAUDE.md는 에이전트에게 무엇을 불러오라고 알려주는 장치입니다.
늘 업데이트되는 CLAUDE.md가 있으면 사전 설명은 사라집니다. 매 채팅마다 반복하던 모든 규칙이 하나의 파일에 들어 있고, 매 세션이 시작될 때 자동으로 표시됩니다. 프롬프트는 “X를 해”처럼 짧아집니다. “Y 프로젝트를 하고 있고, 도구는 Z야. A나 B는 하지 말고, 참, C도 기억해”라고 설명할 필요가 없습니다.
그러면 같은 실수도 반복되지 않습니다.
에이전트가 실수할 때마다 CLAUDE.md에 한 줄을 추가할 이유가 생깁니다. 한 달이 지나면 살아 있는 “프로젝트 헌장”이 만들어지고 Claude는 익숙한 함정에 더 이상 빠지지 않습니다.
세 번째 효과도 있습니다. 에이전트가 아무런 맥락 없이 글을 쓰지 않게 됩니다. `CLAUDE.md`를 통해 Claude를 맥락이 담긴 폴더로 안내합니다. 독자층, 가격, 브랜딩에 관한 정보를 어디서 찾아야 하는지 알려주는 겁니다. 이런 안내가 없으면 에이전트는 내 사업의 경제성을 모른 채 “고품질 솔루션”을 작성하므로 추상적이고 판에 박히며 “다른 곳과 똑같은” 결과가 나옵니다.
## CLAUDE.md란 무엇이며, Claude는 어떤 순서로 읽을까요?
핵심 요점
CLAUDE.md는 Markdown 형식의 텍스트 파일입니다. Claude Code는 시스템 수준, 사용자 수준, 프로젝트 루트, 로컬 메모 등 네 곳을 한 번에 찾습니다. 네 파일 모두 매 세션이 시작될 때 컨텍스트에 로드됩니다. 파일명은 대소문자를 구분하므로 항상 대문자를 쓴 `CLAUDE.md`를 사용하세요.
Anthropic은 공식 문서에서 CLAUDE.md를 이렇게 설명합니다.
CLAUDE.md 파일은 프로젝트, 개인 작업 흐름 또는 조직 전체에 관한 지속적인 지침을 Claude에 제공하는 Markdown 파일입니다. 일반 텍스트로 작성하며 Claude가 매 세션 시작 시 읽습니다.
— Anthropic, code.claude.com/docs/en/memory
Claude Code가 CLAUDE.md를 찾는 네 곳을 우선순위가 낮은 순서대로 나열하면 다음과 같습니다.
| 수준 | 위치 | 목적 |
|----|----|----|
| **조직** | Mac의 `/Library/Application Support/ClaudeCode/CLAUDE.md`, Linux의 `/etc/claude-code/CLAUDE.md` | 회사 관리자가 MDM을 통해 팀 전체에 배포하는 규칙입니다. 개인 사용자에게는 필요하지 않습니다. |
| **사용자** | `~/.claude/CLAUDE.md` | 모든 프로젝트에 적용되는 개인 규칙입니다. “항상 사용자가 선호하는 언어로 답변하기”, “긴 대시를 사용하지 않기” 등이 있습니다. |
| **프로젝트** | 프로젝트 루트의 `./CLAUDE.md` 또는 `./.claude/CLAUDE.md` | 도구, 폴더 구조, 비즈니스 로직 등 특정 프로젝트를 위한 규칙입니다. 이 파일은 git에 커밋됩니다. |
| **로컬** | `./CLAUDE.local.md` | git에 넣지 않을 프로젝트 개인 메모입니다. 예를 들어 임시 실험이나 팀에서 알 필요가 없는 개인 선호 사항입니다. |
네 파일 모두 동시에 컨텍스트에 로드됩니다. 규칙이 충돌하면 어떤 규칙이 우선할지 알 수 없다고 Anthropic은 공식 문서에서 직접 밝힙니다. Claude가 임의로 하나를 선택할 수도 있습니다. 따라서 중요한 내용은 프로젝트 CLAUDE.md에 모으고 중복 파일을 만들지 않는 편이 간단합니다.
팁
파일명은 대소문자를 엄격하게 구분합니다. 대문자로 `CLAUDE.md`라고 쓰면 Claude가 읽습니다. `claude.md`나 `Claude.md`는 읽지 않습니다. `CLAUDE.local.md`도 마찬가지입니다. Claude Code를 처음 설정하는 사람들이 자주 저지르는 실수입니다. 파일을 만들고 지침을 작성한 뒤 왜 작동하지 않는지 고민하다가 파일명이 소문자였다는 사실을 발견합니다.
거의 아무도 언급하지 않지만, 이상한 동작을 많이 설명해 주는 기술적 세부 사항이 하나 있습니다.
CLAUDE.md의 내용은 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 뒤에 사용자 메시지로 전달됩니다. Claude는 이를 읽고 따르려고 하지만 엄격히 준수한다고 보장할 수는 없습니다.
— Anthropic, code.claude.com/docs/en/memory
다시 말해 CLAUDE.md는 엄밀한 의미의 “시스템 프롬프트”가 아닙니다. Claude가 보는 첫 번째 사용자 메시지입니다. 따라서 규칙은 법이 아니라 강력한 권고입니다. 강제가 필요한 규칙에는 해당 이벤트를 다루는 검증된 hook을 쓰고 더 넓은 접근 경계에는 권한이나 환경 격리를 사용하세요. hook이 자동 실행된다고 검사가 완전해지는 것은 아닙니다. 아래에서 `hooks`와 `CLAUDE.md`의 경계를 설명하겠습니다.
## 5분 만에 최소한의 CLAUDE.md를 작성하는 방법 (바로 쓰는 템플릿)?
핵심 요점
템플릿을 복사하고 대괄호 안의 항목을 바꾼 뒤 프로젝트 루트에 `CLAUDE.md`라는 이름으로 저장하세요. 그러면 Claude가 세션마다 처음부터 시작하는 일을 막을 수 있습니다. “에이전트가 실수할 때마다 한 줄을 추가한다”는 규칙에 따라 필요할 때 내용을 확장하면 됩니다.
아래는 수십 개의 제 프로젝트에서 테스트한 템플릿입니다. Anthropic의 200줄 미만 권장에 맞춰 80-120줄로 파일 길이를 맞췄습니다. 이 템플릿을 쓰면 에이전트가 가장 합리적인 결과를 내놓습니다.
```markdown
# [PROJECT NAME] - project navigation
This document is the project map. Read it at the start of every session
to understand where things are and how to work with them.
## What this project is
**[NAME]** - [one sentence: what it is and who it’s for].
[1-2 sentences: what problem it solves and how].
Details are in `business/INDEX.md`.
## Reading order at the start of every session
1. `about-me/INDEX.md` - who I am and how I think
2. `business/INDEX.md` - what we do (product, audience, economics)
3. `CLAUDE.md` (this file) - repo rules, tools, navigation
4. Task area: the relevant file from `business/`, `plans/`,
`mastery/` or the feature folder in the code
Principle: layer 1 (about me) comes before layer 2 (business) for a reason.
First, **who** is thinking, then **about what**.
## Repository structure
[NAME]/
├── CLAUDE.md ← this file, navigation
├── about-me/ ← digital projection of you (how you think, what you value)
│ └── INDEX.md
├── business/ ← the business’s second brain
│ ├── INDEX.md
│ ├── audience/ ← customer profile
│ ├── products/ ← products, prices
│ ├── goals/ ← goals, metrics
│ └── economics/ ← unit economics, revenue
├── plans/ ← technical plans (one plan = one feature)
├── retrospectives/ ← reflections after each session
└── (project code)
### Where to find things
| What you need | Where to look |
|---|---|
| Why we’re building the project, and for whom | `business/INDEX.md` |
| Target customer, pains, desires | `business/audience/` |
| Product, plans, prices | `business/products/` |
| Goals and metrics | `business/goals/` |
| Economics | `business/economics/` |
| Technical plans | `plans/` |
## Tools
[INSERT TOOLS - for example: Next.js 14, TypeScript, Tailwind CSS, Prisma + PostgreSQL].
## Repo rules
1. Never hardcode dynamic data (prices, dates, figures) -
get everything from files in `business/` and the LIVE marker.
2. Don’t publish without my explicit command.
3. Before `git push`, run `npm run build` and check that it
builds without errors or warnings.
4. Add files by name with `git add`. Never use `git add .` or `git add -A`.
5. Don’t read `.env` in full. To check a variable, use
`grep "^VAR=" .env`.
## Big features = a plan in `plans/`
Any task lasting more than an hour must be written up as a plan in the `plans/` folder:
1. Filename: `YYYY-MM-DD-feature-name.md`.
2. Divide the plan into phases. Mark each phase `[ ]` or `[x]`.
3. At the end of the plan, add a summary: whether it was fully implemented and what remains.
## End-of-feature cycle
After each feature is complete, go through these 5 steps:
1. Find errors → prove them with an example → fix them.
2. What was missed (edge cases, input validation, error handling).
3. Is this a real problem in our project? Check `business/` and `plans/`.
4. Take a fresh look: reread the diff as if you’re seeing it for the first time.
5. Security review. Especially: personal data and third-party materials.
## End-of-session reflection
In `retrospectives/YYYY-MM-DD_short-name.md`, record:
1. What the task was.
2. How it was solved.
3. Whether it was solved - yes / no / partially.
4. What could have been done better.
5. What was learned about the user or project.
## Language
Always respond in the user’s preferred language. Use hyphens only, not em dashes.
```
Claude가 프로젝트에 맞춰 이 템플릿을 자동으로 작성하게 하려면 다음 프롬프트를 제공하세요. Claude는 맥락을 읽고 대괄호 안의 항목을 채웁니다.
프롬프트: 내 프로젝트의 CLAUDE.md 작성하기
```
Create a CLAUDE.md file at the project root using this template:
[INSERT THE ENTIRE TEMPLATE FROM ABOVE]
Proceed as follows:
Read about-me/INDEX.md and business/INDEX.md to understand the project context and me as the author.
Fill in all the square-bracketed fields in the template based on what you find in those folders.
If some information is missing, ask me clarifying questions one at a time, with 3-4 answer options.
결과 CLAUDE.md는 200줄 미만을 목표로 하세요. 더 길면 중복을 검토하고 상세 절차를 연결된 파일로 옮기세요. 핵심 계획, 회고, 저장소 규칙을 유지한 뒤 대표 작업에서 시험하세요.
Show me the final file and ask what should be revised.
Always respond in the user’s preferred language.
```
아직 `about-me/`과 `business/` 폴더가 없어도 괜찮습니다. Claude가 확인 질문을 하고 현재 이용할 수 있는 내용을 바탕으로 최소한의 CLAUDE.md를 만들어 줍니다. 무엇을 넣을지 알게 되면 나중에 폴더를 만들어도 됩니다.
## CLAUDE.md를 살아 있는 문서로 만드는 6가지 규칙은 무엇일까요?
핵심 요점
이 6가지 규칙은 수십 개 프로젝트에서 얻은 경험을 간추린 것입니다. CLAUDE.md를 “만들어 놓고 잊어버린 파일”에서 Claude가 매 세션 참고하는 실무 문서로 바꿔 줍니다.
### 규칙 1. 200줄 미만으로 유지하기
Anthropic은 공식 문서에서 간결하게 말합니다.
CLAUDE.md를 200줄 미만으로 유지하세요. 파일이 길수록 더 많은 컨텍스트를 사용하고 지침 준수율이 낮아집니다.
— Anthropic, code.claude.com/docs/en/memory
긴 CLAUDE.md는 두 가지 면에서 역효과를 냅니다. 첫째, 토큰을 소모합니다. 800줄짜리 지침 파일은 매 창마다 로드되고 매 세션 예산에서 수천 토큰을 차지합니다. 일일 한도가 있는 Pro 구독에서는 사용할 수 있는 세션 수가 눈에 띄게 줄어듭니다. 둘째, 모델이 규칙을 무시하기 시작합니다.
문서는 컨텍스트 사용을 줄이고 준수율을 높이기 위해 200줄 미만을 목표로 하라고 권합니다. 201번째 줄에서 갑자기 실패하는 경계를 정하지는 않습니다. 무엇을 옮길지 결정하기 전에 관련성, 모순, 로드한 토큰량, 실제 작업 결과를 검토하세요.
경고
이미 300-500줄이 되었더라도 당황하지 마세요. 내용을 폴더별로 나누세요. 예를 들어 디자인 시스템에 관한 자세한 규칙은 `business/assets/brand-guidelines.md`에 넣을 수 있습니다. 그러면 CLAUDE.md에서는 “UI 작업 시 `business/assets/brand-guidelines.md`를 참고할 것”이라고 한 줄로 안내하면 됩니다. 경로 안내의 원칙은 이렇습니다. CLAUDE.md는 목차이지 책이 아닙니다.
### 규칙 2. 모든 세션을 회고로 마무리하기
CLAUDE.md에 이렇게 적으세요. “매 세션이 끝날 때 한 일과 배운 점을 `retrospectives/YYYY-MM-DD_*.md`에 기록할 것.” 이 문장을 추가하면 Claude는 요청하지 않아도 매번 세션을 회고로 마무리하기 시작합니다.
회고가 필요한 이유:
- 2주 뒤에 예전 회고를 열어 그 경로를 선택한 이유를 기억할 수 있습니다.
- 한 달 뒤 프로젝트로 돌아왔을 때 최근 결정 사항을 정리한 지도가 준비되어 있습니다.
- 팀으로 일한다면 파트너가 통화 없이도 회고를 읽고 2분 만에 현재 상태를 파악할 수 있습니다.
### 규칙 3. 작업을 마칠 때마다 커밋하기
내 CLAUDE.md에는 이렇게 적혀 있습니다. “완료된 작업마다 의미 있는 메시지로 git 커밋을 만들 것.” Claude는 알아서 작업을 원자적인 커밋으로 나누기 시작합니다.
이렇게 하면 두 가지 이점이 있습니다. 첫째, 무언가 잘못되면 “오늘 한 모든 작업”이 아니라 하나의 작업만 되돌릴 수 있습니다. 둘째, 커밋 기록이 무엇이 어떤 순서로 바뀌었는지 보여주는 작업 로그가 됩니다.
### 규칙 4. `business/` 폴더를 반드시 확인하기
고객, 제품 또는 문구와 관련된 작업이라면 에이전트는 먼저 `business/INDEX.md`와 그 파일에서 안내하는 관련 파일을 열어야 합니다. 내 CLAUDE.md에는 이렇게 명시되어 있습니다. “UI나 문구를 작업할 때는 `business/audience/avatar.md`와 `business/assets/brand-guidelines.md`를 먼저 확인할 것.”
이 규칙이 없으면 Claude는 “괜찮은 웹사이트의 일반적인 스타일”로 문구를 씁니다. 규칙이 있으면 당신의 스타일로, 고객에 맞게, 금지어를 피해서 작성합니다.
### 규칙 5. 에이전트가 실수할 때마다 규칙을 추가하기
CLAUDE.md를 계속 유지하게 하는 핵심 규칙입니다.
내 CLAUDE.md에 구체적인 실수 뒤에 추가한 규칙의 예:
- “`git add .`로 다른 사람의 WIP 파일을 커밋하지 말 것 - 파일명을 지정해 스테이징할 것.”
- “`main`에 푸시하기 전에 `git log origin/main..main --oneline`을 확인할 것 - 출력이 비어 있지 않으면 푸시하지 말 것.”
- “값을 지어내지 말 것 - `.env`나 코드에서 확인할 것. 특히 URL, 사용자 이름, 토큰.”
각 규칙은 구체적인 사건의 흔적입니다. 한 번은 에이전트가 파트너의 미완성 브랜치를 커밋했습니다. 한 번은 다른 사람의 아직 푸시되지 않은 커밋을 포함했습니다. 또 한 번은 존재하지 않는 URL을 에이전트가 지어냈습니다. 모든 실수가 규칙이 되면 같은 자해성 실수를 되풀이하지 않게 됩니다.
### 규칙 6. 보안 규칙은 CLAUDE.md가 아니라 `.claude/settings.json`에 넣기
CLAUDE.md에 “`.env`를 건드리지 말 것”이라고 적을 수는 있지만, 그건 요청일 뿐입니다. CLAUDE.md는 시스템의 법이 아니라 사용자 메시지로 로드되므로 Claude가 어길 수도 있습니다. 중요한 보안 규칙은 `.claude/settings.json`을 사용해 특정 명령을 엄격하게 차단하세요.
새 프로젝트마다 추가하는 차단 목록:
- `rm -rf` (모든 파일의 재귀적 삭제).
- `.env` 전체 읽기 (`Read .env`).
- 동일한 명령에서 `export`와 `curl` 사용 (비밀 정보를 외부로 유출하는 패턴).
- 명시적인 승인 없이 `git push --force` 실행.
경고
차이는 간단합니다. CLAUDE.md의 규칙은 에이전트가 어길 수 있는 조언입니다. 일치하는 deny 규칙은 적용되는 권한 흐름에서 해당 동작을 차단합니다. 모든 동등 명령, 다른 도구, 다른 권한 모드에 대한 보호 증거는 아닙니다. 중요한 보안 규칙은 `settings.json`에, 나머지는 CLAUDE.md에 두세요.
[Ailoot에서 다른 가이드](https://ailoot.ai/docs/)를 확인하세요.
[Ailoot 가이드](https://ailoot.ai/docs/)
## 실제 비즈니스에서 CLAUDE.md는 어떻게 구성될까요 (280줄 파일의 구조 분석)?
핵심 요점
실제 운영 중인 온라인 서비스에서 사용하는 CLAUDE.md 파일의 구조를 분석합니다. 약 280줄에 11개 섹션으로 구성되어 있습니다. 각 섹션에 무엇이 들어 있고 왜 그런지 보여 드리겠습니다. 운영 세부 정보가 포함되어 있어 실제 텍스트는 공개하지 않겠습니다. 하지만 이 틀은 어떤 비즈니스에도 적용할 수 있습니다.
온라인에서 볼 수 있는 대부분의 CLAUDE.md 예시는 개발자를 위한 기술 템플릿입니다. “TypeScript를 사용하세요”, “50줄보다 긴 테스트를 작성하지 마세요” 같은 내용입니다. 기업가에게 이런 CLAUDE.md는 쓸모가 없습니다. 비즈니스 측면을 다루지 않기 때문입니다.
아래는 내가 실제로 사용하는 CLAUDE.md의 구조입니다. 내부 운영 방식을 반영하는 구체적인 규칙과 경로는 제거했습니다. 그러나 섹션의 구조와 논리는 어떤 프로젝트에도 적용할 수 있습니다. 자신의 상황을 넣으면 실제로 쓸 수 있는 파일이 됩니다.
**1. 프로젝트 간단 설명 (15줄).** 우리가 하는 일, 대상 고객, 제공하는 제품입니다. 마케팅 사이트의 요약이 아니라 에이전트가 “우리가 어디로 가고 있는지” 이해하도록 돕는 요약입니다.
**2. 나에 대해 (10줄).** 내가 생각하는 방식을 디지털로 투영한 `about-me/` 폴더를 가리킵니다. 어조, 가치관, 원칙, 금지어를 담습니다. Claude가 “내가 쓴 것처럼” 글을 작성할 때 먼저 이 폴더를 읽어 내 목소리를 맞춥니다.
**3. 저장소 구조 (20줄).** 코드 위치, 비즈니스 맥락이 담긴 곳, 계획과 회고가 있는 곳을 주석으로 표시한 트리입니다. 이 지도가 없으면 Claude는 매번 파일을 무작정 찾습니다.
**4. “필요한 정보와 위치” 표 (25줄).** “질문 → 파일”의 경로 안내입니다. 예를 들어 부동산 중개업체라면 “주택담보대출 조건이 필요함 → `business/products/mortgage.md`” 또는 “게시물의 말투가 필요함 → `business/assets/voice.md`”라고 적을 수 있습니다. 예시를 자신의 파일로 바꾸세요. 이 표가 CLAUDE.md의 핵심입니다. 표가 없으면 에이전트는 답이 어느 파일에 있는지 추측합니다. 표가 있으면 바로 원본으로 갑니다.
**5. 핵심 프로젝트 원칙 (40줄, 10-15개 항목).** 이 섹션은 천천히 쌓이며 가장 많은 노력이 듭니다. 각 항목은 특정 실수의 흔적입니다. 예를 들어 온라인 상점의 규칙은 “가격과 배송 시간을 코드에 고정하지 말 것”, “명시적인 명령 없이 제품을 게시하지 말 것”, “제품 목록을 게시하기 전에 브랜드 용어집에 맞춰 스타일을 확인할 것”일 수 있습니다. 이 섹션은 “프로젝트 헌장”입니다.
**6. 운영 계획 (20줄).** “사용자의 표현 → 행동”을 연결하는 트리거 표입니다. 예를 들어 “내가 ‘한 주를 계획하자’고 하면 `ops/monthly.md`를 열고 해당 주의 파일을 만들 것”이라고 적습니다. 이렇게 하면 Claude가 명령의 맥락을 이해하는 운영 보조자가 됩니다.
**7. 도구 (5줄).** 기술입니다. 군더더기 없이 간단히 적습니다.
**8. 게시 (15줄).** 변경 사항을 프로덕션에 게시하는 단계별 절차입니다. 어떤 명령을 어떤 순서로 실행하고 무엇을 확인할지 적습니다. 예전에는 매번 설명했습니다. 이제 Claude가 알고 있습니다.
**9-12. 보안 (35줄).** 네 개의 별도 하위 섹션입니다. `.env` 작업 규칙, 프로덕션 데이터베이스 접근, 데모를 위한 안전한 명령(화면 녹화, 스트리밍, 스크린샷에서 토큰이 실수로 노출되지 않도록 하는 규칙), 비밀 정보 교체 규칙입니다.
**13. `plans/` 폴더 (10줄).** 계획 표준입니다. 파일명, 단계 구조, 요약 블록에 들어갈 내용을 정합니다.
**14. `retrospectives/` 폴더 (5줄).** 회고 표준입니다. 템플릿, 파일명, 포함할 내용을 정합니다.
**15. 실시간 데이터베이스 데이터 (15줄).** “최신 데이터”를 표시하는 규칙입니다. 파일에서 수치가 최신이어야 한다고 할 경우 에이전트는 오래된 수치를 사용하지 않고 원본에서 가져옵니다. 이렇게 하면 Claude가 어제의 수치를 사용하는 위험이 사라집니다.
**16. 언어 (3줄).** “항상 사용자가 선호하는 언어로 답변할 것. 긴 대시가 아닌 하이픈만 사용할 것.”
총 약 280줄입니다. 간결성 목표는 넘지만 파일이 무효가 되지는 않습니다. 이 예시에서는 유용했으며 유지 여부는 측정한 컨텍스트 사용과 대표 작업 검사로 판단해야 합니다. 표가 산문보다 자동으로 토큰을 덜 쓰는 것은 아닙니다.
팁
1년 동안 일하며 만든 구조가 절대적인 원칙은 아닙니다. 틀은 이렇습니다. 설명(1-2개 섹션), 구조와 경로 안내(2-3개 섹션), 규칙과 원칙(큰 섹션 1개), 비즈니스에 맞는 운영 절차(2-3개 섹션), 자잘한 세부 사항(언어, 연락처). 자신의 비즈니스에 맞는 세부 정보를 채우세요. 핵심 규칙은 각 섹션이 “이 정보가 없으면 Claude가 실수할까?”라는 질문에 답해야 한다는 것입니다. 아니라면 삭제하세요.
## `/init` 명령은 무엇을 하며, 왜 그것만으로는 부족할까요?
핵심 요점
Claude Code의 `/init` 명령은 프로젝트를 스캔하고 도구와 빌드 명령을 나열해 기본적인 CLAUDE.md를 자동으로 만듭니다. 좋은 출발점이지만 비즈니스 맥락과 원칙이 없으면 파일은 기술적이고 일반적인 내용에 그칩니다. `/init`을 첫 단계로 사용하고, 그 뒤에 직접 내용을 추가하세요.
Anthropic은 문서에서 이 명령을 다음과 같이 설명합니다.
/init을 실행해 시작용 CLAUDE.md를 자동으로 생성하세요. Claude가 코드를 분석하고 빌드 명령, 테스트 지침, 감지된 프로젝트 규칙이 포함된 파일을 만듭니다.
— Anthropic, code.claude.com/docs/en/memory
`/init`이 잘하는 일:
- `package.json`, `Cargo.toml`, `pyproject.toml`에서 도구를 식별합니다.
- 빌드 및 테스트 명령을 나열합니다.
- 기존 파일(`.eslintrc`, `.prettierrc`)에서 규칙을 파악합니다.
- 기존 Cursor 규칙(`.cursorrules`, `.cursor/rules/`)과 Copilot 규칙을 찾아 관련 내용을 포함합니다. `CLAUDE_CODE_NEW_INIT=1` 모드에서는 `AGENTS.md`도 찾아 반영합니다.
`/init`이 하지 못하는 일:
- 고객이 누구인지 알지 못합니다.
- 문구에 사용하면 안 되는 단어를 포함하지 않습니다.
- 에이전트가 저지른 실수에 대한 규칙은 추가하지 않습니다. 아직 그런 실수가 없기 때문입니다.
- 비즈니스 구조에서 필요한 정보를 찾을 수 있는 표를 만들지 않습니다.
따라서 올바른 작업 흐름은 다음과 같습니다.
1. ### Claude Code에서 /init 실행하기
도구와 명령이 들어간 30-50줄짜리 시작용 CLAUDE.md를 얻습니다. 이것이 기술적 기반입니다.
2. ### 이 글의 템플릿을 덧붙이기
“5분 만에 최소한의 CLAUDE.md 작성하기” 섹션을 사용하세요. 탐색, 경로 안내, 원칙 섹션을 추가합니다.
3. ### 대괄호 안의 항목 채우기
Claude에게 “내 프로젝트를 읽고 템플릿을 채워 줘”라고 요청하세요. `business/`와 `about-me/` 폴더가 아직 없다면 Claude가 확인 질문을 합니다.
4. ### 스트레스 테스트하기
Claude에게 “내 CLAUDE.md를 읽고 에이전트인 네가 잘못 이해할 수 있는 모호한 점 10개를 찾아 줘”라고 요청하세요. 그러면 수정 사항 목록을 받을 수 있습니다.
5. ### 이후 파일을 계속 사용하기
에이전트가 실수할 때마다 한 줄을 추가하세요. 한 달이 지나면 비즈니스에 맞춰 살아 있는 CLAUDE.md가 완성됩니다.
네 번째 단계에 사용할 프롬프트:
프롬프트: CLAUDE.md 스트레스 테스트
```
I have a CLAUDE.md. Tomorrow I’ll be building a feature based on it.
Your task is to stress-test it. Find 10 reasons we could potentially fail:
where CLAUDE.md is ambiguous and you, as an agent, might misunderstand it
where there are gaps that would force you to make things up
where rules contradict one another
where I overestimate how much can be done in one day
where I underestimate things (this is even worse)
Don’t hold back. Criticize it harshly. I want to find these issues now, not in production.
At the end, give me a list of specific changes: what to change and how, so these problems don’t happen.
```
## 2026년 CLAUDE.md와 AGENTS.md, MEMORY.md: 각각 누가 무엇을 읽을까요?
핵심 요점
비슷한 파일 세 가지를 혼동하는 경우가 많습니다. CLAUDE.md에는 직접 작성하고 Claude Code가 매 세션 읽는 프로젝트 규칙이 담깁니다. AGENTS.md는 다른 에이전트(Codex, Cursor, Copilot)를 위한 범용 표준이며, 2026년 9월부터 프로젝트에 CLAUDE.md가 없으면 Claude Code도 읽습니다. MEMORY.md에는 Claude가 사용자의 습관에 관해 자동으로 작성하는 메모가 담깁니다. 세 파일을 동시에 사용해도 충돌하지 않습니다.
| 파일 | 누가 작성하나요 | 누가 읽나요 | 언제 불러오나요 |
|----|----|----|----|
| **CLAUDE.md** | 사용자, 직접 작성 | Claude Code (기본 지원) | 매 세션 시작 시 |
| **AGENTS.md** | 사용자, 직접 작성 | Codex CLI, Cursor, GitHub Copilot CLI, Gemini CLI 및, 버전 2.1.277부터는 프로젝트에 CLAUDE.md가 없을 경우 Claude Code | 매 세션 시작 시 |
| **MEMORY.md** | Claude Code 자체 | Claude Code (기본 지원) | 매 세션 시작 시, 처음 200줄(또는 25 KB 중 더 작은 쪽) |
초보자를 가장 헷갈리게 하는 질문은 이겁니다. **Claude Code는 `AGENTS.md`를 읽나요?** 2026년 9월 전에는 답이 “아니요”였습니다. Anthropic 문서는 AGENTS.md를 불러오는 CLAUDE.md를 만들라고 안내했습니다. 2.1.277 버전(2026년 9월 18일 출시)부터 Claude Code는 AGENTS.md 자체를 읽습니다. 단, 작업 폴더나 상위 폴더에 CLAUDE.md, `.claude/CLAUDE.md`, `CLAUDE.local.md`가 없어야 합니다.
Claude Code는 AGENTS.md를 프로젝트 지침으로 읽을 수 있으므로 다른 에이전트용으로 이미 설정된 저장소는 CLAUDE.md, 가져오기 설정 또는 별도 구성 없이 작동합니다.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
프로젝트에 CLAUDE.md가 있으면 Claude Code는 기본적으로 그것만 읽고 AGENTS.md는 건너뜁니다. `/config`의 Project instructions에서 설정을 바꿀 수 있습니다. 예를 들어 `claude-md-and-agents-md` 설정을 사용하면 두 파일을 모두 읽습니다. 모든 버전에서 작동하는 다른 방법도 있습니다. CLAUDE.md에 다음을 가져오도록 지정하세요.
```markdown
@AGENTS.md
## Claude Code
Additional rules for Claude Code that other agents don’t need.
```
`@filename` 구문은 다른 파일을 가져옵니다. Claude는 해당 파일을 읽고 CLAUDE.md와 함께 컨텍스트에 로드합니다. Claude Code가 AGENTS.md를 자체적으로 읽을 수 있더라도 이 가져오기로 인해 파일을 두 번 읽지는 않습니다.
**AGENTS.md가 필요한 경우.** Claude Code와 Codex CLI, Cursor 또는 Copilot을 병행한다면 단일 정보 출처로 AGENTS.md를 만들고, CLAUDE.md에 `@AGENTS.md`를 넣은 뒤 Claude 전용 규칙을 추가하세요. Claude 전용 규칙이 없다면 CLAUDE.md를 만들 필요가 없습니다. 2.1.277부터 Claude Code가 AGENTS.md를 직접 읽기 때문입니다. Claude Code만 사용한다면 AGENTS.md는 필요 없고 CLAUDE.md 하나만 사용하면 됩니다. 모든 방법을 단계별로 보려면 [한 프로젝트에서 AGENTS.md와 CLAUDE.md를 함께 사용하는 가이드](https://ailoot.ai/blog/ko/agents-md-claude-md-one-instruction-file/)를 참고하세요.
**MEMORY.md란 무엇인가요?** 최근 업데이트 이후 Claude Code는 `~/.claude/projects//memory/MEMORY.md`에 사용자에 관한 메모를 자동으로 보관합니다. “사용자는 짧은 답변을 선호함” 같은 대화 습관, “코드에서 이모지를 금지함” 같은 반복되는 표현, “macOS에서 작업하며 zsh를 사용함” 같은 행동 관찰이 포함됩니다.
이것은 CLAUDE.md와 별개인 메모리 시스템입니다. 직접 작성하지 않으며 Claude가 대화 내용을 바탕으로 작성합니다. MEMORY.md에 규칙으로 만들어야 할 내용이 있으면 CLAUDE.md로 옮기세요. 불필요하거나 잘못된 내용이 있으면 직접 삭제할 수 있습니다. 텍스트 파일이기 때문입니다.
참고
세션 시작 시 무엇이 로드되는지 확인하려면 Claude Code에서 `/memory`를 입력하세요. CLAUDE.md, MEMORY.md 및 로드된 다른 파일의 내용이 표시됩니다. Claude가 이상하게 행동할 때 유용합니다. `/memory`를 열고 원인이 되었을 수 있는 규칙을 찾아보세요.
## 유용한 CLAUDE.md 크기는 어느 정도이며 긴 파일은 어떻게 검토하나요?
핵심 요점
긴 지침은 컨텍스트를 더 쓰고 중복이나 모순이 있으면 관련 규칙을 따르기 어렵게 할 수 있습니다. Anthropic은 200줄 미만을 목표로 권합니다. 기술적 상한이나 준수할 규칙 수의 보편적 예측은 아닙니다.
Claude Code 창마다 여러 계층이 컨텍스트에 로드됩니다. Anthropic의 시스템 프롬프트(수만 토큰으로 추정), CLAUDE.md, `@`로 가져온 파일, MEMORY.md, 현재 채팅 기록, Claude가 여는 파일의 내용입니다. 이 모든 내용은 모델의 컨텍스트( Sonnet은 200K 토큰, Opus는 1M 토큰)에 들어가야 합니다.
CLAUDE.md가 커질수록 현재 작업에 쓸 공간은 줄어듭니다. 1,000줄짜리 파일은 약 8,000토큰이며 매 세션마다 반복됩니다. Pro 구독의 경우(내 경험상 하루 약 10-12개의 “고강도” 프롬프트) 처리 능력이 4분의 1 줄어듭니다.
비용만 문제가 되는 것은 아닙니다. 지침이 길고 관련이 없거나 충돌하면 준수율이 낮아질 수 있지만 안정적으로 따르는 지침 수의 보편적 기준은 없습니다. 핵심 규칙을 쓰는 대표 작업 몇 개를 시험하고 실패를 기록한 뒤 집중 수정 후의 동작과 비교하세요.
비대해진 CLAUDE.md 파일 때문에 Claude가 실제 지침을 무시하게 됩니다.
— Anthropic, code.claude.com/docs/en/best-practices
따라서 파일 크기에 관한 경험칙은 다음과 같습니다.
- **80-120줄**: 간결한 프로젝트 지도에 편리한 시작 범위이며 준수율을 보장하지 않음.
- **150-200줄**: 관련성을 검토하고 상세 절차를 연결된 파일로 옮길 계기.
- **200-300줄**: 토큰량, 중복, 작업 결과를 확인. 위의 280줄 업무 예시도 잘 작동할 수 있음.
- **400+줄**: 집중 검토할 이유는 되지만 사용 불가의 증거는 아님. 필수 제약을 유지하고 링크와 규칙이 작동하는지 확인한 뒤 상세 내용을 옮기세요.
줄 수만으로 성공이나 실패를 판단할 수 없습니다. 수정 후 같은 대표 작업을 반복해 핵심 규칙을 검증하고 근거 없는 준수율을 부여하지 마세요.
경고
CLAUDE.md가 너무 커졌다면 직접 다시 구성하지 마세요. Claude에게 다음 프롬프트를 주세요. “CLAUDE.md를 읽고 ‘이 줄을 없애면 에이전트가 실수할까?’라는 질문에 따라 모든 줄을 평가해. 손실 없이 삭제할 수 있는 줄을 이유와 함께 목록으로 돌려줘.” 그러면 객관적으로 효과가 없는 내용을 삭제합니다.
Anthropic은 문서에서 직접 확인하는 방법을 제시합니다.
각 줄마다 물어보세요. ‘이 줄을 없애면 Claude가 실수하기 시작할까?’ 아니라면 삭제하세요.
— Anthropic, code.claude.com/docs/en/best-practices
모든 줄에 적용하세요. “그래도 올바르게 처리할 것”이라는 답이 나오면 그 줄을 삭제하세요. CLAUDE.md는 문서, 의사 결정 기록, 철학을 담는 곳이 아닙니다. 에이전트가 실수하지 않도록 필요한 규칙만 적는 곳입니다.
## CLAUDE.md를 쓸모없게 만드는 7가지 실수는 무엇일까요?
핵심 요점
다른 사람들의 CLAUDE.md에서 자주 보는 실수 일곱 가지입니다. 각각 파일을 체계적으로 정리해야 하는 이유입니다. 대부분은 같은 문제의 변형입니다. CLAUDE.md를 에이전트의 작업 도구로 유지하는 대신 범용 “프로젝트 문서”로 만들려는 것입니다.
### 실수 1. “훌륭한 엔지니어처럼 행동하기”
가장 흔한 실수입니다. 사람들은 CLAUDE.md에 “깔끔한 코드를 작성해”, “모범 사례를 사용해”, “시니어 엔지니어처럼 생각해” 같은 일반적인 바람을 적습니다.
이런 말은 아무 의미가 없습니다. Claude는 일반적인 의미에서 이미 “깔끔한 코드”를 씁니다. 이런 문장은 어떤 결정에도 영향을 주지 않으면서 컨텍스트만 차지합니다.
“깔끔한 코드를 작성해”를 “들여쓰기는 공백 2개를 사용해”, “TypeScript에서 `any`를 사용하지 마”, “함수는 30줄을 넘지 않아야 해”로 바꾸세요. 구체적이고 검증할 수 있습니다.
### 실수 2. Claude가 이미 아는 내용 반복하기
표준 언어 규칙에 관한 설명(“JavaScript에서는 함수가 일급 객체다”, “TypeScript는 정적 타입을 지원한다”), npm, git, docker의 작동 방식에 관한 설명입니다.
Claude는 학습 과정에서 이미 이 내용을 배웠습니다. CLAUDE.md에서 반복해도 새로운 내용은 없고 컨텍스트만 줄어듭니다.
### 실수 3. CLAUDE.md 안에 긴 단계별 지침 넣기
“프로젝트 배포 방법”, “데이터베이스 마이그레이션 작성 방법”, “새 컴포넌트 설정 방법” 같은 긴 지침입니다. 단계별 설명이 수십 줄 이어집니다.
이곳은 긴 단계별 설명을 넣는 곳이 아닙니다. 한 줄 규칙을 넣는 곳입니다. 긴 지침은 `skills/`(필요할 때 불러오는 별도의 Claude Code 기능) 또는 `docs/`에 넣으세요. CLAUDE.md에는 한 줄 링크를 사용하세요. “새 마이그레이션을 만들 때는 `docs/migrations.md`를 열 것.”
### 실수 4. 자동 코드 분석기가 이미 확인하는 규칙
“세미콜론을 사용해”, “사용하지 않는 import를 남기지 마”, “`var`를 사용하지 마.” ESLint, Prettier, Biome은 이런 항목을 모두 잡아내는 린터(자동 코드 검사 도구)입니다.
린터는 결정론적입니다. 실행하면 오류를 찾아 고칩니다. CLAUDE.md 규칙은 확률적이므로 에이전트가 잊을 수 있습니다. 중복해서 적을 필요 없이 린터를 설정하면 됩니다.
### 실수 5. CLAUDE.md에 비밀 정보 넣기
테스트 계정 암호, 샌드박스 API 토큰, 인증이 필요한 관리 패널 링크가 들어간 경우를 봤습니다. 전부 git에 커밋되는 파일 안에 있었고 Anthropic 모델의 컨텍스트에 로드됐습니다.
절대 그러지 마세요. 비밀 정보는 `.gitignore`에 포함된 `.env`에 둬야 합니다. CLAUDE.md에는 기껏해야 “`.env` 전체를 읽지 말고 특정 변수에는 `grep`을 사용할 것”이라고 적으세요.
### 실수 6. 6개월 동안 정리하지 않은 500줄 이상의 잡동사니 파일
CLAUDE.md가 커지면서 `docs/`의 절반을 중복하고, 여기저기 서로 모순되며, 안에 무엇이 있는지 아무도 기억하지 못합니다. 에이전트는 대부분의 내용을 무시하기 시작합니다. 팀에서는 “Claude가 지침을 따르지 않는다”고 불평하며 규칙을 더 추가해 문제를 악화시킵니다.
방치된 CLAUDE.md의 징후는 300줄 초과, 여러 섹션에 반복된 규칙, 더 이상 존재하지 않는 파일로 연결되는 오래된 링크, “2024년에 이렇게 하기로 했다가 나중에 생각을 바꿨다” 같은 “과거 기록”입니다.
해결 방법은 2주마다 Anthropic의 테스트를 사용해 Claude에게 검토를 요청하는 것입니다. “이 줄을 없애면 에이전트가 실수할까?” 답이 “아니요”인 내용은 삭제하세요.
### 실수 7. CLAUDE.md를 만들고 잊어버리기
앞의 실수와는 정반대입니다. 파일을 두 달 전에 한 번 만들고 그 뒤로 건드리지 않았습니다. 그 사이 도구가 바뀌고 새 폴더가 추가됐으며 새로운 에이전트 실수가 나타났습니다. 아무도 업데이트하지 않아 CLAUDE.md는 이 모든 것을 모릅니다.
뚜렷한 징후는 매 세션마다 같은 지시를 반복한다는 것입니다. “X는 하지 마”, “Y는 건드리지 마”, “Z를 기억해.” 두 번 넘게 반복했다면 그 규칙은 머릿속이 아니라 CLAUDE.md에 있어야 합니다.
[Ailoot 가이드](https://ailoot.ai/docs/)
## “세션 종료 시 업데이트” 규칙으로 CLAUDE.md가 스스로 학습하게 하려면 어떻게 할까요?
핵심 요점
CLAUDE.md를 문서에서 살아 있는 도구로 바꾼 핵심 기법은 파일에 규칙 하나를 추가한 것이었습니다. “매 세션이 끝날 때 CLAUDE.md에 없는 사용자에 관한 새로운 정보나 사용자와 일하는 방식에 대해 배운 점이 있는지 확인하고 한 줄을 추가할 것.” 두 달이 지나자 별도의 절차 없이도 파일에 개인화된 규칙이 쌓이기 시작했습니다.
내 CLAUDE.md에는 짧은 섹션이 있습니다.
```markdown
## Self-learning
At the end of every session, check:
- Have I learned anything new about the user or how to work with them?
- Did I break any rule that should now be recorded?
If so, create or update a file in `about-me/feedback/` in this format:
Rule (one-line rule) → Why (why it was added)
→ How to apply (when it applies).
I don’t write the rules by hand - I say, “not like that, because this is how,”
and you put it into a file.
```
이 섹션을 CLAUDE.md에 추가한 뒤 Claude는 매 세션 끝에 “기록할 만한 새로운 내용이 있었나요?”라고 묻기 시작했습니다. 있다면 규칙 초안을 제안했고, 내가 내용을 명확히 하면 파일을 만들었습니다.
이 방식으로 두 달 동안 일한 뒤 `about-me/feedback/`에는 구체적인 실수에서 배운 규칙 파일이 두어 다스 넘게 쌓였습니다. 각 파일은 규칙 → 이유 → 적용 방법 형식의 한 페이지입니다. 그 폴더는 내 개인적인 선호와 금기를 기록한 “두 번째 기억”이 됐습니다.
실수가 규칙이 되기 때문에 다시 반복되지 않고, 규칙은 쌓이며 서로를 강화합니다. 6개월이 지나면 한 달 동안 쉬고 돌아온 나보다 Claude가 내 프로젝트를 더 잘 알게 됩니다.
## CLAUDE.md에 법률, 마케팅, 운영 규칙을 어떻게 추가할까요?
핵심 요점
CLAUDE.md의 기술 지침은 전체 그림의 절반에 불과합니다. 나머지 절반은 비즈니스 규칙입니다. 법적 요구사항에 따른 금지 표현, 브랜드에 맞는 외부 문구 형식, 팀의 주간 업무 방식입니다. CLAUDE.md가 두 측면을 모두 다루면 Claude는 프로그래머뿐 아니라 편집자이자 운영 보조자도 됩니다.
대부분의 팀에서 CLAUDE.md는 도구, 빌드 명령, 코딩 규칙을 다루는 순수 기술 문서입니다. 유용하지만 전체 가치의 3분의 1에 불과합니다.
기업가가 CLAUDE.md를 관리한다면 비즈니스 섹션을 추가하는 것이 좋습니다. 가장 중요한 것은 세 가지입니다.
### 법률 규칙 (규제 시장용)
금융, 의료, 의약품 광고, 어린이 제품 등 규제 산업에서 문구를 게시한다면 금지어는 법적 효력이 있으며 CLAUDE.md에 명시적인 규칙으로 들어가야 합니다. 누군가의 머릿속이나 편집기 스크린샷에 둘 게 아니라, 매 세션 에이전트가 보는 파일에 넣으세요.
은행업 면허가 없는 핀테크 프로젝트의 예:
편집자 참고: 다음 내용은 특정 프로젝트 내부 규칙의 형식을 보여줍니다. 나열된 용어를 사용해도 된다는 보편적 허가가 아닙니다. 표현의 허용 여부는 적용되는 법률과 회사의 지위에 따라 달라집니다.
> 🚨 중요 - 금융 관련 표현은 금지됩니다. 고객에게 보이는 자료에는 “예금”, “보장 수익”, “투자 상품”을 사용하지 마세요. 대신 “저축 계좌”, “예상 수익”, “변동 금리 상품”을 사용하세요. 이 규칙은 이 프로젝트의 금융 서비스 광고에 적용되는 법적 요건을 따르기 위한 것입니다.
CLAUDE.md에 이 블록을 넣으면 간단한 일이 이뤄집니다. Claude에게 고객 대상 문구를 작성해 달라고 할 때마다 에이전트가 이 금지 사항에 비춰 확인합니다. 규칙이 없으면 세 캠페인 중 하나에서 금지어가 나옵니다. 규칙이 있으면 그런 표현이 있다는 사실조차 잊을 수 있습니다.
같은 방식은 다음에도 적용됩니다.
- 의료 프로젝트 (“치료한다” 또는 “완치한다”는 주장 금지).
- 의약품 광고 (“가장 효과적”이라는 주장 금지, 필수 경고 포함).
- 고유한 광고 규칙이 있는 모든 규제 산업.
### 마케팅 스타일과 문구 형식
소셜 미디어, 뉴스레터, 웹사이트에 정기적으로 문구를 게시한다면 CLAUDE.md에 형식을 한 단락으로 정리하는 것이 좋습니다. 메시징 채널을 운영하는 인플루언서나 대행사가 쓸 만한 예시는 다음과 같습니다.
> 채널 게시물을 쓸 때 `style/posts.md`를 참고하세요. 채널에서 허용하는 서식 표시를 사용하고 “위험한” 특수 문자는 피하세요. 다음 규칙에 맞는 UTM 태그를 넣은 CTA로 마무리하세요: `utm_source=&utm_medium=&utm_campaign=`.
Claude는 “일반적인 마케팅 웹사이트의 스타일”로 게시물을 쓰곤 했습니다. 이제는 지정한 형식을 따르고 UTM을 사용하며 AI가 썼다는 티를 내지 않습니다.
### 운영 습관
트리거 표입니다. 특정 표현을 말하면 에이전트가 열 파일과 할 일을 압니다. 주 단위로 계획하는 팀의 예시는 다음과 같습니다.
> “이번 주를 계획해” → `ops/monthly.md`를 열고 같은 폴더에 `YYYY-WNN.md`를 만든 뒤 `ops/backlog.md`의 작업을 해당 요일 아래로 옮깁니다. “백로그에 뭐가 있어?” → `ops/backlog.md`를 읽고 목록으로 보여 줍니다. “이번 주를 마무리해” → 현재 주 파일의 “주간 요약” 섹션을 작성합니다.
이런 표가 있으면 Claude는 “코드를 작성하는 도우미”에서 비즈니스의 일과를 아는 “운영자”로 바뀝니다. 매주 월요일마다 “이번 주를 계획하자”라고 말하면 Claude는 올바른 파일을 열고 월간 목표를 읽어 일을 어떻게 나눌지 제안합니다.
참고
CLAUDE.md에 비즈니스별 지침을 두는 것은 독자층, 제품, 목표에 관한 실제 맥락이 담긴 `business/` 폴더가 있을 때 적절합니다. 아직 없다면 먼저 `business/`를 만들고 그다음 CLAUDE.md에 링크를 추가하세요. 그렇지 않으면 아무것도 가리키지 않는 지침이 생깁니다.
## 5분 만에 12개 항목 점검표로 CLAUDE.md를 확인하는 방법은 무엇일까요?
핵심 요점
이 점검표로 현재 CLAUDE.md를 확인하세요. 각 항목은 30초면 됩니다. “아니요”가 5개 이상이면 파일을 정리해야 합니다.
1. **크기.** 간결하며 약 200줄을 합격·불합격 상한이 아닌 검토 목표로 다루나요?
2. **이름.** `claude.md`가 아니라 대문자를 쓴 정확한 이름 `CLAUDE.md`인가요?
3. **위치.** 프로젝트 루트 또는 `./.claude/CLAUDE.md`에 있나요?
4. **프로젝트 설명.** 처음 5줄을 읽으면 프로젝트가 무엇이며 누구를 위한 것인지 명확한가요?
5. **도구.** 기술이 군더더기 없이 명시적으로 나열되어 있나요?
6. **구조.** 설명이 포함된 저장소 다이어그램이 있나요?
7. **경로 안내.** 답을 어디서 찾는지 보여주는 “질문 → 파일” 표가 있나요?
8. **원칙.** “절대”와 “항상”으로 시작하는 규칙 섹션이 있나요?
9. **구체성.** 모든 규칙을 검증할 수 있나요? (“아름답게 작성해”가 아니라 “공백 2개를 사용해.”)
10. **자체 업데이트.** “세션이 끝날 때 추가할 내용이 있는지 확인하기” 규칙이 있나요?
11. **회고.** “세션 요약을 `retrospectives/`에 기록하기” 규칙이 있나요?
12. **보안.** `.env`, `rm -rf` 등 중요한 금지 사항이 `.claude/settings.json`에도 들어 있나요?
“아니요”가 5개 넘게 나왔다면 Claude를 열고 다음 프롬프트를 입력하세요.
프롬프트: 점검표에 따라 CLAUDE.md 감사하기
```
Read my CLAUDE.md and compare it with the checklist below. For each item, say: yes / no / partly, and what specifically to fix.
Checklist:
작업에 충분히 간결하게 유지. 약 200줄에서 검토하되 강제 상한으로 다루지 않기
프로젝트 설명 in the first 5 lines
Tools listed explicitly
Repository structure diagram included
“Question → file” table included
Principles section with rules included
Every rule is specific and verifiable
“Update at the end of the session” rule included
“Reflect at the end of the session” rule included
Critical prohibitions included in .claude/settings.json
No duplicates of the same rule in different sections
No dangling links to files that no longer exist
After the audit, give me a list of specific changes that will make the file living.
```
## CLAUDE.md 다음에는 무엇을 써야 할까요: Plan Mode, Skills, sub-agents?
핵심 요점
CLAUDE.md가 토대입니다. 제대로 작동하면 다음 단계로 넘어갈 수 있습니다. Plan Mode(Claude가 먼저 계획을 세우고 나서 실행), Skills(자주 쓰지 않는 지식을 CLAUDE.md에서 별도 파일로 옮기기), sub-agents(각자 분리된 컨텍스트에서 진행하는 작업)입니다.
CLAUDE.md가 토대입니다. 제대로 작동하면 서로 힘을 보태는 Claude Code 기능 세 가지를 추가할 수 있습니다.
**Plan Mode.** Claude가 먼저 변경 계획을 만들고, 승인을 기다린 뒤 작업을 시작하는 모드입니다. Shift+Tab 또는 `/plan` 명령으로 활성화합니다. 바이브 코딩의 가장 큰 골칫거리를 해결합니다. “Claude에게 한 가지를 고쳐 달라고 했더니 프로젝트의 절반을 다시 썼다.” Plan Mode에서는 그런 일이 일어나지 않습니다. 에이전트가 파일을 건드리기 전에 계획을 볼 수 있습니다.
**Skills.** 특정 유형의 작업에 필요한 지식이 담긴 별도의 `.md` 파일로, `.claude/skills/` 폴더에 둡니다. 예를 들어 “데이터베이스 마이그레이션 작성 방법” 스킬에는 구체적인 절차, 템플릿, 예시가 들어갑니다. 내용이 너무 방대하므로 CLAUDE.md에는 두지 않습니다. Claude가 “마이그레이션 작성” 같은 작업을 만나면 관련 스킬을 불러와 따릅니다.
**Sub-agents.** 큰 기능 검토처럼 많은 맥락이 필요한 작업에서 Claude는 별도의 깨끗한 컨텍스트로 sub-agent를 실행할 수 있습니다. sub-agent는 작업을 수행하고 결과를 돌려주므로 메인 채팅의 컨텍스트를 복잡하게 만들지 않습니다.
세 기능 모두 CLAUDE.md를 출발점으로 사용합니다. 작업을 시작할 때 파일을 읽고 프로젝트 맥락을 파악합니다. 그래서 살아 있는 CLAUDE.md가 없으면 이 기능들도 제대로 작동하지 않습니다. 먼저 토대를 만들고 그 위에 기능을 쌓으세요.
**다음 단계.** 프로젝트 루트에 `CLAUDE.md` 파일을 만들고 이 글 앞부분의 템플릿을 복사해 보조 프롬프트를 사용하여 대괄호 항목을 채우세요. 그런 다음 실제 작업에서 파일을 계속 사용하고, 에이전트의 실수를 한 줄 규칙으로 바꾸세요. 2~3주가 지나면 CLAUDE.md는 “작성하고 잊은 문서”가 아니라 Claude가 매 세션 실제로 참고하는 자료가 됩니다.
`CLAUDE.md`를 중심으로 세컨드 브레인을 위한 `business/` 폴더, 당신의 디지털 투영을 위한 `about-me/` 폴더, 기본 스킬, 설정된 Plan Mode를 갖춘 완전한 프레임워크를 만들고 싶다면 이 글의 단계와 예시를 활용하세요. [Ailoot 가이드](https://ailoot.ai/docs/).
### 출처
- [Anthropic - Claude Code Memory](https://code.claude.com/docs/en/memory) - CLAUDE.md, MEMORY.md, 로딩 계층에 관한 공식 문서
- [Anthropic - Best Practices](https://code.claude.com/docs/en/best-practices) - 효과적인 CLAUDE.md 작성 규칙과 “이 줄을 제거하면 Claude가 실수할까?”라는 테스트
- [Anthropic Support - Give Claude Context](https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-prompts) - 컨텍스트 활용에 관한 지원 가이드
- [Ailoot 가이드](https://ailoot.ai/docs/) - 문서.
[Ailoot 계속하기](https://ailoot.ai/).
[Ailoot 계속하기](https://ailoot.ai/)
[Ailoot 계속하기](https://ailoot.ai/)
## 2026년 CLAUDE.md 설정 방법: 템플릿과 6가지 규칙: 자주 묻는 질문
### CLAUDE.md가 200줄을 넘으면 무효가 되나요?
아닙니다. 간결성 목표이며 파싱 상한이나 보장된 실패 지점이 아닙니다. 중복, 모순, 로드된 컨텍스트를 검토하고 대표 작업에서 중요한 규칙을 시험하세요. 글의 280줄 예시도 같은 평가가 필요합니다.
### 커지는 CLAUDE.md에서 무엇을 옮기나요?
상세 절차, 긴 참고 자료, 결정 기록은 관련 문서나 스킬로 옮기세요. 진입 파일에는 간결한 프로젝트 사실, 필수 제약, 명확한 링크를 남기세요. 수정 후 실제 작업으로 경로 안내와 핵심 규칙을 재검증하세요.
## Ailoot · 회사와 그 프로젝트 포트폴리오
Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다.
회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출.
Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.