메모리(CLAUDE.md)

확인 날짜 안내

확인 날짜가 섞인 페이지다. 공식 문서 두 건(Claude Code 메모리, Claude Code 확장 기능 개요)은 원본 날짜 미상이라 수집일(2026-10-18) 기준이고, 공식 CLI 문서 Claude Code CLI 레퍼런스(원본 날짜 미상, 서버 Last-Modified 2026-10-20, 수집 2026-10-21) 부분은 2026-10-21, Anthropic 엔지니어링 글 부분은 발행일(2025-09-29), Anthropic 블로그 Steering Claude Code 부분은 발행일(2026-06-18) 기준이다. 날짜가 다른 문장에는 기준일을 따로 적었다. 페이지 확인 날짜는 2026-10-18이다. 2025-09-29 글의 Claude Code 동작(CLAUDE.md를 시작 때 넣기), 루트·하위 디렉터리 CLAUDE.md의 로드·컴팩션 동작, 중앙 관리 CLAUDE.md 문장은 공식 문서가 확인한다. 블로그의 비용 등급과 managed settings "유일한 방법"은 "(블로그 평가)"로 표시하고, --append-system-prompt의 적용 범위는 공식 CLI 문서가 직접 적어(플래그 텍스트는 첫 요청에서 만든 시스템 프롬프트에 기록되고 컴팩션 전까지 --resume·--continue로 돌아와도 유지, 예외는 Claude Code CLI 플래그) 블로그의 "그 실행에만 적용된다"와 상충으로 나란히 두고 설명은 공식 기준으로 한다. 그래서 블로그 단독인 변하는 사실이 남지 않는다.

정의#

Claude Code가 매 세션 시작 때 읽는 마크다운(용어 사전) 지시 파일이다. 프로젝트, 개인 작업 방식, 조직 전체에 대한 지속 지시를 담는다. Claude Code 메모리 원본 예시: "npm 말고 pnpm을 써라. 커밋 전에 테스트를 돌려라." Claude Code 확장 기능 개요

Claude Code 세션은 매번 빈 컨텍스트 창으로 시작한다. 세션을 넘어 지식을 잇는 장치는 두 가지다. 사용자가 쓰는 CLAUDE.md와, Claude가 사용자의 교정과 선호를 바탕으로 스스로 쓰는 자동 메모리(Auto memory)다. Claude Code 메모리

이름이 비슷한 다른 장치: Claude Developer Platform의 메모리 도구(memory tool)는 API로 앱을 만드는 개발자가 요청에 넣는 도구로, Claude가 /memories 폴더의 파일로 대화를 넘어 정보를 쌓고 실제 저장은 그 앱이 맡는다(2026-10-26 기준). 그 공식 문서는 Claude Code를 말하지 않으므로, 이 페이지의 CLAUDE.md·자동 메모리와 같은 것으로 설명하지 않는다. Claude 메모리 도구 문서 → 장기 작업 컨텍스트 관리

근거: Claude Code 메모리 (원본 "CLAUDE.md vs auto memory" 표를 옮긴 것이다)

Claude Code는 저장소에 CLAUDE.md 대신 AGENTS.md가 있으면 그것을 프로젝트 지시로 읽을 수 있다. Claude Code 메모리 → AGENTS.md와 CLAUDE.md 함께 쓰기

원본은 Claude Code를 처음 쓰면 CLAUDE.md부터 시작하고, 다른 확장은 구체적인 계기가 생길 때 추가하라고 권한다. Claude Code 확장 기능 개요 → Claude Code 셋업 점진적으로 키우기

LLM Wiki 패턴에서는 이 파일이 위키의 스키마 파일 역할을 한다. Karpathy LLM Wiki

무엇을 넣는가#

