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

CLAUDE.md를 200줄 아래로 유지하라고 하면 첫 번째 질문이 돌아옵니다. "API 사양서 80줄은 어디에 두나요?" 답은 별도 파일로 빼고 CLAUDE.md에서 @docs/api.md 한 줄로 가리키는 것입니다. 이것이 @참조입니다. 우리 팀의 관례 "CLAUDE.md에는 규칙과 참조만, 상세는 분리"가 이 기능 위에 서 있습니다.

이 글은 @참조의 문법과 경로 기준, 백쿼트로 감싸면 왜 안 읽히는지, 실전 구성 세 가지, 그리고 .claude/rules/와 무엇이 다른지를 다룹니다. 앞 글은 「퍼미션 설정 최적화」, 다음 글은 「CLAUDE.md 배치 장소와 우선순위」입니다.

핵심 요약

• CLAUDE.md 안의 @경로는 그 파일을 세션 시작 시 함께 읽어 들입니다. 상대 경로, 절대 경로, ~/ 홈 경로 모두 됩니다.
• 상대 경로는 작업 디렉터리가 아니라 @참조가 적힌 파일의 위치가 기준입니다.
• 참조된 파일이 또 다른 파일을 참조할 수 있으며 최대 4단계까지 따라갑니다.
• 백쿼트나 코드 블록 안의 @경로는 문자 그대로 남고 읽히지 않습니다.
• @참조는 정리용이지 절약용이 아닙니다. 읽힌 파일은 그대로 컨텍스트를 차지합니다. 절약이 목적이면 .claude/rules/의 paths를 씁니다.

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

두 가지입니다. 첫째, 본체를 짧게 유지하면서도 필요한 문서를 매 세션 자동으로 싣습니다. 둘째, 이미 있는 문서를 복사하지 않고 그대로 씁니다. README, package.json, 팀 코딩 가이드는 이미 존재합니다. CLAUDE.md에 다시 베껴 넣으면 두 곳이 어긋나기 시작합니다. 한 줄로 가리키면 원본 하나만 관리하면 됩니다.

다른 코딩 에이전트와 함께 쓰는 저장소에서도 유용합니다. Claude Code는 AGENTS.md를 읽지 않으므로, CLAUDE.md 첫 줄에 @AGENTS.md를 적으면 두 도구가 같은 지침을 중복 없이 읽습니다.

기본 사용법

문장 어디에든 @경로를 적으면 됩니다.

# 프로젝트 규칙
프로젝트 개요는 @README.md, 사용 가능한 스크립트는 @package.json을 참조한다.

## 상세 문서
- API 사양 @docs/api.md
- git 워크플로우 @docs/git-flow.md

세션이 시작되면 이 CLAUDE.md와 함께 네 파일이 확장되어 컨텍스트에 실립니다. 프로젝트에서 처음 외부 참조를 만나면 파일 목록을 보여 주는 승인 대화가 뜹니다. 거부하면 그 참조는 비활성 상태로 남고 다시 묻지 않습니다.

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

핵심은 상대 경로가 "작업 디렉터리"가 아니라 "그 @참조를 담은 파일"을 기준으로 해석된다는 점입니다. backend/CLAUDE.md에 @docs/db.md라고 쓰면 backend/docs/db.md를 찾습니다. 루트의 docs/db.md를 원하면 @../docs/db.md로 씁니다.

여러 파일을 참조하려면

한 줄에 하나씩 나열하면 됩니다. 참조된 파일 안에서 다시 @를 쓸 수도 있으며, 이 연쇄는 최대 4홉까지 따라갑니다. CLAUDE.md → docs/index.md → docs/api/auth.md처럼 목차 파일을 두고 그 안에서 세부 문서를 가리키는 구성이 가능합니다. 다만 깊게 묶을수록 무엇이 실리는지 파악하기 어려워지므로 2단계 안에서 끝내는 것을 권합니다. 지금 어떤 파일이 읽혔는지는 /context의 Memory files 목록에서 확인합니다.

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

