새 Claude Code 세션은 이전 대화를 유지하지 않습니다. 새 컨텍스트 창은 시스템 프롬프트로 시작하고, 이어서 CLAUDE.md 파일과 자동 메모리가 올라옵니다. CLAUDE.md는 빌드 명령, 규칙, 작업이 끝났는지를 아는 방법처럼 프로젝트 사실이 매번 따라오도록 추가하는 마크다운입니다.
Claude는 이 파일을 맥락으로 읽고, 적힌 지시를 따르려고 합니다. Claude가 어떻게 판단하든 막아야 하는 동작은 이 파일 밖에서 막으세요. permissions.deny 규칙을 추가하거나, Claude가 도구를 쓰기 전에 실행되어 그 호출을 거절할 수 있는 PreToolUse 훅을 넣으면 됩니다.
파일은 어디에 만들까요?
프로젝트의 가장 바깥 폴더에 CLAUDE.md를 만들거나, .claude/CLAUDE.md에 저장하면 됩니다. 팀원이 함께 사용할 규칙이라면 Git으로 관리해 공유하세요.
본인만 사용할 프로젝트 메모는 CLAUDE.local.md에 작성하고, Git 공유 대상에서 제외하는 .gitignore에 추가합니다. 여러 프로젝트에 공통으로 적용할 개인 규칙은 ~/.claude/CLAUDE.md에 둘 수 있습니다. Claude는 이렇게 찾은 파일을 이어 붙입니다. 두 규칙이 어긋나면 한쪽만 따르고, 다른 쪽은 무시할 수 있습니다.
초안부터 직접 쓰기 어렵다면 Claude Code에서 /init을 실행해 보세요. 프로젝트를 살펴보고 초안을 만드는 데 사용할 수 있습니다. 초안이 나오면 불필요한 설명이나 잘못된 명령을 정리하세요.
코드만 보고는 알기 어려운 내용을 적으세요
다음 네 가지부터 시작하면 충분합니다.
- 실행 명령: 개발 서버, 테스트, 타입 검사, 빌드를 어떻게 실행하는지
- 파일 위치: 화면 구성 요소와 서버 코드를 어디에 두는지
- 언어 기본값과 다른 관례: 그 언어에서 보통 쓰는 방식과 다르게 지킬 규칙
- 완료 기준: 코드를 수정한 뒤 무엇을 확인해야 작업이 끝난 것인지
“깔끔하게 작성해 줘”보다 “들여쓰기는 공백 두 칸을 사용해 줘”, “멈추기 전에 작업한 파일에 pnpm test를 실행해 줘”처럼 확인할 수 있는 문장이 좋습니다.
할 일 관리 앱의 작성 예시
아래는 예시입니다. 명령과 경로는 실제 프로젝트에 맞게 바꿔 사용하세요.
# 할 일 관리 앱의 작업 규칙
## 실행 명령
- 패키지 설치: `pnpm install`
- 개발 서버 시작: `pnpm dev`
- 테스트 실행: `pnpm test`
- 타입 검사: `pnpm check`
## 파일 위치
- 화면 구성 요소는 `src/components/`에 둡니다.
- 서버 요청을 처리하는 코드는 `src/api/`에 둡니다.
## 오류 처리
- API 오류는 `{ error, code }` 형식의 JSON과 알맞은 HTTP 상태 코드로 반환합니다.
- 네트워크 요청이 실패하면 사용자에게 오류 상태를 보여 줍니다.
## 작업 완료 전에 확인할 것
- 할 일이 없을 때, 불러오는 중일 때, 오류가 났을 때의 화면이 모두 표시되어야 합니다.
- 변경한 파일에 대해 `pnpm test`가 통과해야 합니다.이 예시는 “어떻게 실행하는가”, “어디에 코드를 두는가”, “무엇을 확인하는가”를 한 파일에 모은 것입니다. Claude가 같은 실수를 반복한다면 해당 부분에 구체적인 규칙을 한 줄 더해 보세요.
파일을 짧게 유지하는 이유
200줄 아래를 목표로 하세요. 일반적인 CLAUDE.md는 전체를 불러옵니다. 파일이 길어지면 토큰을 더 쓰고, 무시하기도 쉽습니다. 4 MiB를 넘는 파일은 건너뜁니다.
여러 단계로 된 절차는 스킬에 두고, 일부 파일에만 중요한 지시는 .claude/rules/의 경로 범위 규칙에 둡니다. 스킬은 직접 호출하거나 Claude가 관련 있다고 판단할 때 불러옵니다. CLAUDE.md는 세션마다 불러옵니다. 예를 들어 매번 필요한 테스트 명령은 CLAUDE.md에, 배포할 때만 필요한 긴 점검 절차는 스킬에 두는 식입니다.
프로젝트 파일로 /init을 실행해 지침 초안을 만든 뒤, package.json만 봐도 알 수 있는 내용은 지웁니다. /context를 실행하고 Memory files 목록에서 그 파일이 읽혔는지 확인합니다.
Claude Code v2.1.277 이상은, 작업 디렉터리와 그 상위에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없을 때 AGENTS.md를 직접 읽습니다. ~/.claude/CLAUDE.md는 이 유무를 볼 때 포함하지 않습니다. 그런 프로젝트 파일이 하나라도 있으면 Claude는 CLAUDE.md 파일만 읽습니다. 예외는 CLAUDE.md에 @AGENTS.md가 있을 때와, Project instructions가 claude-md-and-agents-md일 때입니다. CLAUDE.local.md를 추가하면, Project instructions를 claude-md-and-agents-md로 설정하지 않는 한 AGENTS.md를 직접 읽는 동작도 멈춥니다.
AGENTS.md를 읽지 못하는 세션에서는 CLAUDE.md에 다음 한 줄을 넣어 같은 지침을 불러옵니다. 해당하는 경우는 v2.1.277 이전의 Claude Code, 기본 제공 agents-md 플러그인을 끈 경우, v2.1.281 이전의 일부 세션입니다.
@AGENTS.md파일 내용을 복사하지는 않습니다.
Claude가 같은 실수를 반복하면 구체적인 문장을 한 줄 추가하세요. 같은 문단을 채팅에 그대로 붙여 넣는 절차가 되면 .claude/skills/<name>/SKILL.md로 옮깁니다. 자동 메모리에는 Claude가 직접 쓴 수정이 남을 수 있습니다. 팀원이 함께 봐야 하는 내용은 CLAUDE.md에 적습니다.