CLAUDE.md 프로젝트 지침

들어가며

Claude Code 세션은 매번 빈 컨텍스트로 시작한다. 어제 알려준 빌드 명령, 코딩 컨벤션, 폴더 구조를 오늘 다시 설명해야 하는 셈이다. 같은 정정을 매번 채팅에 입력하다 보면 이게 도구의 정상 동작인지 의심하게 된다.

CLAUDE.md가 이 문제를 해결한다. 프로젝트 루트에 두는 마크다운 파일이고, Claude Code가 세션 시작 때 자동으로 읽는다. 빌드 명령, 컨벤션, 폴더 구조 같은 영속적 컨텍스트를 한 번 적어두면, 매 세션마다 같은 설명을 반복할 필요가 없다.

이번 차시에서는 네 가지를 다룬다. 먼저 CLAUDE.md의 역할과 어디에 두어야 하는지를 살펴본다. 그 다음 효과적인 작성 4원칙과 섹션 구성을 알아본다. 그리고 /init로 자동 생성하기, @ 임포트로 다른 문서 참조하기, AGENTS.md와 연동하기 같은 활용 방법을 정리한다. 마지막으로 팀과 공유하는 법과 자주 마주치는 문제 해결 방법을 다룬다.

메모리 계층 구조의 세부 사항(자동 메모리, 우선순위 흐름)은 22차시, 경로별 조건부 규칙(.claude/rules/)은 23차시에서 따로 다룬다.

CLAUDE.md란

CLAUDE.md는 Claude Code에게 영속적인 지시를 전달하는 마크다운 파일이다. 평문으로 작성하면 Claude Code가 세션 시작 때 읽는다.

다른 두 가지 메모리 메커니즘과 비교하면 역할이 분명해진다.

CLAUDE.md는 행동 가이드다. 강제 설정이 아니라 컨텍스트로 취급되므로, 구체적이고 간결하게 쓸수록 잘 따른다.

어디에 두어야 하는가

CLAUDE.md는 네 가지 위치에 둘 수 있고, 더 구체적인 위치가 우선한다.

작업 디렉토리에서 위로 트리를 따라 올라가며 각 디렉토리에서 CLAUDE.md와 CLAUDE.local.md를 찾는다. 발견된 파일은 모두 컨텍스트에 연결된다(덮어쓰지 않는다). 같은 디렉토리 안에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 추가되므로, 충돌하는 지시는 개인 노트가 마지막에 적용된다.

하위 디렉토리의 CLAUDE.md는 시작 시점에 로드되지 않는다. Claude가 그 디렉토리의 파일을 읽을 때 컨텍스트에 포함된다.

/init으로 자동 생성하기

빈 파일에서 시작하지 않아도 된다. Claude Code 안에서 /init을 실행하면 코드베이스를 분석해 빌드 명령, 테스트 명령, 발견된 컨벤션이 담긴 시작용 CLAUDE.md를 만든다. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선 제안을 한다.

> /init

새로운 인터랙티브 멀티 페이즈 흐름을 쓰려면 환경 변수를 설정한다.

export CLAUDE_CODE_NEW_INIT=1

이 모드에서는 /init이 어떤 산출물(CLAUDE.md, skills, hooks)을 만들지 먼저 묻고, 서브에이전트로 코드베이스를 탐색한 뒤, 후속 질문으로 빈칸을 채운다. 그리고 파일을 쓰기 전에 검토 가능한 제안서를 보여준다.

효과적인 작성 4원칙

CLAUDE.md는 컨텍스트 윈도우에 로드되어 토큰을 소비한다. 그리고 시스템 프롬프트가 아닌 사용자 메시지로 전달되기 때문에, 잘 따르게 만드는 책임이 작성자에게 있다. 공식 문서가 강조하는 4원칙을 정리한다.

1. Size — 200줄 이하 목표

파일이 길수록 컨텍스트를 더 소비하고 준수율이 떨어진다. 지시가 늘어나면 @ 임포트로 분리하거나 23차시에서 다룰 .claude/rules/로 쪼갠다.

2. Structure — 마크다운으로 그룹화

