CLAUDE.md @참조로 다른 파일 불러오기

CLAUDE.md의 @참조는 @docs/spec.md처럼 적은 파일을 세션 시작 시 컨텍스트에 함께 읽어 들이는 기능입니다. 상세한 API 사양서나 스타일 가이드를 별도 파일로 분리하고 CLAUDE.md 본체는 개요와 핵심 규칙만 남겨 짧게 유지할 수 있습니다. CLAUDE.md 작성법에서 권하는 "200줄 이하"를 지키면서도 상세 문서를 함께 쓰고 싶을 때 가장 먼저 꺼내 드는 도구입니다.

핵심 요약

• @path/to/file.md라고 적으면 그 파일 내용이 컨텍스트에 읽혀 들어옵니다
• 사양서·스타일 가이드·DB 스키마 같은 기존 문서를 그대로 활용할 수 있습니다
• 경로는 @참조를 적은 파일 자신의 위치를 기준으로 한 상대 경로입니다
• 백쿼트로 감싸면 평가되지 않습니다(가장 흔한 실수)
• 참조 파일이 많을수록 컨텍스트를 소비하므로 꼭 필요한 것만 남깁니다

@참조는 어떤 문제를 푸는가

CLAUDE.md는 세션마다 통째로 로드됩니다. 편리하다고 API 엔드포인트 목록, 데이터베이스 스키마, 코딩 규약을 전부 적어 넣다 보면 금방 수백 줄이 되고, 매 세션 그만큼의 고정 비용이 생깁니다.

@참조는 이 문제를 "분리"로 풉니다. 예를 들어 API 사양을 docs/api-specification.md로 빼 두고 CLAUDE.md에 @docs/api-specification.md 한 줄만 적으면, Claude Code가 시작할 때 그 파일 내용을 자동으로 읽어 프로젝트 컨텍스트로 인식합니다. CLAUDE.md 본체에는 개요와 중요한 규칙만 남고, 상세 정보는 전용 파일이 맡는 구조가 됩니다.

기본 사용법

서식은 한 줄입니다. 제목 아래에 경로를 적기만 하면 됩니다.

## API 사양
@docs/API_SPECIFICATION.md

## 코딩 스타일
@docs/CODING_STYLE.md

## 데이터베이스 스키마
@docs/DATABASE_SCHEMA.md

이렇게 적어 두면 Claude는 작업을 시작하는 시점에 이미 세 문서의 내용을 파악한 상태가 됩니다. 세션 안에서 "API 사양서를 읽어줘"라고 매번 부탁할 필요가 없어집니다.

경로는 어디를 기준으로 쓰나

경로의 기준은 @참조를 적은 파일 자신의 위치입니다. 작업 디렉터리가 아니라는 점에 주의하세요. 절대 경로도 쓸 수 있습니다.

프로젝트 루트의 CLAUDE.md에 적는 경우에는 CLAUDE.md가 있는 곳이 곧 프로젝트 루트이므로, 결과적으로 "프로젝트 루트 기준 상대 경로"와 같은 모양이 됩니다.

기준이 달라지는 경우는 세 가지입니다. .claude/CLAUDE.md에 적을 때, 하위 디렉터리의 CLAUDE.md에 적을 때, 그리고 @참조로 불러온 파일이 다시 다른 파일을 @참조할 때입니다. 이때는 각 파일 자신의 위치가 기준이 됩니다.

my-project/
├── CLAUDE.md          # 여기서 @docs/spec.md
├── docs/
│   └── spec.md

위 구조라면 루트 CLAUDE.md에는 @docs/spec.md라고 적으면 되고, 상위 폴더를 가리킬 때는 @../docs/spec.md처럼 적습니다. 파일을 어디에 둘지 자체가 고민된다면 CLAUDE.md 배치 장소와 우선순위를 먼저 읽어 두면 좋습니다.

여러 파일을 참조하려면

@참조를 줄마다 나열하면 됩니다. 분야별로 소제목을 달아 두면 나중에 봤을 때 무엇을 왜 불러오는지 한눈에 들어옵니다.

## 프로젝트 고유 정보

### API 관련
@docs/api/endpoints.md
@docs/api/authentication.md

### 설계 문서
@docs/architecture/overview.md
@docs/architecture/database.md

### 개발 가이드라인
@docs/guidelines/code-style.md
@docs/guidelines/testing.md

참조한 파일은 전부 컨텍스트에 올라갑니다. 여섯 개를 적으면 여섯 파일 분량의 토큰을 매 세션 씁니다. "이 문서가 정말 매 세션 필요한가"를 한 번씩 자문하고, 아니라면 빼는 편이 좋습니다. 컨텍스트 예산을 어떻게 관리하는지는 컨텍스트 윈도우 관리에서 자세히 다룹니다.

백쿼트로 감싸면 왜 안 읽히나

처음 쓰는 분이 가장 자주 걸리는 지점입니다. 백쿼트(코드 스팬)로 감싼 @참조는 평가되지 않고 그냥 문자열로 남습니다.

