Claude Code의 CLAUDE.md는 짧게 두고 필요할 때 불러온다

바이브 코딩으로 만든 프로젝트를 넘겨받으면 Claude Code에게 알려 줄 것이 많다. 마이그레이션은 도구로 만들 것, 배포 스크립트는 건드리지 말 것, 테스트 러너를 새로 만들지 말 것. 이런 지시를 전부 CLAUDE.md 한 파일에 쌓는 것이 가장 흔한 실수다. CLAUDE.md는 세션을 시작할 때마다 컨텍스트에 들어가므로, 길어질수록 모든 대화가 그 비용을 치른다. 공식 문서는 파일당 200줄 이하를 권한다. 프로젝트 전반의 원칙만 CLAUDE.md에 두고, 특정 파일에만 필요한 지침은 경로 규칙으로, 개인 선호는 local 파일과 자동 메모리로 뺀다

이 글은 터미널에서 claude를 실행해 본 정도의 독자를 기준으로 한다. 다 읽으면 어떤 지시를 어느 파일에 둘지, 대화가 길어졌을 때 /compact와 /clear 중 무엇을 쓸지 판단할 수 있다

컨텍스트는 요청마다 다시 실리는 대화 기록이다

컨텍스트(context)는 모델이 응답을 만들 때 참고하는 정보 전체다. 내가 보낸 메시지만 가는 것이 아니다. 이전 메시지, Claude의 답변, 도구 호출과 그 결과, 시작할 때 읽은 CLAUDE.md가 함께 전달된다. 토큰(token)은 이 양을 재는 단위로, 글자 몇 개를 묶은 조각이라고 보면 된다

[세션 시작]
시스템 프롬프트 + CLAUDE.md + 규칙 + 스킬 목록 + 메모리
        │
        ▼
내 메시지 1 → 도구 호출 → 도구 결과 → Claude 답변 1
        │
        ▼
내 메시지 2 를 보낼 때 위의 전부가 함께 전달된다

그림에서 볼 수 있듯 파일을 하나 읽거나 디렉터리 목록을 한 번 조회한 기록까지 다음 요청에 다시 실린다. /context를 실행하면 현재 컨텍스트를 항목별로 나눠 색 격자로 보여 주고, 어떤 메모리 파일이 로드됐는지도 표시한다(commands)

담을 수 있는 양에는 한도가 있다. 강의는 Opus 5와 100만 토큰 컨텍스트를 기준으로 설명한다. 2026년 9월 27일 기준 공식 문서에서 opus 별칭은 Opus 5.5를 가리킨다. Opus 5.5는 Fable 5.1·Sonnet 5와 함께 Anthropic API에서 요금제와 관계없이 100만 토큰 창으로 동작한다(model-config). 창이 크다고 많이 넣을수록 좋은 것은 아니다. 문서는 긴 CLAUDE.md가 “컨텍스트를 더 쓰고 지시 준수율을 떨어뜨린다”고 적는다(memory). 한 대화에서 로그인, 비밀번호 처리, 스키마 변경, 애니메이션을 연달아 다루면 서로 무관한 기록이 쌓여 판단이 흐려진다는 강의의 설명도 같은 맥락이다

/init은 초안을 만들고 빠진 규칙은 사람이 채운다

/init은 코드베이스를 분석해 빌드 명령, 테스트 방법, 프로젝트 관례를 담은 CLAUDE.md를 만든다. 이미 파일이 있으면 덮어쓰지 않고 개선안을 제안한다(memory). 강의의 예제 프로젝트에서는 vinext, Cloudflare Workers, D1, Drizzle ORM을 쓴다는 사실과 스키마 변경 절차, 요청 처리 흐름을 찾아냈다

CLAUDE_CODE_NEW_INIT=1을 설정하고 /init을 실행하면 질문을 주고받는 방식으로 바뀐다. CLAUDE.md뿐 아니라 스킬과 훅까지 만들지 묻고, 서브에이전트로 코드를 탐색한 뒤 파일을 쓰기 전에 검토할 제안을 보여 준다. 강의는 이 방식이 곧 기본값이 될 수 있다고 했지만, 현재 문서에서도 환경변수로 켜는 선택 기능이다

