CLAUDE.md로 Claude Code 프로젝트 기억 설계하는 법

세션을 닫으면 Claude Code는 모든 걸 잊는다. 스택 정보, 포트 번호, 커밋 규칙 — 어제 알려준 것들을 오늘 다시 처음부터 설명해야 한다. CLAUDE.md 프로젝트 기억 설계는 이 반복을 끊는 가장 직접적인 방법이다. 파일 하나를 제대로 써두면 매 세션마다 쏟아지는 확인 질문이 사라지고, 첫 코드 제안까지 걸리는 시간이 눈에 띄게 줄어든다.

1. 왜 지금 이걸 봐야 하나

Claude Code를 팀 프로젝트나 복잡한 인프라에 붙여 쓰는 순간, 반복 온보딩 비용이 쌓이기 시작한다. 새 세션을 열 때마다 '포트가 뭐예요', '어떤 스택이에요', '커밋 규칙이 있나요' 같은 질문이 7~9회씩 나온다. 이건 AI가 멍청한 게 아니라 구조적인 문제다. Claude Code는 세션 단위로만 기억하고, 대화가 끊기면 컨텍스트가 초기화된다.

문제는 이 확인 질문들이 단순한 번거로움에 그치지 않는다는 점이다. 컨텍스트 창의 앞부분을 세팅 토큰이 차지하면, 실제 작업에 쓸 수 있는 공간이 줄어든다. Mac Mini 4대 클러스터 환경에서 실측해보니 CLAUDE.md 없이 세션을 시작하면 첫 의미 있는 코드 제안까지 평균 4분 12초가 걸렸다. 같은 작업 기준으로 CLAUDE.md를 적용하자 43초로 줄었다. 컨텍스트 세팅에 쓰던 토큰이 실제 작업 토큰으로 전환된 결과다.

이 문제를 구조로 해결하는 도구가 CLAUDE.md다.

2. 핵심 아이디어

CLAUDE.md는 Claude Code에게 보내는 프로젝트 브리핑 문서다. 없으면 매 세션이 온보딩 첫날이고, 있으면 시니어 동료가 이미 상황을 파악하고 앉아 있는 상태로 시작할 수 있다.

Claude Code가 실행 시 읽는 파일의 순서는 다음과 같다.

위치	역할	우선순위
~/.claude/CLAUDE.md	전역 규칙 (모든 프로젝트 공통)	낮음
프로젝트 루트 CLAUDE.md	프로젝트 공통 규칙	중간
서브디렉토리 CLAUDE.md	도메인별 세부 규칙	높음

가까운 쪽이 우선 적용된다. n8n 워크플로우 프로젝트라면 루트에 공통 규칙을 두고, workflows/ 디렉토리 하위에 도메인 룰을 따로 배치하면 된다. 티켓팅에 비유하면 전국 공통 입장 규칙이 먼저 통과되고 VIP 구역 규칙이 나중에 덮이는 구조다.

핵심은 얇게, 핵심만, 최신 상태로 유지하는 것이다. 너무 짧으면 Claude Code가 매번 확인 질문을 던지고, 너무 길면 컨텍스트 창을 잠식한다.

3. 바로 따라하는 방법

아래는 Mac Mini 4대 클러스터 환경에서 실측한 최소 유효 구조다. 이 구조를 기준점으로 삼고, 자신의 프로젝트 스택에 맞게 값만 바꾸면 된다.

# PROJECT CONTEXT
- Stack: Node 20, n8n 2.8.4, Ollama 0.3.x (Mac Mini M2 Pro)
- Infra: 4x Mac Mini TB5 mesh, Draw Things 20-step default
- Style: TypeScript strict, 함수형, 주석 한국어

# CONSTRAINTS
- 외부 API 호출 시 반드시 retry 3회 + 500ms 간격
- 포트 5678 = n8n, 11434 = Ollama, 7860 = Draw Things
- 커밋 메시지: feat/fix/chore prefix 필수

# NEVER DO
- .env 파일 직접 수정 금지
- Mac Mini 노드 직접 SSH 명령 금지 (Ansible만)