헤더와 불릿으로 관련 지시를 묶는다. Claude는 사람과 같은 방식으로 구조를 스캔하기 때문에, 빽빽한 문단보다 정리된 섹션을 잘 따른다.

3. Specificity — 검증 가능한 구체적 지시

추상적 표현은 모델마다 다르게 해석된다. “잘 작성해주세요”는 따를 수가 없다. 검증 가능한 형태로 적는다.

4. Consistency — 충돌 제거

두 규칙이 충돌하면 Claude는 임의로 하나를 고른다. 프로젝트가 커지면 정기적으로 CLAUDE.md, 하위 디렉토리의 CLAUDE.md, .claude/rules/를 검토해서 오래되거나 충돌하는 지시를 정리한다.

섹션별 작성 가이드

CLAUDE.md에 어떤 섹션을 넣을지 정해진 형식은 없다. 하지만 다음 카테고리는 대부분의 프로젝트에 공통적으로 유용하다.

프로젝트 정보

## 프로젝트
사용자 관리 대시보드. React 18 + TypeScript SPA.
주요 기능: 사용자 CRUD, 권한 관리, 통계 리포트.

빌드와 테스트 명령

## 명령
- 개발 서버: `pnpm dev`
- 빌드: `pnpm build`
- 테스트: `pnpm test`
- 린트: `pnpm lint`
- 타입 체크: `pnpm typecheck`

여기에 Claude가 코드를 변경한 후 자동으로 실행해야 할 것을 명확히 적어두면 매 세션마다 시키지 않아도 된다.

코딩 컨벤션

## 코딩 규칙
- 함수형 컴포넌트만 사용
- Props는 interface로 정의
- 모든 public 함수에 반환 타입 명시
- 에러 처리는 Result 타입 사용

폴더 구조

## 구조
src/
├── components/  # 재사용 UI 컴포넌트
├── features/    # 기능별 모듈 (라우트 단위)
├── lib/         # 외부 라이브러리 래퍼
├── hooks/       # 커스텀 훅
└── pages/       # 라우트 진입점

Git 컨벤션

## Git
- 커밋: Conventional Commits (feat/fix/docs/refactor/test/chore)
- 브랜치: `feature/`, `bugfix/`, `hotfix/` 접두사
- PR 생성 전 `pnpm test`와 `pnpm lint` 통과 필수

주의사항

## 주의
- `.env` 커밋 금지
- 프로덕션 DB 직접 접근 금지
- API 키는 환경 변수로만 관리
- 마이그레이션 파일은 수정하지 말고 새로 생성

@ 임포트로 다른 문서 참조하기

CLAUDE.md는 @path/to/import 구문으로 다른 파일을 임포트할 수 있다. 임포트된 파일은 시작 시점에 CLAUDE.md와 함께 컨텍스트에 펼쳐진다.

프로젝트 개요는 @README, npm 명령어는 @package.json 참고.

# 추가 지시
- git 워크플로 @docs/git-instructions.md

상대 경로와 절대 경로 모두 허용된다. 상대 경로는 작업 디렉토리가 아니라 임포트하는 파일 기준으로 해석된다. 임포트된 파일은 다시 다른 파일을 임포트할 수 있고, 최대 5단계까지 재귀적으로 따라간다.

코드 블록 안의 @는 import로 취급되지 않는다. 예시 코드에 @somewhere를 적어도 안전하다.

홈 디렉토리에 둔 개인용 지시 파일을 여러 워크트리에서 공유하고 싶다면 다음처럼 쓴다.

# 개인 선호
- @~/.claude/my-project-instructions.md

CLAUDE.local.md는 같은 워크트리에만 존재하므로, 워크트리 간 공유에는 이 패턴이 더 안전하다.

처음으로 외부 임포트를 만나면 Claude Code가 승인 다이얼로그를 띄워 임포트할 파일 목록을 보여준다. 거부하면 임포트가 비활성화된 채 다이얼로그는 다시 나타나지 않는다.

AGENTS.md와 호환하기

다른 코딩 에이전트(예: 다른 IDE 통합 도구)가 AGENTS.md를 읽는 표준을 따른다면, CLAUDE.md에서 임포트로 연결하면 된다. Claude Code 자체는 CLAUDE.md만 읽기 때문이다.