@참조 구문은 마크다운 코드 스팬과 펜스 코드 블록을 건너뜁니다. 즉 `@README.md`라고 쓰면 글자 그대로 남고, 백쿼트 없이 @README.md라고 써야 읽힙니다. 이 규칙은 반대로도 쓸 수 있습니다. "이 파일을 참조하지 말고 이름만 언급"하고 싶을 때 백쿼트로 감싸면 됩니다. 우리 레포 CLAUDE.md의 "lib/db.ts는 클라이언트에서 import하지 않는다" 같은 문장에서 경로를 백쿼트로 감싼 이유가 그것입니다. 경로를 언급했을 뿐인데 파일이 통째로 실리는 사고를 막습니다.

실전 구성 예 3가지

예 1: API 사양서 분리

project/
├── CLAUDE.md          # 규칙 20줄 + "@docs/api-spec.md"
└── docs/
    └── api-spec.md    # 엔드포인트, 요청·응답 형식, 오류 코드 80줄

CLAUDE.md에는 "API 핸들러는 app/api/ 아래에 두고 응답 형식은 @docs/api-spec.md를 따른다" 한 줄만 남깁니다. 사양이 바뀌면 docs/api-spec.md만 고칩니다.

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

# CLAUDE.md
공통 규칙은 아래 4줄이다.
1. ...
프론트엔드 스타일 @docs/guide-frontend.md
백엔드 규칙 @docs/guide-backend.md

팀마다 문서 하나씩 관리하고 루트에서 모읍니다. 다만 프론트엔드 작업 중에도 백엔드 가이드가 실린다는 점이 남습니다. 이 낭비가 크면 다음 절의 .claude/rules/로 넘어갑니다.

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

프로젝트 설명 @README.md
스크립트 목록 @package.json
다른 에이전트용 공통 지침 @AGENTS.md

새 문서를 쓰지 않고 있는 파일을 붙입니다. AGENTS.md가 이미 있으면 Claude 전용 내용만 그 아래에 덧붙입니다. Windows에서 심볼릭 링크는 관리자 권한이 필요하므로 ln -s 대신 이 방식을 씁니다.

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

"항상 알아야 하는가"를 물어 예라면 @참조, 아니라면 rules입니다. 둘을 섞어도 됩니다. 루트 CLAUDE.md는 규칙과 @참조 몇 줄, 프론트엔드 전용 규칙은 .claude/rules/frontend.md에 paths: ["app/**/*.tsx"]로 두는 식입니다.

주의할 점

컨텍스트 소비

@참조로 나눈 파일은 시작 시 전부 확장되어 실립니다. 200줄짜리 CLAUDE.md를 50줄 본체와 150줄 참조로 나눠도 컨텍스트는 그대로 200줄입니다. /context로 CLAUDE.md 항목의 토큰을 확인하고, 매 세션 필요 없는 부분은 rules나 Skill로 옮깁니다.

파일 수정 후 반영 시점

참조된 파일은 세션 시작 시 읽힙니다. 세션 중에 docs/api-spec.md를 고쳐도 지금 대화에는 반영되지 않습니다. 새 세션을 열거나, 급하면 그 파일을 Claude에게 직접 읽으라고 요청합니다. /compact 뒤에는 루트 CLAUDE.md가 디스크에서 다시 읽히므로 그 시점의 참조 내용이 실립니다.

상대 경로 기준 재확인

하위 폴더의 CLAUDE.md에서 상대 경로를 쓸 때는 그 폴더 기준입니다. 경로가 틀리면 조용히 빠지고 오류가 뜨지 않으므로, 작성 후 /context의 Memory files 목록에 들어 있는지 반드시 확인합니다.

정리

• @참조는 CLAUDE.md를 짧게 유지하면서 기존 문서를 중복 없이 붙이는 방법입니다.
• 상대 경로는 참조가 적힌 파일 기준, 최대 4홉, 백쿼트 안은 무시됩니다.
• 컨텍스트 절약은 되지 않습니다. 절약이 필요하면 .claude/rules/의 paths입니다.
• 작성 뒤 /context의 Memory files 목록으로 실제 로드를 확인합니다.

자주 묻는 질문