CLAUDE.md와 메모리

CLAUDE.md는 회사의 운영 헌법입니다. 클로드 코드는 켜질 때마다 이 문서부터 읽습니다. 매일 새로 출근하는 AI 직원이 가장 먼저 펼쳐 보는 회사의 업무 매뉴얼인 셈입니다.

왜 필요할까요. 새 세션(대화창을 열어 일하고 닫기까지)을 시작할 때마다 앞 대화의 기억은 저절로 따라오지 않습니다. 클로드는 어제 알려 준 회사 규칙도, 방금 고쳐 준 습관도 다음 세션에서는 잊습니다. 그래서 “보고서는 이 형식으로 써”, “자료는 이 폴더에 있어” 같은 설명을 매번 되풀이하게 됩니다. CLAUDE.md에 한 번 적어 두면, 그다음부터는 새 세션마다 클로드가 그 내용을 저절로 읽고 일을 시작합니다. 아침마다 기억이 백지가 되는 이 약점이 왜 생기는지는 「AI는 왜 어제 일을 잊을까요」 페이지에서 설명합니다.

만들기 — 두 가지 방법

/init은 폴더를 훑어 초안을 자동으로 만들어 주고, 인터뷰식은 클로드와 말을 주고받으며 함께 씁니다. /init은 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선안을 제안하므로, 나중에 다시 실행해도 기존 내용이 날아가지 않습니다. 직접 따라 하는 절차는 따라 하기 2편에 있습니다.

어디에 둘까요 — 네 층

CLAUDE.md는 여러 곳에 둘 수 있고, 위치마다 적용 범위가 다릅니다. 아래 표는 넓은 층부터 좁은 층 순서입니다.

가장 많이 쓰는 것은 프로젝트용입니다. 저장소(깃으로 기록을 관리하는 폴더)에 담겨 팀원 모두와 공유되므로, 개인 취향보다 팀 전체가 지켜야 할 규칙을 적습니다. 개인 취향은 사용자용에 적습니다. 저장소에 올리고 싶지 않은 나만의 설정은 로컬용에 두고 .gitignore(공유 제외 목록)에 넣어 함께 올라가지 않게 합니다.

다른 AI 도구와 함께 쓰는 폴더라면 AGENTS.md도 알아 두십시오. 여러 AI 도구가 함께 쓰는 공통 표준 문서로, 하는 일은 운영 헌법과 같습니다(책 8장). 클로드를 켠 폴더와 그 위쪽 폴더에 프로젝트용·로컬용 CLAUDE.md가 하나도 없으면 클로드 코드는 AGENTS.md를 대신 읽습니다. 하나라도 있으면 기본으로는 CLAUDE.md만 읽습니다. 홈 폴더의 ~/.claude/CLAUDE.md는 이 판단에 들어가지 않습니다. 둘 다 읽게 하려면 /config 화면의 Project instructions 줄을 기본값 claude-md-or-agents-md에서 claude-md-and-agents-md로 바꿉니다. 운영 지표(원격 측정)를 앤트로픽에 보내지 않도록 꺼 둔 세션에서도 똑같이 작동합니다.

읽히는 순서

클로드 코드는 지금 켠 폴더에서 위쪽으로 폴더를 하나씩 거슬러 올라가며 CLAUDE.md를 전부 찾아 읽습니다. 여러 개를 찾으면 덮어쓰지 않고 이어 붙이는데, 바깥쪽(상위 폴더) 내용이 먼저, 켠 폴더에 가까운 내용이 마지막에 놓입니다. 마지막에 읽힌 지시는 클로드에게 가장 최근 지시처럼 느껴집니다. 그래서 세부 사정은 지금 켠 폴더에 가까운 파일에 적는 편이 좋습니다. 다만 규칙끼리 부딪칠 때 어느 쪽을 따르라고 적어 두어도 클로드가 꼭 그대로 따른다는 보장은 없으니, 서로 부딪치는 규칙은 아예 남겨 두지 않는 편이 낫습니다.

