클로드 코드 CLAUDE.md 쓰는 법: /init 으로 만들고 어디에 두고 무엇을 적나

이 글 순서

1. CLAUDE.md 가 뭔가요
2. 처음이라면: 언제 만드나
3. /init 으로 만들기
4. # 로 넣기는 없어졌어요
5. 무엇을 적나
6. 익숙해졌다면: 두는 곳
7. 읽는 순서
8. @ 로 불러오기
9. 길이와 넘칠 때
10. 더 깊이: rules
11. 자동 메모리
12. 팀과 공유하기
13. AGENTS.md 도 읽어요
14. 켤 때 옵션
15. 안 지켜질 때
16. 코덱스·안티그래비티는
17. 한국에서 되나
18. 참고한 자료

클로드 코드를 며칠 쓰다 보면 같은 말을 반복하게 돼요. “답은 한국어로 해 줘”, “원본 파일은 건드리지 마”, “고친 뒤에는 테스트 돌려 줘”. 세션을 새로 켤 때마다 Claude 는 어제 한 말을 모르고 시작하거든요. 이 반복을 끝내는 파일이 CLAUDE.md 예요. 클로드 코드 사용법 글에서는 /init 으로 만드는 데까지만 짚었는데, 이 글은 그다음을 이어서 써요.

클로드 코드 공식 문서의 기억(memory) 쪽과 명령 목록(commands), 확장 기능 개요(features-overview), 변경 기록(changelog)을 2026년 10월 8일에 읽고 옮겼어요. 캡처는 한국어 문서를 캡처했고, 버전 숫자와 파일 이름은 영어 문서와 맞춰 봤어요. 터미널 그림은 클로드 코드 2.1.292 가 깔린 윈도우 PC 에서, 임시 폴더 안에 만든 연습 폴더 두 개로 같은 날 돌린 명령의 출력을 옮겨 그린 거예요. 문서에 없는 것은 “미확인”으로 적었어요.

CLAUDE.md 가 뭔가요

CLAUDE.md 는 작업 폴더에 두는 텍스트 파일이에요. 클로드 코드는 세션을 켤 때마다 이 파일을 먼저 읽고 일을 시작해요. 새로 온 동료 책상에 붙여 두는 “이 폴더에서 지킬 것” 메모라고 생각하면 돼요. 파일 이름 끝의 .md 는 마크다운이라는 간단한 글 형식인데, # 로 제목을, – 로 목록을 적는 게 거의 전부라 메모장으로도 쓸 수 있어요.

단어 몇 개만 풀고 갈게요.

• 세션: 클로드 코드를 켜서 끌 때까지 이어지는 대화 한 묶음이에요.
• 컨텍스트: Claude 가 지금 대화에서 기억하고 있는 것 전부예요. 책상에 펼쳐 둔 종이 더미와 같고, 담을 수 있는 양(컨텍스트 윈도우)에는 끝이 있어요. CLAUDE.md 도 이 컨텍스트에 들어가요.
• 작업 폴더: claude 를 켠 위치의 폴더예요. 터미널에서 cd 로 들어간 폴더라고 보면 돼요.
• 깃(git): 파일이 바뀐 이력을 저장해 두는 도구예요. 팀은 보통 깃으로 파일을 나눠 가져요.

Claude 가 세션을 넘어 기억을 이어 가는 방법은 둘이에요. 내가 적는 CLAUDE.md, 그리고 Claude 가 스스로 적는 자동 메모리예요. 둘 다 세션을 켤 때 읽혀요.

표 위의 문장에서 꼭 가져갈 것이 하나 있어요. Claude 는 이 파일들을 “강제된 구성이 아닌 컨텍스트로” 다룬다는 거예요. 대체로 따르지만 꼭 지킨다는 보장은 없어요. 그래서 “절대 지우면 안 되는 폴더” 같은 것은 CLAUDE.md 만 믿지 말고 권한 규칙이나 훅으로 막아야 해요. 이 얘기는 아래 “어디에 적을까” 그림에서 한 번 더 나와요.

처음이라면: 언제 만드나

처음부터 거창하게 쓸 필요는 없어요. 문서는 CLAUDE.md 를 “다시 설명해야 할 내용을 적는 곳”이라고 적었어요.