@AGENTS.md

## Claude Code

`src/billing/` 아래 변경은 plan 모드 사용.

이렇게 하면 AGENTS.md에 정의한 공통 지시를 두 도구가 모두 읽고, 그 아래에 Claude Code 전용 지시를 추가할 수 있다.

CLAUDE.local.md와 사용자 전역 설정

CLAUDE.local.md는 프로젝트 안에 두지만 Git에는 커밋하지 않는 개인 설정이다. 로컬 DB URL, 테스트용 자격 증명, 작업 중인 기능 메모처럼 본인만 쓰는 정보를 둔다.

# CLAUDE.local.md

## 내 환경
- 로컬 DB: localhost:5432
- 테스트 API: http://localhost:3001
- Redis: localhost:6379

## 개인 선호
- 응답은 한국어로
- 주석도 한국어로

.gitignore에 추가한다.

CLAUDE.local.md

/init으로 personal 옵션을 선택하면 이 작업을 자동으로 해준다.

모든 프로젝트에 적용할 개인 선호는 ~/.claude/CLAUDE.md에 둔다.

## 전역 선호
- 응답 언어: 한국어
- 패키지 매니저: pnpm
- 테스트 프레임워크: Vitest 우선
- 함수는 짧게 (20줄 이내)
- Early return 패턴 선호

팀과 Git으로 공유하기

프로젝트 CLAUDE.md의 가장 큰 장점은 Git으로 공유 가능하다는 점이다. 한 사람이 적어두면 팀 전체가 같은 컨벤션을 따라 작업할 수 있다.

git add CLAUDE.md
git commit -m "docs: add CLAUDE.md with project conventions"
git push

팀원이 클론한 뒤 Claude Code를 실행하면 같은 지시를 자동으로 받게 된다.

git clone <repo>
cd project
claude

별도의 설정이나 onboarding 문서를 따라야 할 필요가 없다. 새 팀원도 첫 세션부터 일관된 컨벤션을 따른다.

자주 쓰는 명령

/memory — 어떤 파일이 로드됐는지 확인

> /memory

현재 세션에서 로드된 모든 CLAUDE.md, CLAUDE.local.md, rules 파일 목록이 표시된다. 자동 메모리 토글, 자동 메모리 폴더 열기, 파일 클릭 시 에디터에서 열기 같은 기능이 함께 제공된다.

CLAUDE.md를 수정했는데 Claude가 따르지 않는 것 같으면 먼저 /memory로 파일이 실제로 로드되어 있는지 확인한다. 목록에 없으면 Claude가 못 보고 있는 것이다.

”기억해줘” — Auto memory에 저장

> 앞으로 이 프로젝트에서는 항상 pnpm을 사용해줘

이런 지시를 하면 Claude가 auto memory에 저장한다. 자동 메모리는 22차시에서 자세히 다룬다. CLAUDE.md에 직접 추가하고 싶다면 다음처럼 명시한다.

> 이걸 CLAUDE.md에 추가해줘

/compact 이후의 동작

긴 세션 도중 /compact로 컨텍스트를 압축할 수 있다. 이때 프로젝트 루트의 CLAUDE.md는 디스크에서 다시 읽혀 세션에 재주입된다. 즉, 압축 후에도 프로젝트 지침은 살아남는다.

다만 하위 디렉토리의 중첩된 CLAUDE.md는 자동 재주입되지 않는다. 그 디렉토리의 파일을 다시 읽을 때 비로소 로드된다. 압축 직후 어떤 지시가 사라진 느낌이라면 (1) 대화에서만 준 지시였거나, (2) 하위 디렉토리 CLAUDE.md에 있어서 재로드 대기 중인 경우다. 영속적으로 적용되어야 할 것은 CLAUDE.md에 적어두는 게 안전하다.

monorepo에서 다른 팀 CLAUDE.md 제외하기

대규모 monorepo에서는 부모 디렉토리에 다른 팀의 CLAUDE.md가 있을 수 있다. 내 작업과 관련이 없으면 컨텍스트만 차지한다.

claudeMdExcludes 설정으로 특정 파일을 패턴으로 제외한다.

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

.claude/settings.local.json에 두면 본인 머신에만 적용된다. Managed policy CLAUDE.md는 제외할 수 없다.