파일을 저장했으면 새 세션을 열어 확인 질문이 줄었는지 바로 점검할 수 있다.

# 파일 생성 후 Claude Code 세션을 새로 시작
# 첫 프롬프트: "현재 프로젝트 스택이 뭔지 말해줘"
# 기대 결과: CLAUDE.md에 적힌 내용을 그대로 반환

# CLAUDE.md 로딩 확인 (Claude Code 내부 명령)
cat CLAUDE.md

전역 설정을 별도로 두고 싶다면 홈 디렉토리에 파일을 하나 더 만든다.

mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md
# 모든 프로젝트에 공통으로 적용할 스타일 가이드, 절대 금지 행동 등을 여기에 작성

4. 운영할 때 조심할 점

문서는 쓰는 순간부터 썩기 시작한다. CLAUDE.md도 마찬가지다. 스택 버전이 올라가거나 포트가 변경됐는데 파일을 갱신하지 않으면 Claude Code가 잘못된 전제로 코드를 낸다. 더 나쁜 건 이 오류가 조용히 진행된다는 점이다.

# CLAUDE.md 마지막 수정 이력 확인
git log --follow -p CLAUDE.md | head -20

# 마지막 커밋 날짜만 빠르게 확인
git log -1 --format="%ci" -- CLAUDE.md

마지막 수정일이 30일을 넘었다면 그 파일은 신뢰하지 않는 편이 낫다. 실측 기준으로 CLAUDE.md 리뷰 주기는 스프린트 2회(약 4주)가 가장 적절했다. 스프린트 시작 시 CLAUDE.md 점검을 체크리스트 항목에 포함시키면 자연스럽게 유지된다.

환경별 차이도 주의할 부분이다. 루트 CLAUDE.md와 서브디렉토리 CLAUDE.md가 동일한 키(예: 포트 번호)를 다르게 정의하면 가까운 쪽이 이기지만, Claude Code가 어느 걸 따랐는지 겉으로는 확인이 어렵다. 충돌 가능성이 있는 설정은 한 곳에서만 관리하는 게 원칙이다.

---

자주 묻는 질문

CLAUDE.md는 언제 만들어두는 게 좋을까?

프로젝트 초기 세팅 시 바로 만들어두는 게 최선이다. 스택과 포트, 커밋 규칙이 확정되는 시점에 작성하면 나중에 복기할 필요가 없다. 기존 프로젝트라면 세션을 새로 열 때 Claude Code가 확인 질문을 3회 이상 던지기 시작하는 순간이 CLAUDE.md가 필요하다는 신호다.

적용 전에 무엇을 확인해야 할까?

현재 프로젝트에서 Claude Code에게 가장 자주 반복 설명하는 항목 3가지를 먼저 적어본다. 그게 CLAUDE.md의 초안이다. 포트, 스택 버전, 금지 행동 순으로 작성하면 빠진 항목이 적다. 전역 ~/.claude/CLAUDE.md와 겹치는 내용이 있다면 중복을 제거해 컨텍스트 낭비를 줄인다.

결과가 제대로 적용됐는지 어떻게 검증할까?

새 세션을 열고 "현재 프로젝트 스택이 뭔지 말해줘"라고 입력하면 된다. CLAUDE.md에 적은 내용을 그대로 반환하면 정상 로딩된 것이다. 응답이 엉뚱하거나 "모르겠습니다"가 나오면 파일 위치나 문법 오류를 점검한다. 특히 서브디렉토리 CLAUDE.md는 해당 디렉토리에서 세션을 시작해야 로딩된다.

---

마무리

CLAUDE.md 프로젝트 기억 설계의 핵심은 단순하다. 얇게 핵심만, 항상 최신 상태로 유지하면 Claude Code가 매 세션마다 시니어 동료처럼 작동한다. 세팅 토큰 낭비를 줄이고, 첫 코드 제안까지 시간을 줄이고, 반복 질문을 없애는 것 — 그 전부를 파일 하나가 처리한다.

다음 글에서는 CLAUDE.md와 연동해 Claude Code가 자율적으로 태스크를 분기하는 멀티 에이전트 구조를 다룰 예정이다.

---

🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: Code 실전
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독