CLAUDE.md 처음 쓰기 — 넣을 것 · 뺄 것 · 나누는 기준

조회 1발행 2026.10.22글쓴이 KAITABASE 자체 제작

항목	내용
대상	Claude Code를 쓰기 시작한 개발자 · 팀 리더 (비개발자도 개념은 그대로 적용)
걸리는 시간	약 30분
준비물	Claude Code(로그인된 상태), Git으로 관리하는 프로젝트 폴더 1개
원문	Claude Code 공식 문서 · How Claude remembers your project
직접 실행	일부 실행 — 로컬 Claude Code 버전 2.1.307 확인. /init · /context · /memory 같은 세션 안 명령은 계정 로그인이 필요해 공식 문서 기준(직접 실행 안 함)
라이선스	문서 출처 Anthropic (Claude Code 자체는 Anthropic 상용 약관 적용)
확인일	2026-10-22

KAITABASE가 공식 문서와 원문을 직접 읽고 새로 쓴 가이드입니다.

이 가이드로 할 수 있는 것

Claude Code는 세션마다 빈 상태로 시작합니다. 공식 문서는 세션을 넘어 지식을 잇는 방법을 둘로 나눕니다. 내가 써 두는 CLAUDE.md, 그리고 Claude가 스스로 적는 자동 메모리(auto memory) 입니다. 이 가이드는 그중 CLAUDE.md를 다룹니다.

핵심은 하나입니다. 공식 문서는 CLAUDE.md를 "강제되는 설정이 아니라 맥락"이라고 설명합니다. 그래서 짧고 구체적으로 쓸수록 잘 지켜지고, 반드시 지켜야 하는 규칙은 CLAUDE.md가 아니라 훅(hook)이나 권한 설정으로 막아야 합니다.

빠른 시작

프로젝트 폴더에서 Claude Code를 열고 다음을 입력합니다.

text

/init

공식 문서 기준(직접 실행 안 함): Claude가 코드베이스를 살펴 빌드 명령 · 테스트 방법 · 규칙을 담은 CLAUDE.md 초안을 만듭니다. 이미 파일이 있으면 덮어쓰지 않고 개선안을 제안합니다. 만든 뒤에는 다음으로 실제로 읽혔는지 확인합니다.

text

/context

결과의 Memory files 목록에 CLAUDE.md 가 보이면 성공입니다.

STEP 1. 어디에 둘지 정하기

목표: 파일 위치에 따라 누구에게 적용되는지 이해합니다. · 예상 시간: 3분

범위	위치	쓰임
조직 정책	Windows `C:\Program Files\ClaudeCode\CLAUDE.md` · macOS `/Library/Application Support/ClaudeCode/CLAUDE.md` · Linux `/etc/claude-code/CLAUDE.md`	IT가 배포하는 회사 공통 규칙
내 전체 프로젝트	`~/.claude/CLAUDE.md`	나만의 습관 · 도구 선호
이 프로젝트(팀 공유)	`./CLAUDE.md` 또는 `./.claude/CLAUDE.md`	빌드 · 테스트 명령, 팀 규칙
이 프로젝트(나만)	`./CLAUDE.local.md`	내 테스트 주소 등. `.gitignore` 에 추가

공식 문서에 따르면 이 파일들은 서로 덮어쓰지 않고 모두 이어 붙여 읽힙니다. 상위 폴더 것이 먼저, 작업 폴더에 가까운 것이 나중에 들어갑니다. 하위 폴더의 CLAUDE.md는 시작할 때가 아니라 Claude가 그 폴더 파일을 읽거나 고칠 때 불러옵니다.

확인 팀이 같이 쓸 내용은 ./CLAUDE.md, 나만 쓸 내용은 CLAUDE.local.md 로 나눴는지 봅니다.

STEP 2. /init으로 초안 만들기

목표: 빈 파일에서 시작하지 않고 초안을 받습니다. · 예상 시간: 5분 · 공식 문서 기준(직접 실행 안 함)

프로젝트 루트에서 claude 를 실행합니다.
/init 을 입력합니다.
만들어진 CLAUDE.md 를 열어 읽습니다.