트러블슈팅

Claude가 CLAUDE.md를 따르지 않는다

CLAUDE.md는 시스템 프롬프트가 아니라 그 다음에 오는 사용자 메시지로 전달된다. Claude는 읽고 따르려 하지만, 모호하거나 충돌하는 지시는 엄격하게 지켜지지 않는다. 다음 순서로 점검한다.

1. /memory로 파일이 로드되어 있는지 확인
2. 위치가 맞는지 확인 (현재 디렉토리에서 위로 트리 안에 있어야 함)
3. 지시를 더 구체적으로 (Specificity 원칙 참고)
4. 여러 CLAUDE.md 사이에서 충돌하는 지시 검토

시스템 프롬프트 레벨의 지시가 정말 필요하다면 CLI 플래그 --append-system-prompt를 쓴다. 매 호출마다 전달해야 하므로 인터랙티브 사용보다는 스크립트나 자동화에 적합하다.

CLAUDE.md가 너무 커졌다

200줄을 넘으면 컨텍스트를 많이 소비하고 준수율이 떨어진다. 두 가지 선택이 있다.

• 상세한 내용을 별도 파일로 옮기고 @path 임포트로 참조
• 23차시에서 다룰 .claude/rules/로 토픽별 분리 (경로별 조건부 로딩 가능)

팀원 머신에서만 다르게 동작한다

CLAUDE.md는 공유되지만 CLAUDE.local.md와 ~/.claude/CLAUDE.md는 사람마다 다르다. 같은 파일을 본다고 같은 지시를 받는 건 아니다. 팀 공통 동작은 반드시 프로젝트 CLAUDE.md에 둔다.

HTML 주석으로 메모 남기기

블록 레벨 HTML 주석(<!-- 유지보수 메모 -->)은 컨텍스트에 주입되기 전에 제거된다. Claude가 읽지 않는 메모를 사람용으로 남길 수 있다. 코드 블록 안의 주석은 그대로 보존되고, Read 도구로 CLAUDE.md를 직접 열면 주석도 보인다.

<!-- 이 섹션은 분기마다 검토 -->
## 코딩 규칙
- ...

정리

핵심 요점

1. 빈 컨텍스트로 시작하는 세션을 매번 채우지 않기 위한 도구: 프로젝트 루트의 CLAUDE.md는 자동으로 로드된다

2. 4가지 위치, 더 구체적인 위치 우선: Managed → Project → User → Local. 발견된 파일은 모두 연결되며, 같은 디렉토리에서 CLAUDE.local.md가 CLAUDE.md 뒤에 추가됨

3. /init으로 자동 생성: 코드베이스 분석 후 시작용 파일 생성. CLAUDE_CODE_NEW_INIT=1로 인터랙티브 흐름 사용 가능

4. 작성 4원칙: Size(<200줄), Structure(마크다운), Specificity(검증 가능), Consistency(충돌 제거)

5. @ 임포트로 모듈화: 다른 문서, AGENTS.md, 홈 디렉토리 파일까지 참조 가능. 최대 5단계 재귀 임포트

6. 팀 공유는 Git으로: 프로젝트 CLAUDE.md를 커밋하면 팀 전체가 같은 컨벤션 자동 적용

7. /memory로 점검: Claude가 안 따르는 것 같으면 먼저 어떤 파일이 로드됐는지 확인

확인해볼 링크

• 공식 문서: How Claude remembers your project (Memory)
• 공식 문서: CLI reference
• 공식 문서: Quickstart
• 공식 문서: Skills

다음 단계

다음 차시에서는 Claude Code의 메모리 시스템을 더 깊이 다룬다. CLAUDE.md 외에 자동으로 누적되는 Auto Memory의 동작 원리, ~/.claude/projects/<project>/memory/ 저장 구조, MEMORY.md 인덱스의 200줄/25KB 로드 한계, CLAUDE_CODE_DISABLE_AUTO_MEMORY 환경 변수와 autoMemoryEnabled/autoMemoryDirectory 설정을 살펴본다.

참고 자료

• How Claude remembers your project (Memory)
• CLI reference
• Quickstart - Claude Code
• Skills