쉬운 말로 바꾸면 이래요. Claude 가 같은 실수를 두 번 했을 때, 어제 친 말을 오늘 또 치고 있을 때, 새 사람이 와도 똑같이 알려 줘야 할 것이 생겼을 때예요. 반대로 여러 단계로 된 긴 절차나 폴더 한 곳에만 해당하는 규칙은 CLAUDE.md 가 아니라 스킬이나 경로별 규칙으로 옮기라고 같은 부분에 적혀 있어요. 그 둘은 “더 깊이”에서 다뤄요.

/init 으로 만들기

가장 쉬운 방법은 /init 이에요. 순서는 이래요.

1. 터미널(마우스 대신 글자로 일을 시키는 까만 창, 윈도우에서는 PowerShell)을 열어요.
2. cd 로 작업 폴더에 들어가 claude 를 쳐요.
3. 입력 칸에 /init 을 치고 Enter 를 눌러요.
4. Claude 가 폴더를 훑어보고 CLAUDE.md 를 만들어요. 만들어진 파일을 열어 읽고, 틀린 줄은 고치고 빠진 것은 더해요.

cd my-project
claude

첫 줄은 my-project 폴더로 들어가는 명령, 둘째 줄은 그 폴더에서 클로드 코드를 켜는 명령이에요. 켠 뒤 입력 칸에 /init 을 쳐요.

문서에 적힌 /init 의 일은 세 가지예요. 코드를 훑어 빌드 명령, 테스트 방법, 프로젝트 규칙을 적어 줘요. 이미 CLAUDE.md 가 있으면 덮어쓰지 않고 고칠 곳을 내놓아요. 그리고 폴더에서 코덱스나 제미나이 CLI 설정을 찾으면 /import 로 옮겨 오겠느냐고 물어요(명령 목록의 /init 줄). 코드가 없는 폴더, 예를 들어 글이나 표만 있는 폴더에서 무엇을 적어 주는지는 문서에 없어요(미확인). 그런 폴더라면 아래 다른 방법이 더 맞을 수 있어요.

/init 말고 만드는 방법도 있어요.

• 대화 중에 “이 규칙을 CLAUDE.md 에 넣어 줘”라고 말해요.
• /memory 를 쳐서 목록에서 파일을 골라 직접 적어요. 아직 없는 파일을 고르면 만들어서 열어 줘요.
• 메모장으로 직접 만들어요. 저장할 때 “파일 형식”을 “모든 파일”로 바꿔야 이름이 CLAUDE.md.txt 가 되지 않아요.

/init 을 더 꼼꼼하게 돌리는 방식도 문서에 있어요. CLAUDE_CODE_NEW_INIT 이라는 환경 변수(프로그램이 켜질 때 읽어 가는 설정 값)를 1 로 두고 /init 을 치면, CLAUDE.md 말고 스킬과 훅까지 무엇을 만들지 묻고, 서브에이전트로 폴더를 둘러본 뒤 되묻는 질문으로 빈 곳을 채우고, 파일을 쓰기 전에 제안을 먼저 보여 준다고 적혀 있어요. 이 PC 에서는 켜 보지 않았어요.

# 로 넣기는 없어졌어요

예전 글이나 영상에서 “입력 칸 맨 앞에 # 를 치면 CLAUDE.md 에 바로 들어간다”는 설명을 볼 수 있어요. 이 기능은 2025년 12월 15일 나온 2.0.70 에서 빠졌어요. 변경 기록에 “CLAUDE.md 를 고쳐 달라고 Claude 에게 말하라”는 말과 함께 적혀 있어요.

지금의 대화형 모드 문서에서도 입력 칸 맨 앞 글자로 쓰는 것은 / ! @ : ? 다섯 가지뿐이고 # 는 없어요. 지금은 “이거 CLAUDE.md 에 넣어 줘”라고 말하거나 /memory 로 파일을 열어 적으면 돼요.

무엇을 적나

문서가 드는 기준은 “확인할 수 있을 만큼 구체적으로”예요. “코드를 적절히 포맷해”보다 “2칸 들여쓰기”, “변경 사항을 테스트해”보다 “커밋 전에 npm test 실행”이 낫다는 식이에요.

문서의 요령을 추리면 셋이에요. 크기는 파일 하나에 200줄 아래. 비슷한 것끼리 # 제목과 – 목록으로 묶기. 서로 어긋나는 줄이 생기면 Claude 가 아무 쪽이나 고를 수 있으니 가끔 읽어 보고 지우기.