공식 문서는 /init 이 .cursor/rules/, .cursorrules, .github/copilot-instructions.md 같은 다른 도구의 규칙 파일도 읽어 반영한다고 설명합니다. 질문을 주고받으며 스킬 · 훅까지 함께 만드는 대화형 방식을 원하면, 실행 전에 환경 변수 CLAUDE_CODE_NEW_INIT=1 을 설정합니다.

되돌리기 Git으로 관리 중이면 git checkout -- CLAUDE.md(새 파일이면 삭제)로 되돌립니다. 커밋 전에 git diff 로 내용을 먼저 봅니다.

STEP 3. 넣을 것 · 뺄 것 고르기

목표: 매 세션 읽혀도 아깝지 않은 줄만 남깁니다. · 예상 시간: 10분

공식 모범 사례 문서는 줄마다 "이 줄을 지우면 Claude가 실수하는가?"를 물어 보고, 아니면 지우라고 권합니다.

넣을 것	뺄 것
Claude가 추측할 수 없는 실행 명령	코드를 읽으면 알 수 있는 내용
기본값과 다른 코드 스타일 규칙	누구나 아는 언어 관례
테스트 방법 · 쓰는 테스트 도구	자세한 API 문서(링크로 대신)
브랜치 이름 · PR 규칙	자주 바뀌는 정보
이 프로젝트만의 설계 결정	긴 설명이나 튜토리얼
필요한 환경 변수 같은 개발 환경 특이점	파일 하나하나 설명
겉으로 안 보이는 함정	"깔끔하게 짜라" 같은 당연한 말

규칙은 확인할 수 있게 구체적으로 씁니다. 공식 문서의 예처럼 "코드를 잘 정리해" 대신 "API 핸들러는 src/api/handlers/ 에 둔다", "테스트해" 대신 "커밋 전 npm test 를 실행한다"로 씁니다.

확인 파일 하나가 200줄 안인지 봅니다. 공식 문서는 200줄을 넘으면 맥락을 더 쓰고 지시를 덜 지킨다고 설명합니다. 4MiB를 넘는 파일은 아예 건너뜁니다.

막히면 한 규칙만 자꾸 무시되면 그 줄 하나에만 IMPORTANT 같은 강조를 붙입니다. 여러 줄에 붙이면 아무것도 눈에 띄지 않습니다(공식 모범 사례).

STEP 4. 긴 내용은 rules · 스킬로 나누기

목표: 일부 파일에만 필요한 규칙은 필요할 때만 읽히게 합니다. · 예상 시간: 7분

특정 경로에만 해당하는 규칙은 .claude/rules/ 에 파일로 두고 paths 를 붙입니다. 그 경로의 파일을 Claude가 읽거나 고칠 때만 불러옵니다.

markdown

12345678---
paths:
  - "src/api/**/*.ts"
---

## API 규칙
- 모든 엔드포인트에 입력값 검증을 넣는다
- 오류 응답은 표준 형식을 쓴다

여러 단계짜리 절차(배포, PR 리뷰 순서 등)는 스킬로 옮깁니다. 스킬 본문은 불렀을 때만 읽히므로 평소 맥락을 차지하지 않습니다. @경로 가져오기(import)는 정리에는 좋지만, 가져온 파일도 시작할 때 함께 읽혀 맥락을 줄여 주지는 않습니다.

확인 paths 가 없는 rules 파일은 시작할 때 항상 읽힙니다. 줄이려는 목적이라면 paths 를 붙였는지 봅니다.

STEP 5. 읽혔는지 · 지켜지는지 점검하기

목표: 파일을 만들었는데 효과가 없을 때 원인을 좁힙니다. · 예상 시간: 5분 · 공식 문서 기준(직접 실행 안 함)

/context 의 Memory files 에 파일이 있는지 봅니다. 없으면 Claude는 그 파일을 못 본 것입니다.
/memory 로 어떤 CLAUDE.md · 자동 메모리 파일이 있는지 열어 봅니다.
/doctor prompt-audit 으로 낡은 지시, 없는 파일 참조, 서로 모순되는 지시를 찾습니다(Claude Code v2.1.283 이상). 보고서만 만들고 내가 승인하기 전에는 파일을 고치지 않습니다.
세션 중에 CLAUDE.md를 고쳤다면 바로 반영되지 않습니다. 공식 문서에 따르면 다음 /clear, /compact, 재시작 때 새 내용이 읽힙니다.

powershell

