CLAUDE.md로 프로젝트 규칙을 반복 설명하지 않는 방법 | DAKER 커뮤니티
Claude Code를 쓰다 보면 같은 규칙을 세션마다 다시 설명하게 되는 순간이 자주 생깁니다. 빌드 명령, 테스트 기준, 건드리면 안 되는 영역처럼 늘 반복되는 내용이 대표적입니다.
이럴 때 프로젝트 루트의 CLAUDE.md를 정리해 두면, 매번 같은 맥락을 길게 붙이지 않아도 됩니다. 자동 메모리와의 역할 차이까지 함께 이해해 두면, 어떤 규칙을 어디에 두어야 할지도 훨씬 분명해집니다.
CLAUDE.md는 무엇을 담는 파일인가
CLAUDE.md는 Claude Code가 세션을 시작할 때 읽는 프로젝트 지침 파일입니다. 빌드 명령, 코딩 규칙, 검증 기준처럼 반복해서 전달해야 하는 사실을 한곳에 모아 둘 때 적합합니다.
CLAUDE.md는 매번 다시 설명해야 하는 프로젝트 규칙을 세션 시작 시점에 읽히는 방식으로 정리하는 파일입니다.
자동 메모리는 Claude가 작업 중 발견한 패턴을 저장하는 보조 장치입니다. 다만 두 기능 모두 강제 정책이라기보다 컨텍스트로 작동합니다. 그래서 반드시 막아야 하는 행동까지 CLAUDE.md에만 기대는 것은 적절하지 않을 수 있습니다.
언제 쓰면 좋은가
같은 수정 요청을 두 번 이상 반복했을 때, 새 팀원이 알아야 할 프로젝트 구조가 있을 때, 또는 코드 리뷰에서 Claude가 이미 알고 있었어야 할 규칙이 드러났을 때 CLAUDE.md를 쓰는 것이 좋습니다.
반대로 파일 종류별 세부 규칙은 별도 규칙 파일로 나누는 편이 낫고, 위험 명령 차단처럼 반드시 막아야 하는 행동은 hook으로 분리하는 편이 더 안전합니다.
기본 사용법
핵심은 프로젝트 루트에 짧은 규칙을 먼저 두고, 세션 안에서 실제로 어떤 기억이 로드됐는지 확인하는 흐름입니다.
- 프로젝트 루트의
CLAUDE.md에는 빌드 명령, 검증 기준, 꼭 지킬 코딩 원칙처럼 반복되는 규칙만 적습니다. - 세션을 시작한 뒤 Claude Code에서
/memory로 현재 로드된 기억을 확인하고, 오래되었거나 틀린 항목은 정리하면 됩니다. - 실패했을 때 위험한 행동은 hook으로 막고, 긴 절차는 skill이나 별도 문서로 분리해
CLAUDE.md를 짧게 유지하는 것이 좋습니다.
# 프로젝트 루트에 팀 규칙 작성
cat > CLAUDE.md <<'EOF'
# Project instructions
- Use pnpm for package scripts.
- Run pnpm test before reporting a feature as complete.
- Do not change database migrations without explicit review.
EOF
# 현재 세션에서 로드된 메모리와 규칙 확인
claude
/memory
짧게 유지해야 하는 이유
CLAUDE.md는 200줄 안팎의 짧은 원칙 파일로 유지하는 편이 좋습니다. 길고 절차적인 내용까지 한 파일에 몰아넣으면, 모델이 매번 읽어야 할 핵심이 흐려질 수 있기 때문입니다.
기대 행동은 CLAUDE.md에 두고, 실패하면 위험한 행동은 hook으로 보강하는 구성이 더 안전합니다.
예를 들어 항상 테스트 실행처럼 기대하는 행동은 CLAUDE.md에 적을 수 있습니다. 반면 삭제 금지처럼 한 번의 실수가 큰 문제로 이어질 수 있는 항목은 PreToolUse hook 같은 실행 전 차단 장치로 보강하는 편이 적절합니다.
또한 긴 절차나 상세한 운영 방식은 skill이나 별도 문서로 분리하면, CLAUDE.md는 핵심 원칙만 담는 파일로 유지할 수 있습니다.
참고 자료
기능 사실은 Anthropic Claude Code 공식 문서의 memory, extension overview, CLI reference 항목을 바탕으로 정리됐습니다. 공개 본문에는 아래 링크가 포함되어 있습니다.
여러분은 프로젝트에서 반복 설명이 가장 자주 필요한 규칙을 어떤 방식으로 정리하고 있나요?