Claude Code Rules란 무엇인가? .claude/rules 폴더와 paths Frontmatter가 규칙 로드 시점을 결정하는 방법 (2026)

Anthropic의 memory(기억) 문서는 이를 다음과 같이 소개합니다: "대규모 프로젝트의 경우, .claude/rules/ 디렉토리를 사용하여 지침을 여러 파일로 구성할 수 있습니다. 이를 통해 지침을 모듈화하고 팀에서 유지 관리하기 쉽게 유지할 수 있습니다."

규칙은 마크다운 파일입니다. 프로젝트의 .claude/rules/ 디렉토리에 파일당 하나의 주제를 넣고, testing.md 또는 api-design.md와 같이 다루는 내용을 나타내는 이름을 지정합니다. "모든 .md 파일은 재귀적으로 검색되므로, 규칙을 frontend/ 또는 backend/와 같은 하위 디렉토리로 구성할 수 있습니다."

두 가지 종류가 있습니다:

• paths frontmatter가 없는 규칙. 모든 세션이 시작될 때 로드됩니다.
• 경로 범위(Path-scoped) 규칙. paths 필드가 있으며 Claude가 일치하는 파일로 작업할 때만 로드됩니다.

문서에서는 참고 사항을 통해 트레이드오프를 요약합니다: "규칙은 매 세션마다 또는 일치하는 파일이 열릴 때 context에 로드됩니다. 항상 context에 있을 필요가 없는 작업별 지침의 경우, 대신 skills를 사용하세요. skills는 사용자가 호출하거나 Claude가 프롬프트와 관련이 있다고 판단할 때만 로드됩니다."

paths 필드가 없는 규칙은 프로젝트 지침의 일부처럼 작동합니다. "paths frontmatter가 없는 규칙은 .claude/CLAUDE.md와 동일한 우선순위로 실행 시 로드됩니다."

따라서 범위가 지정되지 않은 규칙은 Claude가 보는 내용을 바꾸지 않고 긴 CLAUDE.md를 분할하는 방법이 됩니다. 내용은 여전히 매 세션마다 로드되지만, 별도의 파일로 유지 관리하기가 더 쉬워집니다.

경로 범위 규칙은 glob 패턴을 나열하는 YAML frontmatter로 시작합니다.

---
paths:
  - "src/api/**/*.ts"
---

- 모든 API 엔드포인트는 입력 유효성 검사를 포함해야 함
- 표준 에러 응답 형식을 사용함

문서에서는 트리거에 대해 구체적으로 설명합니다: "경로 범위 규칙은 Claude가 일치하는 파일에 대해 Read, Write 또는 Edit 도구를 사용할 때 로드됩니다." 또한 Claude가 단일 파일에 대해 cat 또는 head와 같이 읽기로 간주되는 Bash 명령으로 일치하는 파일을 볼 때도 로드되며, 프로젝트 디렉토리에 대한 심볼릭 링크 경로를 통해서도 작동합니다.

두 가지 결과가 따릅니다:

• 파일을 언급하는 것만으로는 충분하지 않습니다. 규칙은 사용자가 프롬프트에서 파일 이름을 말할 때가 아니라, Claude가 일치하는 파일을 읽거나 쓰거나 수정할 때 로드됩니다.
• 규칙은 시작할 때 존재하지 않습니다. Claude가 일치하는 파일을 건드리기 전까지는 해당 규칙이 context에 포함되지 않습니다.

패턴 매칭 방법

패턴은 규칙의 기본 디렉토리를 기준으로 합니다. 프로젝트 규칙의 경우 규칙의 .claude 폴더가 포함된 디렉토리입니다. 사용자 수준 규칙의 경우 세션의 기본 작업 디렉토리입니다.

여러 패턴을 나열하고 src/**/*.{ts,tsx}와 같은 중괄호 확장(brace expansion)을 사용할 수 있습니다. 중괄호 확장에는 예산이 있습니다. 규칙의 전체 paths 목록은 "1,000개의 확장된 패턴과 4 MiB의 예산"을 공유하며, 이를 초과하는 패턴은 확장되지 않은 상태로 사용되므로 중괄호가 어떤 파일과도 일치하지 않게 됩니다.

