claude.md 파일 위치 · 클로드 코드 claude.md 작성법: 저장소 맨 위 CLAUDE.md 에, 200줄 안쪽으로 매번 필요한 것만

claude.md 는 어디에 둬야 Claude Code가 읽을까? 팀이 같이 쓸 프로젝트 규칙은 저장소 맨 위 CLAUDE.md(또는 .claude/CLAUDE.md)에 둔다. 모든 프로젝트에 쓸 내 취향은 ~/.claude/CLAUDE.md, 이 프로젝트에서 나만 쓸 설정은 CLAUDE.local.md, 한 폴더에만 해당하는 규칙은 그 폴더 안의 CLAUDE.md. 작성법의 요점은 셋, 파일당 200줄 아래로 짧게, 맞았는지 확인할 수 있게 구체적으로, 코드를 보면 알 수 있는 내용은 빼고. 기준은 2026년 10월 14일에 읽은 Claude Code 공식 문서다.

claude.md 파일 위치 네 곳과 읽히는 순서 (2026-10-14 공식 문서 기준)

Claude Code 메모리 문서가 드는 위치를 개인 · 팀 쪽 넷으로 추리면 이렇다. 문서에 적힌 파일 이름은 대문자 CLAUDE.md.

범위	위치	넣을 것(문서 예시)	읽히는 때
프로젝트	./CLAUDE.md 또는 ./.claude/CLAUDE.md	빌드 · 테스트 명령, 코딩 규칙, 구조 결정, 이름 규칙, 자주 쓰는 작업 흐름	시작할 때
사용자	~/.claude/CLAUDE.md	모든 프로젝트에 쓰는 코드 스타일 취향, 개인 도구 단축	시작할 때
로컬	./CLAUDE.local.md	이 프로젝트에서 나만 쓰는 것(샌드박스 URL, 즐겨 쓰는 테스트 데이터)	시작할 때
하위 폴더	하위폴더/CLAUDE.md	그 폴더 아래에서만 필요한 지시	Claude가 그 폴더의 파일을 읽거나 쓰거나 고칠 때

프로젝트 파일은 버전 관리로 팀과 같이 쓰고, CLAUDE.local.md 는 .gitignore 에 넣어 나만 쓴다. 회사가 모든 사용자 기기에 까는 관리 정책 파일도 따로 있다. 리눅스 · WSL 은 /etc/claude-code/CLAUDE.md, macOS 는 /Library/Application Support/ClaudeCode/CLAUDE.md, Windows 는 C:\Program Files\ClaudeCode\CLAUDE.md. 이 파일은 개인 설정으로 뺄 수 없다고 적혀 있다.

읽는 순서는? Claude Code는 실행한 폴더와 그 위의 모든 폴더에서 CLAUDE.md 와 CLAUDE.local.md 를 찾아 시작할 때 읽는다. foo/bar/ 에서 실행하면 foo/CLAUDE.md 와 foo/bar/CLAUDE.md 가 둘 다 실리는 식. 서로 덮어쓰지 않고 이어 붙고, 위 폴더 것이 먼저, 실행한 자리에 가까운 것이 나중에 놓인다. 같은 폴더 안에서는 CLAUDE.local.md 가 CLAUDE.md 뒤에 붙는다. 범위로 보면 조직 → 사용자 → 프로젝트 → 로컬 순.

하위 폴더의 CLAUDE.md 는 시작할 때 실리지 않는다. Claude가 그 폴더 안의 다른 파일을 읽거나 쓰거나 고칠 때 실린다. 새로 만든 걸 시험할 때는 Claude에게 쓰게 하지 말고 셸에서 직접 만든 뒤, 그 폴더의 파일 하나를 읽어 달라고 하라는 게 문서의 방법.

실렸는지는 세션에서 /context 를 치고 Memory files 목록으로 확인한다. 목록에 없는 파일은 Claude도 못 본다. 하위 폴더 파일은 예외. 실릴 때 목록 대신 터미널에 경로가 붙은 Loaded 줄로 찍힌다.

