Claude Code CLAUDE.md 작성법: 위치, 규칙 나누기, /init부터 점검까지
Claude가 테스트를 돌릴 때마다 npm test 대신 엉뚱한 명령을 쓴다면, 그 한 줄을 CLAUDE.md에 적어 둘 때입니다. 그런데 공식 문서를 읽다 보면 짚고 넘어가야 할 문장이 하나 있어요. CLAUDE.md는 시스템 프롬프트 뒤에 사용자 메시지로 전달되고, Claude가 따르려 하지만 엄격한 준수는 보장되지 않는다는 것입니다.
설정 파일처럼 보이지만 실제로는 매 세션 대화 앞에 붙는 메모라는 뜻이죠. 이걸 알고 나면 쓰는 법이 달라집니다.
프로젝트 루트에서 /init으로 초안을 만들고, Claude가 코드만 봐서는 알 수 없는 것(빌드·테스트 명령, 기본값과 다른 코드 규칙, 꼭 지킬 작업 규칙, 자주 빠지는 함정)만 200줄 안에 남기세요. 길어지면 .claude/rules/로 나누고, 실제로 읽혔는지는 /context로 확인합니다.
2026년 9월 9일 Anthropic 공식 문서(메모리·모범 사례·명령어) 기준이고, AGENTS.md 관련 내용은 9월 28일에 다시 확인했습니다. 10월 12일에는 Windows 11 · PowerShell 5.1과 Claude Code 2.1.296으로 /context, paths 규칙, AGENTS.md가 빠지는 경우를 직접 확인했습니다.
예제 프로젝트와 규칙 파일은 이 글을 위해 새로 썼습니다. Claude Code를 아직 설치하지 않았다면 Windows 설치 글부터 보세요.
확인한 버전·환경
- Claude Code 2.1.296 · Windows 11 · Windows PowerShell 5.1 · 확인일 2026-10-12
지시서이지, 강제 설정은 아니다
Claude Code는 세션마다 빈 컨텍스트로 시작합니다. 세션을 넘어 기억을 이어 주는 장치는 사람이 쓰는 CLAUDE.md와, Claude가 스스로 남기는 자동 메모리 둘이고, 둘 다 대화 시작 때 로드돼요.
자동 메모리는 Claude가 사용자의 교정과 선호를 보고 남기는 메모입니다. 프로젝트별 ~/.claude/projects/<프로젝트>/memory/에 MEMORY.md 색인과 주제 파일로 저장되고, 세션 시작 때 MEMORY.md의 처음 200줄 또는 25KB까지만 로드됩니다. /memory에서 켜고 끄거나, autoMemoryEnabled 설정이나 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1로 끕니다.
CLAUDE.md는 강제 설정이 아니라 맥락입니다. 그래서 지시는 짧고 구체적으로 쓰고, 반드시 막아야 하는 동작은 PreToolUse 훅으로 처리해야 해요.
특정 도구·명령·경로를 막으려면 설정의 permissions.deny, 정해진 시점에 스크립트를 반드시 돌리려면 훅을 씁니다. 설정은 클라이언트가 강제하고, CLAUDE.md는 행동을 안내할 뿐입니다.
비슷해 보이는 장치가 여럿이라 처음에 한 번 갈라 두면 편합니다.
| 장치 | 성격 | 이런 것에 |
|---|---|---|
CLAUDE.md |
매 세션 읽는 지시서 | 빌드 명령, 코드 규칙 |
.claude/rules/*.md |
주제별로 나눈 CLAUDE.md |
파일 종류별 규칙 |
| 스킬 | 필요할 때만 로드되는 절차 | 여러 단계 작업, 가끔 쓰는 지식 |
| 훅 | 정해진 시점에 반드시 실행 | 편집 후 린트, 커밋 전 테스트 |
| 권한 설정 | 클라이언트가 강제하는 허용·차단 | 위험 명령 차단 |
저는 매 세션 필요한 사실만 CLAUDE.md에 두고, 여러 단계짜리 절차나 일부 파일에만 해당하는 내용은 스킬이나 경로 조건 규칙으로 옮기길 권합니다. 셋을 직접 비교한 결과는 훅·스킬·CLAUDE.md를 고르는 기준에 있습니다.
파일을 둘 수 있는 네 곳과 읽히는 순서
범위가 넓은 곳부터 좁은 곳 순서로 로드되므로, 프로젝트 지시가 사용자 지시 뒤에 붙습니다.
| 범위 | 위치 | 공유 대상 |
|---|---|---|
| 조직 관리 정책 | Windows: C:\Program Files\ClaudeCode\CLAUDE.md |
조직 전체 |
| 사용자 | ~/.claude/CLAUDE.md(%USERPROFILE%\.claude\CLAUDE.md) |
나, 모든 프로젝트 |
| 프로젝트 | ./CLAUDE.md 또는 ./.claude/CLAUDE.md |
저장소를 쓰는 팀 |
| 로컬 | ./CLAUDE.local.md(.gitignore에 추가) |
나, 이 프로젝트 |
조직 정책 파일은 IT 부서가 배포하는 공통 규칙이고 macOS·Linux는 경로가 다릅니다. 로컬 파일에는 테스트 데이터나 개인 URL 같은 나만의 메모를 둡니다.
팀과 공유하는 방법도 이 표에서 나옵니다. CLAUDE.md(또는 .claude/CLAUDE.md)와 .claude/rules/를 저장소에 커밋하고, 개인 취향은 CLAUDE.local.md에 적어 .gitignore에 넣으면 돼요.
코드처럼 다루면 됩니다. 문제가 생기면 검토하고, 정기적으로 가지치기하고, 바꾼 뒤 Claude의 행동이 실제로 달라지는지 봅니다.
헷갈리기 쉬운 건 어느 폴더의 파일이 언제 읽히느냐입니다.
- 현재 폴더와 그 위의 모든 폴더의
CLAUDE.md·CLAUDE.local.md는 시작 때 읽힙니다.foo/bar/에서 실행하면foo/bar/CLAUDE.md와foo/CLAUDE.md가 함께 읽힙니다. - 하위 폴더의 파일은 시작 때가 아니라 Claude가 그 폴더의 파일을 읽을 때 포함됩니다. 모노레포에서 패키지별 규칙을 두는 방법입니다.
- 파일들은 서로 덮어쓰지 않고 이어 붙습니다. 루트에서 현재 폴더 방향 순서이고, 같은 폴더에서는
CLAUDE.local.md가CLAUDE.md뒤에 붙습니다.
상위 폴더에 다른 팀의 CLAUDE.md가 있어 방해되면 설정의 claudeMdExcludes에 경로 패턴을 적어 뺄 수 있습니다. 조직 정책 파일은 뺄 수 없어요.
/init으로 만들고, 줄여 나가기
빈 파일에서 시작할 필요는 없습니다. 저라면 이 순서로 하겠습니다.
1. /init으로 초안 만들기
프로젝트 폴더에서 Claude Code를 실행하고 /init을 입력하면, Claude가 코드베이스를 분석해 빌드 명령·테스트 방법·관례를 담은 CLAUDE.md를 만듭니다. 이미 파일이 있으면 덮어쓰지 않고 개선안을 제안해요. .cursor/rules/·.cursorrules(Cursor)나 .github/copilot-instructions.md(Copilot)가 있으면 그 내용도 반영합니다.
환경 변수 CLAUDE_CODE_NEW_INIT=1을 켜면 무엇을 만들지(CLAUDE.md, 스킬, 훅) 묻고, 서브에이전트로 코드베이스를 살핀 뒤 제안서를 보여 주고 나서 파일을 쓰는 대화형 흐름으로 바뀝니다.
2. /context로 실제로 읽혔는지 보기
/context를 실행하면 지금 세션에 로드된 파일이 Memory files 항목에 나옵니다. 여기에 없으면 Claude는 그 파일을 보지 못한 거예요.
대화를 열지 않고 claude -p "/context"로도 같은 표를 볼 수 있어서 확인이 빠릅니다. CLAUDE.md에 @AGENTS.md 한 줄과 개인 메모 CLAUDE.local.md를 둔 C:\work\todo-cli에서 돌려 보니 이렇게 나왔습니다. 사용자 범위 줄은 뺐어요.
### Memory Files
| Type | Path | Tokens |
|------|------|--------|
| Project | C:\work\todo-cli\CLAUDE.md | 19 |
| Project | C:\work\todo-cli\AGENTS.md | 39 |
| Local | C:\work\todo-cli\CLAUDE.local.md | 38 |
파일마다 토큰 수가 붙어 나와서, 어느 파일이 컨텍스트를 얼마나 쓰는지도 같이 보여요. /memory는 사용자·프로젝트 범위의 CLAUDE.md 위치를 보여 주고, 아직 없는 파일도 고르면 만들어 편집기로 열어 줍니다.
3. 줄마다 “지우면 실수할까?” 묻기
/init의 초안은 출발점일 뿐입니다. 줄마다 “이 줄을 지우면 Claude가 실수할까?“를 묻고, 아니면 지우세요.
파일이 길수록 중요한 규칙이 묻혀 오히려 무시됩니다. 권장 크기는 파일당 200줄 이하이고, 4 MiB를 넘는 파일은 통째로 건너뜁니다.
| 넣을 것 | 뺄 것 |
|---|---|
| 추측할 수 없는 빌드·테스트·배포 명령 | 코드를 읽으면 아는 폴더 구조·의존성 |
| 언어 기본값과 다른 코드 규칙 | 이미 아는 표준 관례 |
| 선호하는 테스트 방법 | 상세 API 문서(링크로 대체) |
| 브랜치 이름, PR 규칙 | 자주 바뀌는 정보 |
| 이 프로젝트만의 아키텍처 결정 | 긴 설명·튜토리얼 |
| 필요한 환경 변수 같은 특이점 | 파일별 설명 |
| 자주 빠지는 함정 | “깨끗한 코드를 쓴다” 같은 당연한 말 |
문장은 지켰는지 확인할 수 있을 만큼 구체적으로 씁니다. “코드를 잘 포맷한다” 대신 “2칸 들여쓰기를 쓴다”, “변경을 테스트한다” 대신 “커밋 전에 npm test를 실행한다”처럼요.
강조는 아껴 쓰세요. 한 지시만 계속 빠지면 그 줄에만 “IMPORTANT”를 붙이고, 여러 줄을 강조하면 어느 것도 눈에 띄지 않습니다.
규칙끼리 부딪히면 Claude가 임의로 하나를 고르니 주기적으로 모순을 정리하고요. 사람만 볼 메모는 HTML 주석(<!-- -->)으로 적으면 컨텍스트에 들어가기 전에 지워집니다(코드 블록 안 주석은 남음).
4. 예제: 23줄짜리 CLAUDE.md
할 일을 JSON 파일에 저장하는 Node 22 + TypeScript CLI(todo-cli)를 가정해 새로 쓴 예제입니다. 모든 줄이 “코드만 봐서는 모르거나, 알아도 자주 빠지는 것”이에요.
# todo-cli
로컬 JSON 파일에 할 일을 저장하는 Node 22 + TypeScript CLI.
## 명령
- 설치: `npm ci`
- 테스트 전체: `npm test` (vitest). 파일 하나만: `npx vitest run tests/add.test.ts`
- 타입 검사: `npm run check` (tsc --noEmit)
- 빌드: `npm run build` → `dist/`
## 코드 규칙
- ES 모듈(import/export)만 쓴다. require는 쓰지 않는다.
- 저장 파일 경로는 `src/config.ts`의 `DATA_FILE`만 참조한다. 경로를 직접 적지 않는다.
- 새 명령은 `src/commands/<이름>.ts` 파일 하나에 하나씩 만들고, 시그니처는 `add.ts`를 따른다.
## 작업 규칙
- 코드를 바꾼 뒤 `npm run check`와 관련 테스트를 실행하고 결과를 그대로 보고한다.
- `data/` 아래 파일은 사용자 데이터다. 읽기만 하고 수정·삭제하지 않는다.
## 함정
- Windows PowerShell 5.1에는 `&&`가 없다. 명령을 한 줄에 하나씩 실행한다.
“파일 하나만 테스트하는 법”은 전체 대신 단일 테스트를 돌리라는 모범 사례와 같은 이유로 넣었습니다. 폴더 설명이나 의존성 목록은 package.json을 읽으면 알 수 있어서 뺐고요.
길어지면 .claude/rules/로 나누기
.claude/rules/ 폴더의 .md 파일은 하위 폴더까지 모두 읽힙니다. 파일 하나에 주제 하나(code-style.md, testing.md, security.md)를 두면 되고, 규칙은 paths가 있느냐 없느냐로 갈립니다.
paths가 없는 규칙은 시작 때 로드되고.claude/CLAUDE.md와 우선순위가 같습니다.CLAUDE.md를 여러 파일로 나눈 것과 같아요.paths가 있는 규칙은 패턴에 맞는 파일을 다룰 때만 로드됩니다. 모든 도구 호출이 아니라 그 파일에 Read·Write·Edit를 쓸 때이고, Claude Code 2.1.288 이전에는 Read로 읽을 때만 로드됐습니다.
위 예제에서 테스트 규칙은 테스트 파일을 다룰 때만 필요하므로 .claude/rules/tests.md로 뺐습니다. 세션 시작 때 컨텍스트를 차지하지 않으니 루트 CLAUDE.md가 짧아지죠.
정말 그때만 들어오는지 직접 확인해 봤습니다. 아래 규칙을 두고 “테스트에서 실제 파일 시스템 대신 무엇을 쓰라는 지시를 받았냐”고 물으니, 파일을 열지 않은 세션은 그런 지시를 받은 적이 없다고 답하더라고요.
tests/add.test.ts를 먼저 읽게 하자 답이 달라졌습니다. 그 파일을 읽을 때 .claude/rules/tests.md가 함께 들어왔고, tmp-store.ts를 쓰라는 규칙을 정확히 짚었어요.
---
paths:
- "tests/**/*.test.ts"
---
# 테스트 규칙
- 실제 파일 시스템 대신 `tests/helpers/tmp-store.ts`의 임시 저장소를 쓴다.
- 테스트 이름은 "무엇을 하면 무엇이 된다" 형태의 한 문장으로 쓴다.
- 실패를 재현하는 테스트를 먼저 추가한 뒤 코드를 고친다.
paths에는 glob 패턴을 씁니다. **/*.ts는 모든 폴더의 TypeScript 파일, src/**/*는 src/ 아래 전부, *.md는 루트의 Markdown 파일이에요. 쓰다 보면 걸리는 것들도 적어 둡니다.
src/**/*.{ts,tsx}처럼 중괄호로 묶을 수 있고, 규칙 하나의paths에 확장 패턴 1,000개·4 MiB 예산이 있습니다(v2.1.217 이전에는 중괄호가 많으면 시작이 멈추는 문제가 있었습니다).- 파일명에
[가 있으면\[로 이스케이프합니다. - 개인 규칙은
~/.claude/rules/에 둡니다. 프로젝트 규칙보다 먼저 로드돼 프로젝트 규칙이 우선합니다. 심볼릭 링크도 되므로 공용 규칙 폴더를 여러 프로젝트에 연결할 수 있습니다.
@경로는 파일을 나눌 뿐 컨텍스트를 줄이지 않는다
CLAUDE.md 안에 @경로를 적으면 그 파일이 시작 때 함께 펼쳐져 들어갑니다. 정리는 되지만 컨텍스트 절약은 안 되니, 절약이 목적이라면 paths 규칙을 쓰세요.
프로젝트 개요는 @README, 사용 가능한 npm 명령은 @package.json 참고.
- git 작업 규칙 @docs/git-instructions.md
- 상대 경로는 작업 폴더가 아니라 그
@를 적은 파일 기준입니다. 최대 4단계까지 따라갑니다. - 코드 스팬·코드 블록 안의
@는 무시됩니다. 백틱으로 감싼`@README`는 글자로 남습니다. @~/.claude/my-project-instructions.md처럼 홈 폴더 파일도 가져올 수 있어, 여러 워크트리에서 개인 지시를 공유할 때 씁니다.- 프로젝트 파일이 작업 폴더 밖을 가져오면 처음 한 번 승인 대화상자가 뜹니다. 거절하면 그 import는 계속 꺼져 있습니다.
AGENTS.md도 쓰는 저장소라면
v2.1.277부터 Claude Code는 AGENTS.md를 직접 읽습니다. 다만 기본값에서는 작업 폴더와 그 위에 CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md가 하나도 없을 때만 읽어요.
~/.claude/CLAUDE.md, 조직 정책 파일, .claude/rules/는 이 판단에 들어가지 않고, 기본값은 /config의 Project instructions에서 바꿉니다.
이 조건이 실제로 얼마나 쉽게 걸리는지 Windows에서 재현해 봤습니다. AGENTS.md에 “테스트: pnpm test:unit” 한 줄만 둔 폴더에서 테스트 명령을 물으니 바로 그 명령을 답했어요.
그런데 개인 메모용 CLAUDE.local.md를 하나 추가하자, 같은 질문에 “받은 지시에 테스트 명령이 없어서 모른다”고 답하더라고요. 이때 /context의 Memory files에는 CLAUDE.local.md 한 줄만 남고 AGENTS.md가 사라져 있었습니다.
CLAUDE.md에 @AGENTS.md 한 줄을 넣자 다시 pnpm test:unit을 답했고, Memory files에도 AGENTS.md가 돌아왔습니다. 개인 메모 하나가 팀 지시 전체를 조용히 끄는 셈이라, 이 함정은 꼭 기억해 두세요.
그래서 CLAUDE.md도 있는 저장소라면 내용을 복제하지 말고 한 줄로 가져오는 걸 권합니다. import 아래 적은 Claude 전용 지시는 가져온 파일 다음에 읽힙니다.
@AGENTS.md
## Claude Code
`src/billing/` 아래를 바꿀 때는 plan 모드를 쓴다.
이 import는 Project instructions를 claude-md(CLAUDE.md만)로 둔 경우와, AGENTS.md를 직접 읽지 못하는 세션(v2.1.277 이전, /plugin에서 내장 agents-md 플러그인을 끈 경우, v2.1.281 이전의 Amazon Bedrock·텔레메트리를 끈 세션 등)에서도 쓸모가 있습니다. 설정값이 무엇이든 import 때문에 AGENTS.md가 두 번 읽히지는 않아요.
macOS·Linux에서는 ln -s AGENTS.md CLAUDE.md 심볼릭 링크도 되지만, Windows는 관리자 권한이나 개발자 모드가 필요해 @AGENTS.md를 권합니다.
하위 폴더의 AGENTS.md가 언제 붙는지, AGENTS.override.md처럼 이름이 비슷한 파일이 읽히는지는 Claude Code가 읽는 AGENTS.md와 안 읽는 파일에 따로 확인해 뒀습니다.
Codex나 Gemini CLI 설정을 통째로 옮기려면 /import(v2.1.213 이상)를 씁니다. 여러 도구의 설정 파일을 나란히 비교한 내용은 CLAUDE.md·AGENTS.md·GEMINI.md 비교에 있습니다.
잘 안 지켜질 때 점검 순서
1. CLAUDE.md를 무시하는 것 같을 때
파일이 로드되지 않았거나, 지시가 모호하거나, 다른 파일과 부딪히는 경우입니다.
/context의 Memory files에 파일이 있는지부터 보세요. 없으면 위치 문제입니다.
있으면 지시를 “2칸 들여쓰기”처럼 확인 가능한 문장으로 바꾸고, 여러 CLAUDE.md와 .claude/rules/ 사이의 충돌을 찾습니다. 반드시 실행돼야 하는 일(커밋 전, 편집 후)은 훅으로 옮기고요.
2. 파일이 너무 길 때
200줄을 넘으면 컨텍스트를 많이 쓰고 준수율이 떨어집니다. 4 MiB를 넘으면 아예 로드되지 않아요.
경로 조건으로 옮길 수 있는 내용은 .claude/rules/로 빼고, 매 세션 필요 없는 내용은 지웁니다. 커밋된 CLAUDE.md라면 /doctor가 코드에서 알 수 있는 내용(폴더 구조, 의존성, 아키텍처 개요)을 골라 삭제를 제안합니다(v2.1.206 이상).
3. AGENTS.md가 있는데 읽히지 않을 때
작업 폴더나 그 위에 CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md 중 하나라도 있으면 기본값에서는 그 파일만 읽습니다. 개인 메모용 CLAUDE.local.md 하나만 추가해도 AGENTS.md가 빠지는 거예요. v2.1.277보다 낮거나 Project instructions가 claude-md·managed-only여도 읽지 않습니다.
위 세 파일이 있으면 Project instructions를 claude-md-and-agents-md로 바꾸거나 @AGENTS.md를 넣으세요.
claude --version이 v2.1.277 이상인지, Amazon Bedrock이나 텔레메트리를 끈 세션이면 v2.1.281 이상인지도 봅니다. /config에 Project instructions 항목이 아예 없으면 직접 읽을 수 없는 세션이니 @AGENTS.md를 씁니다.
읽혔는지는 /memory 목록이나 /context의 Memory files에 AGENTS.md 경로가 있는지로 봅니다. v2.1.280 이전에는 직접 읽힌 AGENTS.md가 /memory·/context에 나오지 않으니 Claude에게 프로젝트 지시를 물어보세요.
4. /compact 뒤에 지시가 사라진 것 같을 때
대화로만 말한 지시는 압축 때 요약될 수 있습니다. 하위 폴더 CLAUDE.md와 paths 규칙은 해당 파일을 다시 다룰 때 재로드되고요. 프로젝트 루트 CLAUDE.md는 /compact 뒤 디스크에서 다시 읽히므로, 계속 유지할 지시는 대화가 아니라 CLAUDE.md에 적어 두세요.
5. 어떤 파일이 언제 로드되는지 모르겠을 때
하위 폴더 파일과 경로 조건 규칙은 나중에 로드돼 눈에 잘 안 띕니다. /context로 현재 상태를 보고, 더 자세히는 InstructionsLoaded 훅으로 어떤 지시 파일이 언제, 왜 로드됐는지 기록합니다. 단, CLAUDE.md를 거치지 않고 직접 읽힌 AGENTS.md에는 이 훅이 발동하지 않습니다.
시스템 프롬프트 수준의 지시가 필요하면 --append-system-prompt를 쓰되, 실행마다 넘겨야 하므로 스크립트용이에요.
다른 사람들이 겪은 문제
규칙을 빠짐없이 길게 적어 두면 더 잘 지킬 것 같지만, 다른 사람들이 공개한 기록은 반대 방향을 가리킵니다. 아래는 각 작성자의 기록을 정리한 것입니다.
- 471줄까지 늘렸다가 61줄로 줄인 경우. Pawel Jozefiak(2026-02-28, 글)는 1,000회 넘는 세션을 거치며
CLAUDE.md를 3줄에서 471줄로 키웠다가 61줄로 줄였다고 정리했습니다. 백과사전처럼 쓰자 에이전트가 혼란스러워했고, 얇은 안내 계층과 필요할 때 읽는 참고 문서로 나눠 해결했다고 합니다. “철저하게 하라” 같은 형용사를 “실행하고 출력을 보여 준 뒤 완료로 표시한다” 같은 행동으로 바꿨다는 대목이 제게는 가장 실용적이었습니다. - 200줄 규칙을 썼는데 무시당한 경우. DavidAI311(2026-03-08, 글)은 200줄 규칙과 258개 문서의 지식베이스로 “답하기 전에 검색” 같은 절차를 강제하려 했지만 반복해서 무시당했고, 결국 훅과 커밋 전 검사로 옮겼다고 적었습니다. 공식 문서가 반드시 실행돼야 하는 일을 훅으로 옮기라는 것과 같은 결론입니다.
- 압축 뒤 지시가 사라진 경우. 2026-01-20 Claude Code 저장소에 올라온 #19471(버전 2.0.76)은 루트
CLAUDE.md에 적은 폴더 규칙이 긴 세션에서 압축된 뒤 무시됐다고 보고했고, not planned로 닫혔습니다. 공식 문서는 프로젝트 루트CLAUDE.md는 압축 뒤 디스크에서 다시 읽힌다고 설명하지만, 하위 폴더 파일과paths규칙은 해당 파일을 다시 다룰 때 로드되므로 압축 직후 잠시 빠지는 구간이 생길 수 있습니다.
“80줄부터 규칙이 빠지기 시작한다” 같은 커뮤니티 수치도 돌지만 측정 방법이 공개돼 있지 않아 주장으로만 봅니다. 확인된 기준은 공식 권장값인 200줄 이하이고, 그보다 길면 준수율이 떨어진다는 방향만 여러 기록이 공통으로 가리킵니다.
마치며
CLAUDE.md는 “설정”이라는 이름 때문에 적으면 지켜질 거라고 기대하기 쉽지만, 실제로는 매 세션 붙는 메모에 가깝습니다. 그래서 저는 코드만 봐서는 모르는 것만 짧게 적고, 길어지면 paths 규칙으로 나누고, 반드시 지켜야 하는 것은 훅이나 권한으로 내리는 쪽을 권합니다.
가장 먼저 해 볼 만한 건 /context를 열어 자기 CLAUDE.md가 Memory files에 있는지 확인하고, 줄마다 “지우면 실수할까?“를 물어 하나라도 지워 보는 것입니다. 그다음은 권한이에요. 어떤 명령을 묻지 않고 실행하게 하고 어떤 폴더는 막을지는 allow·deny 규칙의 평가 순서와 자주 새는 패턴에서 이어집니다.
참고한 공식 자료
- How Claude remembers your project — 위치·로드 순서,
.claude/rules/와paths,@import, 자동 메모리, 문제 해결 (2026-09-09 확인).AGENTS.md절과 문제 해결 항목 (2026-09-28 확인) - Claude Code CHANGELOG — 2.1.277의
AGENTS.md직접 읽기, 2.1.281의 지원 세션 확대 (2026-09-28 확인), 2.1.288의 경로 규칙 로드 범위 변경 - Best practices for Claude Code — “지우면 실수할까” 기준, 넣을 것·뺄 것, IMPORTANT 강조 (2026-09-09 확인)
- Built-in commands —
/init,/memory,/context,/doctor,/import와 버전 요건 (2026-09-09 확인,/context는 2026-10-12 직접 실행)
인용한 공개 사례
- Pawel Jozefiak, How to Structure CLAUDE.md: Lessons From 1,000+ Sessions (2026-02-28)
- DavidAI311, I Wrote 200 Lines of Rules for Claude Code. It Ignored Them All. (2026-03-08)
- anthropics/claude-code 이슈 #19471 — 압축 후 지시 무시 보고, 계획 없음으로 종료 (2026-01-20)
변경 이력
- 2026-10-12 — Windows 11에서 직접 확인한 결과를 더했습니다. claude -p "/context"로 로드된 지시 파일을 보는 법, paths 규칙이 테스트 파일을 읽을 때만 들어오는 것, CLAUDE.local.md 하나를 추가하면 AGENTS.md가 읽히지 않고 @AGENTS.md로 되돌릴 수 있는 것입니다.
- 2026-10-06 — Claude Code 2.1.288부터 경로 규칙(paths)이 파일을 읽을 때뿐 아니라 만들거나 고칠 때도 로드되도록 바뀌어 설명을 고쳤습니다.
- 2026-09-28 — Claude Code v2.1.277부터 CLAUDE.md가 없는 프로젝트에서 AGENTS.md를 직접 읽게 되어, AGENTS.md를 읽지 않는다고 적은 설명과 점검 순서 3번을 새 동작에 맞게 고쳤습니다.
- 2026-09-09 — 공개 사례 4건을 출처와 함께 정리한 절을 추가했습니다.