클로드 코드 CLAUDE.md 사용법: 프로젝트 지침과 메모리를 안전하게 고정하는 팁
TL;DR
클로드 코드 CLAUDE.md 사용법의 핵심은 매번 반복 설명하는 프로젝트 규칙을 짧고 검증 가능한 지침으로 남기는 것입니다.
Anthropic 공식 문서는 Claude Code가 세션마다 새 컨텍스트로 시작하며, 지식을 이어 가는 장치로 사용자가 작성하는 CLAUDE.md 파일과 Claude가 자동으로 쌓는 auto memory를 구분합니다.
초보자는 빌드 명령, 테스트 명령, 코드 스타일, 금지 작업처럼 매 세션 필요한 기준만 CLAUDE.md에 넣고, 길거나 특정 작업에만 필요한 절차는 rules, skills, hooks로 나누는 편이 안전합니다.
핵심 3줄 요약
- 핵심 1
CLAUDE.md는 Claude Code가 매 세션 읽는 프로젝트 지침 파일입니다. - 핵심 2
auto memory는 Claude가 사용자의 수정과 선호에서 배운 내용을 저장하는 보조 기억입니다. - 핵심 3
지침이 길고 모호하면 오히려 덜 지켜질 수 있으므로, 200줄 이하의 짧고 검증 가능한 규칙으로 관리하는 것이 좋습니다.
이 글에서 다룰 내용
- 클로드 코드 CLAUDE.md가 무엇인지
- CLAUDE.md와 auto memory의 차이
- 누가 쓰면 좋은지
- 언제 쓰면 좋은지
- 프로젝트 CLAUDE.md를 만드는 순서
- .claude/rules로 나누는 기준
- auto memory를 점검하는 방법
- 바로 쓰는 지침 예시
- 주의할 점과 FAQ
- 공식 출처
클로드 코드 CLAUDE.md란 무엇인가요?
CLAUDE.md는 Claude Code에게 프로젝트별 지침을 전달하는 Markdown 파일입니다. Anthropic 공식 문서는 CLAUDE.md 파일을 "Claude에게 지속적인 맥락을 주기 위해 사용자가 작성하는 지침"으로 설명합니다.
쉽게 말하면 Claude Code용 작업 규칙 문서입니다. 예를 들어 "테스트는 npm test로 실행한다", "API 코드는 src/api 아래에 둔다", "배포 명령은 사용자 승인 전 실행하지 않는다" 같은 규칙을 매번 채팅에 다시 쓰지 않고 파일로 남기는 방식입니다.
한 문장 정의: 클로드 코드 CLAUDE.md는 Claude Code가 프로젝트를 이해하고 같은 기준으로 작업하도록 매 세션 읽는 프로젝트 지침 파일입니다.
중요한 점은 CLAUDE.md가 강제 보안 장치가 아니라는 점입니다. 공식 문서는 CLAUDE.md와 auto memory가 모두 컨텍스트로 취급되며, 특정 행동을 반드시 막으려면 PreToolUse hook 같은 별도 장치를 써야 한다고 설명합니다.
한 줄 정리: CLAUDE.md는 Claude Code의 "작업 기준"을 알려 주는 문서이지, 권한을 물리적으로 막는 방화벽은 아닙니다.
CLAUDE.md와 auto memory는 어떻게 다른가요?
Anthropic 문서는 Claude Code의 기억 장치를 두 가지로 나눕니다.
첫째, CLAUDE.md는 사용자가 직접 작성합니다. 프로젝트 구조, 빌드 명령, 테스트 명령, 코드 스타일, PR 규칙, 금지 작업처럼 Claude가 매번 알아야 할 기준을 담습니다.
둘째, auto memory는 Claude가 사용자의 수정, 반복되는 선호, 디버깅 패턴에서 스스로 기록하는 메모리입니다. 공식 문서 기준으로 auto memory는 저장소 단위로 공유될 수 있고, 세션 시작 때 일부가 로드됩니다.
비유하면 CLAUDE.md는 팀이 합의한 운영 매뉴얼이고, auto memory는 Claude가 작업하면서 적어 둔 작업 노트입니다. 둘 다 유용하지만 역할이 다릅니다.
핵심 인사이트: 팀이 반드시 지켜야 하는 기준은 CLAUDE.md에 쓰고, Claude가 반복 실수에서 배운 보조 정보는 auto memory로 관리하는 편이 깔끔합니다.
누가 쓰면 좋은가요?
첫째, Claude Code를 팀 프로젝트에 쓰는 사람에게 필요합니다. 개발자마다 "테스트는 어디까지 돌릴지", "커밋 메시지는 어떻게 쓸지", "어떤 파일은 건드리면 안 되는지" 기준이 다르면 AI 작업 결과도 흔들립니다. CLAUDE.md는 이 기준을 한곳에 모으는 역할을 합니다.
둘째, 비개발자 운영자에게도 유용합니다. 감자나라ai님처럼 블로그 발행, 데이터 정리, 자동화 스크립트 수정처럼 반복 workflow를 다룬다면 "원본 파일을 덮어쓰기 전 백업", "dry-run 먼저", "발행 후 공개 URL 확인" 같은 규칙을 지침으로 남길 수 있습니다.
셋째, 여러 에이전트 도구를 함께 쓰는 사람에게 좋습니다. 공식 문서는 저장소에 이미 AGENTS.md가 있다면 CLAUDE.md에서 AGENTS.md를 import해 중복 없이 같은 지침을 읽게 할 수 있다고 안내합니다.
넷째, Claude가 같은 실수를 반복하는 프로젝트에 특히 필요합니다. 공식 문서는 Claude가 같은 실수를 두 번째로 하거나, 사용자가 지난 세션과 같은 설명을 다시 입력할 때 CLAUDE.md에 추가하라고 권합니다.
언제 쓰면 좋은가요?
CLAUDE.md는 "매 세션 반드시 필요한 기준"을 저장할 때 좋습니다.
예를 들어 다음 기준은 CLAUDE.md에 적합합니다.
- 빌드와 테스트 명령
- 코드 스타일과 네이밍 규칙
- 프로젝트 구조와 주요 폴더 역할
- 배포, 삭제, 결제, 개인정보 관련 금지 행동
- 리뷰 전에 반드시 확인할 체크리스트
반대로 다음 내용은 CLAUDE.md에 넣지 않는 편이 좋습니다.
- Claude가 코드를 읽으면 알 수 있는 파일별 설명
- 자주 바뀌는 긴 API 문서
- 특정 작업에만 필요한 긴 절차
- 튜토리얼처럼 장황한 배경 설명
- "깨끗하게 작성하라"처럼 검증하기 어려운 추상 문장
실전 팁: "이 줄을 지우면 Claude가 실제로 실수할 가능성이 커지는가?"라고 물어보고, 아니라면 CLAUDE.md에서 빼는 편이 좋습니다.
따라 하는 순서 1: 먼저 반복 실수를 적습니다
처음부터 완벽한 CLAUDE.md를 만들려고 하면 파일이 길어집니다. 먼저 Claude가 자주 놓치는 것만 적으세요.
좋은 시작 질문은 다음과 같습니다.
- Claude가 지난 작업에서 같은 실수를 반복했는가?
- 내가 매번 다시 말하는 실행 명령이 있는가?
- 팀원이 새로 오면 반드시 알아야 할 구조가 있는가?
- 승인 없이 실행하면 위험한 명령이 있는가?
- 테스트나 검증 기준이 매번 누락되는가?
이 질문에 답한 뒤 5~10개 규칙만 먼저 씁니다. 짧게 시작해야 나중에 유지하기 쉽습니다.
따라 하는 순서 2: 프로젝트 루트에 CLAUDE.md를 만듭니다
공식 문서 기준으로 프로젝트 지침은 프로젝트 루트의 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 둘 수 있습니다. 팀과 공유할 기준이면 버전 관리에 포함하고, 개인만 볼 기준이면 CLAUDE.local.md를 쓰고 .gitignore에 넣는 방식이 적합합니다.
예시는 다음과 같습니다.
프로젝트 개요
– 이 저장소는 WordPress 발행 자동화 도구입니다.
– 일반 글은 사용자가 명시적으로 요청하기 전에는 발행하지 않습니다.
실행 명령
– 발행 전에는 반드시 python scripts/wp_post_from_md.py drafts/파일명.md –dry-run을 먼저 실행합니다.
– 발행 뒤에는 REST 응답과 공개 URL을 모두 확인합니다.
금지 사항
– .env 값은 출력하지 않습니다.
– 사용자 파일이나 unrelated 변경을 되돌리지 않습니다.
– 네트워크 오류가 나면 원고를 다시 쓰지 말고 같은 명령 재시도 가능성을 보고합니다.
검수 기준
– 제목, TL;DR, FAQ, 출처 링크, raw Markdown 잔여 기호를 확인합니다.
한 줄 정리: 좋은 CLAUDE.md는 "Claude가 바로 실행하고 확인할 수 있는 기준"으로 구성됩니다.
따라 하는 순서 3: /init으로 초안을 만들고 사람이 줄입니다
Anthropic 문서는 /init 명령으로 프로젝트 CLAUDE.md 초안을 만들 수 있다고 안내합니다. /init은 코드베이스를 분석해 빌드 명령, 테스트 지침, 프로젝트 관례를 찾아 초안을 제안합니다.
하지만 /init 결과를 그대로 믿고 끝내면 안 됩니다. 사람이 확인해야 할 항목은 다음과 같습니다.
- 실제 빌드 명령이 맞는가?
- 오래된 테스트 명령이 들어가지 않았는가?
- 보안상 금지할 작업이 빠지지 않았는가?
- Claude가 추측한 폴더 설명이 실제와 맞는가?
- 불필요한 장문 설명이 들어가지 않았는가?
공식 best practices 문서는 CLAUDE.md를 짧고 사람이 읽기 쉽게 유지하라고 안내합니다. 특히 각 줄을 보며 "이 줄을 지우면 Claude가 실수할까?"라고 점검하라고 설명합니다.
따라 하는 순서 4: 200줄 이하로 유지합니다
공식 memory 문서는 CLAUDE.md 파일당 200줄 이하를 목표로 하라고 권합니다. 긴 지침은 컨텍스트를 많이 쓰고, 실제 작업 요청의 중요도를 흐릴 수 있습니다.
줄이는 기준은 간단합니다.
- 명령은 실제 실행 가능한 형태로 씁니다.
- 추상적인 원칙보다 구체적인 금지 행동을 씁니다.
- 자주 바뀌는 정보는 링크나 별도 문서로 둡니다.
- 특정 폴더에만 필요한 규칙은 .claude/rules로 분리합니다.
- 긴 업무 절차는 skill로 분리합니다.
주의: CLAUDE.md가 길어질수록 더 안전해지는 것이 아닙니다. 너무 긴 지침은 오히려 중요한 규칙을 묻히게 만들 수 있습니다.
따라 하는 순서 5: .claude/rules로 범위를 나눕니다
큰 프로젝트라면 모든 규칙을 CLAUDE.md 하나에 넣지 않는 편이 좋습니다. Anthropic 문서는 .claude/rules/ 디렉터리에 여러 Markdown 규칙을 두고, 필요한 경우 paths frontmatter로 특정 파일 경로에만 적용할 수 있다고 설명합니다.
예를 들어 frontend 규칙은 프론트엔드 파일에만, API 규칙은 API 파일에만 적용할 수 있습니다.
예시
paths:
– "src/api/*/.ts"
API 규칙
– 모든 API endpoint는 입력 검증을 포함합니다.
– 오류 응답은 표준 error format을 사용합니다.
– 변경 후 관련 API 테스트를 실행합니다.
이 방식은 monorepo나 큰 팀에 특히 좋습니다. Claude가 모든 세션에서 모든 규칙을 읽지 않아도 되고, 해당 파일을 다룰 때 필요한 지침을 더 선명하게 볼 수 있습니다.
따라 하는 순서 6: AGENTS.md가 있으면 import합니다
이미 AGENTS.md를 쓰는 저장소라면 지침을 두 번 복사하지 않는 편이 좋습니다. 공식 문서는 Claude Code가 CLAUDE.md를 읽고 AGENTS.md를 직접 기준으로 삼지는 않으므로, CLAUDE.md에서 AGENTS.md를 import하는 방식을 안내합니다.
예시는 간단합니다.
@AGENTS.md
## Claude Code
– 결제 관련 파일은 plan mode에서 먼저 변경 범위를 설명합니다.
– 배포 명령은 사용자 승인 전 실행하지 않습니다.
Windows에서는 symlink보다 @AGENTS.md import가 더 실용적일 수 있습니다. 공식 문서도 Windows에서 symlink는 관리자 권한이나 Developer Mode가 필요할 수 있다고 설명합니다.
실전 팁: Codex와 Claude Code를 함께 쓰는 저장소라면 AGENTS.md를 공통 원칙으로 두고, CLAUDE.md에는 Claude Code 전용 보충 규칙만 짧게 두는 방식이 관리하기 쉽습니다.
따라 하는 순서 7: auto memory를 믿기 전에 점검합니다
auto memory는 편하지만, 사람이 쓴 운영 매뉴얼을 대체하지 않습니다. Claude가 자동으로 기록한 메모리는 실제 프로젝트 기준과 다르거나, 오래된 상황을 반영할 수 있습니다.
공식 문서는 /memory 명령으로 메모리를 보고 편집할 수 있다고 안내합니다. Claude가 이상한 기준을 계속 적용한다면 먼저 auto memory에 무엇이 저장됐는지 확인해야 합니다.
점검할 항목은 다음과 같습니다.
- 오래된 빌드 명령이 남아 있지 않은가
- 개인 취향이 팀 규칙처럼 저장되지 않았는가
- 임시 디버깅 방법이 영구 지침처럼 남지 않았는가
- 보안상 남기면 안 되는 힌트가 저장되지 않았는가
- CLAUDE.md와 모순되는 내용이 있지 않은가
핵심 인사이트: auto memory는 편의 기능입니다. 팀 기준, 보안 기준, 발행 기준처럼 중요한 내용은 사람이 관리하는 CLAUDE.md에 남기는 편이 안전합니다.
바로 쓰는 CLAUDE.md 예시
예시 1: 작은 웹 프로젝트
프로젝트 기준
– 이 프로젝트는 React 기반 관리자 화면입니다.
– UI 변경 후에는 npm run lint와 npm test를 실행합니다.
– 버튼 문구는 짧게 쓰고, 새 라이브러리는 사용자 승인 전 추가하지 않습니다.
검수 기준
– 모바일 390px 폭에서 텍스트가 겹치지 않아야 합니다.
– 폼 저장 흐름은 성공, 실패, 로딩 상태를 모두 확인합니다.
예시 2: WordPress 발행 자동화
발행 규칙
– 항상 dry-run을 먼저 실행합니다.
– dry-run에서 title, slug, status, category, content_length를 확인합니다.
– 발행 후 REST 응답의 id, status, link를 확인합니다.
– 공개 페이지에서 TL;DR, FAQ, 출처 링크, raw Markdown 잔여 기호를 확인합니다.
금지 사항
– .env 값은 출력하지 않습니다.
– WordPress 오류가 나면 새 글을 만들지 말고 같은 원고를 보존합니다.
예시 3: 데이터 분석 프로젝트
분석 기준
– 원본 데이터는 수정하지 않습니다.
– 파생 파일은 outputs/ 아래에 저장합니다.
– 결측치 처리와 필터 기준은 결과 요약에 반드시 적습니다.
– 차트는 제목, 축 단위, 표본 수를 포함합니다.
주의 사항
– 개인정보가 포함된 행은 샘플 출력하지 않습니다.
– 추정과 확인된 사실을 구분합니다.
좋은 지침과 나쁜 지침의 차이
나쁜 지침:
- 코드를 잘 작성하세요.
- 테스트를 적절히 하세요.
- 보안에 주의하세요.
좋은 지침:
- 변경 후 npm test를 실행하고 실패하면 원인을 요약합니다.
- 결제, 삭제, 배포 명령은 실행 전 사용자 승인을 받습니다.
- API handler는 src/api/handlers/에 추가합니다.
- 고객 이메일과 토큰 값은 응답에 출력하지 않습니다.
나쁜 지침은 읽기에는 좋아 보이지만 검증하기 어렵습니다. 좋은 지침은 Claude가 실제 행동으로 옮길 수 있고, 사용자가 결과를 확인할 수 있습니다.
실전 팁
실전 팁
CLAUDE.md는 한 번 만들고 끝내는 문서가 아닙니다. Claude가 같은 실수를 반복할 때마다 짧게 보강하고, 오래된 규칙은 지워야 합니다.
첫째, 팀 공유 규칙과 개인 규칙을 분리하세요. 팀 규칙은 CLAUDE.md, 개인 선호는 CLAUDE.local.md나 사용자 레벨 규칙에 두는 편이 깔끔합니다.
둘째, 위험한 행동은 CLAUDE.md만 믿지 마세요. 배포, 삭제, 결제, 외부 전송처럼 실제 피해가 생길 수 있는 행동은 permissions, hooks, sandbox 같은 더 강한 장치와 함께 관리해야 합니다.
셋째, AGENTS.md와 CLAUDE.md를 중복 작성하지 마세요. 같은 내용을 두 파일에 따로 쓰면 한쪽만 업데이트되어 충돌할 가능성이 큽니다.
넷째, "항상"이라는 표현을 쓸 때는 조심하세요. 항상 전체 테스트를 돌리라고 하면 작은 문구 수정에도 시간이 낭비될 수 있습니다. "코드 변경 후 관련 테스트를 우선 실행하고, 배포 전 전체 테스트를 실행한다"처럼 상황을 나누는 편이 좋습니다.
주의할 점
주의
CLAUDE.md는 권한 설정이 아닙니다. 공식 문서도 CLAUDE.md와 auto memory가 컨텍스트이지 강제 설정이 아니라고 설명합니다. 중요한 차단은 hooks나 managed settings 같은 별도 장치가 필요합니다.
첫째, 민감한 정보를 넣지 마세요. API 키, 비밀번호, 고객정보, 내부 가격표처럼 유출되면 안 되는 값은 CLAUDE.md에 적으면 안 됩니다. "어디에 있다" 정도의 운영 힌트도 신중해야 합니다.
둘째, 너무 긴 문서를 피하세요. Claude가 모든 내용을 읽더라도 긴 지침은 컨텍스트를 차지하고 실제 요청의 집중도를 낮출 수 있습니다.
셋째, auto memory를 방치하지 마세요. 오래된 디버깅 노트나 개인 선호가 남아 있으면 다음 세션에서 엉뚱한 결정을 유도할 수 있습니다.
넷째, 팀 저장소에서는 변경 리뷰가 필요합니다. CLAUDE.md는 AI 작업 방식에 직접 영향을 주므로 코드처럼 리뷰하고 관리해야 합니다.
자주 묻는 질문
Q1. CLAUDE.md만 있으면 Claude Code가 항상 지침을 지키나요?
아닙니다. 공식 문서 기준으로 CLAUDE.md는 컨텍스트로 로드되는 지침입니다. 더 잘 따르게 만들 수는 있지만 강제 설정은 아닙니다. 반드시 막아야 할 작업은 hooks나 권한 설정을 함께 써야 합니다.
Q2. CLAUDE.md에는 무엇을 넣어야 하나요?
빌드 명령, 테스트 명령, 코드 스타일, 프로젝트 구조, 금지 작업, 검수 기준처럼 매 세션 필요한 내용을 넣으면 됩니다. Claude가 코드를 읽으면 알 수 있는 장황한 파일 설명은 빼는 편이 좋습니다.
Q3. AGENTS.md가 이미 있으면 새로 다 써야 하나요?
아닙니다. 공식 문서는 CLAUDE.md에서 AGENTS.md를 import하는 방식을 안내합니다. 공통 지침은 AGENTS.md에 두고, Claude Code 전용 보충 규칙만 CLAUDE.md에 추가하면 중복을 줄일 수 있습니다.
Q4. CLAUDE.local.md는 언제 쓰나요?
개인만 필요한 프로젝트별 선호를 저장할 때 씁니다. 예를 들어 개인 sandbox URL, 선호 테스트 데이터, 로컬 환경 힌트처럼 팀에 공유하면 안 되거나 공유할 필요가 없는 내용에 적합합니다.
Q5. .claude/rules는 언제 필요한가요?
프로젝트가 커서 규칙을 파일 유형이나 폴더별로 나눠야 할 때 필요합니다. 예를 들어 API 규칙, 프론트엔드 규칙, 보안 규칙을 분리하면 Claude가 관련 파일을 다룰 때 더 정확한 지침을 볼 수 있습니다.
Q6. auto memory는 꺼야 하나요?
반드시 끌 필요는 없습니다. 다만 자동 저장된 내용이 현재 프로젝트 기준과 맞는지 /memory로 확인하고, 오래되거나 잘못된 항목은 정리해야 합니다. 중요한 팀 규칙은 auto memory가 아니라 CLAUDE.md에 쓰는 편이 좋습니다.
출처
마무리
클로드 코드 CLAUDE.md 사용법은 어렵게 시작할 필요가 없습니다. 먼저 Claude가 자주 틀리는 명령, 반복해서 설명하는 기준, 승인 없이 실행하면 안 되는 행동만 5~10개 적으세요.
그다음 /init으로 초안을 보강하고, 200줄 이하로 줄이고, 폴더별 규칙은 .claude/rules로 나누면 됩니다. 감자나라ai님이 자동화나 콘텐츠 운영처럼 반복 workflow를 다룬다면 CLAUDE.md는 "AI에게 매번 다시 말하던 운영 기준"을 문서화하는 가장 실용적인 출발점입니다.
