# 같은 실수를 두 번 하면 적을 때입니다 — CLAUDE.md란, 비개발자가 AI에게 주는 프로젝트 지침 파일

CLAUDE.md란 무엇인가. AI에게 주는 헌법 비유, 언제 적나, 3줄짜리 첫 파일과 적용 확인법.

- source: https://polroute.com/posts/what-is-claude-md/
- category: AI 워크플로우
- published: 2026-09-29

---

Claude Code를 며칠 쓰다 보면 같은 설명을 또 하고 있는 자신을 발견합니다. "이건 동네 빵집 예약 사이트야", "새 프로그램은 함부로 설치하지 마", "확인할 땐 이 명령으로 켜 봐". CLAUDE.md는 이런 말을 한 번만 적어 두는 파일입니다.

공식 문서의 정의가 딱 그렇습니다.

> "Treat CLAUDE.md as the place you write down what you'd otherwise re-explain."
> (안 적어 두면 또 설명하게 될 내용을 적는 곳이라고 생각하세요.)

Claude Code는 세션(Claude Code를 켜서 끌 때까지의 대화 한 묶음)을 시작할 때마다 이 파일을 알아서 읽습니다. 결론은 간단합니다. **프로젝트 폴더 맨 위에 `CLAUDE.md` 파일을 하나 만들어 세 줄로 시작하고 Claude가 같은 실수를 두 번 하면 한 줄씩 더하세요.**

