Claude Code 임포트(Import)란? CLAUDE.md에서 다른 지침 파일 불러오는 법

AI로 홈페이지를 만들다 보면 이런 상황이 생깁니다. “프로젝트 규칙이 길어져서 파일을 나눴는데, Claude Code가 다른 파일에 적은 규칙도 읽을 수 있을까?” 이럴 때 알아두면 좋은 기능이 임포트(Import)입니다. Claude Code의 지침 파일 임포트란, CLAUDE.md 안에 @파일경로를 적어 다른 파일의 내용을 작업 지침과 함께 불러오는 기능입니다. 예를 들어 메인 규칙 파일에는 핵심 안내만 적고, 자세한 테스트 규칙은 docs/testing.md라는 별도 파일에 저장해 연결할 수 있습니다. 쉽게 말해 한 장짜리 안내문에 “자세한 규칙은 이 설명서도 함께 읽으세요”라는 표시를 붙이는 것과 비슷합니다. 다만 일반적인 웹 링크와 달리 Claude Code는 지원되는 임포트 구문을 해석해 해당 파일의 내용을 대화 맥락에 포함할 수 있습니다. 이 글은 코딩 문법 전체가 아니라 Claude Code의 지침 파일 임포트 하나를 다룹니다. 아래 예시는 교육용 가상 프로젝트이며, 실제 컴퓨터에서 실행해 검증한 화면은 아닙니다.

자체 제작 개념도 · EMFLS AI

이 글의 순서

1. 임포트가 필요한 이유부터 알아볼까요?
2. CLAUDE.md 에서 임포트하는 가장 쉬운 예시
3. @ 기호가 있으면 언제나 임포트가 되나요?
4. 파일의 위치가 중요한 이유: 상대경로와 절대경로
5. AGENTS.md 도 불러올 수 있나요?
6. 일반적인 링크와 임포트는 어떻게 다른가요?
7. 가져올 파일을 많이 나누면 토큰을 절약할 수 있나요?
8. 보안 문제가 생길 수도 있나요?
9. 임포트가 제대로 적용됐는지 확인하는 방법
10. 임포트한 파일 안에서 또 다른 파일을 불러올 수 있나요?
11. 어떤 파일은 CLAUDE.md 에, 어떤 파일은 따로 보관하면 좋을까요?
12. 초보자 실습: 내가 만든 규칙이 연결됐는지 확인하기
13. 자주 묻는 질문(FAQ)
14. 오늘 내용 세 줄 정리
공식 자료

1. 임포트가 필요한 이유부터 알아볼까요?

처음 프로젝트를 시작했을 때는 규칙이 몇 줄일 수 있습니다.

“초보자도 알아듣게 설명해 주세요.”
“기존 파일을 지우기 전에 알려 주세요.”
“수정한 뒤 테스트 결과를 보고해 주세요.” 시간이 지나면서 디자인 규칙, 코드 작성 규칙, 배포 전 점검 사항이 쌓입니다. 모든 내용을 하나의 긴 CLAUDE.md에 몰아넣으면 사람이 읽거나 고치기 어려워집니다. 임포트는 규칙의 주제별 파일을 나누고 메인 문서에서 참조하는 방법입니다. 예를 들어 편집팀이 ‘편집 원칙’과 ‘오탈자 검사표’를 따로 보관하되 작업할 때 두 문서를 함께 참고하는 방식과 비슷합니다. 그러나 파일을 나누었다고 AI가 읽어야 하는 글의 총량이 자동으로 줄지는 않습니다. 임포트한 파일도 작업 맥락에 포함되므로 너무 많은 내용을 불러오면 컨텍스트가 커질 수 있습니다.

2. `CLAUDE.md`에서 임포트하는 가장 쉬운 예시

다음은 설명을 위한 가상 프로젝트 폴더입니다.

my-blog/
├── CLAUDE.md
├── AGENTS.md
└── docs/
    └── review-rules.md

각 파일 역할은 다릅니다.

CLAUDE.md: Claude Code가 프로젝트에서 참고할 기본 지침.
AGENTS.md: 여러 AI 코딩 도구에서 사용할 수 있는 에이전트 지침 문서.
docs/review-rules.md: 이 프로젝트의 글 또는 코드 검토 규칙을 적어 둔 별도 문서. 먼저 docs/review-rules.md 파일에 다음 내용을 저장했다고 가정하겠습니다.


- 공개 글의 제목과 본문 내용이 일치하는지 확인한다.
- 실제 테스트하지 않았다면 테스트 완료라고 말하지 않는다.
- 개인정보나 API 키가 본문에 들어 있지 않은지 살펴본다.

