프로젝트별 커스터마이징

CLAUDE.md 설계의 핵심 의사결정은 "어떤 지시를 어느 스코프에 두는가"이다. 같은 규칙이라도 위치에 따라 적용 범위와 공유 대상이 달라진다. 시험은 특정 요구사항을 주고 "이 내용은 어느 CLAUDE.md에 두어야 하는가"를 의사결정 문제로 묻는다. 스코프를 잘못 고르면 팀원 전체에 강제되어야 할 규칙이 개인에게만 적용되거나, 개인 취향이 팀 저장소에 새어 들어간다.

세 가지 스코프와 배치 기준

프로젝트 CLAUDE.md(./CLAUDE.md)는 소스 관리에 커밋되어 팀과 공유된다. 그 프로젝트에서 작업하는 모든 사람과 모든 에이전트 세션에 동일하게 적용되어야 하는 규칙을 둔다. 빌드·테스트 명령, 디렉터리 구조, 아키텍처 규약, 프로젝트 고유의 코드 마킹 규칙이 여기에 속한다.

사용자 CLAUDE.md(~/.claude/CLAUDE.md)는 한 개발자의 모든 프로젝트에 걸쳐 적용되는 개인 전역 메모리다. 커밋 메시지 형식 선호, 파일 명명 습관, 응답 언어, 개인 워크플로우처럼 프로젝트와 무관하게 일관되게 지키고 싶은 규칙을 둔다. 이 책의 사용자 환경에서 글로벌 CLAUDE.md가 Conventional Commits 규격이나 한국 학회 논문 작법 같은 공통 규칙을 담는 것이 전형적인 예다.

조직 정책 CLAUDE.md(enterprise managed policy)는 IT/DevOps가 배포하며 개인이 제외할 수 없다. 보안 정책, 컴플라이언스 요구, 조직 차원의 금지 사항처럼 모든 구성원에게 무조건 강제되어야 하는 규칙을 둔다. 시험 포인트: managed policy의 CLAUDE.md는 claudeMdExcludes 같은 제외 설정으로도 배제할 수 없어, 조직 지시가 개인 설정과 무관하게 항상 적용된다.

하위 디렉터리 CLAUDE.md

단일 저장소(monorepo)나 다중 모듈 프로젝트에서는 하위 디렉터리에 CLAUDE.md를 두어 해당 영역에만 적용되는 규칙을 추가할 수 있다. 예를 들어 frontend/CLAUDE.md와 backend/CLAUDE.md를 두면 각 영역에서 작업할 때 루트 CLAUDE.md에 더해 해당 디렉터리의 규칙이 함께 적용된다. 이는 영역별로 다른 기술 스택·규약을 가진 프로젝트에서 루트 파일을 비대하게 만들지 않으면서 국소 규칙을 주입하는 방법이다. 이 책의 워크스페이스에서 05_프로젝트/CLAUDE.md가 상위 ~/workspace/CLAUDE.md를 보완하는 구조가 같은 패턴이다.

Progressive Disclosure 적용

스코프 분리와 별개로, 각 CLAUDE.md 내부에서도 핵심만 본문에 두고 세부는 분리하는 것이 좋다. 본문은 300줄 미만으로 유지하고, 영역별 상세 규칙은 별도 문서로 두어 경로로 참조한다. 이렇게 하면 매 세션 적재되는 본문이 가벼워지고, 필요한 세부 규칙만 작업 맥락에서 찾아 읽도록 유도할 수 있다. 다만 @import로 끌어온 파일은 시작 시 전부 로드되므로(01절 참조), 토큰 절감을 노린다면 import가 아니라 경로 언급(참조)으로 두어 Claude가 필요할 때만 읽게 하는 편이 효과적이다.

정리

• 팀 전원에 적용할 규칙은 프로젝트 CLAUDE.md(./CLAUDE.md, 커밋됨), 개인 전역 규칙은 사용자 CLAUDE.md(~/.claude/CLAUDE.md)에 둔다.
• 조직 정책 CLAUDE.md(enterprise managed)는 개인이 제외할 수 없으며 항상 강제된다. claudeMdExcludes로도 배제 불가다.
• monorepo에서는 하위 디렉터리 CLAUDE.md로 영역별 국소 규칙을 추가하며, 루트 규칙과 함께 적용된다.
• 스코프 선택은 "공유 대상과 적용 범위가 무엇인가"로 판단한다. 시험은 요구사항을 주고 올바른 배치 위치를 묻는다.
• 본문은 짧게 유지하고 세부는 분리하는 Progressive Disclosure를 적용하되, 토큰 절감 목적이면 @import 대신 경로 참조를 쓴다.