[Claude Code] CLAUDE.md (4)

클로드는 새 대화(세션)를 열면 빈 컨텍스트로 시작하기 때문에 이전 대화 내용을 모른다.
한 프로젝트에서 매 세션마다 이전 대화 내용에 포함된 지시와 규칙을 클로드에게 다시 설명하지 않아도 되도록 만드는 것이 바로 CLAUDE.md 파일이다.

 

Step 1. CLAUDE.md 초안 만들기

프롬프트 박스에 다음 명령어를 입력하면

/init

 

클로드가 코드베이스를 조사해서 빌드 명령, 테스트 방법, 발견한 규칙 등을 담은 CLAUDE.md를 생성한다.

 

Step 2. CLAUDE.md 파일의 내용 걷어내기

생성된 CLAUDE.md를 열고 각 줄에 다음 질문을 던져야 한다.

해당 줄은 클로드가 코드를 읽어보면 알 수 있는 내용인가?

 

/init을 통해 클로드가 이미 코드를 읽어봤으니 CLAUDE.md의 상당 부분이 클로드가 코드를 다시 읽어보면 알 수 있는 내용이다.

 

CLAUDE.md에 남길 것과 지울 것

지운다	남긴다
파일 목록, 디렉터리 구조	왜 그렇게 설계했는지
함수 클래스 목록	이 프로젝트만의 함정
코드를 보면 아는 모든 것	코드에 안 적혀 있는 정책

 

예를 들어,

지울 부분은

↓

모듈 3개, 의존 방향은 단방향: `main` → `pricing` → `models`.

- app/models.py — 순수 dataclass(Item, Order). ORM도 검증 계층도 없다.
- app/pricing.py — 금액 로직 전부.
- app/main.py — FastAPI 라우트.

이 부분은 클로드에게 파일을 주면 즉시 아는 내용이므로 지운다.

그리고 아키텍터 헤더 또한 더 이상 아키텍처 구조가 아닌 함정 목록에 대한 내용이므로 변경한다.

 

↓

`checkout()`은 쿠폰을 *먼저* 적용한 뒤, **할인된 금액**을 기준으로 배송비를 판단한다:

```
discounted = int(subtotal - subtotal * coupon_rate)   # 반올림이 아니라 절삭
fee        = 0 if discounted >= 50000 else 3000
total      = discounted + fee
```

checkout() 함수에 대한 설명과 그 밑의 단순한 코드 블록은 코드를 읽어보면 아는 내용이므로 지운다.

 

남겨야 하는 특히 중요한 부분은 이러한 부분이다.

왜냐하면, 코드 어디에도 없는 내용이고, 클로드가 ModuleNotFoundError를 접하고 나서야 알게 될 함정이다. 
미리 알려주면 한 번의 실패를 통째로 건너뛰게 된다. 함정과 그 이유로 정확히 남겨야 할 종류이다.

 

Step 3. 이전 실습(Plan 모드 (3))에서 내가 클로드에게 내린 결정을 CLAUDE.md에 작성하기

## 금액 계산 규칙

- 무료배송 판정은 **할인 후 결제 금액** 기준이다. 할인 전 금액이 아니다.
- 할인 후 금액은 `int()` 버림으로 정수화한 뒤 임계값과 비교한다.
  부동소수 오차로 경계 판정이 흔들리는 것을 막기 위함이다.
- 금액 계산 규칙을 바꿀 때 기존 테스트를 삭제하지 않는다.
  회귀 방지선이므로 케이스를 추가하는 방식으로만 확장한다.

금액 계산 규칙의 세 줄 모두 코드를 읽어도 알 수 없는 것이다. 
int() 버림이 부동소수 때문이라는 건 코드에 안 적혀 있다. 

 

CLAUDE.md 작성 원칙 - 검증 가능하게 쓰기

나쁜 작성	좋은 작성
코드를 깔끔하게 유지할 것	들여쓰기는 4칸
테스트를 잘 할 것	커밋 전 pytest -q
금액 계산에 주의할 것	무료배송은 할인 후 금액 기준