개발을 안 하는 분이라면 무엇을 적을지 막막할 수 있어요. 글 쓰는 폴더라면 이런 것들이에요. 아래는 이 PC 의 임시 폴더에 동네 독서 모임 소식지 원고 폴더를 흉내 내 만들고, 그 안의 파일 목록과 CLAUDE.md 를 터미널로 읽어 본 화면이에요. 내용은 제가 지어 적은 연습용 예시예요.

Get-ChildItem -Recurse -Name
Get-Content .\CLAUDE.md -Encoding UTF8

첫 줄은 지금 폴더와 그 안 폴더의 파일 이름을 모두 보여 주는 PowerShell 명령이고, 둘째 줄은 CLAUDE.md 의 내용을 화면에 읽어 주는 명령이에요. -Encoding UTF8 은 한글이 깨지지 않게 글자 형식(인코딩)을 알려 주는 부분이에요. 윈도우에 기본으로 깔린 PowerShell 5.1 에서 이걸 빼고 읽으니 한글이 깨져 나왔어요.

지킬 것과 하지 말 것을 짧은 목록으로, 확인할 수 있는 말로 적었어요. “깔끔하게 써 줘”보다 “날짜는 10월 8일(수) 형식”이 Claude 가 지켰는지 내가 보기에도 쉬워요.

이제 막 코드를 배우는 분이라면 첫 줄은 명령이에요. 앱을 켜는 명령, 테스트하는 명령, 검사하는 명령을 적어 두면 Claude 가 고친 뒤에 무엇을 돌려 확인할지 알아요. 아래는 연습용으로 만든 작은 앱 폴더의 CLAUDE.md 예요.

npm 은 자바스크립트 프로그램을 깔고 돌리는 도구이고, npm test 는 그 프로젝트에 적힌 테스트를 돌리는 명령이에요. 맨 위 줄의 @README.md 와 @package.json 은 다른 파일을 불러오는 표시인데, 아래 “@ 로 불러오기”에서 풀어요.

적지 않아도 되는 것도 있어요. 폴더 구조, 깔린 패키지 목록처럼 Claude 가 파일을 열어 보면 알 수 있는 것은 줄이라고 문서가 적었어요(아래 “길이와 넘칠 때”의 /doctor 부분). 사람에게만 남기고 싶은 메모는 <!-- 메모 --> 형식의 HTML 주석으로 적으면 Claude 에게 넘어가기 전에 빠져서 컨텍스트를 먹지 않아요. 문서의 “CLAUDE.md 파일이 로드되는 방식” 부분에 있는 내용이에요.

익숙해졌다면: 두는 곳

여기부터는 며칠 써 본 뒤에 봐도 돼요.

CLAUDE.md 는 한 곳에만 두는 게 아니에요. 같은 이름의 파일이라도 놓인 위치에 따라 누가 읽는지가 달라요.

표의 ~/.claude 는 내 사용자 폴더 안의 .claude 폴더예요. 윈도우에서는 보통 C:\Users\내이름\.claude 예요. 여기에 둔 CLAUDE.md 는 어느 폴더에서 켜든 읽혀서, “답은 한국어로” 같은 나만의 버릇을 적기 좋아요. 반대로 작업 폴더의 CLAUDE.md 는 그 폴더에서 일하는 모두가 같이 보는 규칙이고, CLAUDE.local.md 는 그 폴더에서 나만 쓰는 메모예요.

처음 쓰는 분이 헷갈리기 쉬운 점은, 작업 폴더의 CLAUDE.md 를 ./CLAUDE.md 와 ./.claude/CLAUDE.md 둘 중 어디에 둬도 된다는 거예요. 앞의 점 하나(.)는 “지금 폴더”를 뜻해요.

읽는 순서

여러 곳에 CLAUDE.md 가 있으면 어느 것이 우선 적용되느냐가 궁금해져요. 문서의 답은 “우선 적용되는 것 없이 다 이어 붙인다”예요.

문서 예시로 풀면 이래요. foo 폴더 안의 bar 폴더에서 claude 를 켜면 foo/CLAUDE.md 와 foo/bar/CLAUDE.md 를 둘 다 읽는데, 위 폴더(foo) 것이 먼저, 켠 위치(bar) 것이 나중에 들어가요. 같은 폴더 안에서는 CLAUDE.md 다음에 CLAUDE.local.md 가 와요. 나중에 읽힌 것이 Claude 에게는 가장 가까이 있는 말이 되는 거예요.