그리고 CLAUDE.md에 다음처럼 적습니다.


- 답변은 쉬운 한국어로 작성한다.
- 추가 검토 규칙은 @docs/review-rules.md 를 참고한다.

여기에서 핵심은 @docs/review-rules.md입니다. Anthropic 공식 문서가 설명하는 파일 임포트 형식에 맞춰, Claude Code가 다른 지침 문서의 내용을 함께 참고하도록 연결한 것입니다. 이 구문을 작성했다고 파일이 자동으로 생성되는 것은 아닙니다. 참조 대상 파일이 실제로 존재해야 합니다.

3. @ 기호가 있으면 언제나 임포트가 되나요?

그렇지는 않습니다. 임포트 문법을 해석하는 위치와 작성 방식이 중요합니다. Anthropic의 현재 공식 설명에 따르면 CLAUDE.md에서 다음처럼 적는 참조를 사용할 수 있습니다.

프로젝트 개요는 @README 를 참고합니다.
테스트 규칙은 @docs/testing.md 를 참고합니다.

반면 문서 작성법을 설명하려고 아래처럼 인라인 코드나 코드 블록 안에 적는 경우는 임포트 대상으로 처리하지 않습니다.

명령어를 보여 주는 예시는 `@README` 입니다.

위 예시의 @README는 설명을 위한 인라인 코드 표기입니다. 실제 파일을 불러오려는 목적이라면 임포트 문법을 실행할 수 있는 일반 텍스트 위치에 작성해야 합니다. 즉, 임포트를 설명하는 글자와 Claude Code에게 파일을 참조하도록 지시하는 글자는 겉보기에 비슷하더라도 처리 결과가 다를 수 있습니다.

4. 파일의 위치가 중요한 이유: 상대경로와 절대경로

파일 경로는 컴퓨터에서 해당 파일을 찾기 위한 주소입니다. 상대경로는 기준 파일을 출발점으로 위치를 표현합니다. @docs/review-rules.md는 지금 예시에서 CLAUDE.md가 들어 있는 폴더 아래의 docs 폴더를 가리킵니다. 절대경로는 파일 시스템의 전체 위치로 접근하는 방법입니다. 어떤 운영체제인지에 따라 표기 방식이 다릅니다. 중요한 규칙이 하나 있습니다.

Claude Code 임포트의 상대경로는 명령어를 실행한 현재 폴더가 아니라, 임포트를 적어 둔 파일의 위치를 기준으로 해석합니다. 그러므로 CLAUDE.md를 다른 폴더로 옮겼다면 이전 @docs/... 경로가 더는 유효하지 않을 수 있습니다. 파일명 대소문자, 확장자, 폴더명도 함께 확인해야 합니다. 파일명에 공백이 있으면 최신 공식 문서는 공백 앞에 역슬래시를 사용하는 방식을 안내합니다. 초보자라면 처음에는 공백이 없는 단순한 영문 파일명을 선택하는 편이 관리하기 쉽습니다.

5. AGENTS.md도 불러올 수 있나요?

가능한 구성입니다. 팀에서 AGENTS.md에 공통 작업 규칙을 관리하고, CLAUDE.md에서도 그 규칙을 참조하도록 만들 수 있습니다. 예를 들어 두 파일이 같은 폴더에 있다면 CLAUDE.md에 다음처럼 적는 방식입니다.


- Claude Code 관련 기본 규칙을 따른다.
- 팀의 공통 AI 작업 규칙은 @AGENTS.md 를 참고한다.

다만 여기에는 제품 버전에 따른 중요한 차이가 있습니다. 현재 Claude Code 공식 문서는 일정 버전부터 AGENTS.md를 직접 프로젝트 지침으로 읽는 기능도 안내합니다. 따라서 최신 환경에서는 CLAUDE.md가 없는 프로젝트에서 AGENTS.md를 읽기 위해 별도의 임포트가 꼭 필요한 것은 아닐 수 있습니다. 반대로 CLAUDE.md와 AGENTS.md가 함께 존재할 때 어떤 파일을 기본적으로 선택하는지, 두 문서를 모두 포함하도록 설정했는지는 버전과 프로젝트 설정에 따라 확인해야 합니다. 결론: “Claude Code는 AGENTS.md를 절대 읽지 못하니까 무조건 임포트해야 한다”는 설명은 정확하지 않습니다. 내 환경에서 실제로 어느 지침 파일이 로드되는지 확인하는 것이 우선입니다.

6. 일반적인 링크와 임포트는 어떻게 다른가요?

