[Claude Code 스킬] CLAUDE.md — 프로젝트 기억을 코드처럼 버전 관리하기 | DAKER 커뮤니티
무엇
CLAUDE.md는 Claude Code가 매 세션을 시작할 때 자동으로 읽어들이는 프로젝트 메모리 파일입니다. 새 팀원이 출근 첫날 온보딩 문서를 먼저 읽듯, Claude는 이 파일에서 빌드 명령·코딩 컨벤션·아키텍처 규칙·금지사항을 흡수한 뒤 작업을 시작합니다. 매번 같은 설명을 반복할 필요가 없는 '프로젝트의 장기 기억'인 셈입니다. 평범한 마크다운이라 git으로 버전 관리하면 팀의 규칙이 코드와 함께 진화합니다.
핵심은 계층 구조입니다. 넓은 범위(조직·개인)가 먼저 깔리고, 좁은 범위(프로젝트)가 그 위를 덮어씁니다. 같은 규칙이 충돌하면 더 구체적인 쪽이 이깁니다.
언제 쓰나
빌드·테스트·린트 명령처럼 매번 알려주던 것을 고정하고 싶을 때
팀 전체가 같은 코딩 규칙·금지 패턴을 공유해야 할 때 (
CLAUDE.md를 git에 커밋)"이 프로젝트에선 X 대신 Y를 써라" 같은 관례를 Claude가 까먹지 않게 하고 싶을 때
개인 취향(한국어 설명, 함수형 스타일 등)을 내 모든 프로젝트에 적용하고 싶을 때 (
~/.claude/CLAUDE.md)
사용법
① /init — 빈손에서 시작하는 가장 빠른 길. 프로젝트 루트에서 실행하면 Claude가 코드베이스를 분석해 초안을 만들어 줍니다.
> /init # 코드베이스 스캔 → CLAUDE.md 초안 자동 생성
> /memory # 지금 로딩된 메모리 파일의 경로·순서 확인② 직접 작성 — 규칙은 짧은 명령형 한 줄로. (산문이 아니라 체크리스트처럼)
# CLAUDE.md
## 명령어
- 빌드: `npm run build`
- 단위 테스트: `npm run test:unit`
## 규칙
- 날짜·시각은 항상 UTC로 저장한다
- console.log 금지 — logger.debug() 사용
- 새 의존성 추가 전 먼저 물어본다③ @import로 모듈화 (최대 깊이 5). 거대한 단일 파일 대신 주제별로 쪼개 불러옵니다.
@~/.claude/my-style.md
@docs/architecture.md
@.claude/rules/testing.md④ 프롬프트 맨 앞에 # 를 붙이면, 저장할 파일을 골라 즉석에서 메모를 추가할 수 있습니다.
# 앞으로 PR 설명은 한국어로 작성해줘
팁
200줄 이내로 유지하세요. CLAUDE.md는 매 세션 토큰을 소비합니다. 길고 장황할수록 오히려 지시 준수율이 떨어집니다 — 컨텍스트라는 책상이 어질러지면 정작 중요한 규칙이 묻히는 원리입니다. '코드를 잘 짜라' 같은 모호한 다짐보다 'npm run lint를 통과시킨다' 같은 검증 가능한 규칙이 훨씬 잘 지켜집니다.
주제별로
.claude/rules/에 분리하고 @import로 조립하면 관리가 쉽습니다. 그리고 규칙을 적었다고 끝이 아니라,/memory로 실제 로딩 여부를 늘 확인하세요. 오타 난 경로나 깊이 초과로 조용히 빠지는 경우가 흔합니다.