켠 위치보다 아래 폴더의 CLAUDE.md 는 켤 때 읽지 않아요. Claude 가 그 폴더 안의 파일을 읽거나 고칠 때 비로소 더해져요. 아래는 연습용 앱 폴더의 구조예요. 맨 위 CLAUDE.md 는 켤 때 읽히고, src\api\CLAUDE.md 는 Claude 가 src\api 안의 파일을 만질 때 더해져요.

tree /f /a

지금 폴더 아래의 폴더와 파일을 나무 모양으로 보여 주는 명령이에요. /f 는 파일까지 보이게, /a 는 선을 기본 글자로 그리게 하는 옵션이에요.

어떤 파일이 실제로 읽혔는지는 세션 안에서 /context 를 쳐서 Memory files 아래 목록으로 본다고 문서에 적혀 있어요. 하위 폴더의 CLAUDE.md 는 켤 때 읽는 것이 아니라 그 목록에 안 나오고, 읽히는 순간 터미널에 Loaded 줄로 뜬다고 해요.

@ 로 불러오기

CLAUDE.md 안에 @ 를 붙여 다른 파일 경로를 적으면 그 파일 내용이 같이 읽혀요. 경로는 파일의 위치를 글자로 적은 거예요. 위 연습 앱의 첫 줄 “앱 설명은 @README.md, 쓸 수 있는 명령은 @package.json 을 본다”가 그 예예요.

문서에 적힌 규칙을 추리면 이래요.