문서를 연결한다는 점은 비슷하지만 처리 목적이 다릅니다.

구분	예시	핵심 목적
문서 안의 일반 링크	`[검토표](docs/review-rules.md)`	사람이 눌러 문서로 이동
Claude Code 지침 임포트	`@docs/review-rules.md`	지원되는 지침 파일에서 다른 파일 내용을 맥락에 포함
프로그래밍 언어의 import	`import ...`	프로그램에서 코드·모듈을 불러오는 언어별 기능
파일 복사	복사 후 새 파일 생성	별도 파일 사본 보관

이 글의 임포트는 JavaScript나 Python의 프로그래밍 언어 문법을 설명하는 것이 아닙니다. 실제로 프로그램을 설치·실행하거나 새로운 복사 파일을 생성하는 명령도 아닙니다.

7. 가져올 파일을 많이 나누면 토큰을 절약할 수 있나요?

아니요. 그것만으로는 자동 절약되지 않습니다. 하나의 300줄짜리 지침 파일을 세 개의 100줄 파일로 나눈 뒤 세 파일을 모두 임포트했다고 가정해 보겠습니다. 사람이 수정하기에는 더 편해졌지만, AI가 그 내용을 모두 불러온다면 실제로 읽는 지침의 총량은 크게 달라지지 않습니다. 임포트의 주요 장점은 구조 정리·재사용·유지관리입니다. 토큰 사용 최적화와 동일한 개념이 아닙니다. 지침 파일이 길어진다면 다음 기준으로 구분해 보세요.

매 작업에 필요한 짧은 기본 규칙은 CLAUDE.md에 남깁니다.
특정 폴더나 파일 형식에만 필요한 규칙은 지원되는 경로별 규칙 파일을 검토합니다.
특정 작업을 할 때만 필요한 긴 자료나 절차는 상황에 맞는 스킬·참조 문서를 검토합니다. 서비스별 지침 로딩 방식은 다르며, 임포트가 자동으로 필요한 문단만 골라 읽는 검색 시스템은 아닙니다.

8. 보안 문제가 생길 수도 있나요?

그렇습니다. 임포트는 다른 파일의 내용을 AI 작업 맥락에 포함하는 기능이기 때문에, 무엇을 불러오느냐가 중요합니다. 예를 들어 다음과 같은 내용을 지침 파일에 넣는 것은 피해야 합니다.

API 키, 로그인 비밀번호, 인증 토큰 등 비밀정보
공개되면 곤란한 고객 정보나 개인 주소
출처가 불명확한 파일에 포함된 “다른 지시를 무시하라” 같은 악성 요청 프로젝트 폴더 밖에 있는 파일을 임포트하려는 경우 외부 파일을 포함하기 전에 승인 화면이 표시될 수 있습니다. 이는 낯선 파일이 마음대로 지침이 되는 위험을 줄이기 위한 장치입니다. 계정·제품 실행 모드에 따른 예외도 있으므로 항상 승인창이 뜬다고 가정해서는 안 됩니다. 또 하나 알아둘 사항이 있습니다. 임포트한 규칙 파일에 “절대 파일을 삭제하지 마세요”라고 적더라도 그것은 AI에게 주는 지침입니다. 운영체제나 도구의 실제 삭제 권한을 차단하는 보안 장치는 아닙니다. 중요한 작업은 별도의 도구 권한·승인 절차·백업·버전 관리로 보호하세요.

9. 임포트가 제대로 적용됐는지 확인하는 방법

임포트를 적었다고 해서 무조건 잘 적용되었다고 단정하지 않는 편이 좋습니다. 확인할 때는 다음 순서로 살펴봅니다.

실제 파일 존재: CLAUDE.md에서 참조한 파일 이름과 위치가 정확한가요?
참조 구문: @경로가 코드 블록이나 인라인 코드 밖에 있나요?
상대경로 기준: 참조를 적은 파일을 기준으로 경로를 계산했나요?
외부 파일 승인: 프로젝트 밖 파일이라면 필요한 접근 승인을 확인했나요?
로드 상태: 사용 중인 Claude Code 환경에서 /context의 Memory files 목록 등 실제 로드 정보를 확인했나요?
행동 검증: 간단한 교육용 작업에서 지침이 반영되는지 확인했나요? 만약 화면에서 파일 목록이 보이지 않거나 지침이 반영되지 않으면 '분명히 적용됐다'고 주장하지 말고 경로·설정·버전부터 다시 확인합니다. 지침 파일을 실제로 읽었더라도 AI가 모든 지침을 100% 완벽하게 따르는 것은 아닙니다. 파일 로드 여부와 지침 준수 여부는 서로 다른 검사 항목입니다.

