CLAUDE.md 작성 가이드: 프로젝트 규칙을 AI에게 알려주는 법

클로드 코드로 작업하다 보면 새 세션을 시작할 때마다 AI가 프로젝트에 대해 아무것도 모른다는 걸 느끼게 됩니다. “테스트는 bun run test로 돌려”, “커밋 메시지는 영어로 써줘”, “이 프로젝트는 Prettier를 쓰고 있어”… 매번 같은 말을 반복하는 건 꽤 피곤한 일이죠.

CLAUDE.md는 이 문제를 해결하는 가장 직접적인 방법입니다. 프로젝트의 빌드 명령어, 코딩 스타일, 아키텍처 결정 같은 규칙을 마크다운으로 적어두면 Claude가 매 세션 시작 시 읽어들이거든요. Git에 커밋하면 팀 전체가 공유할 수 있고, 개인 설정으로만 쓸 수도 있습니다.

무엇을 CLAUDE.md에 넣을까

막상 파일을 만들어도 “그래서 뭘 적어야 하지?”에서 막히곤 하는데요. 기준은 의외로 단순합니다. 매번 다시 설명하게 되는 것을 적어두면 됩니다.

이런 신호가 보이면 CLAUDE.md에 추가할 때입니다.

• Claude가 같은 실수를 두 번째로 반복할 때
• 코드 리뷰에서 “이 코드베이스에선 이렇게 해야 한다”는 지적이 나올 때
• 지난 세션에 입력했던 교정이나 설명을 이번 세션에 또 타이핑하고 있을 때
• 새 팀원이 합류하면 똑같이 알려줘야 할 맥락일 때

담을 내용은 매 세션 Claude가 알고 있어야 할 사실들입니다. 빌드 명령어, 코딩 컨벤션, 프로젝트 구조, “항상 X를 해라” 같은 규칙이죠.

반대로 모든 걸 CLAUDE.md에 욱여넣을 필요는 없습니다. 여러 단계를 거치는 절차이거나 코드베이스의 일부에서만 의미 있는 내용이라면, 스킬이나 경로 기반 규칙으로 옮기는 게 낫습니다. 매 세션 로드되는 CLAUDE.md는 늘 필요한 것만 담아 가볍게 유지하는 게 핵심이에요.

CLAUDE.md 파일의 위치와 스코프

CLAUDE.md 파일을 어디에 놓느냐에 따라 적용 범위가 달라집니다. 여러 위치에 동시에 둘 수 있고, 구체적인 위치가 더 높은 우선순위를 갖습니다.

가장 많이 쓰는 건 프로젝트 지시 파일입니다. ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 두면 팀원 모두가 공유하는 프로젝트 규칙이 됩니다. 빌드 명령어, 테스트 방법, 코딩 컨벤션 같은 내용을 여기에 적고 Git에 커밋하면 돼요.

사용자 지시 파일(~/.claude/CLAUDE.md)은 모든 프로젝트에 적용되는 개인 설정입니다. “응답은 한국어로 해줘”, “커밋 메시지는 Conventional Commits 형식으로” 같은 선호를 담기에 좋죠.

로컬 지시 파일(./CLAUDE.local.md)은 프로젝트 안에서 나만 쓰는 설정입니다. 샌드박스 URL이나 테스트 데이터 같은 걸 넣어두면 돼요. .gitignore에 자동으로 추가되어 Git에 커밋되지 않습니다.

조직 관리자라면 관리 정책 파일도 있습니다. macOS는 /Library/Application Support/ClaudeCode/CLAUDE.md, Linux는 /etc/claude-code/CLAUDE.md에 두면 해당 기기의 모든 사용자에게 적용돼요. 회사 보안 정책이나 코딩 표준을 강제할 때 쓰이며, 개별 설정으로 비활성화할 수 없습니다.

별도 파일을 두는 대신 관리 설정 파일(managed-settings.json)의 claudeMd 키에 내용을 직접 넣을 수도 있습니다. 우선순위는 관리 정책 파일과 동일하며, 사용자·프로젝트·로컬 설정에 같은 키를 넣어도 무시돼요.

{
  "claudeMd": "커밋 전 항상 `make lint`를 실행하세요.\n절대 main에 직접 푸시하지 마세요."
}