• 상대 경로는 작업 폴더가 아니라 @ 를 적은 그 파일 위치에서 따져요.
• 불러온 파일이 또 다른 파일을 불러올 수 있는데, 네 단계까지예요.
• 경로에 빈칸이 있으면 빈칸마다 앞에 \ 를 붙여요. 따옴표로 감싼 경로는 불러오지 않아요.
• `@README` 처럼 백틱(`)으로 감싸면 불러오지 않고 글자 그대로 남아요.
• 작업 폴더 밖의 파일을 불러오면, 그 프로젝트에서 처음 한 번 권한 확인 창이 떠요. 남이 올린 파일로부터 나를 지키려는 장치라고 적혀 있어요.

불러오기를 “길이를 줄이는 법”으로 오해하기 쉬운데, 그렇지 않아요. 불러온 파일도 켤 때 다 읽혀서 컨텍스트를 똑같이 먹어요. 파일을 보기 좋게 나누는 데만 도움이 돼요. 정말 길이를 줄이려면 아래 “더 깊이”의 경로별 규칙을 써요.

길이와 넘칠 때

200줄은 권하는 길이고, 넘는다고 안 읽는 건 아니에요. 문서는 길수록 컨텍스트를 더 먹고 덜 지켜진다고 적었어요. 아예 건너뛰는 건 4MiB(약 4백만 바이트)를 넘는 파일이에요.

내 파일이 몇 줄인지는 터미널에서 바로 셀 수 있어요. 위 연습 앱 그림의 아래 두 줄이 그거예요.

(Get-Content .\CLAUDE.md -Encoding UTF8).Count
(Get-Item .\CLAUDE.md).Length

첫 줄은 CLAUDE.md 가 몇 줄인지, 둘째 줄은 몇 바이트인지 보여 주는 PowerShell 명령이에요. 연습 앱의 CLAUDE.md 는 13줄, 333바이트였어요.

길어졌을 때 손을 빌릴 명령도 둘 있어요. /doctor 는 설치 상태를 점검하면서, 깃에 올린 CLAUDE.md 에서 Claude 가 코드를 보면 알 수 있는 내용(폴더 구조, 의존성 목록 등)을 덜어 내자고 제안해요(v2.1.206 부터). /doctor prompt-audit 는 오래된 지시, 없는 파일이나 명령을 가리키는 줄, 서로 어긋나는 파일을 찾아 고칠 거리를 보고서로 보여 줘요(v2.1.283 부터). 둘 다 먼저 보여 주고, 내가 하라고 해야 고쳐요.

대화가 길어져 /compact 로 줄여도 작업 폴더 맨 위의 CLAUDE.md 는 다시 읽어 넣는다고 문서에 적혀 있어요. 반대로 대화에서만 말한 규칙은 줄이는 과정에서 빠질 수 있어요. 오래 지켜야 하는 말은 CLAUDE.md 로 옮겨 두세요. 세션 도중에 CLAUDE.md 를 손으로 고치면 언제부터 반영되는지는 문서에서 찾지 못했어요(미확인). 확실하게 하려면 나갔다가 새로 켜세요. 켤 때 읽는다는 것은 문서에 적혀 있어요.

더 깊이: rules

여기부터는 파일이 길어졌거나 폴더가 커졌을 때 쓰는 것들이에요.

.claude 폴더 안에 rules 폴더를 만들고 주제별로 .md 파일을 나눠 둘 수 있어요. 문서가 드는 이름은 code-style.md, testing.md, security.md 같은 것들이에요. rules 안의 하위 폴더까지 다 찾아 읽어요.

rules 의 쓸모는 paths 에 있어요. 파일 맨 위에 --- 두 줄 사이로 paths 를 적으면, 그 규칙은 Claude 가 그 형식의 파일을 읽거나 고칠 때만 컨텍스트에 들어가요. 이렇게 파일 맨 위에 붙이는 설정 몇 줄을 프론트매터(frontmatter)라고 불러요. 프론트매터에 쓰는 YAML 은 “이름: 값”으로 적는 설정 글 형식이에요.

연습 앱에는 테스트 파일에만 해당하는 규칙을 하나 넣어 봤어요. 그리고 src\api 폴더에도 그 폴더 전용 CLAUDE.md 를 하나 뒀어요. 폴더 한 곳의 규칙을 나누는 두 가지 방법이에요.

tests/**/*.js 는 “tests 폴더 아래 어디에 있든 .js 로 끝나는 파일”이라는 뜻의 패턴이에요. ** 는 몇 겹의 폴더든, * 는 아무 이름이든을 뜻해요. 알아 둘 점은 넷이에요.

• paths 가 없는 규칙 파일은 켤 때 바로 읽혀요. .claude/CLAUDE.md 와 같은 무게로 다뤄져요.
• 프론트매터에서 클로드 코드가 읽는 필드는 paths 하나뿐이에요. 다른 필드는 오류 없이 무시해요.
• 프론트매터 글을 못 읽으면(띄어쓰기가 틀리는 등) paths 가 없는 규칙처럼 늘 읽어요. claude --debug 로 켜면 오류를 볼 수 있다고 적혀 있어요.
• 내 사용자 폴더의 ~/.claude/rules/ 에 두면 모든 프로젝트에 먹혀요. 프로젝트 규칙보다 먼저 읽히고, 둘이 엇갈리면 어느 쪽을 따를지 보장이 없어요.

그럼 무엇을 어디에 적을지, 한 장으로 모으면 이래요.

스킬은 반복하는 일을 명령 하나로 묶어 두는 기능이고, 훅은 정해진 때에 클로드 코드가 반드시 돌리는 내 명령이에요. 둘은 따로 다룬 글이 있어요(스킬 만들기 글, 훅 글, 권한 설정 글).

자동 메모리

CLAUDE.md 는 내가 쓰고, 자동 메모리는 Claude 가 써요. 내가 고쳐 준 것, 좋아하는 방식, 코드만 봐서는 모르는 일의 사정 같은 것을 Claude 가 알아서 적어 둬요. 로컬 세션에서는 기본으로 켜져 있어요.

문서에 적힌 것을 추리면 이래요.

• 저장 위치는 ~/.claude/projects/<프로젝트>/memory/ 예요. 그 안의 MEMORY.md 가 목록 노릇을 하고, 자세한 메모는 주제별 파일로 따로 둬요.
• 켤 때 읽히는 것은 MEMORY.md 의 앞 200줄이나 앞 25KB 가운데 먼저 도달하는 쪽까지예요. 주제별 파일은 필요할 때 Claude 가 열어 봐요.
• 이 컴퓨터에만 있어요. 다른 컴퓨터나 클라우드와는 공유하지 않아요.
• /memory 에서 켜고 끄고, 메모 폴더를 열어 읽거나 고치거나 지울 수 있어요. 모두 보통 마크다운 파일이에요.

말 한마디로 갈 곳이 갈려요. “앞으로 pnpm 써, 기억해”처럼 기억하라고 하면 자동 메모리에 들어가고, “이거 CLAUDE.md 에 넣어 줘”라고 하면 CLAUDE.md 에 들어간다고 /memory 부분에 적혀 있어요. 팀과 공유할 규칙은 CLAUDE.md 쪽으로 말하세요. 자동 메모리는 내 컴퓨터에만 남으니까요.

팀과 공유하기

작업 폴더의 CLAUDE.md 는 깃으로 팀과 공유하는 파일이에요. 그래서 문서는 여기에 개인 취향보다 프로젝트 기준을 적으라고 해요. 나만 쓸 메모는 CLAUDE.local.md 에 적고, 그 이름을 .gitignore(깃에 올리지 않을 파일 목록)에 넣어요.

git ls-files
git status --short --ignored

첫 줄은 깃이 지금 맡아 관리하는 파일 목록을 보여 주는 명령이고, 둘째 줄은 바뀐 파일과 함께 깃이 일부러 빼 둔 파일을 !! 표시로 보여 주는 명령이에요. 연습 앱에서는 CLAUDE.md, .claude/rules/testing.md, src/api/CLAUDE.md 는 목록에 있고 CLAUDE.local.md 만 !! 로 빠져 있어요. 팀원이 이 저장소를 받으면 앞의 셋은 같이 받고, 내 메모는 안 받는 거예요.

팀이 커지면 쓸 것이 둘 더 있어요. 회사가 모든 컴퓨터에 같은 지침을 깔고 싶으면 관리형 CLAUDE.md(윈도우는 C:\Program Files\ClaudeCode\CLAUDE.md)를 배포하는데, 이건 개인 설정으로 뺄 수 없어요. 반대로 여러 팀이 한 저장소를 쓰다 다른 팀 CLAUDE.md 까지 읽혀 번거로우면, 설정 파일의 claudeMdExcludes 에 그 경로를 적어 건너뛰게 할 수 있어요. 둘 다 문서의 “대규모 팀을 위한 CLAUDE.md 관리하기” 부분에 있어요.

AGENTS.md 도 읽어요

AGENTS.md 는 코덱스 같은 다른 코딩 도구가 읽는 지침 파일 이름이에요. 클로드 코드도 2.1.277(2026년 9월 18일)부터 이 파일을 읽어요. 다만 조건이 있어요.

• 작업 폴더와 그 위에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md 가 하나도 없을 때만 AGENTS.md 를 읽어요.
• 사용자 폴더의 ~/.claude/CLAUDE.md 와 .claude/rules 는 이 따짐에 안 들어가요. 그래서 AGENTS.md 와 같이 읽혀요.
• AGENTS.override.md, AGENTS.local.md, .agents 폴더 안의 것은 읽지 않아요.
• 둘 다 늘 읽히게 하려면 /config 의 Project instructions 를 claude-md-and-agents-md 로 바꿔요.

함정이 하나 있어요. AGENTS.md 로 굴러가던 폴더에 나만 쓸 메모로 CLAUDE.local.md 를 하나 만들면, 그 순간부터 Claude 가 AGENTS.md 를 안 읽어요. CLAUDE.local.md 도 “CLAUDE 파일이 있다”로 치기 때문이에요.

여러 도구가 파일 하나를 같이 쓰게 하고 싶다면 CLAUDE.md 맨 위에 @AGENTS.md 한 줄을 적고, 그 아래에 클로드 코드에만 줄 말을 더하는 방법을 문서가 권해요. 링크 파일(심볼릭 링크)로 연결하는 방법도 있지만, 윈도우에서는 그걸 만들려면 관리자 권한이나 개발자 모드가 필요하고 깃이 그 링크를 한 줄짜리 텍스트 파일로 받아 올 수 있어서, 윈도우를 쓰는 사람이 하나라도 있으면 @AGENTS.md 쪽을 쓰라고 적혀 있어요.

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

문서 예시 그대로예요. 첫 줄이 AGENTS.md 를 불러오고, 아래 두 줄은 “src/billing 아래를 고칠 때는 plan 모드를 써라”라는 클로드 코드 전용 지시예요.

켤 때 옵션

CLAUDE.md 를 어떻게 읽을지 켤 때 바꾸는 옵션도 있어요. 아래는 이 PC 에서 claude --help 를 친 출력에서 관련 부분 셋만 옮긴 거예요. 이 명령은 도움말만 보여 주고 세션은 켜지 않아요.

옵션	CLAUDE.md 와 얽힌 일
--bare	CLAUDE.md 찾기와 자동 메모리를 건너뛰고 켬
--add-dir 폴더	다른 폴더도 쓰게 함. 그 폴더의 CLAUDE.md 는 환경 변수를 켜야 읽음
--setting-sources	project 를 빼면 프로젝트 rules 를 안 읽음

출처: claude --help 출력(2.1.292), 클로드 코드 문서 memory 의 Load from additional directories·Set up rules. 10월 8일 확인.

--add-dir 로 더한 폴더의 CLAUDE.md 까지 읽히게 하려면 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 라는 환경 변수를 1 로 두라고 문서에 적혀 있어요. --bare 는 조심하세요. 같은 도움말 줄 뒤쪽에 이 모드는 로그인으로 ANTHROPIC_API_KEY(돈을 쓴 만큼 내는 개발자용 키)나 --settings 로 준 apiKeyHelper 만 쓰고, 구독 로그인(OAuth)은 읽지 않는다고 적혀 있어요. Pro·Max 구독으로만 쓰는 분은 이 옵션으로 켜면 로그인이 안 된 채로 시작될 수 있어요. 이 PC 에서는 돌려 보지 않았어요. 처음 쓰는 분은 이 셋을 몰라도 돼요. 스크립트로 클로드 코드를 돌리다 “왜 내 CLAUDE.md 를 안 읽지?” 싶을 때 떠올리면 돼요.

안 지켜질 때

CLAUDE.md 에 적었는데 Claude 가 안 따를 때 문서가 권하는 순서예요.

1. /context 를 쳐서 Memory files 목록에 그 파일이 있는지 봐요. 없으면 Claude 는 그 파일을 못 본 거예요.
2. 파일이 읽히는 위치에 있는지 봐요(위 “두는 곳” 그림).
3. 말을 더 구체적으로 바꿔요. “깔끔하게”보다 “2칸 들여쓰기”.
4. 다른 CLAUDE.md 나 rules 와 엇갈리는 줄이 없는지 봐요.
5. 매번 꼭 돌아야 하는 일(커밋 전 검사 등)이면 훅으로 옮겨요.

문서는 CLAUDE.md 내용이 시스템 프롬프트(AI 에게 처음 주는 기본 지시)가 아니라, 그 뒤에 사용자 메시지로 들어간다고 적었어요. 대체로 따르지만 반드시는 아닌 이유가 여기 있어요.

코덱스·안티그래비티는

터미널에서 쓰는 다른 코딩 AI 도 같은 노릇을 하는 파일이 있어요. 코덱스 CLI 는 AGENTS.md, 구글의 안티그래비티 CLI 는 GEMINI.md 나 AGENTS.md 예요. 각 회사 문서에서 찾아 비교했어요.

항목	클로드 코드	코덱스 CLI	안티그래비티 CLI
파일 이름	CLAUDE.md(없으면 AGENTS.md)	AGENTS.md(override 가 먼저)	GEMINI.md, AGENTS.md
만드는 명령	/init	/init	문서에서 못 찾음
모든 폴더용	~/.claude/CLAUDE.md	~/.codex/AGENTS.md	~/.gemini/GEMINI.md 등
나만 쓰는 파일	CLAUDE.local.md	문서에서 못 찾음	문서에서 못 찾음

항목	클로드 코드	코덱스 CLI	안티그래비티 CLI
읽는 범위	켠 폴더와 그 위, 하위 폴더는 만질 때	프로젝트 맨 위에서 켠 폴더까지, 폴더마다 한 파일	만진 파일 폴더에서 맨 위까지
다른 파일 불러오기	@경로(내용을 넣음, 네 단계까지)	문서에서 못 찾음	@[이름](경로)는 내용, @파일은 위치만
크기에 대한 말	파일 하나 200줄 아래 권장, 4MiB 넘으면 건너뜀	합쳐서 32KiB 까지 읽음	파일 하나 24KB, 늘 켜진 규칙 합쳐 2만 토큰
파일별 조건 규칙	.claude/rules 의 paths	문서에서 못 찾음	.agents/rules 의 trigger

출처: 클로드 코드 문서 memory, OpenAI 코덱스 문서 Custom instructions with AGENTS.md·Developer commands, 안티그래비티 문서 Rules·CLI reference·Slash commands·Migrating from Gemini CLI. 10월 8일 확인.

제 생각에는 셋 사이를 오가는 분이라면 공통 규칙은 AGENTS.md 에 적고, 클로드 코드 쪽에는 @AGENTS.md 한 줄로 불러오는 CLAUDE.md 를 두는 방법이 가장 손이 덜 가요. 코덱스는 AGENTS.md 를, 안티그래비티 CLI 는 AGENTS.md 와 GEMINI.md 를 둘 다 읽으니까요. 다만 코덱스의 AGENTS.override.md 는 클로드 코드가 읽지 않으니 거기엔 공통 규칙을 두지 마세요. 세 도구 처음 쓰는 법은 코덱스 CLI 사용법 글과 안티그래비티 CLI 사용법 글에, 기능별로 비교한 표는 클로드 코드·코덱스·제미나이 CLI 비교 글에 있어요.

한국에서 되나

돼요. CLAUDE.md 는 내 컴퓨터의 텍스트 파일이라 나라에 따라 달라지는 게 없어요. 한국어로 적어도 되는지는 문서에 따로 적혀 있지 않은데(예시는 모두 영어), 이 글의 연습 파일은 한국어로 적었어요.

궁금한 것	공식 문서에 적힌 것
한국에서 되나	됨(Anthropic 지원 국가 목록에 South Korea)
무슨 요금제	클로드 코드는 Pro·Max·Team·Enterprise·Console. 무료 안 됨
한국어 문서	있음(code.claude.com/docs/ko/memory)
AGENTS.md 읽기	v2.1.277 부터
# 로 바로 넣기	2.0.70 에서 없어짐

출처: 클로드 코드 문서 memory·setup·changelog, anthropic.com 지원 국가 목록. 10월 8일 확인.

이 글의 내용은 2026년 10월 8일, 클로드 코드 2.1.292 기준이에요. CLAUDE.md 와 AGENTS.md 를 읽는 방식은 요즘 버전마다 조금씩 바뀌고 있어요. 글과 다르게 움직이면 /memory, /context 화면과 공식 문서의 지금 내용을 먼저 보세요.

같이 보면 좋은 글: 클로드 코드 사용법 처음부터: @ 로 파일 가리키기, 되돌리기, CLAUDE.md 만들기

같이 보면 좋은 글: 클로드 코드 훅 글

같이 보면 좋은 글: 클로드 코드 사용량 아끼는 법: 대화·캐시·서브에이전트부터 스킬·훅·권한 설정까지

같이 보면 좋은 글: AI 비교 2026: 클로드·챗GPT·제미나이 요금제·한도·기능 표

같이 보면 좋은 글: 클로드 코드 출력 스타일 바꾸는 법: Explanatory·Learning 으로 설명 받기, 내 스타일 파일까지

같이 보면 좋은 글: 클로드 코드 /simplify 사용법: 바꾼 코드 다듬기 한 줄부터 /code-review 차이·되돌리기까지

같이 보면 좋은 글: 클로드 코드 /context 사용법: 대화 창 얼마나 찼나 보기부터 줄이는 순서·창 크기까지

참고한 자료

2026년 10월 8일에 확인했어요. 클로드 코드 문서는 영어 문서와 한국어 문서(/docs/ko/)를 같이 봤어요.

• How Claude remembers your project (클로드 코드 공식 문서, CLAUDE.md 두는 곳·읽는 순서·@ 불러오기·rules·AGENTS.md·자동 메모리·문제 해결)
• Commands (클로드 코드 공식 문서, /init·/memory·/doctor·/context)
• Interactive mode (클로드 코드 공식 문서, 입력 칸 맨 앞 글자 표)
• Extend Claude Code (클로드 코드 공식 문서, CLAUDE.md·rules·스킬 비교하기)
• Changelog (클로드 코드 공식 문서, 2.0.70 # 줄임 없앰·2.1.277 AGENTS.md)
• Set up Claude Code (클로드 코드 공식 문서, 쓸 수 있는 요금제)
• Supported countries (Anthropic, South Korea)
• Custom instructions with AGENTS.md (OpenAI 코덱스 공식 문서, 읽는 순서·override·32KiB)
• Developer commands (OpenAI 코덱스 공식 문서, /init 으로 AGENTS.md 만들기)
• Rules (안티그래비티 공식 문서, GEMINI.md·AGENTS.md 위치·@ 두 가지·크기 한도)
• CLI reference (안티그래비티 공식 문서, 명령 표)
• Slash commands (안티그래비티 공식 문서, 명령 목록에 /init 없음·/learn)
• Migrating from Gemini CLI (안티그래비티 공식 문서, GEMINI.md·AGENTS.md 계속 읽음)