10. 임포트한 파일 안에서 또 다른 파일을 불러올 수 있나요?

공식 문서는 임포트한 파일이 다시 다른 파일을 임포트하는 중첩 참조를 설명합니다. 예를 들어 메인 지침이 디자인 규칙을 참조하고, 디자인 규칙이 다시 용어표를 참조하는 구조를 생각할 수 있습니다.

CLAUDE.md
   └── @docs/design.md
         └── @docs/words.md

하지만 무한정 깊게 연결할 수 있는 기능은 아닙니다. Anthropic 현행 문서는 재귀 임포트 깊이에 제한이 있다고 설명합니다. 문서 버전별로 안내 수치가 바뀔 수 있으므로 깊은 연결은 피하고, 실제 사용 중인 버전의 공식 문서를 확인하는 편이 안전합니다. 특히 여러 파일이 서로를 가리키는 복잡한 구성보다 메인 파일에서 주제별 문서를 짧고 명확하게 연결하는 구성이 초보자에게 적합합니다.

11. 어떤 파일은 `CLAUDE.md`에, 어떤 파일은 따로 보관하면 좋을까요?

처음에는 다음과 같이 시작하면 충분합니다.

내용	권장 위치	이유
항상 지켜야 할 짧은 프로젝트 공통 규칙	`CLAUDE.md`	시작할 때 공통으로 참고
항상 필요한 별도 팀 지침	지원되는 `@경로` 임포트	문서 분리와 재사용
특정 파일·폴더 작업에만 해당하는 규칙	경로별 규칙 파일 검토	불필요한 전역 문맥 최소화
특정 상황의 긴 실행 절차	작업별 스킬/참조 문서 검토	항상 불러오는 지침과 분리

물론 이것은 정리 방법의 예시입니다. 실제 파일을 언제 읽고 어떤 조건에서 로드하는지는 각 Claude Code 기능의 지원 범위를 확인해야 합니다.

12. 초보자 실습: 내가 만든 규칙이 연결됐는지 확인하기

민감한 파일을 사용하지 않는 교육용 예제입니다. 실제 Claude Code 프로그램을 실행해 본 결과를 재현한 것은 아닙니다. 첫째. 새 연습 폴더를 만들고 CLAUDE.md, docs/checklist.md라는 텍스트 파일을 준비합니다. 둘째. docs/checklist.md에는 다음과 같이 작성합니다.


- 답변 마지막에 '확인하지 못한 점'을 구분한다.
- 테스트하지 않았다면 실험 성공이라고 말하지 않는다.

셋째. CLAUDE.md 파일에는 다음과 같이 적습니다.


- 가능한 쉬운 한국어를 사용한다.
- 추가 검토 규칙은 @docs/checklist.md 를 따른다.

넷째. 이 연습 폴더를 Claude Code 프로젝트로 열고, 사용 중인 버전에서 제공하는 메모리 파일 로드 상태와 응답을 확인합니다. 실제 앱 환경을 실행하지 않았다면 '검증 완료'가 아니라 '설정 예시 작성 완료'라고 적어 두세요. 다섯째. 임포트한 문장을 바꾸고 새로운 세션 또는 해당 도구의 지원되는 재로드 절차를 사용해 적용 여부를 확인합니다. 기능마다 새 세션 반영 방식은 다를 수 있습니다. 이 실습의 목표는 코드를 만드는 것이 아니라 어느 파일을 어디서 불러오는지 이해하는 것입니다.

13. 자주 묻는 질문(FAQ)