/memory 로 여는 목록은 사용자 · 프로젝트 범위의 CLAUDE.md · CLAUDE.local.md 위치. 사용자 · 프로젝트 CLAUDE.md 는 아직 없는 파일도 목록에 나오고, 고르면 편집기로 열리면서 없던 파일은 먼저 만들어진다. 내가 쓰는 CLAUDE.md 와 달리 Claude가 스스로 적어 두는 auto memory 를 켜고 끄는 것도 여기서.

/compact 로 대화를 줄인 뒤엔? 프로젝트 맨 위 CLAUDE.md 는 디스크에서 다시 읽혀 들어간다. 대화에서만 한 지시는 그때 사라질 수 있으니, 계속 지켜야 할 건 파일에 적어 두라는 게 문서의 설명.

처음 만들 때: /init 으로 뼈대를 받고 손으로 채운다

/init 을 돌리면 Claude가 코드베이스를 훑어 빌드 명령, 테스트 방법, 찾아낸 프로젝트 관례로 첫 CLAUDE.md 를 만든다. 파일이 이미 있으면 덮어쓰지 않고 고칠 점을 제안한다. 그다음은 Claude가 스스로 찾지 못할 지시를 사람이 더하는 순서. 환경 변수 CLAUDE_CODE_NEW_INIT=1 을 켜고 돌리면 CLAUDE.md · 스킬 · 훅 중 무엇을 만들지 먼저 묻고, 파일을 쓰기 전에 제안을 보여 준다.

claude.md 작성법: 매 세션 필요한 사실만, 확인할 수 있게

문서가 드는 「CLAUDE.md 에 더할 때」는 네 가지.

• Claude가 같은 실수를 두 번째로 할 때
• 코드 리뷰에서 Claude가 이 코드베이스에 대해 알았어야 할 것이 걸렸을 때
• 지난 세션에 쳤던 정정이나 설명을 이번 세션에도 또 칠 때
• 새로 온 팀원에게도 같은 맥락이 필요할 때

넣을 것은 모든 세션에서 알아야 할 사실이다. 빌드 명령, 관례, 프로젝트 구조, 「항상 X 를 한다」 같은 규칙. 여러 단계짜리 절차나 코드 일부에만 필요한 건 스킬이나 경로 규칙(아래)으로 옮기라고 적혀 있다.

문장은 맞았는지 확인할 수 있을 만큼 구체적으로. 문서의 예를 옮기면 이렇다.

흐린 문장	확인되는 문장
「코드를 제대로 정리해」	「들여쓰기는 스페이스 2칸」
「변경 사항을 테스트해」	「커밋 전에 npm test 를 돌린다」
「파일을 정리해 둬」	「API 핸들러는 src/api/handlers/ 에 있다」

비슷한 지시는 마크다운 제목과 글머리표로 묶는다. 빽빽한 문단보다 나뉜 절을 Claude가 더 따르기 쉽다는 설명.

긴 내용은 @경로 로 다른 파일을 불러와 나눌 수 있다. 상대 경로는 작업 폴더가 아니라 불러오는 파일이 있는 자리 기준이고, 불러온 파일이 또 다른 파일을 부르는 건 네 단계까지.

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

주의할 점 하나. 불러온 파일도 시작할 때 같이 실린다. 정리에는 도움이 돼도 컨텍스트 비용은 그대로인 셈이다. 경로를 불러오지 않고 글자로만 적으려면 백틱으로 감싼다(`@README`).

우리 저장소 CLAUDE.md 는 이 파일이 무엇인지부터 적었다. 전체 규칙은 AGENTS.md 에 두고 여기는 요약만 한다는 것, 둘이 다르면 AGENTS.md 를 따른다는 것. 2026년 10월 14일 기준 뼈대의 앞부분.

> **Role:** session entrypoint only. ... It summarizes `AGENTS.md` for convenience at session start. If this file conflicts with `AGENTS.md`, follow `AGENTS.md`.