CLAUDE_CODE_NEW_INIT=1 claude
# 세션 안에서
/init

스킬과 훅을 아직 모른다면 기본 /init으로 시작하는 편이 낫다. 질문에 답하려면 그 기능이 무엇인지 알아야 하기 때문이다.

자동으로 생성된 내용은 반드시 읽는다. Claude가 코드에서 찾을 수 없는 결정은 사람이 적어야 한다. 강의에서는 다음 두 규칙을 추가했다.

## 데이터베이스
- SQL 마이그레이션 파일을 직접 작성하거나 수정하지 않는다.
  스키마를 바꾼 뒤 `npx drizzle-kit generate`로 생성한다.

## 검증
- 이 프로젝트에는 테스트 러너가 없다. 새로 만들지 말고 `npm run typecheck`로 검증한다.

첫 규칙은 Claude가 SQL을 손으로 쓰는 습관을 막는다. 두 번째 규칙은 테스트가 없다는 사실을 알려 주지 않으면 Claude가 테스트 환경을 새로 세우려 드는 문제를 막는다. npm run typecheck는 예시 이름이다. 실제 스크립트 이름은 package.json에서 확인한다

어떤 지시가 CLAUDE.md에 들어가야 하는지 판단하는 기준은 반복이다. “그 파일은 옮기지 마”, “함수를 그렇게 크게 만들지 마”를 두 번째 말하고 있다면 그 지시는 파일로 옮길 후보다

세션 중에 CLAUDE.md를 고쳐도 이미 읽은 내용은 대화에 남는다

강의는 CLAUDE.md에 “항상 해적처럼 대답해라”를 넣고 Claude를 다시 실행하는 시연을 한다. 해적 말투로 답한다. 이어서 파일에서 그 줄을 지우고 같은 대화에서 다시 물으면 여전히 해적 말투다. /clear를 실행한 뒤에야 평범하게 답한다

공식 문서는 CLAUDE.md를 “실행 시점에 로드한다”고 적을 뿐, 세션 중 편집이 언제 반영되는지는 따로 설명하지 않는다. 시연 결과는 시작할 때 읽은 내용이 대화 기록에 남아 있었다는 설명과 맞는다. 다만 이것은 강의에서 관찰한 결과이고, 모든 버전에서 같은지는 확인하지 않았다. 문서가 명시하는 것은 두 가지다

/compact를 실행하면 프로젝트 루트의 CLAUDE.md를 디스크에서 다시 읽어 주입한다(memory)
/clear는 빈 컨텍스트로 새 대화를 시작한다. 이전 대화를 지우지는 않으며 /resume으로 다시 열 수 있다(commands)

/clear로 기록이 “사라진다”는 말은 현재 컨텍스트에서 빠진다는 뜻이다. 대화 파일은 ~/.claude/projects/ 아래 JSONL로 남고, cleanupPeriodDays 보존 기간이 지나야 정리된다

특정 파일에만 필요한 지침은 paths 규칙으로 뺀다

프로젝트가 커지면 “스키마 파일을 다룰 때는 이렇게”, “API 라우트에서는 저렇게” 같은 조건부 지시가 늘어난다. 이런 지시는 .claude/rules/ 아래 마크다운 파일로 분리한다. 파일 이름은 자유이고, 하위 폴더도 재귀적으로 찾는다

다음은 데이터베이스 관련 파일을 읽을 때만 적용할 규칙이다

---
paths:
  - "src/db/**/*.ts"
  - "drizzle/**/*.sql"
---

# 데이터베이스 작업 규칙
- 마이그레이션 SQL을 직접 편집하지 않는다.
- 스키마를 바꿨다면 `npx drizzle-kit generate`를 실행한다.

위아래를 하이픈 세 개(---)로 감싼 부분이 프런트 매터(frontmatter)다. 마크다운 본문 앞에 붙이는 메타데이터 영역이다. paths에는 glob 패턴을 쓴다. **는 하위 폴더 전체, *.ts는 확장자 필터이고, "src/**/*.{ts,tsx}"처럼 중괄호로 여러 확장자를 묶을 수도 있다(memory)