> 2026년 9월 29일 기준, Claude Code v2.1.284와 [공식 memory 문서](https://code.claude.com/docs/en/memory)로 확인했습니다. `.md`는 마크다운(`#`나 `-` 같은 기호로 제목과 목록을 표시하는 글 형식) 파일이라는 뜻입니다. 메모장으로도 열리는 평범한 글 파일입니다.

## CLAUDE.md는 'AI에게 주는 헌법'입니다

비개발자에게 잘 통하는 설명 하나는 헌법 비유입니다. 한 비개발자 기획자는 AI 앱을 만들면서 AI가 모든 작업 전에 읽도록 `가이드 문서.md`를 작성했고 그 단계를 [“AI에게 줄 '헌법' 문서 만들기”](https://brunch.co.kr/@jjay0410/1)라고 불렀습니다. 이 비유가 잘 맞는 이유는 헌법과 CLAUDE.md가 세 가지 성질을 똑같이 갖기 때문입니다.

**하나, 매번 낭독하지 않아도 적용됩니다.** 이 블로그 저장소의 CLAUDE.md는 9줄짜리입니다.

```markdown
# dev.log

Astro static markdown blog (light single theme). Posts live in `src/content/posts/*.md`; see README.md for authoring and deploy.

## Subagent Model Routing

- **Development** (feature work, bug fixes, refactors) → dispatch subagents on **`sonnet`**.
- **Review** (code review, verification, SHIP/NO-SHIP verdicts) → dispatch subagents on **`opus`**.
- A sonnet dev agent never self-approves its own diff; commit only after an opus reviewer returns **SHIP**.
```

마지막 줄은 "검토 담당 Claude가 통과(SHIP)를 주기 전에는 저장(커밋)하지 말라"는 규칙입니다. 2026년 9월 28일 이 시리즈의 요금제 편을 발행 준비할 때 저는 이 규칙을 한 번도 입에 올리지 않았습니다. 그런데도 Claude는 검토를 맡겼고 첫 판정이 불통과(NO-SHIP)로 나오자 커밋을 멈췄다가 고친 뒤 통과를 받고서야 커밋했습니다. 같은 규칙이 모든 프로젝트에 적용되는 사용자 지침(`~/.claude/CLAUDE.md`)에도 들어 있어 두 파일이 함께 작용했습니다. 헌법을 매일 아침 낭독하지 않아도 효력이 있는 것과 같습니다.

**둘, 사건마다 해석이 필요합니다.** "인간의 존엄"처럼 넓게 쓴 조항은 구체적인 사건 앞에서 해석이 갈립니다. CLAUDE.md도 "코드를 깔끔하게"처럼 쓰면 무엇이 깔끔한지는 Claude가 매번 짐작합니다. 공식 문서는 규칙을 "concrete enough to verify"(지켰는지 확인할 수 있을 만큼 구체적으로) 쓰라고 하고 두 규칙이 서로 부딪히면 "Claude may pick one arbitrarily"(Claude가 둘 중 하나를 임의로 고를 수 있다)고 경고합니다. 구체적으로 쓰는 요령과 예시는 [CLAUDE.md 템플릿 글](/posts/coding-system-prompt-templates/)에 정리해 뒀습니다.

**셋, 길어질수록 지켜지지 않습니다.** 공식 권장 분량은 "target under 200 lines per CLAUDE.md file"(파일 하나당 200줄 미만)입니다. 이유도 적혀 있습니다. "Longer files consume more context and reduce adherence." 길수록 Claude의 기억 공간을 더 차지하고 지키는 비율은 떨어진다는 뜻입니다.

제 컴퓨터의 사용자 지침(`~/.claude/CLAUDE.md`)을 줄인 기록도 하나 있습니다. 2026년 9월 28일에 **134줄에서 25줄**로 바뀌었습니다. 134줄도 공식 권장치 200줄 안이었습니다. 3계층 구조를 글자로 그린 도식이 든 57줄짜리 섹션과 스킬·에이전트 목록 표가 빠졌고, 소통·작업 흐름·서브에이전트·계층 원칙·UI 기본값 다섯 섹션이 남았습니다.

## 비유가 깨지는 곳: CLAUDE.md에는 강제력이 없습니다

헌법은 어기면 위헌 판결이 나옵니다. CLAUDE.md는 그렇지 않습니다. 공식 문서의 표현입니다.

> "Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead."
> (Claude는 이 파일들을 강제 설정이 아니라 참고 맥락으로 다룹니다. Claude의 판단과 상관없이 어떤 행동을 막으려면 PreToolUse 훅을 쓰세요.)

그러니 CLAUDE.md는 명령서가 아니라 **참고 자료**입니다. "결제 폴더는 절대 수정 금지"처럼 어기면 사고가 나는 규칙은 CLAUDE.md에 적어 두는 것만으로 안전하지 않습니다. 그런 규칙은 훅(Hook, 도구 실행 직전·직후처럼 정해진 시점에 자동으로 도는 명령)으로 막아야 하고 훅은 이 시리즈 뒤쪽에서 따로 다룹니다. CLAUDE.md가 시스템 프롬프트가 아니라 사용자 메시지로 전달된다는 기술적인 배경은 [템플릿 글](/posts/coding-system-prompt-templates/)에 있습니다.

## Claude의 '진짜 헌법', 오토 메모리와 무엇이 다른가

"Claude 헌법"으로 검색하면 CLAUDE.md가 아닌 문서가 먼저 나올 수 있습니다. Anthropic이 2026년 1월 공개한 [Claude's Constitution](https://www.anthropic.com/constitution)입니다. 이 문서는 "plays a crucial role in our training process", 즉 **모델을 훈련하는 단계**에서 Claude의 가치관과 행동을 만드는 데 쓰입니다. 우리가 고칠 수 있는 파일이 아닙니다.

비슷해 보이는 것들을 한 표에 놓으면 이렇습니다.

| | 누가 쓰나 | 언제 적용되나 | 강제력 |
|---|---|---|---|
| Claude's Constitution | Anthropic | 모델 훈련 단계 | 모델의 가치관·행동에 반영 |
| CLAUDE.md | 나(또는 팀) | 세션을 시작할 때마다 | 없음 (참고 맥락) |
| 채팅창에 친 지시 | 나 | 그 대화 안에서만 | 없음 |
| 오토 메모리 | Claude | 세션을 시작할 때마다 (처음 200줄 또는 25KB) | 없음 |
| 훅 | 나 | 정해진 시점 (예: 행동 직전) | 있음 (행동을 막을 수 있음) |

채팅창에 친 지시와 CLAUDE.md의 차이는 생각보다 큽니다. 공식 문서에 따르면 대화가 길어져 `/compact`(대화 요약)가 일어나도 프로젝트 폴더 맨 위의 CLAUDE.md는 디스크에서 다시 읽혀 들어갑니다. 반대로 요약 뒤에 지시가 사라졌다면 대개 "given only in conversation", 대화에서만 했던 말이었기 때문입니다. 하위 폴더에 둔 CLAUDE.md가 아직 다시 읽히지 않은 경우도 있습니다.

오토 메모리는 Claude가 스스로 적는 메모장입니다. 여기서 헷갈리기 쉬운 점이 하나 있습니다. **Claude에게 "기억해"라고 말하면 CLAUDE.md가 아니라 오토 메모리에 저장됩니다.** CLAUDE.md에 넣고 싶으면 "이거 CLAUDE.md에 추가해 줘"라고 파일 이름을 짚어서 말해야 합니다. 오토 메모리는 따로 한 편을 할애해 다룹니다.

## 언제 적나: 공식 기준은 '두 번째'입니다

공식 문서는 CLAUDE.md에 한 줄을 더할 때를 네 가지로 꼽습니다.

![공식 memory 문서의 'When to add to CLAUDE.md' 절. 첫 기준이 'Claude makes the same mistake a second time'이다](/images/what-is-claude-md-1.webp)

1. Claude가 **같은 실수를 두 번째** 할 때
2. 결과물을 검토하다가 "이건 Claude가 이 프로젝트에 대해 알았어야지" 싶은 게 나왔을 때
3. 지난 세션에 했던 정정을 이번 세션 채팅창에 또 치고 있을 때
4. 새로 합류한 사람에게도 똑같이 설명해야 할 맥락일 때

이 블로그의 템플릿 글은 "같은 지시를 세 번째 붙여넣고 있다면" 파일로 옮기라고 썼습니다. 여기서 바로잡습니다. 공식 기준은 그보다 한 번 빠른 **두 번째**입니다. 같은 실수를 한 번 더 참을 이유가 없습니다.

반대로 적지 말아야 할 것도 있습니다. 공식 문서는 CLAUDE.md를 "매 세션 알고 있어야 할 사실"로 채우라고 합니다. 실행 명령, 약속, 폴더 구조, "항상 X 하라" 같은 규칙입니다. 여러 단계로 된 절차나 특정 폴더에만 해당하는 내용은 스킬이나 규칙 파일로 옮기라고 권합니다. 무엇을 넣고 뺄지는 다음 편들에서 자세히 나눕니다.

## 3분이면 되는 첫 CLAUDE.md: 세 줄

위치는 **프로젝트 폴더 맨 위**(루트)입니다. CLAUDE.md를 둘 수 있는 곳은 몇 군데 더 있고 읽히는 순서도 정해져 있는데, 그건 다음 편에서 다룹니다. 폴더 구조 전체가 궁금하면 [.claude 디렉터리 지도](/posts/claude-directory-map/)를 보세요.

처음에는 세 줄이면 됩니다. 이 프로젝트가 무엇인지 한 줄, 하지 말아야 할 것 한 줄, 확인할 때 쓰는 명령 한 줄입니다.

```markdown
# 동네 빵집 예약 사이트

- 손님이 빵을 미리 예약하는 웹사이트입니다. 사장님 혼자 관리하므로 화면은 단순하게 유지합니다.
- 새 프로그램(라이브러리)을 설치하기 전에는 무엇을 왜 설치하는지 먼저 물어보세요.
- 결과는 `npm run dev`로 실행해서 확인합니다.
```

만드는 방법은 세 가지입니다. 편한 쪽을 고르세요.

- **Claude에게 부탁하기**: 채팅창에 "이 폴더에 CLAUDE.md 파일 만들고 아래 세 줄 적어 줘"라고 치고 세 줄을 붙여 넣습니다.
- **`/memory`로 만들기**: `/memory`를 치면 CLAUDE.md 위치 목록이 나옵니다. 아직 없는 파일을 고르면 새로 만들어서 편집기로 열어 줍니다.
- **`/init`으로 자동 생성하기**: Claude가 폴더를 훑어보고 실행 명령과 약속을 찾아 초안을 써 줍니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 고칠 점을 제안합니다. 빈 폴더에서는 찾을 게 없으니 코드가 좀 쌓인 뒤에 쓰는 편이 낫습니다.

## 여기서 막힙니다: 적었는데 안 읽히는 것 같을 때

**먼저 `/context`를 치세요.** 화면에 나오는 **Memory files** 목록에 CLAUDE.md가 보이면 읽힌 것입니다. 공식 문서는 여기에 없으면 "Claude can't see it", 즉 Claude가 볼 수 없다고 적습니다.

목록에 없다면 대부분 위치 문제입니다. 프로젝트 CLAUDE.md는 Claude Code를 켠 폴더(작업 디렉터리)와 그 위쪽 폴더에 있는 것만 시작할 때 읽힙니다. 하위 폴더에 넣어 둔 CLAUDE.md는 Claude가 그 폴더의 파일을 읽을 때 뒤늦게 읽힙니다. 켜기 전에 `cd`로 프로젝트 폴더에 들어갔는지부터 확인하세요. 방법은 [첫 세션 10분](/posts/claude-code-first-session/) 글에 있습니다.

목록에는 있는데 지켜지지 않는다면 앞에서 말한 두 번째와 세 번째 성질을 의심하세요. 규칙이 모호하거나, 서로 부딪히거나, 파일이 너무 긴 경우입니다. 강제력이 없다는 점도 다시 떠올리세요.

## 처음부터 잘 쓸 필요는 없습니다

완벽한 CLAUDE.md를 한 번에 쓰려고 하면 오히려 길어집니다. 그러면 세 번째 성질에 걸립니다. 세 줄로 시작해서 Claude가 같은 실수를 두 번 할 때마다 한 줄씩 붙이는 게 정석입니다.

이 블로그의 CLAUDE.md도 2026년 8월 20일 첫 커밋 이후 한 번도 고치지 않았습니다. 다만 그 사이 모든 교훈이 CLAUDE.md로 간 것은 아닙니다. 발행 절차처럼 여러 단계짜리 규칙은 스킬 파일로 갔고 Claude가 작업하며 배운 주의사항은 오토 메모리에 쌓였습니다. **CLAUDE.md는 모든 걸 담는 곳이 아니라 매 세션 꼭 알아야 할 것만 담는 곳**입니다. 이렇게 규칙과 장치로 AI의 작업 환경을 짜는 일을 넓게는 [하네스 엔지니어링](/posts/harness-engineering/)이라고 부릅니다.