/init으로 시작하기

처음 CLAUDE.md를 만들 때 빈 파일에서 뭘 써야 할지 막막하죠? 클로드 코드의 /init 커맨드를 쓰면 코드베이스를 분석해서 CLAUDE.md를 자동으로 만들어줍니다.

$ claude
> /init

Claude가 package.json, README.md, 기존 설정 파일들을 참고해서 프로젝트 구조, 빌드 명령어, 테스트 방법, 코딩 컨벤션 등을 파악하고 적절한 내용으로 채워줍니다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선 사항을 제안합니다.

자동 생성된 내용에서 시작해서, Claude가 알아서 못 찾는 프로젝트 고유의 규칙이나 주의사항을 직접 추가하면 됩니다.

조금 더 꼼꼼하게 설정하고 싶다면 CLAUDE_CODE_NEW_INIT=1 환경 변수로 다단계 인터랙티브 모드를 켤 수 있습니다. 이 모드에서는 /init이 무엇을 설정할지(CLAUDE.md, 스킬, 훅) 먼저 묻고, 서브에이전트로 코드베이스를 탐색한 뒤 부족한 부분을 추가 질문으로 채웁니다. 그리고 실제로 파일을 쓰기 전에 검토할 수 있는 제안을 먼저 보여줘요.

효과적인 지시문 작성법

CLAUDE.md는 매 세션마다 컨텍스트 윈도우에 로드되기 때문에 토큰을 잡아먹습니다. 너무 길면 오히려 지시 준수율이 떨어져요. 몇 가지 원칙만 지키면 효과가 확 달라집니다.

우선 분량은 200줄 이내로 유지하는 게 좋습니다. 파일이 길어지면 핵심이 묻혀요. 꼭 필요한 정보만 담고 상세한 내용은 별도 파일로 분리하세요.

마크다운 헤딩과 불릿으로 구조를 잡아주는 것도 중요합니다. 빽빽한 문단보다 정리된 섹션이 Claude 입장에서 파악하기 훨씬 쉬워요.

무엇보다 구체적으로 작성해야 합니다. “코드를 잘 포맷해줘”보다 “들여쓰기는 2칸 스페이스를 써”가 훨씬 효과적이에요. 검증 가능한 수준으로 구체적이어야 Claude가 일관되게 따라갑니다.

## 빌드와 테스트

- 개발 서버: `bun run dev`
- 빌드: `bun run build`
- 테스트: `bun run test`

## 코드 스타일

- 들여쓰기: 2칸 스페이스
- 세미콜론 사용하지 않음
- 문자열은 작은따옴표 사용
- 커밋 전 `bun run format` 실행

## 프로젝트 구조

- API 핸들러: `src/api/handlers/`
- 공유 유틸리티: `src/utils/`
- 테스트 파일: `__tests__/` 디렉토리에 작성

여러 CLAUDE.md 파일에 서로 충돌하는 규칙이 있으면 Claude가 임의로 하나를 골라버릴 수 있으니 주의하세요. 가끔 검토해서 오래된 지시를 정리하는 습관이 필요합니다.

다른 파일 임포트하기

CLAUDE.md가 길어지면 파일을 나눠서 관리할 수 있습니다. @경로 문법으로 다른 파일을 임포트하면 세션 시작 시 함께 로드됩니다.

프로젝트 개요는 @README.md를 참고하세요.
사용 가능한 명령어는 @package.json을 참고하세요.

# 추가 지시사항
- Git 워크플로우는 @docs/git-instructions.md를 따르세요.

상대 경로와 절대 경로 모두 쓸 수 있어요. 상대 경로는 임포트하는 파일이 있는 디렉토리 기준입니다. 임포트된 파일이 또 다른 파일을 임포트할 수도 있는데, 최대 4단계까지 허용됩니다.

한 가지 유의할 점은, 임포트가 파일을 정리하는 데는 좋지만 컨텍스트 토큰을 줄여주지는 않는다는 겁니다. 임포트된 파일도 결국 세션 시작 시 전부 로드되거든요. 분량이 부담된다면 임포트가 아니라 경로 기반 규칙(.claude/rules/)을 써야 합니다.