대괄호는 glob 구문입니다. 대괄호 표현식으로 읽을 수 없는 [가 포함된 패턴은 유효하지 않으며 아무것도 일치시키지 못하지만, 규칙의 다른 패턴은 계속 작동합니다. 리터럴 [를 일치시키려면 이스케이프 처리를 하세요.

Worktrees는 흔히 저지르는 실수입니다. 문서에 따르면 형제 git worktree에 있는 파일에 대해 경로 범위 규칙을 로드하려면 해당 worktree에서 Claude Code를 시작하거나 /cd를 사용하여 세션을 해당 위치로 이동해야 합니다.

Frontmatter에 포함될 수 있는 내용

오직 하나의 필드만 중요합니다. "paths는 Claude Code가 규칙에서 읽는 유효한 유일한 필드이며, 다른 모든 필드는 오류 없이 무시됩니다." Claude Code는 규칙을 로드하기 전에 frontmatter를 제거하므로 context를 차지하지 않습니다.

YAML이 파싱되지 않으면 규칙이 그냥 조용히 실패하는 것이 아닙니다. Claude Code는 "frontmatter를 무시하고 paths가 없는 것처럼 규칙을 로드합니다." frontmatter의 오타는 범위가 지정된 규칙을 매 세션마다 로드되는 규칙으로 바꿔버립니다. 파싱 오류를 확인하려면 claude --debug를 실행하세요.

규칙은 프로젝트별로만 존재하는 것이 아닙니다. "~/.claude/rules/에 있는 개인 규칙은 머신의 모든 프로젝트에 적용됩니다." 이는 단일 코드베이스에 얽매이지 않는 선호도에 적합합니다.

사용자 규칙과 프로젝트 규칙이 충돌할 때는 순서가 중요합니다. "Claude Code는 프로젝트 규칙보다 사용자 수준 규칙을 먼저 로드하므로, 프로젝트 규칙은 Claude의 context에서 사용자 규칙보다 나중에 나타납니다. 어느 쪽도 다른 쪽을 덮어쓰지 않습니다. 사용자 규칙과 프로젝트 규칙이 충돌하면 Claude는 둘 중 하나를 따를 수 있으므로 두 규칙을 일관되게 유지하세요." 충돌하는 CLAUDE.md 레이어를 조정하는 가이드에서 이러한 충돌을 찾는 방법을 다룹니다.

심볼릭 링크로 규칙 공유하기

.claude/rules/ 디렉토리는 심볼릭 링크를 지원하므로, 팀에서 하나의 규칙 세트를 유지 관리하고 이를 여러 프로젝트에 링크할 수 있습니다. 심볼릭 링크가 작업 디렉토리 외부를 가리키는 경우 Claude Code는 이를 외부 임포트로 취급합니다. 링크된 규칙은 프로젝트에 대해 외부 임포트를 승인할 때까지 로드되지 않으며, 그 후에는 paths 필드가 없는 규칙만 로드됩니다. 네트워크 경로에 대한 심볼릭 링크는 전혀 로드되지 않습니다.

둘 다 사용자가 작성하는 지침입니다. 발견되는 방식과 로드되는 시점이 다릅니다.

하위 디렉토리의 CLAUDE.md 파일도 필요에 따라 로드되므로, 디렉토리별 범위 지정은 두 방식 모두 가능합니다. Rules는 패턴별 범위 지정을 추가하여, 위치에 상관없이 모든 테스트 파일과 같이 디렉토리를 가로지르는 범위를 지정할 수 있습니다.

온디맨드(On-demand) 파일은 제한을 공유합니다. 경로 범위 규칙과 하위 디렉토리 CLAUDE.md 파일은 각각 파일당 크기 제한이 있으며, Claude는 제한을 초과하는 파일의 시작 부분만 수신합니다. Claude Code의 하위 디렉토리 CLAUDE.md 제한 가이드에서 수치와 확인 방법을 다룹니다.

다른 코딩 도구와 지침을 공유하는 경우, Cursor와 Claude Code 간에 하나의 memory를 공유하는 가이드에서 각 도구가 읽는 파일을 다룹니다.

압축은 두 종류의 규칙을 다르게 취급합니다. context window 문서는 프로젝트 루트의 CLAUDE.md와 범위가 지정되지 않은 규칙을 압축 후 "디스크에서 다시 주입(Re-injected)"되는 것으로 나열하며, paths: frontmatter가 있는 규칙은 필요에 따라 다시 로드되는 것으로 나열합니다.

그 이유는 다음과 같습니다: "경로 범위 규칙과 중첩된 CLAUDE.md 파일은 Claude가 트리거 파일을 읽거나 쓰거나 수정할 때 메시지 기록에 로드되므로, 압축 시 다른 모든 내용과 함께 요약되어 사라집니다." 압축 후 경로 범위 규칙은 Claude가 일치하는 파일을 다시 건드릴 때만 다시 돌아옵니다.

문서에서는 누락되어서는 안 되는 규칙에 대해 직접적인 지침을 제공합니다: "규칙이 압축 후에도 유지되어야 한다면 paths: frontmatter를 삭제하거나 프로젝트 루트의 CLAUDE.md로 옮기세요." Claude Code의 자동 압축(auto-compact) 대상을 설정하는 가이드에서 압축이 유지하는 나머지 항목들을 다룹니다.

규칙에 범위를 지정하고 시작할 때 로드되기를 기대함. 경로 범위 규칙은 세션이 시작될 때가 아니라 Claude가 일치하는 파일을 건드릴 때 로드됩니다.

frontmatter에 description과 같은 필드 추가. paths만 읽히며, 다른 필드는 오류 없이 무시됩니다.

잘못된 YAML 작성. 이 경우 규칙은 paths가 없는 것처럼 매 세션마다 로드됩니다.

반드시 따라야 하는 규칙을 paths 뒤에 배치. 압축 후에는 일치하는 파일을 다시 건드릴 때까지 사라집니다.

서로 충돌하는 사용자 규칙과 프로젝트 규칙 유지. 어느 쪽도 우선하지 않으며 Claude는 둘 중 하나를 따를 수 있습니다.

형제 worktree에서 실행. 다른 worktree의 경로 범위 규칙은 해당 위치에서 세션을 시작하거나 /cd로 이동하지 않는 한 로드되지 않습니다.

1단계: CLAUDE.md를 주제별 파일로 분할

긴 CLAUDE.md의 각 독립적인 섹션을 .claude/rules/의 자체 파일로 옮기고, 다루는 내용을 나타내는 이름을 지정합니다. 처음에는 범위 지정을 하지 않은 상태로 둡니다. Claude가 보는 내용은 아직 변하지 않으며, 파일이 읽기 및 검토하기 더 쉬워질 뿐입니다.

2단계: 가끔씩만 관련 있는 규칙에 범위 지정

결제 모듈, 테스트 프레임워크, 프런트엔드 디렉토리와 같이 특정 파일에만 중요한 규칙에 paths를 추가합니다. 압축 후에도 유지되어야 하는 규칙을 포함하여 Claude가 모든 작업에서 따라야 하는 규칙은 범위 지정을 하지 않은 상태로 둡니다. 각 패턴을 저장소의 실제 파일 경로와 대조하여 확인하고, 각 범위 지정 파일이 파일당 크기 제한 내에 있도록 유지합니다.

3단계: 실제로 로드된 규칙 확인

/context를 실행하여 실행 시 어떤 CLAUDE.md와 규칙 파일이 로드되었는지 확인합니다. 경로 범위 규칙은 트리거되기 전까지는 나타나지 않습니다. 트리거가 발생하는 것을 실시간으로 보려면 문서에서 제안하는 InstructionsLoaded 훅을 사용하세요. 이 훅은 어떤 CLAUDE.md와 규칙 파일이 언제, 왜 로드되는지 기록합니다. 규칙이 로드되어야 하는데 로드되지 않았다면 패턴, 기본 디렉토리, frontmatter, 그리고 프로젝트 설정을 건너뛰는 --setting-sources가 프로젝트 규칙을 제외했는지 확인하세요.

규칙이 로드되었음에도 Claude가 여전히 따르지 않는 경우, AI 에이전트가 지침 파일을 무시하는 이유 가이드에서 다른 원인들을 다룹니다. 그리고 Claude에게 준 수정 사항이 유지되지 않는다면, Claude Code가 수정 사항을 잊어버리는 이유 가이드에서 수정 사항이 어디로 가는지 설명합니다.

규칙은 저장소의 코드가 어떻게 작성되어야 하는지에 대한 지침을 두기에 적합한 장소입니다. 하지만 그 이면의 추론(왜 컨벤션이 존재하는지, 어떤 대안을 시도했는지, 코드보다는 회의에서 결정된 사항 등)을 담기에는 덜 적합합니다. 이러한 context는 하나 이상의 저장소와 하나 이상의 도구에 중요합니다.

MemoryLake는 이러한 종류의 context를 사용자가 관리하는 하나의 목록으로 유지하고, Claude Code뿐만 아니라 Codex 및 ChatGPT와 같이 연결된 다른 어시스턴트에서도 사용할 수 있게 해주는 memory 레이어입니다.

사용자는 자신의 언어로 직접 항목을 작성합니다. .claude/rules/ 파일, CLAUDE.md 파일, 자동 memory 또는 공급업체의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다. Claude Code는 Anthropic이 설명하는 방식대로 규칙을 계속 로드합니다.

1단계: API 키 생성

로그인하고 대시보드에서 키를 생성합니다. 키는 MemoryLake 워크스페이스에 속하며 Claude 계정과는 별개입니다.

2단계: 첫 번째 memory 업로드

규칙 이면의 이유부터 시작하세요: 컨벤션이 존재하는 이유, 무엇을 대체했는지, 그 전에 무엇이 잘못되었는지 등입니다. 항목당 하나의 포인트를 작성하고, 날짜를 기입하고, 설명하는 저장소나 규칙 파일로 레이블을 지정합니다.

3단계: AI 및 에이전트 연결

Claude Code와 사용하는 다른 어시스턴트를 연결합니다. 규칙은 저장소에 유지되고, 추론은 작업이 일어나는 어디에서나 사용할 수 있습니다.

첫 번째 차이점은 CLAUDE.md가 내용을 잃지 않으면서도 짧아진다는 것입니다. 주제 파일이 동일한 지침을 전달하며, 범위가 지정된 파일은 필요하지 않은 세션에서 context를 차지하지 않게 됩니다.

두 번째는 규칙이 언제 작동하는지 알 수 있다는 것입니다. 범위가 지정되지 않은 규칙은 시작부터 존재하며 압축 후에도 돌아옵니다. 범위 지정 규칙은 첫 번째 일치하는 파일과 함께 도착하며 압축 후 사라질 수 있습니다.

세 번째는 누락된 규칙을 추측하는 대신 /context와 InstructionsLoaded 훅으로 확인할 수 있다는 점입니다.

파일당 하나의 주제. 다루는 내용에 따라 파일 이름을 지정하세요.

필수 규칙은 범위 미지정 상태로 유지. 매 세션마다 로드되고 압축 후에도 유지됩니다.

조건부인 것만 범위 지정. 그리고 실제 경로에 대해 패턴을 테스트하세요.

frontmatter에는 paths만 사용. 다른 필드는 무시됩니다.

YAML 유효성 검사. 유효하지 않은 frontmatter는 범위 지정 규칙을 모든 곳에서 로드되게 만듭니다.

사용자 규칙과 프로젝트 규칙을 일관되게 유지. 어느 쪽도 다른 쪽을 덮어쓰지 않습니다.

/context로 확인. 그리고 InstructionsLoaded 훅을 사용하여 트리거를 디버깅하세요.

Claude Code rules는 지침을 주제별로 나누는 .claude/rules/ 내의 마크다운 파일입니다. paths가 없는 규칙은 .claude/CLAUDE.md와 동일한 우선순위로 실행 시 로드되며 압축 후 다시 주입됩니다. paths가 있는 규칙은 Claude가 일치하는 파일을 읽거나 쓰거나 수정할 때 로드되며, 압축 시 트리거될 때까지 요약되어 사라집니다. ~/.claude/rules/에 있는 사용자 수준 규칙은 프로젝트 규칙보다 먼저 로드되며, 어느 쪽도 다른 쪽을 덮어쓰지 않습니다.

긴 지침을 주제별 파일로 나누고, 진정으로 조건부인 것만 범위를 지정하고, 필수 규칙은 범위 미지정 상태로 유지하며, /context로 로드된 항목을 확인하세요.