우리회사/                  ← ② 위 폴더의 CLAUDE.md도 읽음 (먼저 놓임)
└── 우리회사/온라인가게/    ← ① 여기서 켜면 이 폴더 것을 읽음 (마지막에 놓임)
    └── …/자료실/          ← ③ 하위 폴더 것은 그 폴더 파일을 다룰 때에야 읽음

하위 폴더의 CLAUDE.md는 시작할 때 바로 읽지 않고, 클로드가 그 폴더의 파일을 실제로 다룰 때 그제야 함께 읽습니다. 필요할 때만 꺼내 보는 서랍과 같습니다.

그래서 어디에 두면 무엇이 달라질까요 — 회사 조직으로 보기

회사가 커져 부서 폴더가 생겼다고 해 봅시다. 같은 문서라도 어느 층에 두느냐가 “누가, 언제 읽는가”를 정합니다.

우리회사/
├── CLAUDE.md              # 본사 CLAUDE.md — 어느 부서에서 일해도 읽힘
├── 마케팅/
│   ├── CLAUDE.md          # 마케팅 CLAUDE.md — 마케팅에서 켜거나, 마케팅 파일을 만질 때
│   └── 자료실/CLAUDE.md   # 자료실 CLAUDE.md — 자료실 파일을 만질 때만
└── 회계/
    └── CLAUDE.md          # 회계 CLAUDE.md — 마케팅 일을 할 때는 안 읽힘

규칙을 상위에 올릴수록 넓게, 항상 적용되고 하위로 내릴수록 좁게, 필요할 때만 읽힙니다. 상위에 두면 매 세션 그만큼 기억 그릇(클로드가 한 번에 기억할 수 있는 양)을 차지합니다. 하위로 내리면 그릇은 아끼지만 다른 부서 일에는 보이지 않습니다. 마케팅 부서에서 회계 규칙까지 읽게 하고 싶지 않다면, 회계 규칙은 회계 폴더로 내리면 됩니다.

어느 폴더에서 클로드를 켜느냐가 세 가지를 한꺼번에 정합니다. ⓐ 클로드가 따로 허락받지 않고도 읽고 고칠 수 있는 파일 범위, ⓑ 시작할 때 불러오는 CLAUDE.md, ⓒ 적용되는 프로젝트 설정입니다. 여러 부서에 걸친 일이면 회사 루트에서, 한 부서에만 집중하는 일이면 그 부서 폴더에서 켜십시오. 부서 폴더에서 켜면, 따로 허락해 넓히기 전까지는 파일을 다룰 수 있는 범위도 그 폴더 안쪽으로 좁혀집니다.

다만 설정 파일(.claude/settings.json)은 CLAUDE.md와 다릅니다. 위쪽 폴더를 거슬러 올라가며 읽지 않고, 일을 시작한 폴더의 것을 읽습니다. 그래서 회사 루트에 둔 공용 설정(권한·훅)을 쓰려면 그 폴더에서 클로드를 켜야 합니다. 아래 부서 폴더에서 켜면 위쪽 공용 설정은 따라오지 않습니다(책 8장). 자세한 것은 설정 파일 페이지에 있습니다.

다른 파일 불러오기 — @ 문법

CLAUDE.md 안에서 @경로라고 적으면 다른 파일을 불러올 수 있습니다. 불러온 파일은 세션을 시작할 때 CLAUDE.md와 함께 읽힙니다.

# CLAUDE.md 안에서 다른 파일을 불러오는 예
프로젝트 개요는 @README 를 보세요.
- git 작업 규칙은 @docs/git-instructions.md