paths가 있는 규칙은 Claude가 패턴에 맞는 파일을 읽을 때 컨텍스트에 들어온다. 문서의 표현으로는 “도구를 쓸 때마다가 아니라 패턴에 맞는 파일을 읽을 때” 동작한다. 강의는 규칙 파일에 해적 말투 지시를 넣고 확인한다. “안녕”에는 평범하게 답하고, “각 테이블에 어떤 컬럼이 있어?”라고 물어 schema.ts를 읽게 하자 해적 말투로 바뀐다

paths를 빼면 이 규칙은 .claude/CLAUDE.md와 같은 우선순위로 세션 시작 때 로드된다. 파일은 나뉘어 보기 좋지만 컨텍스트 비용은 큰 CLAUDE.md 하나와 같다. @파일경로 가져오기도 마찬가지로 실행 시점에 모두 로드된다

한 가지 더 알아 둘 점이 있다. 경로 규칙은 대화를 압축하면 요약 과정에서 빠지고, 맞는 파일을 다시 읽어야 돌아온다(context-window). 압축 직후 규칙을 어긴 것처럼 보이면 이 경우를 먼저 의심한다

지침이 언제 컨텍스트에 들어오는지 한 표로 비교하면 다음과 같다

위치	들어오는 시점	적합한 내용
`CLAUDE.md`	세션 시작	프로젝트 개요, 모든 작업에 적용할 원칙
`.claude/rules/*.md` (paths 없음)	세션 시작	주제별로 나눠 관리하고 싶은 전역 원칙
`.claude/rules/*.md` (paths 있음)	맞는 파일을 읽을 때	특정 디렉터리·확장자에만 필요한 규칙
스킬 `SKILL.md`	시작 때는 이름·설명만, 본문은 호출 시	긴 절차·모범 사례 모음 (2편에서 다룬다)
자동 메모리 `MEMORY.md`	세션 시작 (앞부분만)	이 사용자의 작업 선호

표의 핵심은 “항상 필요한가”다. 항상 필요하지 않은 지시를 시작 시점에 싣고 있다면 옮길 곳이 있다

팀 규칙과 개인 선호는 파일을 나눠 둔다

CLAUDE.md와 settings.json은 저장소에 커밋해 팀이 공유하는 파일이다. 이름에 local이 붙은 CLAUDE.local.md와 .claude/settings.local.json은 이 컴퓨터에서 일하는 개인의 선호를 담는다. 내가 간결한 답변을 좋아한다고 팀 전체가 같은 설정을 써야 하는 것은 아니다

파일	공유 범위	로드 방식	Git
`CLAUDE.md`	팀	세션 시작	커밋
`CLAUDE.local.md`	나	`CLAUDE.md` 뒤에 이어서 로드	직접 `.gitignore`에 추가
`.claude/settings.json`	팀	설정 병합	커밋
`.claude/settings.local.json`	나	설정 병합, 프로젝트 설정보다 우선	Claude Code가 처음 쓸 때 전역 git excludes에 추가

표에서 주의할 칸은 Git 열이다. CLAUDE.local.md는 자동으로 제외되지 않는다. 문서는 “.gitignore에 추가하라”고 적는다(memory). CLAUDE_CODE_NEW_INIT=1로 초기화하면서 개인 파일 옵션을 고른 경우만 예외다. settings.local.json은 Claude Code가 그 파일을 처음 쓸 때 전역 git excludes에 등록한다. 손으로 만든 파일이라면 직접 제외해야 한다(settings). CLAUDE.local.md는 만든 worktree 안에만 존재한다는 점도 4편의 병렬 작업에서 걸린다

마크다운 지침과 JSON 설정은 합쳐지는 방식이 다르다. CLAUDE.md와 CLAUDE.local.md는 둘 다 컨텍스트에 들어간다. 설정 파일은 같은 키가 겹치면 우선순위가 이긴다. 순서는 관리형 설정, 명령줄 인수, settings.local.json, settings.json, 사용자 설정(~/.claude/settings.json) 순이다. 예외로 permissions.allow 같은 목록 키는 하나를 고르지 않고 여러 파일의 목록을 합친다(settings). 팀 설정에서 허용한 명령에 개인 설정의 허용 명령이 더해지는 구조다

