CLAUDE.md가 길어질 때 토픽별로 쪼개고, 특정 파일을 만질 때만 규칙이 로드되게 하는 방법을 정리합니다. .claude/rules/ 디렉토리, paths 프론트매터로 path-scoped rules, @ 멘션 import의 5단계 재귀, AGENTS.md 호환, user/project rules 우선순위, 모노레포에서 다른 팀 CLAUDE.md 제외, /memory와 InstructionsLoaded 훅으로 디버깅까지 다룹니다.
📌 다루는 내용
- CLAUDE.md 200줄 권장 한도와 길어졌을 때의 준수율 하락 문제
- .claude/rules/ 디렉토리: 토픽별 마크다운 분리, 재귀 발견, 서브디렉토리(frontend/, backend/) 지원
- 무조건 로드 vs path-scoped: paths 프론트매터의 동작 차이와 글롭 패턴(브레이스 확장)
- @ 멘션 import: 상대/절대 경로, 최대 5단계 재귀, 첫 외부 import 승인 다이얼로그
- AGENTS.md 호환 패턴: @AGENTS.md import 후 Claude 전용 지침 추가
- ~/.claude/rules/ user-level rules와 project rules 우선순위, 심볼릭 링크로 여러 프로젝트에 규칙 공유
- 모노레포 노이즈 제거: claudeMdExcludes 글롭 패턴, managed policy 예외
- 추가 디렉토리에서 rules 로드: CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 환경 변수
- 디버깅: /memory로 로드된 파일 확인, InstructionsLoaded 훅으로 audit log
📌 환경 정보
- Claude Code 최신 버전 (.claude/rules/와 paths 프론트매터 지원)
- claude --version으로 버전 확인
- Git 저장소 환경 (.claude/ 커밋 전제)
📌 챕터
0:00 CLAUDE.md만으로 부족해지는 순간
1:43 .claude/rules/ 디렉토리 구조
2:50 path-scoped rules: paths 프론트매터
3:32 글롭 패턴과 브레이스 확장
5:08 @ 멘션 import와 5단계 재귀
6:55 import vs path-scoped 차이
7:23 AGENTS.md 호환 패턴
7:57 user vs project rules 우선순위
8:46 팀과 규칙 공유, 심볼릭 링크
11:22 claudeMdExcludes로 모노레포 제외
12:07 /memory와 InstructionsLoaded 훅 디버깅
📌 참고 링크
- 블로그: https://neosarchizo.github.io/posts/claude-code-23-conditional-rules-and-file-references
- 공식 문서 Memory: https://code.claude.com/docs/en/memory
- Hooks reference: https://code.claude.com/docs/en/hooks
- CLI reference: https://code.claude.com/docs/en/cli-reference
- Settings: https://code.claude.com/docs/en/settings
- Sub-agents: https://code.claude.com/docs/en/sub-agents
#ClaudeCode #ClaudeRules #ClaudeMD
