Claude Code의 CLAUDE.md를 @import로 분할하여 토픽별 규칙으로 정리하기

Claude Code를 사용하다 보면 프로젝트별 또는 사용자별로 CLAUDE.md를 작성하게 됩니다. 처음에는 파일 하나로 충분하지만, 규칙을 추가하다 보면 200행을 넘어서게 되고, 매 세션마다 그대로 읽히면서 컨텍스트 (Context)가 무거워집니다.

이 기사에서는 CLAUDE.md를 @import 구문을 사용하여 토픽별 파일로 분할한 구성과, 분할할 때 결정한 판단 기준을 정리합니다.

대상은 다음과 같은 분들을 상정하고 있습니다.

• Claude Code를 도입했지만 CLAUDE.md의 분할 입도 (Granularity)를 고민 중인 분
• 규칙이 늘어나면서 매 세션의 로딩이 무거워진 분
• 글로벌 규칙 (Global rules)과 프로젝트 고유 규칙 (Project-specific rules)의 위치를 정리하고 싶은 분

단일 CLAUDE.md에 규칙을 계속 써 내려가다 보니 다음과 같은 문제가 발생했습니다.

• 200행을 넘어가면 편집 중에 어디에 무엇이 있는지 알 수 없게 됨
• 규칙 하나를 수정하고 싶을 뿐인데 거대한 파일을 열어야 함
• "여기에 추가할까, 아니면 다른 곳에 추가할까"를 매번 고민하는 비용이 상승함
• 세션마다 전체 문장이 읽히기 때문에, 사용하지 않는 규칙도 토큰 (Token)을 소비함

마지막 점이 결정타였습니다. 규칙이 늘어날수록 1 세션당 컨텍스트가 압박을 받습니다.

CLAUDE.md는 import를 위한 목차로만 두고, 본체는 .claude/rules/<topic>.md로 나누었습니다.

~/.claude/
├── CLAUDE.md # 38행 (@import만 포함)
└── rules/
...

CLAUDE.md의 내용은 다음과 같이 @가 붙은 상대 경로로 나열합니다.

# 글로벌 규칙 (Global rules)
사용자에게 동조하지 않고, 목적 달성을 우선한다.
@rules/claude-md-generation.md
...

Claude Code는 세션 시작 시 CLAUDE.md를 읽고, 그 안의 @<path>를 따라가며 각 파일을 가져옵니다. 프로젝트 측 <repo>/CLAUDE.md도 동일한 서식으로 가져올 수 있습니다.

실운용에서는 다음과 같은 라인으로 정착했습니다.

기준	채택한 라인
1 파일의 입도	1 토픽 (예: git 조작, API 쿼터, 보안 코딩)
...	<repo>/.claude/rules/<topic>.md로 동일한 구조를 계승

"언제 적용할지"를 서두에 적는 이유는, 규칙이 많아졌을 때 "이 규칙이 지금 관계가 있는가"를 판단하기 쉽게 하기 위해서입니다.

예: git-ops.md의 서두는 다음과 같이 시작합니다.

# Git 조작 규칙
## git add는 개별 파일 지정
`git add -A`나 `git add .`는 사용하지 않는다.

규칙 이름(헤더)이 짧고 구체적이어서, CLAUDE.md에서 이동했을 때 어떤 규칙인지 즉시 알 수 있습니다.

분할할 때 빠졌던 함정을 정리합니다.

공식 문서 (Memory and CLAUDE.md)의 "Import additional files" 섹션에 따르면, @path/to/import 구문에는 다음과 같은 사양이 있습니다.

• 상대 경로와 절대 경로를 모두 사용할 수 있음
• 상대 경로는 import 문을 포함하는 파일로부터의 상대 경로임 (현재 작업 디렉토리가 아님)
• import는 재귀적으로 최대 5 hop까지 추적됨
• 홈 디렉토리 에일리어스 (Alias)도 사용 가능 (예: @~/.claude/my-project-instructions.md)