여러 워크트리에서 작업하는 경우, CLAUDE.local.md는 한 워크트리에만 존재합니다. 모든 워크트리에서 공유할 개인 설정이 있다면 홈 디렉토리의 파일을 임포트하는 방식이 좋습니다.

# 개인 설정
- @~/.claude/my-project-instructions.md

프로젝트에서 처음 외부 임포트를 발견하면 승인 대화상자가 나타납니다. 거부하면 해당 임포트는 비활성화되고 대화상자는 다시 나타나지 않습니다.

AGENTS.md와 함께 쓰기

클로드 코드는 AGENTS.md가 아니라 CLAUDE.md를 읽습니다. 그런데 요즘은 여러 AI 도구가 공유하는 AGENTS.md를 표준으로 쓰는 저장소가 많죠. 이미 AGENTS.md가 있다면, 내용을 복사해서 두 파일을 따로 관리하는 대신 CLAUDE.md에서 임포트하는 게 가장 깔끔합니다.

@AGENTS.md

## 클로드 코드 전용

- `src/billing/` 아래를 수정할 때는 플랜 모드를 사용하세요.

이렇게 하면 세션 시작 시 AGENTS.md가 그대로 로드되고, 그 아래에 클로드 코드에만 해당하는 지시를 덧붙일 수 있습니다. 다른 도구는 AGENTS.md만 읽고, 클로드 코드는 AGENTS.md와 전용 지시를 함께 읽는 거죠. 단일 진실 소스(single source of truth)를 유지하면서 도구별 차이를 흡수할 수 있습니다.

클로드 코드 전용 내용을 따로 둘 필요가 없다면 심볼릭 링크(ln -s AGENTS.md CLAUDE.md)로 두 파일을 아예 같게 만들어도 됩니다. 다만 Windows에서는 심볼릭 링크에 관리자 권한이나 개발자 모드가 필요하니, 이럴 땐 @AGENTS.md 임포트 방식이 더 무난해요. Cursor, Windsurf 등 여러 도구에 걸쳐 컨텍스트 파일을 통합하는 방법은 AGENTS.md와 CLAUDE.md에서 더 자세히 다룹니다.

참고로 /init도 AGENTS.md를 인식합니다. 이미 AGENTS.md가 있는 저장소에서 /init을 실행하면 그 내용을 읽어 CLAUDE.md에 반영하고, .cursorrules나 .windsurfrules 같은 다른 도구의 설정 파일도 함께 참고합니다.

.claude/rules/로 규칙 나누기

CLAUDE.md 하나가 비대해지면 .claude/rules/ 디렉토리로 규칙을 주제별 파일로 쪼갤 수 있습니다. 특히 paths 프론트매터를 붙인 경로 기반 규칙은 특정 파일을 작업할 때만 로드되어 컨텍스트를 아껴줍니다. 작성법과 CLAUDE.md·스킬과의 차이, 사용자 레벨 규칙과 공유 방법은 .claude/rules로 규칙 체계화하기에서 따로 자세히 다룹니다.

CLAUDE.md가 로드되는 방식

클로드 코드는 현재 작업 디렉토리에서 디렉토리 트리를 위로 올라가면서 CLAUDE.md와 CLAUDE.local.md 파일을 찾습니다. 예를 들어 foo/bar/에서 실행하면 foo/bar/CLAUDE.md와 foo/CLAUDE.md가 모두 로드됩니다.

하위 디렉토리의 CLAUDE.md는 좀 다르게 동작합니다. 세션 시작 시 바로 로드되지 않고, Claude가 해당 디렉토리의 파일을 읽을 때 함께 포함됩니다. 필요한 순간에 로드되는 것이죠.

대규모 모노레포에서 다른 팀의 CLAUDE.md가 함께 로드되는 게 신경 쓰인다면 설정 파일의 claudeMdExcludes 옵션으로 특정 파일을 제외할 수 있습니다.

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

패턴은 절대 파일 경로에 대해 글로브 매칭됩니다. 관리 정책 CLAUDE.md는 제외할 수 없도록 되어 있어서, 조직 전체의 규칙은 항상 적용됩니다.

--add-dir 플래그로 추가 디렉토리를 지정한 경우, 기본적으로는 해당 디렉토리의 CLAUDE.md가 로드되지 않습니다. 로드하려면 환경 변수를 설정해야 합니다.

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