claude --version

실제 출력(이 가이드 작성 PC): 2.1.307 (Claude Code) — 위 기능이 요구하는 버전보다 높습니다.

막히면 저장소에 AGENTS.md 만 있고 CLAUDE.md 가 없으면 Claude Code가 AGENTS.md 를 대신 읽습니다(v2.1.277 이상). 둘 다 있으면 기본값으로는 CLAUDE.md 만 읽으므로, 공용 파일을 쓰려면 CLAUDE.md 첫 줄에 @AGENTS.md 를 넣습니다. Windows에서는 심볼릭 링크보다 이 가져오기 방식을 쓰라고 공식 문서가 권합니다.

잘못 쓰는 예 · 바르게 쓰는 예

잘못 쓰는 예	바르게 쓰는 예
"코드를 깔끔하게 짜 주세요"	"들여쓰기는 2칸, 세미콜론 없음 (prettier 설정 따름)"
폴더 구조를 파일별로 길게 설명	Claude가 못 찾는 함정만 한 줄씩 ("`legacy/` 는 수정 금지, 생성 코드")
"절대 main에 push 하지 마" 를 CLAUDE.md에만 적음	반드시 막아야 하는 것은 권한 설정 `permissions.deny` 나 훅으로 막음
배포 절차 30줄을 CLAUDE.md에 넣음	`deploy` 스킬로 옮기고 CLAUDE.md에는 "배포는 /deploy" 한 줄
개인 테스트 주소를 팀 CLAUDE.md에 커밋	`CLAUDE.local.md` 에 쓰고 `.gitignore` 에 추가

바로 쓰는 프롬프트 · 템플릿

CLAUDE.md 뼈대(공식 예시 구조를 따라 우리 말로 바꿈):

markdown

1234567891011121314151617## 실행 명령
- 개발 서버: npm run dev
- 테스트(파일 하나): npm test -- <파일경로>
- 타입 검사: npm run typecheck

## 코드 스타일
- ES 모듈(import/export)을 쓰고 require는 쓰지 않는다

## 작업 방식
- 여러 파일을 고친 뒤에는 타입 검사를 돌린다
- 전체 테스트 대신 바뀐 파일의 테스트만 먼저 돌린다

## 함정
- `src/generated/` 는 자동 생성 코드이므로 직접 고치지 않는다

## 압축할 때
- 압축(compact) 때는 바뀐 파일 목록과 테스트 명령을 꼭 남긴다

다듬기를 맡길 때 쓰는 요청:

text

CLAUDE.md를 읽고, 줄마다 "이 줄이 없으면 당신이 실수하는가?"를 기준으로 판단해 주세요.
지워도 되는 줄, 스킬로 옮길 절차, .claude/rules로 옮길 경로별 규칙을 표로 나눠 제안만 해 주세요.
파일은 아직 고치지 마세요.

주의할 점

강제력 없음: CLAUDE.md는 시스템 프롬프트가 아니라 그 뒤의 사용자 메시지로 전달됩니다. 꼭 지켜야 할 일은 훅 · 권한 규칙 · 관리 설정으로 처리합니다.
외부 가져오기: 프로젝트 CLAUDE.md가 작업 폴더 밖 파일을 @ 로 가져오면 처음 한 번 승인 창이 뜹니다. 남이 커밋한 저장소라면 무엇을 가져오는지 보고 승인합니다.
비밀 정보: CLAUDE.md는 보통 Git에 올라갑니다. API 키 · 비밀번호를 적지 않습니다.
요금: CLAUDE.md는 매 요청 맥락에 들어가므로 길수록 사용량이 늘어납니다. 공식 비용 문서도 200줄 안으로 유지하라고 권합니다.
라이선스: 이 가이드는 Anthropic 공식 문서를 우리 말로 다시 정리한 것입니다. Claude Code 자체는 Anthropic 상용 약관을 따릅니다.

공식 자료

How Claude remembers your project (CLAUDE.md · 자동 메모리) — https://code.claude.com/docs/en/memory
Best practices · Write an effective CLAUDE.md — https://code.claude.com/docs/en/best-practices
Skills (절차를 스킬로 옮기기) — https://code.claude.com/docs/en/skills
Commands 목록(/init, /memory, /context, /doctor) — https://code.claude.com/docs/en/commands