저는 처음에 "절대 경로는 사용할 수 없다"고 오해하여 상대 경로로만 작성했었지만, 워크트리 (Worktree)를 넘나들며 개인 설정을 공유할 경우에는 다음과 같이 ~/를 기점으로 하는 절대 경로 import가 편리합니다.

# Individual Preferences
- @~/.claude/my-project-instructions.md

이것은 설계상의 함정입니다. 공식 문서에도 명시되어 있지만, import로 분할하더라도 imported files load at launch, 즉 세션 시작 시에 전부 전개되어 컨텍스트에 올라갑니다.

Splitting into

@path

@import 분할은 조직화에는 도움이 되지만, 임포트된 파일이 실행 시점에 로드되기 때문에 컨텍스트 (Context) 크기를 줄여주지는 않습니다.

( Memory and CLAUDE.md - My CLAUDE.md is too large )

즉, @import 분할은 편집 용이성과 정리를 위한 것이며, 토큰 (Token) 소비 자체를 줄여주지는 않습니다. 진심으로 컨텍스트를 줄이고 싶다면, 공식 문서에서 안내하는 .claude/rules/ 디렉토리의 paths 프론트매터 (frontmatter, path-scoped rules)를 사용하여, 대상 파일을 열었을 때만 읽어오도록 하는 방법을 병행해야 합니다.

저의 운영 방식에서는 다음과 같이 나누고 있습니다.

• 모든 프로젝트에 상시 필요한 규칙: @rules/<topic>.md로 상시 임포트 (import)
• 특정 디렉토리에서만 필요한 규칙: .claude/rules/<topic>.md에 paths: 프론트매터 (frontmatter)를 붙여 경로 범위 지정 (path-scoped) 처리

규칙이 늘어나다 보면 분할의 입도(granularity)나 임포트 (import) 작성 방식이 흔들릴 수 있습니다. 이를 방지하기 위해 claude-md-generation.md라는 메타 규칙 (meta-rule)을 하나 만들어 다음 사항을 강제하고 있습니다.

# CLAUDE.md 생성 규칙
`CLAUDE.md`를 생성하거나 작성할 때는 반드시 `.claude/rules/` 폴더도 병행하여 생성할 것.
- 규칙 내용은 토픽 (topic)별로 파일을 분할한다
...

이것을 CLAUDE.md의 앞부분 근처에서 임포트 (import)해 두면, 신규 프로젝트의 셋업 (setup)을 AI에게 맡겼을 때도 동일한 구조가 유지됩니다.

• CLAUDE.md는 @import의 목차 역할만 수행하고, 본체는 .claude/rules/<topic>.md로 분할한다
• 분할 임계값은 60~100행, 1개 파일당 1개 토픽 (topic)
• 각 규칙의 서두에 "언제 적용할지"를 선언한다
• 명명 규칙 (naming convention)과 분할 방침을 메타 규칙 (meta-rule) 한 장에 작성하여 서두에서 임포트 (import)하면, 신규 프로젝트에서도 구조가 통일된다
• 토큰 (Token) 소비 자체를 줄이고 싶다면 @import 분할만으로는 부족하다. .claude/rules/의 paths: 프론트매터 (frontmatter)를 통한 경로 범위 지정 규칙 (path-scoped rules)을 병행하여, 대상 파일을 열었을 때만 읽어오도록 구성해야 한다

규칙이 늘어나면 배치할 위치를 고민하는 비용 자체가 적지 않은 작업 시간이 됩니다. 미리 토픽 (topic)별로 분할해 두면 나중에 추가할 때 헤매지 않습니다.

• Claude Code 공식 문서: Memory and CLAUDE.md (@path/to/import 구문과 .claude/rules/ 사양)
• 상동: Import additional files 섹션 (상대 경로 / 절대 경로 / ~/ 에일리어스 (alias) / 5 hop 재귀 전개)
• 상동: Path-specific rules 섹션 (paths: 프론트매터 (frontmatter)를 통한 조건부 로드)
• 프로젝트 측 .claude/rules/ 구성 실례: harness17/DevNext - .claude/rules (ASP.NET Core 10 템플릿, 22개 파일의 토픽 분할 예시)