Quick Reference
CLAUDE.md는 사람이 작성해 매 session에 주입하는 지속 지침이고, auto memory는 Claude Code가 같은 저장소에서 발견한 학습을 로컬에 남기는 메모입니다. 둘 다 context이지 강제 정책이 아닙니다. 보안상 반드시 막아야 할 동작은 permissions.deny, sandbox, hook, 조직 managed settings로 처리합니다.
| 필요 | 먼저 둘 곳 | 공유 범위 | 넣지 말 것 |
|---|---|---|---|
| 팀의 build·test·코딩 규칙 | 프로젝트 CLAUDE.md 또는 .claude/CLAUDE.md | source control로 팀 공유 | 개인 경로·token·일회성 작업 |
| 개인 프로젝트 선호 | CLAUDE.local.md | 현재 worktree만 | 팀 전체에 적용할 규칙 |
| 모든 프로젝트의 개인 습관 | ~/.claude/CLAUDE.md | 현재 사용자 | 저장소 고유 구조 |
| 반복해서 발견한 디버깅 지식 | auto memory | 같은 저장소의 worktree, 현재 기기 | 강제 보안 정책·secret |
| 좁은 경로의 긴 절차 | .claude/rules/ | 프로젝트 규칙 | 모든 session에 실을 긴 설명 |
CLAUDE.md: "커밋 전 npm test를 실행한다."
auto memory: "이 저장소의 통합 테스트에는 local Redis가 필요하다."
강제 정책: permissions.deny로 secret 파일 읽기를 막는다.지침 파일의 적용 범위
CLAUDE.md는 현재 디렉터리에서 상위 디렉터리까지 찾아 로드합니다. 현재 위치에 가까운 파일이 context의 뒤쪽에 들어가며, 같은 디렉터리에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙습니다. 하위 디렉터리의 지침은 시작 때 모두 읽지 않고, Claude가 그 디렉터리 파일을 읽을 때 추가로 로드됩니다.
프로젝트 지침은 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 두고 버전 관리합니다. 개인 경로·sandbox URL처럼 커밋하면 안 되는 내용은 ./CLAUDE.local.md에 두고 Git ignore합니다. CLAUDE.local.md는 만든 worktree에만 존재하므로, 여러 worktree에 개인 지침을 공유해야 하면 home directory의 파일을 @ import로 연결합니다.
<!-- CLAUDE.md -->
@AGENTS.md
## Claude Code
- 커밋 전 npm test를 실행한다.@경로 import는 지침을 나누는 방법일 뿐 startup context를 줄이지는 않습니다. import는 최대 5단계까지 재귀적으로 펼쳐질 수 있고, 프로젝트에서 처음 외부 import를 읽을 때는 승인 절차가 필요합니다.
auto memory를 관리하는 법
auto memory는 Claude Code 2.1.59 이상에서 기본 활성화됩니다. 저장소마다 ~/.claude/projects/<project>/memory/에 MEMORY.md와 주제별 파일을 두며, 같은 Git repository의 subdirectory와 worktree는 이 memory를 공유합니다. 다른 기기나 cloud environment와는 공유하지 않습니다.
시작 시에는 MEMORY.md의 앞 200줄 또는 25KB까지만 자동으로 로드됩니다. 상세 메모는 topic file로 옮기고, 매 session에 필요한 index만 짧게 유지합니다. /memory에서 실제로 로드된 CLAUDE.md·rules·memory를 확인하고, auto memory를 켜거나 끌 수 있습니다. 프로젝트 설정의 autoMemoryEnabled 또는 환경 변수로도 끌 수 있습니다.
| 증상 | 원인 후보 | 먼저 할 일 |
|---|---|---|
| 같은 지침을 따르지 않음 | 파일 위치·상충 지침·너무 모호한 문장 | /memory로 load 목록과 내용 확인 |
| 오래된 판단을 반복함 | auto memory의 stale note | memory 파일을 편집·삭제 |
| context가 너무 큼 | 긴 지침·import·초기 memory | path-scoped rule로 옮기고 index 축소 |
| 반드시 특정 시점에 실행해야 함 | context 지침만 사용 | hook 또는 enforced setting으로 전환 |
자주 틀리는 부분
CLAUDE.md는 system policy가 아닙니다. 충돌하거나 모호한 지침은 Claude가 임의로 해석할 수 있고, secret 접근 차단이나 배포 승인 같은 보안 요구를 보장하지 않습니다. 실행 강제가 필요하면 permission, sandbox, hook을 사용합니다.
좋은 후보
- 항상 실행할 build·test 명령
- 프로젝트 구조와 naming 규칙
- 반복되는 장애 원인과 확인 방법
나쁜 후보
- 오늘만 적용하는 예외
- 현재 branch의 임시 TODO
- API key, 고객 데이터, 개인 경로참고 링크
2 sources