클로드코드 11-claude-md

1. CLAUDE.md와 Auto Memory

참고: Claude에게 지속적인 지시사항을 주고, Claude가 스스로 학습 내역을 쌓는 방법

1.1. 개요

Claude Code의 각 세션은 새로운 컨텍스트 윈도우로 시작한다. 두 가지 메커니즘이 세션 간 지식을 전달한다.

- : CLAUDE.md: Auto memory
- 작성자: 사용자: Claude
- 내용: 지시사항과 규칙: 학습한 패턴과 인사이트
- 범위: 프로젝트, 사용자, 조직: 저장소별 (worktree 공유)
- 로드: 매 세션 시작 시: 매 세션 시작 시 (처음 200줄 또는 25KB)
- 용도: 코딩 표준, 워크플로우, 아키텍처: 빌드 명령어, 디버깅 인사이트, 선호도

1.2. CLAUDE.md 파일

1.2.1. 언제 추가하는가?

- Claude가 같은 실수를 두 번째로 할 때
- 코드 리뷰에서 Claude가 알아야 할 것을 놓칠 때
- 매 세션 같은 교정이나 설명을 입력할 때
- 새 팀원이 생산적이려면 같은 컨텍스트가 필요할 때

1.2.2. 파일 위치

- 범위: 위치: 용도
- Managed policy: /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux/WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows): 조직 전체 지시사항
- 사용자: ~/.claude/CLAUDE.md: 모든 프로젝트의 개인 설정
- 프로젝트: ./CLAUDE.md 또는 ./.claude/CLAUDE.md: 팀 공유 지시사항
- 로컬: ./CLAUDE.local.md: 개인 프로젝트별 설정 (.gitignore 권장)

참고: 계층적으로 로드된다. foo/bar/에서 실행하면 foo/CLAUDE.md → foo/bar/CLAUDE.md 순서로 로드된다. 하위 디렉토리의 CLAUDE.md는 해당 디렉토리 파일을 읽을 때 지연 로드된다.

1.2.3. 효과적인 지시사항 작성법

- 크기: 파일당 200줄 이하를 목표로 한다. 긴 파일은 컨텍스트를 많이 소모하고 준수도를 떨어뜨린다.
- 구조: 마크다운 헤더와 불릿으로 그룹화한다.
- 구체성: "Use 2-space indentation"처럼 검증 가능하게 작성한다.
- 일관성: 상충되는 규칙을 제거한다.

# Project conventions

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Stack
- TypeScript with strict mode
- React 19, functional components only

## Rules
- Named exports, never default exports
- Tests live next to source: `foo.ts` -> `foo.test.ts`
- All API routes return `{ data, error }` shape

1.2.4. 파일 임포트

@path/to/import 문법으로 추가 파일을 임포트할 수 있다.

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

참고: 외부 임포트를 처음 만나면 승인 대화상자가 표시된다.

1.2.5. AGENTS.md와 호환

저장소에 이미 AGENTS.md가 있다면 CLAUDE.md를 생성해 임포트한다.

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

1.2.6. Path-scoped rules

.claude/rules/ 디렉토리에 규칙을 모듈화할 수 있다.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format

1.3. Auto Memory

Claude가 사용자 교정과 선호도를 기반으로 스스로 노트를 작성한다.

1.3.1. 활성화/비활성화

기본적으로 켜져 있다. /memory에서 토글하거나 설정으로 제어한다.

{
  "autoMemoryEnabled": false
}

1.3.2. 저장 위치

~/.claude/projects/<project>/memory/

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 인덱스, 매 세션 로드
├── debugging.md       # 디버깅 패턴 상세 노트
├── api-conventions.md # API 설계 결정
└── ...                # 기타 주제 파일

- MEMORY.md: 처음 200줄 또는 25KB가 세션 시작 시 로드
- 주제 파일: 필요할 때 Claude가 읽음

1.3.3. /memory 명령어

로드된 CLAUDE.md, rules 파일 목록을 확인하고 auto memory 폴더를 열 수 있다.

1.4. 문제 해결

1.4.1. Claude가 CLAUDE.md를 따르지 않음

- /memory로 해당 파일이 로드되는지 확인
- 지시사항이 구체적인지 검토
- 상충되는 지시사항이 있는지 확인
- 실행 시점이 중요한 경우 hook으로 작성

1.4.2. /compact 후 지시사항이 사라짐

프로젝트 루트 CLAUDE.md는 compaction 후 재로드된다. 하위 디렉토리의 CLAUDE.md는 해당 디렉토리 파일을 다시 읽을 때까지 재로드되지 않는다.