CLAUDE.md부터 모듈형 규칙까지
Claude Code는 세션이 끝나면 이전 내용을 기억하지 못한다. 새 세션을 시작할 때마다 백지 상태가 된다
그래서 “이 프로젝트에서는 이렇게 해줘”를 매번 다시 설명하는 대신, 파일로 만들어두면 된다. Claude Code가 세션을 시작할 때 자동으로 읽는 이 파일이 CLAUDE.md다
메모리 파일의 종류
어디에 두느냐에 따라 적용 범위가 달라진다
~/.claude/CLAUDE.md ← 사용자 메모리: 이 PC의 모든 프로젝트에 적용 ~/my-project/CLAUDE.md ← 프로젝트 메모리: 이 프로젝트에만 적용 (팀 공유 가능) ~/my-project/.claude/CLAUDE.md ← 위와 동일 (위치만 다름) ~/my-project/CLAUDE.local.md ← 로컬 메모리: 나만의 규칙 (Git에서 제외)
사용자 메모리는 모든 프로젝트에 공통으로 적용할 규칙을 담는다. Git 스타일, 코딩 선호도, PC 환경 정보(Windows 사용자라면 특히 중요)같은 것들이 여기에 어울린다
프로젝트 메모리가 가장 자주 쓰인다. 이 프로젝트의 기술 스택, 코드 스타일, 자주 쓰는 명령어 등을 기재한다. Git으로 커밋하면 팀원과 공유된다
로컬 메모리(CLAUDE.local.md)는 팀과 공유하지 않을 개인 규칙만 담는다. 자동으로 .gitignore 추가되지 않으므로, 사용한다면 직접 .gitignore에 명시해야 한다
CLAUDE.md 작성 기준 세 가지
구체적으로 써야 한다
모호한 규칙은 모호한 결과를 낳는다
# 나쁜 예 - 코드를 적절히 포맷합니다 # 좋은 예 - 들여쓰기는 2칸 공백 사용 - 세미콜론 생략 - 타입은 interface보다 type 사용
구조적으로 써야 한다
항목별로 그룹핑해서 작성하면 Claude가 더 잘 따른다. 긴 문장보다 리스트 형식이 준수율이 높다
중요한 규칙은 강조해야 한다
Claude는 100% 준수를 보장하지 않는다. 메모리 파일이 길어질수록 누락 가능성이 높아진다. 꼭 지켜야 할 규칙에는 강조 구문을 붙인다
IMPORTANT: 절대로 .env 파일을 수정하지 마세요 YOU MUST: 코드 변경 전 반드시 테스트를 실행할 것
공식 문서에서도 500줄 이하로 유지하도록 권장한다
import 문법 – 기존 파일을 메모리로 연결하기
CLAUDE.md 안에서 @파일경로 형식으로 다른 파일을 불러올 수 있다
# CLAUDE.md 프로젝트 개요는 @README.md 를 참고하세요. npm 명령어는 @package.json 을 참고하세요. Git 규칙은 @docs/git-instructions.md 를 따르세요.
프로젝트에 이미 존재하는 문서를 복사 · 붙여넣기 하지 않고 그대로 가져올 수 있다. CLAUDE.md를 짧게 유지하면서도 필요한 정보를 연결하는 방법이다
모듈형 메모리 – 규칙이 많아졌을 때
CLAUDE.md 한 파일이 커지면 관리가 어려워진다. 이때 .claude/rules/ 디렉터리를 사용한다
my-project/
└── .claude/
└── rules/
├── code-style.md
├── git-rules.md
└── api-conventions.md
이 디렉터리 안의 모든 .md 파일은 Claude Code가 실행될 때 자동으로 프로젝트 메모리에 로드된다. CLAUDE.md에 import를 추가할 필요가 없다.
파일 이름만 봐도 내용을 알 수 있도록 짓는 것이 중요하다. rule1.md보다 code-style.md가 낫다
특정 파일에만 규칙 적용하기
모듈형 규칙 파일 상단에 paths frontmatter를 추가하면 특정 디렉터리에만 규칙이 적용된다
---
paths:
- "src/api/**/*.ts"
---
# API 규칙
- 모든 엔드포인트는 zod로 입력값을 검증할 것
- 에러 응답은 반드시 { error: string } 형태로 반환
이 규칙은 src/api/ 하위의 .ts 파일을 다룰 때만 로드된다. 불필요한 규칙이 컨텍스트를 차지하지 않게 된다.
단, paths frontmatter는 꼭 필요할 때만 쓰는 것이 좋다. 많아질수록 오히려 관리가 복잡해진다.
사용자 레벨에서도 동일하게 적용 가능하다
~/.claude/rules/ ├── my-code-style.md └── my-git-preferences.md
이 위치에 두면 모든 프로젝트에 공통으로 적용된다.
/Memory 명령어로 현재 로드된 메모리 확인하기
Claude Code 안에서 /memory를 입력하면 현재 세션에 어떤 메모리 파일이 로드되어 있는지 확인할 수 있다. 목록에서 항목을 선택하면 해당 파일을 바로 열어 편집할 수 있다
한 줄 요약
CLAUDE.md로 시작하고, 기존 문서는 import로 연결하고, 규칙이 많아지면 .claude/rules/로 나눈다
처음부터 완벽하게 만들 필요는 없다. 프로젝트를 진행하면서 Claude에게 반복적으로 설명하는 내용이 생길 때, 그때 하나씩 추가해 나가면 된다