❌ `@docs/spec.md`     → 평가되지 않음 (그냥 문자열)
✅ @docs/spec.md       → 평가됨 (파일이 읽혀 들어옴)

이 동작은 의도적으로 활용할 수도 있습니다. CLAUDE.md 안에서 @참조 예시를 보여 주고 싶지만 실제로 불러오고 싶지는 않을 때 일부러 백쿼트로 감싸면 됩니다.

반대로 "설정했는데 참조가 안 된다"는 상황이라면 제일 먼저 백쿼트부터 확인하세요. 마크다운 습관대로 경로를 코드 스팬으로 감싸 버린 경우가 대부분입니다.

실전 구성 예 3가지

예 1: API 사양서 분리

엔드포인트를 전부 CLAUDE.md에 적으면 금방 수백 줄이 됩니다. 사양은 별도 파일로 빼고 본체에는 규칙만 남깁니다.

# MyProject

## 개요
태스크 관리 애플리케이션

## API 사양
상세한 API 사양은 아래를 참조하세요.
@docs/api-reference.md

## 코딩 규약
- TypeScript strict 모드 필수
- 함수는 50줄 이내

docs/api-reference.md에는 엔드포인트 정의, 요청·응답 형식, 에러 코드를 적습니다. 사양이 바뀌면 그 파일만 고치면 되고 CLAUDE.md는 건드릴 일이 없습니다.

예 2: 팀별 가이드라인 분리

프론트엔드와 백엔드의 규칙이 다른 프로젝트에서는 팀 공통 규칙만 본체에 두고, 팀별 규칙은 각자 관리하는 파일로 분리합니다.

# MyProject

## 팀 공통 규칙
- 커밋 메시지는 Conventional Commits 형식
- PR은 반드시 리뷰를 받는다

## 프론트엔드
@docs/frontend/guidelines.md

## 백엔드
@docs/backend/guidelines.md

## 인프라
@docs/infrastructure/guidelines.md

각 팀이 자기 가이드라인을 독립적으로 고칠 수 있고, CLAUDE.md 본체는 팀이 커져도 늘어나지 않습니다.

예 3: 이미 있는 문서 그대로 연결

업무 사양서나 DB 설계서가 이미 저장소에 있다면 CLAUDE.md용으로 다시 쓸 필요가 없습니다. 있는 파일을 그대로 가리키면 됩니다.

# MyProject

## 프로젝트 개요
사내용 경비 정산 시스템

## 업무 사양
@docs/business-requirements.md

## 데이터베이스 설계
@docs/database-schema.md

## 외부 API 연동
@docs/external-api-integration.md

@참조와 .claude/rules/ 중 무엇을 쓸까

둘 다 "CLAUDE.md를 짧게 유지한다"는 목적은 같지만 작동 방식이 다릅니다.

API 사양서·설계서처럼 이미 있는 문서를 그대로 활용하고 싶다면 @참조가 맞습니다. 반면 "src/api/ 아래를 건드릴 때만 이 규칙을 적용"처럼 특정 파일 패턴에 조건부로 적용하고 싶다면 .claude/rules/로 규칙 모듈화가 적합합니다. 실무에서는 둘을 섞어 쓰는 편이 자연스럽습니다. 사양서는 @참조로, 코딩 규칙은 rules로 나누는 식입니다.

주의할 점

컨텍스트 소비

참조 파일이 크면 그만큼 실제 작업에 쓸 컨텍스트가 줄어듭니다. 한 파일이 수천 줄이라면 통째로 참조하기보다 Claude가 필요할 때 직접 읽게 두는 편이 나을 수 있습니다. 긴 워크플로 지침이라면 호출될 때만 로드되는 Skills로 옮기는 것도 방법입니다.

파일 수정 후 반영 시점

참조 대상 파일을 고치면 다음 Claude Code 실행 시 반영됩니다. "수정했는데 반영이 안 된다"면 현재 세션을 종료하고 다시 시작해 보세요.

상대 경로 기준 재확인

하위 폴더의 CLAUDE.md나 불러온 파일 안의 @참조는 그 파일 자신의 위치가 기준입니다. 루트 기준으로 적어 두고 "파일을 못 찾는다"는 경우가 종종 있습니다.

정리

• @참조는 CLAUDE.md에서 외부 파일을 불러와 본체를 짧게 유지하는 기능입니다
• 경로는 @참조를 적은 파일 자신의 위치 기준 상대 경로입니다
• 백쿼트로 감싸면 평가되지 않으니 안 읽힐 때는 이것부터 확인합니다
• 참조 파일 수만큼 컨텍스트를 쓰므로 꼭 필요한 문서만 남깁니다
• 기존 문서는 @참조, 조건부 규칙은 .claude/rules/로 나눠 씁니다

CLAUDE.md 본체를 어떻게 구성할지는 CLAUDE.md 실전 템플릿의 네 블록 구조를 기준으로 잡고, 그 안에서 길어지는 절을 @참조로 빼내는 순서로 진행하면 무리가 없습니다.