CLAUDE.md에 적은 블록 단위 HTML 주석(<!-- ... -->)은 Claude의 컨텍스트에 주입되기 전에 제거됩니다. 사람이 읽을 유지보수 메모를 토큰 낭비 없이 남길 수 있는 거죠. 단, 코드 블록 안의 주석은 그대로 유지되고, Read 도구로 파일을 직접 열면 주석도 보입니다.

<!-- 아래 빌드 섹션은 릴리스 담당자만 수정할 것 -->

## 빌드

- 테스트: `bun run test`

/compact와 CLAUDE.md

긴 세션에서 컨텍스트 윈도우가 가득 차면 /compact 커맨드로 대화를 압축할 수 있는데요. 이때 CLAUDE.md는 압축의 영향을 받지 않습니다. 압축 후 Claude가 디스크에서 CLAUDE.md를 다시 읽어서 새롭게 주입하기 때문이죠.

다만 대화 중에 말로만 전달한 지시는 압축 과정에서 사라질 수 있습니다. “앞으로 이렇게 해줘”라고 구두로 말한 것이 /compact 후에 안 지켜진다면, 그 내용을 CLAUDE.md에 적어두는 것이 좋습니다.

트러블슈팅

실제 사용하다 보면 몇 가지 문제에 부딪힐 수 있습니다.

“Claude가 CLAUDE.md를 안 따라요.” 이건 가장 흔한 불만인데요. CLAUDE.md는 강제 설정이 아니라 컨텍스트라서 100% 보장은 안 됩니다. 먼저 /memory를 실행해서 파일이 제대로 로드되고 있는지 확인해보세요. 목록에 없으면 Claude가 아예 못 보고 있는 겁니다. 지시가 모호하거나 규칙끼리 충돌하고 있진 않은지도 점검해보세요.

그래도 안 된다면 CLAUDE.md만으로는 한계가 있다는 신호입니다. CLAUDE.md는 강제 설정이 아니라 컨텍스트라서 100% 보장이 안 되거든요. 반드시 정해진 시점에 실행돼야 하는 동작이라면 — 매 커밋 전이나 파일 수정 후처럼 — 셸 명령으로 실행되는 훅으로 옮기는 게 확실합니다. 훅은 Claude의 판단과 무관하게 무조건 실행되니까요. 시스템 프롬프트 레벨로 지시를 넣고 싶다면 --append-system-prompt 플래그도 있는데, 매 실행마다 전달해야 해서 대화형보다는 스크립트·자동화에 어울립니다.

“CLAUDE.md가 너무 길어졌어요.” 200줄이 넘으면 컨텍스트를 많이 잡아먹고 준수율도 떨어집니다. 매 세션에 필요하지 않은 내용을 덜어내거나, 경로 기반 규칙(.claude/rules/)으로 분리해서 관련 파일을 작업할 때만 로드되게 하세요. 앞서 짚었듯 @경로 임포트는 토큰을 줄여주지 않으니 분량 문제의 해법은 아닙니다.

마치며

CLAUDE.md는 프로젝트의 규칙과 지식을 Claude에게 전달하는 가장 직접적인 방법입니다. 시작이 막막하다면 /init으로 기본 파일을 만들고, Claude가 자꾸 틀리는 부분을 하나씩 추가해나가면 됩니다.

여러 AI 코딩 에이전트를 사용하는 팀이라면 위에서 다룬 @AGENTS.md 임포트와 함께, Cursor·Copilot까지 아우르는 통합 설정을 다룬 AGENTS.md와 CLAUDE.md도 참고해보세요. CLAUDE.md와 함께 Claude가 스스로 학습하는 자동 메모리를 활용하면 세션을 거듭할수록 Claude와의 협업이 더 매끄러워집니다. 설정 파일까지 함께 다루면 권한 관리, 모델 선택 등 클로드 코드 환경을 더 세밀하게 제어할 수 있습니다.

로딩 순서, 임포트 문법, 모노레포 제외 설정 등 CLAUDE.md에 대한 더 자세한 내용은 클로드 코드 메모리 공식 문서에서 확인할 수 있습니다.