Q1. 임포트는 다른 파일을 복사하는 기능인가요? 아닙니다. 이 글에서 말하는 것은 지침 파일에 참조를 적어 다른 파일 내용을 작업 맥락으로 불러오는 기능입니다. Q2. CLAUDE.md 없이 AGENTS.md만 있어도 되나요? 현재 Claude Code 공식 문서에는 일부 버전에서 AGENTS.md를 직접 읽는 동작이 안내되어 있습니다. 버전과 프로젝트 설정을 확인하세요. Q3. 파일을 임포트하면 AI가 지침을 반드시 지키나요? 보장되지 않습니다. 파일을 읽은 사실과 실제로 요구사항을 지키는 것은 별개입니다. Q4. @README는 어디에 써야 하나요? 지원되는 지침 파일의 일반 문장에 씁니다. 코드 블록 안에 넣으면 임포트 대상으로 처리되지 않을 수 있습니다. Q5. 외부 파일 경로를 적으면 마음대로 접근하나요? 프로젝트 외부 임포트에는 첫 승인 확인 등 보호 절차가 있을 수 있습니다. 모드·설정에 따라 달라집니다. Q6. 상대경로는 어디를 기준으로 하나요? 임포트를 적어 둔 파일의 위치를 기준으로 해석합니다. Q7. 임포트하면 요금이나 토큰을 아낄 수 있나요? 파일 분리만으로는 자동 절약되지 않습니다. 가져온 내용도 맥락에 포함됩니다. Q8. 일반 Markdown의 [링크](주소)도 임포트인가요? 아닙니다. 화면에 링크를 보여 주는 일반 문법과 Claude Code의 @경로 임포트는 역할이 다릅니다. Q9. 여러 파일이 서로를 불러오게 해도 되나요? 중첩 지원 범위와 깊이 제한이 있습니다. 초보자는 단순한 한두 단계 구성을 권장합니다. Q10. 불러온 규칙을 편집하면 즉시 반영되나요? 작업 환경과 파일 로딩 시점에 따라 달라질 수 있습니다. 새 세션 또는 지원되는 재로드 방법으로 검증하세요.

14. 오늘 내용 세 줄 정리

첫째, Claude Code의 지침 파일 임포트는 CLAUDE.md 안에서 @파일경로로 다른 파일의 내용을 작업 맥락에 포함하는 기능입니다. 둘째, 경로 기준·파일 존재 여부·제품 버전·외부 파일 승인·실제 로드 확인이 중요합니다. 셋째, 임포트는 규칙 정리에는 유용하지만 토큰 절약·완전한 보안·지침 준수를 자동 보장하지는 않습니다. 이 세 가지를 구분하면 AI 코딩 프로젝트의 규칙을 여러 파일로 나눌 때 무엇을 연결하고 무엇을 직접 확인해야 하는지 이해하기 훨씬 쉬워집니다.

공식 자료

제품의 동작과 제한은 바뀔 수 있으므로 게시 시점에도 공식 문서에서 다시 확인하세요.

이 블로그 검색

Claude Code 임포트(Import)란? CLAUDE.md에서 다른 지침 파일 불러오는 법

1. 임포트가 필요한 이유부터 알아볼까요?

2. `CLAUDE.md`에서 임포트하는 가장 쉬운 예시

3. @ 기호가 있으면 언제나 임포트가 되나요?

4. 파일의 위치가 중요한 이유: 상대경로와 절대경로

5. `AGENTS.md`도 불러올 수 있나요?

6. 일반적인 링크와 임포트는 어떻게 다른가요?

7. 가져올 파일을 많이 나누면 토큰을 절약할 수 있나요?

8. 보안 문제가 생길 수도 있나요?

9. 임포트가 제대로 적용됐는지 확인하는 방법

10. 임포트한 파일 안에서 또 다른 파일을 불러올 수 있나요?

11. 어떤 파일은 `CLAUDE.md`에, 어떤 파일은 따로 보관하면 좋을까요?

12. 초보자 실습: 내가 만든 규칙이 연결됐는지 확인하기

13. 자주 묻는 질문(FAQ)

14. 오늘 내용 세 줄 정리

공식 자료

함께 읽으면 좋은 글

Claude Code 임포트(Import)란? CLAUDE.md에서 다른 지침 파일 불러오는 법

1. 임포트가 필요한 이유부터 알아볼까요?

2. CLAUDE.md에서 임포트하는 가장 쉬운 예시

3. @ 기호가 있으면 언제나 임포트가 되나요?

4. 파일의 위치가 중요한 이유: 상대경로와 절대경로

5. AGENTS.md도 불러올 수 있나요?

6. 일반적인 링크와 임포트는 어떻게 다른가요?

7. 가져올 파일을 많이 나누면 토큰을 절약할 수 있나요?

8. 보안 문제가 생길 수도 있나요?

9. 임포트가 제대로 적용됐는지 확인하는 방법

10. 임포트한 파일 안에서 또 다른 파일을 불러올 수 있나요?

11. 어떤 파일은 CLAUDE.md에, 어떤 파일은 따로 보관하면 좋을까요?

12. 초보자 실습: 내가 만든 규칙이 연결됐는지 확인하기

13. 자주 묻는 질문(FAQ)

14. 오늘 내용 세 줄 정리

공식 자료

함께 읽으면 좋은 글

안내

2. `CLAUDE.md`에서 임포트하는 가장 쉬운 예시

5. `AGENTS.md`도 불러올 수 있나요?

11. 어떤 파일은 `CLAUDE.md`에, 어떤 파일은 따로 보관하면 좋을까요?