• 원본은 CLAUDE.md를 "안 적어 두면 다시 설명하게 될 것"을 적는 곳으로 보라고 한다. Claude Code 메모리
• 넣는다: 빌드 명령, 관례, 프로젝트 구조, "항상 X를 하라" 규칙처럼 매 세션 알아야 할 사실. Claude Code 메모리 코딩 관례, 테스트 관례, 아키텍처, "절대 X를 하지 마라" 규칙도 같은 범주다. Claude Code 확장 기능 개요
• 빼서 스킬로: 여러 단계 절차, 가끔만 필요한 참고 자료(API 문서, 스타일 가이드), /<name>으로 부르는 워크플로. Claude Code 메모리, Claude Code 확장 기능 개요 공식 스킬 문서는 이 기준을 "CLAUDE.md의 한 절이 사실이 아니라 절차로 자랐을 때"로 말한다. Claude Code 스킬 → 업무 절차를 스킬로 만들기
• 빼서 .claude/rules/로: 코드베이스 일부에만 해당하는 지시, 언어별·디렉터리별 지침. paths frontmatter를 단 규칙은 맞는 파일을 다룰 때만 로드돼 컨텍스트를 아낀다. Claude Code 메모리, Claude Code 확장 기능 개요
• 빼서 출력 스타일로: 응답 자체에 관한 것(길이, 형식, 설명량, 다른 역할)이면서 다시 끄고 싶을 수 있는 것. CLAUDE.md는 어떤 스타일을 고르든 계속 로드된다. Claude Code 확장 기능 개요 공식 출력 스타일 문서도 같은 구분이다: 프로젝트 관례·명령·구조는 CLAUDE.md, 모든 응답의 목소리·길이·형식은 출력 스타일, 원본 조합 예는 "알아야 할 것은 CLAUDE.md, 응답 방식은 출력 스타일, 보장돼야 하는 것은 훅"(2026-10-18 기준). Claude Code 출력 스타일
• (2026-06-18 기준) 블로그 글은 CLAUDE.md를 Claude가 항상 들고 있을 사실(빌드 명령, 모노레포 구조, 팀 관례)용으로 보고, 코드베이스 개요나 더 많은 정보가 있는 다른 파일을 가리키는 색인처럼 생각하라고 한다. 30줄짜리 절차는 스킬로, src/api/**처럼 일부에만 해당하는 규칙은 paths:로 범위를 지정한 rules로, 개인 선호는 사용자 수준 파일로 옮기라고 한다. Steering Claude Code → Claude Code 확장 기능 고르기

작성 절차와 예시: CLAUDE.md 작성·구성

어디에 두는가: 네 가지 범위 (2026-10-18 기준)#

근거: Claude Code 메모리. 표는 넓은 범위에서 좁은 범위 순, 곧 로드 순서다. 그래서 프로젝트 지시가 사용자 지시보다 컨텍스트에서 뒤에 온다.

어떻게 로드되는가#

• 작업 디렉터리와 그 위 모든 디렉터리의 CLAUDE.md·CLAUDE.local.md를 시작할 때 로드한다. foo/bar/에서 실행하면 foo/bar/CLAUDE.md, foo/CLAUDE.md와 그 옆의 CLAUDE.local.md를 읽는다. Claude Code 메모리 세션 시작 때 managed, user, project 레벨의 CLAUDE.md 전체 내용이 로드된다. Claude Code 확장 기능 개요
• 여러 파일은 덮어쓰지 않고 이어 붙는다. 파일시스템 루트에서 작업 디렉터리 쪽 순서라 시작 위치에 가까운 지시가 마지막에 읽힌다. 같은 디렉터리 안에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙는다. Claude Code 메모리
• 작업 디렉터리 아래 하위 디렉터리의 CLAUDE.md는 시작 때가 아니라, Claude가 그 하위 디렉터리의 다른 파일을 읽거나 쓰거나 고칠 때 한 번 로드된다. cat·head처럼 읽기로 치는 Bash 명령도 포함된다. Claude Code 메모리
• 블록 단위 HTML 주석(<!-- maintainer notes -->)은 컨텍스트에 넣기 전에 지워진다. 사람 관리자용 메모를 토큰 비용 없이 남길 수 있다. 코드 블록 안의 주석은 남는다. Claude Code 메모리
• CLAUDE.md 내용은 시스템 프롬프트의 일부가 아니라 시스템 프롬프트 뒤의 사용자 메시지로 전달된다. Claude Code 메모리
• (2026-10-18 기준, 블로그 글 2026-06-18) 블로그 글의 구분: 루트 CLAUDE.md(공유 저장소의 것과 개인용 로컬 파일 모두)는 세션 시작 때 로드돼 세션 내내 남고 긴 세션에서도 사라지거나 약해지지 않는다. 하위 디렉터리 CLAUDE.md는 필요할 때 로드된다. 예컨대 app/api/CLAUDE.md는 세션 시작이 아니라 Claude가 app/api 아래 파일을 읽을 때 로드된다. 비용 등급은 루트 High, 하위 디렉터리 Low(블로그 평가). Steering Claude Code 로드 시점은 공식 메모리 문서가 확인한다("Files in subdirectories load on demand"). Claude Code 메모리 → 컨텍스트 비용
• --add-dir로 더한 디렉터리의 CLAUDE.md는 기본으로 로드되지 않는다. CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1을 설정하면 로드된다. Claude Code 메모리
• 로드 확인: 세션에서 /context를 실행해 Memory files 목록을 본다. Claude Code 메모리
• (2025-09-29 기준) Anthropic 엔지니어링 글은 Claude Code가 CLAUDE.md를 처음부터 넣는 방식을 혼합 전략의 예로 든다. CLAUDE.md는 처음부터 컨텍스트에 그대로 넣고, 나머지 파일은 glob·grep 같은 기본 도구로 그때그때(just-in-time) 찾는다. 원본은 이렇게 해서 낡은 색인과 복잡한 구문 트리 문제를 피한다고 설명한다. 효과적인 컨텍스트 엔지니어링 → 컨텍스트 엔지니어링

지시가 충돌할 때#

원본끼리 달랐던 점(정리됨)지시가 충돌할 때 (콜아웃 정리 2026-10-21)

• Claude Code 확장 기능 개요 (원본 날짜 미상, 수집 2026-10-18): 여러 레벨의 CLAUDE.md는 모두 더해지고, 지시가 충돌하면 Claude가 판단해(uses judgment) 조정한다.
• Claude Code 메모리 (원본 날짜 미상, 수집 2026-10-18): 두 지시가 서로 모순되면 Claude가 그중 하나를 임의로(arbitrarily) 고를 수 있다. ~/.claude/rules/의 사용자 규칙과 프로젝트 규칙이 충돌해도 어느 쪽이든 따를 수 있으니 둘을 일관되게 유지하라고 한다.
• 2026-10-18에 정한 편집 기준(메모리 문서 쪽)에 맞춰 상충 콜아웃을 "정리됨"으로 바꾼다. 근거: 메모리 문서의 "if two instructions contradict each other, Claude may pick one arbitrarily"는 사람이 할 일(지시를 일관되게 유지)까지 주고, 확장 기능 개요의 "When instructions conflict, Claude uses judgment to reconcile them"은 그렇지 않다. 두 주장과 출처는 그대로 둔다.

편집 기준: 이 위키는 메모리 문서 쪽으로 설명한다. 지시가 모순되면 Claude가 하나를 임의로 고를 수 있으니, 사람이 지시를 일관되게 유지해야 한다. 더 구체적이고 실천 지침이 붙어 있어서다. 위 두 주장은 기록으로 남긴다. Claude Code 메모리

메모리 문서는 이에 대한 대처로 CLAUDE.md, 하위 디렉터리 CLAUDE.md, .claude/rules/를 주기적으로 검토해 낡거나 충돌하는 지시를 지우라고 권하고, /doctor prompt-audit로 Claude에게 찾게 할 수 있다고 한다. Claude Code 메모리 → CLAUDE.md 작성·구성

import와 규칙 파일#

• @path/to/import 구문으로 다른 파일을 가져온다. 상대 경로는 가져오는 파일 기준이고, 재귀 import는 최대 4단계다. 가져온 파일도 시작 때 함께 로드된다. Claude Code 메모리 스킬처럼 @path import를 쓸 수 있지만, 스킬과 달리 /<name>으로 워크플로를 실행할 수는 없다. Claude Code 확장 기능 개요
• import는 긴 파일을 정리하는 데 도움이 되지만 컨텍스트 비용은 줄이지 않는다. Claude Code 메모리 → 컨텍스트 비용
• 프로젝트 수준 메모리 파일의 import가 작업 디렉터리 밖을 가리키면(외부 import) 처음 만날 때 승인 대화상자가 뜬다. 거절하면 꺼진 채로 남고 다시 묻지 않는다. 사용자 범위 파일(~/.claude/CLAUDE.md, ~/.claude/rules/)의 import는 대화상자 없이 로드된다(데스크톱 Cowork 세션 제외). 다른 사람이 공유 프로젝트에 커밋한 파일로부터 보호하기 위해서다. Claude Code 메모리
• .claude/rules/에 주제별 .md 파일을 두면 하위 폴더까지 재귀로 찾는다. paths가 없는 규칙은 .claude/CLAUDE.md와 같은 우선순위로 시작 때 로드되고, paths가 있는 규칙은 맞는 파일을 다룰 때만 로드된다. ~/.claude/rules/는 모든 프로젝트에 적용되는 개인 규칙이며 프로젝트 규칙보다 먼저 로드된다. Claude Code 메모리
• 규칙 파일도 항상 컨텍스트에 있을 필요가 없는 작업별 지시라면 스킬이 낫다. 스킬은 부르거나 관련 있다고 판단될 때만 로드된다. Claude Code 메모리

크기: 200줄#

• 공식 메모리 문서는 CLAUDE.md 파일당 200줄 이하를 목표로 하라고 한다. 길수록 컨텍스트를 더 쓰고 지시 준수가 떨어진다. Claude Code 메모리 확장 기능 개요 문서도 경험칙(rule of thumb)으로 200줄 이하를 권하고, 커지면 참고 내용은 스킬로 옮기거나 .claude/rules/ 파일로 나누라고 한다. Claude Code 확장 기능 개요
• Claude Code는 4 MiB까지의 CLAUDE.md는 전부 로드하고 그보다 큰 파일은 건너뛴다. 원본은 짧은 파일일수록 준수가 좋다고 덧붙인다. Claude Code 메모리
• 권장 길이를 넘는 파일이 있으면 시작 때와 /status에서 경고가 뜬다. 하나하나는 권장 길이 안이어도 합계가 한도를 넘으면 경고가 뜬다. Claude Code 메모리
• /doctor는 체크인된 CLAUDE.md를 줄일 제안을 낸다. 코드베이스에서 알 수 있는 내용(디렉터리 구조, 의존성 목록, 아키텍처 개요)은 빼고, 함정·이유·도구 기본값과 다른 관례는 남긴다. Claude Code 메모리, Claude Code 확장 기능 개요
• 배경: CLAUDE.md는 세션 시작 때 전체가 로드되고 매 요청에 컨텍스트 비용이 든다. Claude Code 확장 기능 개요 → 컨텍스트 비용

서브에이전트와 컴팩션#

• 서브에이전트도 기본적으로 CLAUDE.md를 받는다. 예외: 내장 Explore·Plan 에이전트는 CLAUDE.md 없이 시작하고, 정의에 omitClaudeMd를 둔 에이전트는 user·project·local CLAUDE.md 없이 시작한다. Claude Code 확장 기능 개요
• (2026-10-18 기준) 공식 서브에이전트 문서가 범위를 밝힌다: 포크가 아닌 서브에이전트는 메인이 로드하는 모든 레벨(~/.claude/CLAUDE.md, 프로젝트 규칙, CLAUDE.local.md, managed 정책 파일, 프로젝트 지시로 로드된 AGENTS.md)을 받는다. omitClaudeMd(v2.1.271 이상)는 managed 정책 파일만 남기고(managed 서브에이전트는 그것도 뺌), --agent나 agent 설정으로 메인 세션 에이전트로 돌 때는 무시된다. Explore·Plan·omitClaudeMd 서브에이전트도 하위 디렉터리 CLAUDE.md와 경로별 규칙은 그 디렉터리 파일을 다룰 때 로드된다. 서브에이전트에 꼭 닿아야 하는 규칙은 위임할 때 프롬프트에 다시 적으라고 원본은 말한다. Claude Code 서브에이전트
• (2026-10-26 기준) 세션 중에 고치면: 프로젝트 루트와 사용자 수준 CLAUDE.md는 세션 시작 때 한 번 읽어 둔다. 세션 중에 고쳐도 지금 세션에는 반영되지 않고, 다음 /clear·/compact·재시작 때 들어간다(그래서 프롬프트 캐시도 깨지지 않는다). 하위 디렉터리 CLAUDE.md와 paths: rules는 나중에 필요할 때 로드되므로, 로드되기 전에 고치면 반영된다. 로드된 뒤에는 대화 기록의 일부라 고쳐도 소급되지 않는다. Claude Code 프롬프트 캐싱 → 프롬프트 캐싱
• 프로젝트 루트 CLAUDE.md는 컴팩션 뒤에도 남는다. /compact 후 Claude가 디스크에서 다시 읽어 넣는다. 하위 디렉터리 CLAUDE.md와 경로별 규칙은 필요할 때 다시 로드된다. 대화로만 준 지시는 컴팩션 뒤 사라질 수 있으니 CLAUDE.md에 적는다. Claude Code 메모리 → 장기 작업 컨텍스트 관리
• (2026-10-18 기준, 블로그 글 2026-06-18) 블로그 글도 같은 동작을 다른 말로 적는다. 루트 CLAUDE.md는 "Memoized": 한 번 읽어 세션 동안 캐시하고, 컴팩션 뒤 캐시를 비우고 다시 읽는다. 하위 디렉터리 CLAUDE.md는 경로별 규칙과 컴팩션 동작이 같아, 그 하위 디렉터리를 다시 건드릴 때까지 사라진다. 범위 없는 rules는 컴팩션 때 다시 주입된다. Steering Claude Code 이 동작은 바로 아래 공식 컨텍스트 창 문서가 확인한다("Memoized"·캐시는 블로그 표현).
• (2026-10-18 기준) 공식 컨텍스트 창 문서가 이유를 밝힌다. 경로별 규칙과 하위 디렉터리 CLAUDE.md는 Claude가 트리거 파일을 읽거나 쓰거나 고칠 때 메시지 기록에 들어가므로, 컴팩션이 다른 대화와 함께 요약해 버린다. 컴팩션을 넘어 남아야 하는 규칙이면 paths: frontmatter를 빼거나 프로젝트 루트 CLAUDE.md로 옮긴다. 반대로 프로젝트 루트 CLAUDE.md와 범위 없는 rules는 디스크에서 다시 주입된다. Claude Code 컨텍스트 창 → 장기 작업 컨텍스트 관리
• (2026-10-18 기준) 서브에이전트는 같은 CLAUDE.md를 자기 컨텍스트에 따로 로드하므로, 그 비용은 메인이 아니라 서브에이전트 쪽에 든다. Claude Code 컨텍스트 창

한계: 요청이지 강제가 아니다#

• CLAUDE.md에 쓴 규칙은 Claude가 지시로 따를 뿐 강제되지 않는다. 매번 반드시 지켜져야 하는 것은 훅으로 만든다. Claude Code 확장 기능 개요
• 메모리 문서도 같은 입장이다. Claude는 CLAUDE.md를 강제 설정이 아니라 컨텍스트로 다루고, 특히 모호하거나 충돌하는 지시는 엄격히 지켜진다는 보장이 없다. 행동을 확실히 막으려면 PreToolUse 훅을, 커밋 전·파일 편집 후처럼 특정 시점에 돌아야 하는 일은 훅을 쓴다. Claude Code 메모리
• 조직 단위에서는 역할이 나뉜다. 도구·명령·경로 차단, 샌드박스(샌드박스), 환경 변수, 로그인 제한은 managed settings가 클라이언트에서 강제하고, 코드 스타일·데이터 취급 안내·행동 지시는 managed CLAUDE.md에 둔다. Claude Code 메모리 → 권한 모드
• (2026-10-21 기준) settings reference의 메모리 키: managed 전용 claudeMd는 파일을 따로 배포하지 않고 CLAUDE.md 본문(Markdown, 줄바꿈 \n)을 넣으며, user·project CLAUDE.md보다 앞에 managed 메모리로 로드된다. claudeMdExcludes(Any file, glob·절대 경로 배열)는 user·project·local 메모리 파일만 뺄 수 있고 managed 정책 CLAUDE.md는 뺄 수 없다. 커밋·PR 표기 키 attribution은 managed에 둔 줄이 아니면 사용자의 CLAUDE.md·메모리 지시가 그 줄보다 우선한다고 Claude에게 알린다. Claude Code 설정 키 전체 레퍼런스 → Claude Code 설정 키 레퍼런스
• 설정(settings)은 동작을 바꾸는 JSON 키이고 지시가 아니다. 공식 Settings 문서는 Claude Code의 시스템 프롬프트가 공개되지 않으며, Claude에게 상시 지시를 주려면 CLAUDE.md 파일이나 --append-system-prompt 플래그를 쓰라고 안내한다(2026-10-21 기준). Claude Code 설정 파일과 우선순위 → Claude Code 설정 파일
• 시스템 프롬프트 수준의 지시가 필요하면 시작 때 --append-system-prompt를 넘긴다. 원본은 대화형보다 스크립트·자동화에 맞다고 하고, 재개할 때의 동작은 CLI 문서로 넘긴다. Claude Code 메모리 (2026-10-21 기준) 공식 CLI 문서: 플래그 텍스트는 대화의 첫 요청에서 만든 시스템 프롬프트에 들어가 세션에 기록되고, 컴팩션 전까지 --resume·--continue로 돌아온 나중 실행에서도 그대로 쓰인다. 나중 실행에서 플래그를 바꾸거나 빼면 컴팩션 때나 새 대화에서 반영된다. 기본 동작이다. 기록하지 않는 예외(--system-prompt-snapshot off, 클라우드 세션 밖의 --bare 등)는 프로젝트에서 항상 따라야 할 관례는 플래그 대신 CLAUDE.md에 두라고 한다. Claude Code CLI 레퍼런스 → Claude Code CLI 플래그 블로그 글(2026-06-18)은 지시를 많이 줄수록 덜 엄격하게 따른다(블로그 평가)고 덧붙인다. Steering Claude Code → 출력 스타일

원본끼리 달랐던 점(정리됨)--append-system-prompt 재개 동작

• Steering Claude Code (2026-06-18): 시스템 프롬프트 덧붙이기는 "applies only to that invocation"(그 실행에만 적용), 파일로 세션을 넘어 유지되지 않는다.
• Claude Code CLI 레퍼런스 (수집 2026-10-21): 기본 동작으로 첫 요청에서 만든 시스템 프롬프트를 세션에 기록하고, 컴팩션 전까지 --resume·--continue로 돌아온 나중 실행에서도 쓴다. 나중 실행의 다른 플래그 텍스트(또는 플래그 없음)는 컴팩션 때나 새 대화에서 반영된다.
• 설명과 실무는 공식 CLI 문서 기준. 블로그 문장은 출처와 함께 남긴다. 원문 인용·예외: Claude Code CLI 플래그

• (2026-10-18 기준, 블로그 글 2026-06-18) 블로그 글은 진짜 가드레일은 결정론적이어야 하고 강제 수단은 훅과 권한이라고 말한다. 조직 전체 표준(보안 정책, 컴플라이언스)은 중앙 관리 CLAUDE.md를 MDM이나 구성 관리로 배포할 수 있고 개인 설정으로 제외할 수 없지만, 조직 전체의 결정론적 가드레일을 강제하는 유일한 방법은 managed settings다(블로그 평가). Steering Claude Code → 권한 모드 중앙 관리 CLAUDE.md의 배포와 제외 불가는 공식 메모리 문서가 확인한다("This file cannot be excluded by individual settings"). Claude Code 메모리 이 "덮어쓸 수 없다·유일한 방법"은 블로그 단독 주장이다. 공식 권한 모드 문서(2026-10-18)는 일부만 확인한다: managed·project의 permissions.defaultMode는 ~/.claude/settings.json보다 우선하지만, 시작 모드는 --permission-mode 플래그(또는 --dangerously-skip-permissions)가 settings보다 먼저이고, managed defaultMode로 시작해도 "people can still switch to auto mode"라서 자동 모드를 아무도 못 고르게 하려면 permissions.disableAutoMode를 따로 써야 한다. "유일한 방법"이라는 일반 주장은 공식 문서가 확인하지 않는다. Claude Code 권한 모드 → Claude Code 관리자 권한 통제 공식 managed settings 배포 문서(2026-10-18)는 "덮어쓸 수 없다"를 설정 파일 기준으로 확인한다: user·project·local·--settings 값은 managed 값을 덮어쓰지 못하되, 몇몇 보안 민감 예외에서는 낮은 레벨의 더 엄격한 값이 효력을 갖는다. 같은 문서는 이 규칙 밖의 경우(managed model·autoCompactWindow는 기본값, 로컬 관리자의 관리 출처 수정, Claude Code 밖의 도구)도 적고, "유일한 방법"이라고는 말하지 않는다. Claude Code managed settings 배포 → managed settings

• (2026-10-18 기준) 자동 모드 분류기는 Claude Code가 보내는 검토 요청에서 사용자 메시지, 도구 호출과 함께 CLAUDE.md 내용을 본다. 같은 문서는 대화로 말한 경계가 규칙으로 저장되지 않아 컴팩션으로 사라질 수 있으니, 확실한 보장은 deny 규칙으로 하라고 한다. Claude Code 권한 모드 → 권한 모드 (2026-10-21 기준) 공식 자동 모드 설정 문서는 이것을 설정 요령으로 쓴다: 분류기는 Claude가 로드하는 것과 같은 CLAUDE.md 내용을 읽으므로, 프로젝트 CLAUDE.md의 "never force push" 같은 지시는 Claude와 분류기를 동시에 이끈다. 프로젝트 관례와 행동 규칙은 CLAUDE.md에서 시작하고, 여러 프로젝트에 걸친 신뢰 인프라·조직 차단 규칙은 autoMode 설정 블록에 두라고 한다. 같은 문서는 절대 돌면 안 되는 동작은 managed settings의 permissions.deny로 막으라고 한다. Claude Code 자동 모드 설정 → Claude Code 자동 모드 설정하기

• (2026-10-18 기준) 공식 훅 가이드는 반대 방향의 경계도 말한다. 매 세션 시작 때 같은 컨텍스트를 넣는 일이면 SessionStart 훅 대신 CLAUDE.md를 고려하고, 컴팩션 뒤마다 다시 알려야 할 것은 compact matcher의 SessionStart 훅으로 넣는다. Claude Code 훅 가이드 → Claude Code 훅 설정 레시피

• (2026-10-18 기준) 공식 훅 레퍼런스도 같은 선을 긋는다. 바뀌지 않는 지시는 스크립트 없이 로드되는 CLAUDE.md가 정적 프로젝트 관례의 표준 자리이고, 훅의 additionalContext는 현재 브랜치·배포 대상 같은 환경 상태, 방금 편집한 파일에 맞는 테스트 명령 같은 조건부 규칙, 최근 CI 결과 같은 외부 데이터에 쓰라고 한다. 모델별로 다른 조직 지침은 모든 CLAUDE.md를 고치지 않고 PostModelSwitch 훅으로 줄 수 있다고 한다. InstructionsLoaded 훅은 로드된 파일의 memory_type(User, Project, Local, Managed)과 load_reason을 받는다. Claude Code 훅 레퍼런스 → 훅 이벤트 레퍼런스

지켜지지 않을 때 점검 순서: CLAUDE.md 문제 해결

다른 도구의 상시 지시#

Claude Cowork에도 상시 지시 장치가 두 가지 있다. 모든 세션에 적용되는 Global instructions(톤, 출력 형식, 역할·팀 배경)와 로컬 폴더를 고를 때 프로젝트별 맥락을 더하는 Folder instructions다. Folder instructions는 Claude가 세션 중 작업 방식을 더 알게 되면 스스로 고칠 수도 있다. Claude Cowork 시작하기 → Claude Cowork 시작 세팅

(2026-10-18 기준) Codex의 상시 지시 파일은 AGENTS.md다. Codex 홈(~/.codex)의 전역 파일과 프로젝트 루트에서 현재 디렉터리까지의 파일을 이어 붙이고, 가까운 파일이 뒤에 와서 앞선 지시를 override한다. 디렉터리마다 한 파일만 넣고, 합친 크기 한도는 project_doc_max_bytes(기본 32 KiB)다. Codex AGENTS.md 가이드 CLAUDE.md의 로드 순서·크기 규칙과 나란히 본 비교표는 AGENTS.md와 CLAUDE.md 함께 쓰기.

데스크톱 Cowork 세션에서 Claude Code는 사용자 범위 파일(~/.claude/CLAUDE.md 등)의 import 중 세션 작업 디렉터리 밖을 가리키는 것을 건너뛴다. Claude Code 메모리

고치는 시점#

• 반복되는 실수나 리뷰에서 거듭 나오는 지적은 채팅에서 한 번 바로잡고 끝낼 일이 아니라 CLAUDE.md를 고칠 일이다. Claude Code 확장 기능 개요
• 메모리 문서가 든 계기: Claude가 같은 실수를 두 번째로 할 때, 코드 리뷰에서 Claude가 이 코드베이스에 대해 알았어야 할 것이 걸릴 때, 지난 세션에 친 교정·설명을 채팅에 또 칠 때, 새 팀원에게도 같은 맥락이 필요할 때. Claude Code 메모리
• Claude에게 "기억해"라고 하면 자동 메모리에 저장된다. CLAUDE.md에 넣으려면 "CLAUDE.md에 추가해"라고 직접 말하거나 /memory로 파일을 열어 고친다. Claude Code 메모리 → 자동 메모리(Auto memory)