## 1. Read First
Before doing any task work, read **`AGENTS.md`**. ...
## 2. Non-Negotiable Rules
## 3. Source of Truth
## 4. Before Acting Checklist

참고로 이 파일은 같은 날 기준 212줄이라, 문서가 말하는 200줄 목표를 조금 넘는다.

쓰지 말 것: 코드에 있는 것, 일부에만 필요한 것, 서로 부딪치는 것

빼라는 쪽도 문서에 꽤 구체적으로 나온다.

1. 코드를 보면 알 수 있는 것. 폴더 구조, 의존성 목록, 아키텍처 개요. /doctor 점검은 저장소에 올린 CLAUDE.md 에서 이런 걸 깎자고 제안하고, 함정 · 이유 · 도구 기본값과 다른 관례는 남긴다.
2. 코드 일부에서만 필요한 규칙. .claude/rules/ 아래 규칙 파일에 paths 를 달아 두면 맞는 파일을 다룰 때만 실린다.
3. 서로 부딪치는 지시. 두 지시가 어긋나면 Claude가 아무거나 고를 수 있다. 사용자 규칙과 프로젝트 규칙도 서로를 덮어쓰지 않으니 둘을 맞춰 둬야 한다.
4. 나만 쓰는 설정. 팀이 같이 보는 CLAUDE.md 대신 CLAUDE.local.md 나 ~/.claude/CLAUDE.md 로.
5. 사람만 볼 메모를 맨 글로. 메모는 블록 단위 HTML 주석(<!-- ... -->)으로 적는다. 이 주석은 컨텍스트에 넣기 전에 지워져 자리를 차지하지 않고, 코드 블록 안 주석은 남는다.
6. 꼭 지켜져야 하는 금지. CLAUDE.md 는 강제 설정이 아니라 맥락이다. 시스템 프롬프트 뒤에 사용자 메시지로 들어가고, 엄격히 지켜진다는 보장은 없다고 문서에 적혀 있다. 무조건 막아야 하는 동작은 PreToolUse 훅, 커밋 전마다 돌아야 하는 일도 훅으로.
7. 변경 이력. 이건 문서가 아니라 우리가 정한 기준. 「v1.5 에서 추가」 같은 줄은 Claude에게 시키는 행동이 없다(아래 상자).

경로 규칙은 .claude/rules/ 아래 마크다운 파일 맨 위에 paths 를 다는 식.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation

paths 가 붙은 규칙은 Claude가 맞는 파일을 읽거나 쓰거나 고칠 때만 실린다. paths 가 없는 규칙 파일은 .claude/CLAUDE.md 와 같은 우선순위로 시작할 때 실린다.

크기: 파일당 200줄 아래, 줄이는 길은 둘

문서의 목표치는 CLAUDE.md 파일 하나에 200줄 아래. 길수록 컨텍스트를 더 쓰고 지시를 따르는 정도가 떨어진다고 적었다. 권장 길이를 넘는 파일이 있으면 시작할 때와 /status 에서 경고가 뜬다. 4MiB 를 넘는 파일은 아예 건너뛴다. 줄이는 길은 둘, 경로 규칙으로 필요할 때만 싣거나 매 세션 필요 없는 내용을 덜어 내거나.

AGENTS.md 를 같이 쓴다면: @AGENTS.md 로 불러온다

Codex 같은 다른 코딩 에이전트용 AGENTS.md 가 있는 저장소라면 알아 둘 게 하나 있다. 기본값에서 Claude Code는 작업 폴더나 그 위에 CLAUDE.md(또는 CLAUDE.local.md)가 있으면 AGENTS.md 는 읽지 않고 CLAUDE.md 만 읽는다(AGENTS.md 를 직접 읽는 기능은 v2.1.277 이상). 둘 다 읽히게 하는 방법은 CLAUDE.md 에 @AGENTS.md 한 줄을 넣어 불러오는 것(/config 의 Project instructions 를 claude-md-and-agents-md 로 바꾸는 길도 문서에 있다). 위 우리 뼈대처럼 「AGENTS.md 를 읽어라」라고 글로만 적어 두면 Claude가 그 파일을 열기로 할 때만 본다고 문서는 적는다. 두 파일을 어떻게 나눠 쓰는지는 다음 글에서.