• 짧게 적은 경로(상대 경로)는 켠 폴더가 아니라 그 지시를 담은 파일이 있는 위치를 기준으로 찾습니다.
• 불러온 파일이 또 다른 파일을 불러올 수 있고, 최대 4단계까지 이어집니다.
• 백틱(`)이나 코드 블록 안에 적은 경로는 불러오지 않습니다. 백틱은 키보드 맨 위 왼쪽, 물결표와 같은 자리에 있는 기호입니다. 경로만 언급하고 싶으면 백틱으로 감싸면 됩니다.
• 프로젝트에서 외부 파일을 처음 불러올 때는 어떤 파일을 불러오는지 목록을 보여 주고 승인할지 묻습니다.

규칙 폴더 — .claude/rules/

규칙이 한 파일에 다 들어가지 않으면, .claude/rules/ 폴더에 주제별로 파일을 나눠 둡니다. code-style.md, testing.md처럼 주제마다 하나씩입니다. 이 규칙 파일들도 기본적으로 매 세션에 CLAUDE.md와 함께 읽힙니다.

우리회사/
├── .claude/
│   ├── CLAUDE.md           # 기본 지시
│   └── rules/
│       ├── code-style.md   # 코드 스타일 규칙
│       ├── testing.md      # 테스트 관례
│       └── security.md     # 보안 요구사항

더 좋은 점은 조건을 붙일 수 있다는 것입니다. 규칙 파일 맨 위에 paths 항목으로 대상 경로를 지정하면, 클로드가 그 경로의 파일을 다룰 때만 해당 규칙이 읽힙니다. 늘 읽을 필요가 없는 지시를 필요한 순간에만 불러와 그릇을 아끼는 방법입니다. 공식 안내도 아래 “200줄 유지” 요령 다음으로 이 방식을 권합니다. 우리 회사도 운영 규칙이 한 파일에 넘치자 이 방식으로 주제별 규칙 파일에 나눠 옮겼습니다.

# 규칙 파일 첫머리 — 이 경로를 다룰 때만 읽히게 하는 예
---
paths:
  - "src/api/**/*.ts"
---

자동 메모리 — 클로드가 스스로 적는 노트

기억을 적어 두는 노트는 두 권입니다. CLAUDE.md가 사람이 쓰는 노트라면, 자동 메모리는 클로드가 일하면서 배운 것을 스스로 적어 두는 노트입니다. 매번 적는 것은 아니고, 나중 대화에 쓸모가 있겠다고 판단할 때만 남깁니다. 함께 일할수록 회사 사정에 밝아지는 직원과 같습니다.

자동 메모리는 처음부터 켜져 있습니다. 프로젝트별로 저장되며, 그 안에는 MEMORY.md라는 목차 파일과 주제별 파일들이 있습니다. 세션 시작 때는 목차의 앞부분(200줄 또는 25KB 중 먼저 닿는 데까지)만 읽히고, 나머지는 클로드가 필요할 때 직접 꺼내 봅니다. 화면에 “Writing memory”나 “Recalled memory”라고 뜨면 클로드가 이 노트를 쓰거나 읽고 있는 것입니다. 자동 메모리도 텍스트 파일이라 언제든 열어 고치거나 지울 수 있습니다.

/memory — 기억을 보고 고치는 창구

/memory를 치면 기억 파일(CLAUDE.md·CLAUDE.local.md 등)을 두는 곳이 모두 나옵니다. 아직 만들지 않은 파일을 둘 곳도 함께 보입니다. 이번 세션을 시작할 때 실제로 읽힌 파일은 /context의 Memory files 목록에서 확인합니다. 클로드가 지시를 안 따를 때 가장 먼저 열어 볼 곳이 이 목록입니다. /memory 목록에서 파일을 고르면 편집기로 열리고, 자동 메모리 켜고 끄기도 여기서 합니다. 켜기·끄기 항목은 ←·→ 키로 바꿉니다.

기억하게 하는 방법은 두 가지입니다. 어느 쪽이든 파일을 직접 열기보다 말로 시키는 것이 먼저입니다.

# 말로 기억하게 하기 — 두 가지
항상 npm 말고 pnpm을 써            # → 클로드가 자동 메모리에 스스로 저장
이 규칙을 CLAUDE.md에 추가해 줘    # → 팀과 공유할 규칙은 CLAUDE.md에 기록

그냥 기억하라고 말하면 자동 메모리에 저장되고, 팀과 공유할 규칙은 CLAUDE.md에 넣으라고 지시합니다. 파일을 직접 열어 적고 싶으면 그때 /memory로 엽니다.

좋은 지시 쓰는 법

CLAUDE.md는 매 세션 처음에 통째로 읽히므로, 잘 쓴 지시일수록 클로드가 더 잘 따릅니다. 원칙은 세 가지입니다. 짧게, 정리해서, 구체적으로 씁니다.

구체적인지는 “확인할 수 있는가”로 판단합니다.

서로 어긋나는 규칙이 두 개 있으면 클로드가 아무거나 하나를 고를 수 있습니다. 그래서 가끔 CLAUDE.md를 훑어 낡거나 모순되는 지시를 정리해야 합니다. 특히 새 모델이 나오면 다시 살핍니다. 예전 모델의 약점을 우회하려고 넣은 규칙은 더 나은 모델에게 오히려 짐이 됩니다. “클로드가 같은 실수를 두 번째로 저질렀을 때”, “지난 세션에서 고쳐 준 것을 또 똑같이 고쳐 주고 있을 때”가 항목을 추가할 신호입니다. 여러 단계를 밟는 절차라면 CLAUDE.md보다 스킬이나 경로별 규칙에 담는 것이 맞습니다.

이 정리는 클로드에게 맡길 수 있습니다. /doctor prompt-audit을 치면 클로드가 운영 헌법과 규칙 파일, 스킬, 직원 파일을 훑어 옛 모델에 맞춰 쓴 지시를 찾습니다. 보고서 맨 앞에는 이미 없는 파일이나 명령을 가리키는 규칙, 그리고 지시가 서로 어긋나는 파일이 먼저 나옵니다. 수정안도 함께 내지만, 사장이 반영하라고 하기 전에는 파일이 하나도 바뀌지 않습니다.

손이 덜 가게 유지하는 요령이 두 가지 더 있습니다. 하나는 CLAUDE.md 수정을 다른 문서 변경과 똑같이 동료 검토(다른 사람이 한 번 더 확인하는 절차)를 거쳐 반영하는 것입니다. 그래야 규칙이 실제 일과 따로 놀지 않고 함께 따라옵니다. 다른 하나는 클로드가 답을 마치는 순간 자동으로 실행되는 훅(Stop 훅)을 두어, 방금 한 일을 되짚어 운영 헌법 수정안을 그 자리에서 제안하게 하는 것입니다.

한계와 문제 해결

클로드가 CLAUDE.md를 안 따를 때는 이 순서로 짚어 봅니다.

1. /context의 Memory files 목록으로 그 파일이 실제로 읽혔는지 확인합니다. 켤 때 읽혀야 할 파일이 목록에 없으면 아예 못 본 것이니 위치부터 봅니다. 하위 폴더의 파일은 그 폴더 파일을 다룰 때 늦게 읽혀 처음 목록에는 없을 수 있습니다.
2. 지시를 더 구체적으로 고칩니다(위 표에서 모호한 지시를 구체적인 지시로 바꾼 것처럼).
3. 여러 파일에 서로 어긋나는 지시가 없는지 살펴 모순을 지웁니다.
4. 그래도 반드시 정해진 순간에 실행돼야 하는 일이면, 메모리가 아니라 훅으로 만듭니다.

대화를 압축한 뒤 지시가 사라진 것 같아도, 최상위 CLAUDE.md는 다시 읽혀 그대로 남아 있습니다. 사라진 지시는 파일이 아니라 대화 중에만 말한 내용이었을 가능성이 큽니다. 오래 유지할 지시는 대화에 남기지 말고 CLAUDE.md에 적어 둡니다. 압축이 무엇인지는 맥락 관리에 있습니다.

책과의 연결 — 8장(정체성)이 왜 이 문서가 필요한지를, 10장(회사의 두뇌)이 이 문서가 어떻게 성장하는지를 다룹니다.