왼쪽은 지켰는지 판정할 수 없다. 판정할 수 없는 규칙은 지켜지지도 않는다.

크기는 가능한 200줄 아래로 유지한다. 길수록 컨텍스트를 먹고 준수율이 떨어진다.

 

Step 4. CLAUDE.md 로드 확인과 실제 검증

새 대화를 열고 /context를 실행하여MEMORY FILES 항목에 CLAUDE.md가 로드됐는지 확인한다.

정상적으로 로드된 것을 확인할 수 있다.

 

이제 새 대화를 열고 이전 실습에서의 프롬프트와 비슷한 프롬프트를 보낸다.

@app/pricing.py 무료배송 임계값을 30000원으로 낮춰줘.

 

그럼 이전 실습에서본 사용자의 결정을 요구하는 메시지가 나오지 않을 것이다.

이전 실습에서 반올림 기준에 대해 클로드가 사용자의 결정을 요구한 부분

CLAUDE.md에 이미 답이 있으므로 안 물어보는 것이 정상이다.

 

Step 5. CLAUDE.md 파일이 놓이는 자리

위치	범위	예를 들어
~/.claude/CLAUDE.md	내 모든 프로젝트	개인 선호
./CLAUDE.md	이 프로젝트, 팀 공유	지금 쓴 것
./CLAUDE.local.md	이 프로젝트, 나만	개인 설정 (gitignore)

범위가 넓은 것부터 순서대로 전부 이어붙여 로드된다. 덮어쓰기가 아니다.

 

Step 6. 자동 메모리 살펴보기

	CLAUDE.md	자동 메모리
누가 쓰나	내가	클로드가
내용	지시와 규칙	학습과 패턴
매 세션 로드	전체	MEMORY.md 앞 200줄

 

 

다음 명령어를 실행하면 CLAUDE.md 파일 목록과 함께 자동 메모리 폴더를 열 수 있다. 

/memory

기본으로 켜져 있고(Auto-memory: on), 클로드가 알아서 쓴 노트들이 들어 있다.

전부 평범한 마크다운이므로 읽고 고치고 지울 수 있다.

 

핵심 정리

1. 새 대화는 매번 백지에서 시작한다.
이전 대화 내용은 하나도 따라오지 않는다. CLAUDE.md와 자동 메모리만 새 대화에 자동으로 실린다.

2. /init은 초안이지 완성이 아니다. 

CLAUDE.md는 코드 베이스를 읽고 쓴 파일이라 코드에서 알 수 있는 게 많이 들어간다.

3. 판단 기준: 코드를 읽으면 아는가. 안다면 지운다.

4. 남기는 건 코드에 안 적힌 것. 

왜 그렇게 했는지, 이 프로젝트만의 함정, 코드로 표현되지 않은 정책.

5. 검증 가능하게 쓴다. 

"깔끔하게"가 아니라 "4칸 들여쓰기". 판정할 수 없는 규칙은 지켜지지 않는다.

6. 가능한 200줄 아래로.

길수록 컨텍스트를 먹고 준수율이 떨어진다.

7. CLAUDE.md는 강제 사항이 아니라 컨텍스트다.

시스템 프롬프트 뒤에 사용자 메시지로 전달되므로 준수가 보장되지 않는다. 반드시 실행돼야 하는 것은 훅으로 만든다.

8. 검증은 두 단계. 

/context로 로드 확인, 그리고 실제로 물어보게 만들어서 안 묻는지 확인.

9. CLAUDE.md는 여러 층이 이어붙는다.

사용자 → 프로젝트 → 로컬 순으로 전부 로드된다. 덮어쓰기가 아니라서 모순되는 규칙이 있으면 클로드가 임의로 고른다.

10. 자동 메모리는 클로드가 쓰는 쪽이다.

내 교정과 선호를 스스로 적어둔다. /memory를 통해 읽고 고칠 수 있다.

11. Plan 모드가 꺼낸 결정을 CLAUDE.md에 적으면, 다음부터는 그 질문 자체가 안 나온다.