강의에서 출력 스타일을 선택하자 outputStyle이 settings.json이 아니라 settings.local.json에 저장된 것도 이 구분 때문이다. 말투는 개인 선호로 취급된다. 출력 스타일은 3편에서 다룬다

자동 메모리는 작업 선호를 기억하지만 강제하지 않는다

CLAUDE.md에 적을 만큼 프로젝트 규칙은 아니지만 매번 말하기 귀찮은 선호도 있다. 강의에서는 “파일을 Bash로 편집하지 말고 파일 편집 전용 도구를 쓰길 원한다는 것을 메모리에 저장해 줘”라고 요청한다. 이유는 3편의 되감기에서 드러난다. Bash로 바꾼 파일은 되감기로 복원되지 않는다

자동 메모리는 기본으로 켜져 있다. 저장 위치는 ~/.claude/projects/<project>/memory/이고, git 저장소 기준으로 경로가 정해져 worktree와 하위 디렉터리가 같은 폴더를 공유한다. MEMORY.md는 주제별 파일을 가리키는 색인이다. 세션 시작 때는 앞 200줄 또는 25KB 중 먼저 닿는 쪽까지만 읽는다(memory). /memory로 로드된 메모리 파일을 확인하고, 자동 메모리를 끄고 켜고, 폴더를 열 수 있다

강의에서는 Ctrl+O로 상세 출력을 펼쳐 메모리가 저장된 경로를 확인했다. 프로젝트 소스 파일이 아니라 사용자 홈 아래에 기록된다는 점이 CLAUDE.md와 다르다

메모리를 저장했다고 행동이 보장되지는 않는다. 문서는 메모리와 CLAUDE.md를 “강제되는 설정이 아니라 컨텍스트”로 취급한다고 적고, Claude의 판단과 무관하게 막아야 하는 동작은 PreToolUse 훅을 쓰라고 안내한다. 반드시 지켜야 하는 규칙과 지켜지면 좋은 선호를 나누는 기준이 여기서 나온다

지켜지면 좋다      → CLAUDE.md, rules, 메모리  (모델이 읽고 따른다)
반드시 막아야 한다 → 권한 deny 규칙, 훅        (Claude Code가 실행 전에 검사한다)

권한 규칙은 2편, 훅은 5편에서 다룬다

대화가 길어지면 /compact로 줄이고 주제가 바뀌면 /clear로 끊는다

작업 맥락은 이어 가고 싶은데 기록이 길어졌다면 /compact를 쓴다. 지금까지의 대화를 요약으로 바꿔 컨텍스트를 줄인다. 무엇을 남길지 지시할 수도 있다

/compact 예약 취소 API 변경 내용과 남은 버그 목록 위주로 요약해 줘

한도에 가까워지면 Claude Code가 자동으로 압축한다. 오래된 도구 출력부터 비우고 그다음 대화를 요약한다. 100만 토큰 창을 쓰는 모델은 기본적으로 약 96만 7천 토큰에서 자동 압축이 시작된다. 시점은 /autocompact로 바꿀 수 있다(context-window, model-config). 압축 뒤에는 프로젝트 루트 CLAUDE.md, paths 없는 규칙, 자동 메모리가 디스크에서 다시 주입되고, 경로 규칙은 앞서 말한 대로 빠진다

작업 주제가 완전히 바뀌면 /clear로 새 대화를 여는 편이 낫다. 요약에도 이전 작업의 흔적이 남기 때문이다. 대화 일부만 골라 요약하는 방법도 있다. 되감기 메뉴의 “여기부터 요약”과 “여기까지 요약”인데, 3편에서 되감기와 함께 설명한다

상황	선택
같은 기능을 계속 작업하는데 기록이 길다	`/compact` (필요하면 요약 지시 추가)
다른 기능·다른 버그로 넘어간다	`/clear`
앞부분의 탐색 기록만 줄이고 싶다	되감기 메뉴의 부분 요약

CLAUDE.md는 모든 대화가 매번 내는 고정 비용이므로, 항상 필요한 원칙만 남기고 나머지는 필요한 순간에 들어오도록 배치한다

출처

nomadcoders

Claude Code의 CLAUDE.md는 짧게 두고 나머지는 필요할 때 불러온다