점검: /doctor prompt-audit (2026-10-14 기준 v2.1.283 이상)

세션에서 /doctor prompt-audit 를 치면 Claude가 지시 파일을 훑어 낡았거나 서로 부딪치는 내용을 찾는다. 예전 모델에 맞춰 쓴 지시, 없는 파일이나 명령을 가리키는 줄, 서로 어긋나는 파일 같은 것. 결과는 고칠 안이 붙은 보고서로 나오고, 고쳐 달라고 하기 전까지 파일은 하나도 바뀌지 않는다. 기본 범위는 CLAUDE.md · CLAUDE.local.md · AGENTS.md, 그리고 .claude/ · ~/.claude/ 아래의 규칙 · 스킬 · 명령 · 서브에이전트 · 출력 스타일. 파일 하나만 보려면 뒤에 경로를 붙인다.

실제로 겪은 일

10월 3일, Claude가 우리 저장소의 지시 파일(CLAUDE.md, AGENTS.md, 역할별 지시 파일)을 위 /doctor 명령이 아니라 /claude-api 스킬의 프롬프트 감사로 훑었다. 보고서가 품질을 가장 크게 좌우한다고 꼽은 세 가지 중 하나가 변경 이력. AGENTS.md 앞부분 약 85줄이 릴리스 노트였고, CLAUDE.md 명령 표 설명에도 「added in v1.5」 같은 버전 표기가 섞여 있었다. 이유는 이 줄들이 작업을 시작할 때마다 다시 읽히지만 시키는 행동은 없고, 같은 내용이 결정 기록에 이미 있다는 것. 내가 이력 이동을 승인해 같은 날 이력은 결정 기록으로 원문 그대로 옮겨졌고 규칙 문장은 그대로 남았는데, 그 뒤 지시가 더 잘 지켜졌는지는 재 보지 않았다.

내 claude.md 점검표

1. 팀과 같이 쓸 규칙은 저장소 맨 위 CLAUDE.md, 내 취향은 ~/.claude/CLAUDE.md, 나만 쓸 프로젝트 설정은 CLAUDE.local.md(.gitignore 에 추가)로 갈라 뒀나.
2. /context 의 Memory files 에 실려야 할 파일이 다 보이나.
3. 파일 하나가 200줄을 넘지 않나. 시작할 때나 /status 에 길이 경고가 뜨지 않나.
4. 문장마다 맞았는지 확인할 수 있나(「제대로 정리해」 대신 「스페이스 2칸」).
5. 폴더 구조 · 의존성 목록처럼 코드를 보면 아는 내용이 들어 있지 않나.
6. 코드 일부에만 필요한 규칙을 .claude/rules/ 의 paths 규칙으로 뺐나.
7. 「언제 추가됨」 같은 변경 이력이 규칙 사이에 남아 있지 않나.
8. 반드시 막아야 하는 동작을 CLAUDE.md 문장에만 맡기고 있지 않나.
9. AGENTS.md 도 쓴다면, CLAUDE.md 에서 @AGENTS.md 로 불러오고 있나.

같이 읽을 글

• 2편 — Claude Code 설치(클로드코드 설치)부터 첫 자동화까지: 리눅스에서 매일 도는 작업 만들기: 대화 없이 claude -p 로 불러도 실행한 폴더의 CLAUDE.md 가 따라온다. 빈 폴더에서 돌리고 설정을 걷어 내 입력 토큰을 27만에서 4천으로 줄인 측정.
• 7편 — Claude Code 권한 설정(permissions)과 hooks 예시: auto mode에서 계속 막힐 때 손본 settings.json 세 곳: CLAUDE.md 문장이 아니라 설정과 훅으로 거는 규칙.

다음 글은 claude.md 와 agents.md 의 차이. 한 저장소에 두 파일을 같이 둘 때 무엇을 어디에 적는지 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.