10. 자동 메모리와 설정 파일

두 가지 메모리 시스템

Claude Code에는 세션을 넘어 지식을 나르는 두 개의 상호 보완적 메모리가 있고, 둘 다 매 대화 시작 시 로드됩니다.

비유하자면, CLAUDE.md는 새 팀원에게 건네주는 매뉴얼이고, 자동 메모리는 그 팀원이 일하며 스스로 적어두는 메모입니다.

자동 메모리: Claude가 스스로 배운다

당신이 Claude를 교정하면("이 테스트엔 mock 쓰지 마"), Claude는 그 피드백을 ~/.claude/projects/<project>/memory/의 메모리 파일에 저장합니다. 다음 세션에 그걸 기억합니다. 따로 관리할 필요 없이, 잘못할 때 교정만 해주면 학습합니다.

flowchart TB
    A[당신의 교정·선호<br/>'mock 쓰지 마']:::user --> B[Claude가 메모리에 기록]:::agent
    C[작업 중 발견<br/>'테스트 유틸은 여기 있구나']:::tool --> B
    B --> D[(memory/ 파일들)]:::know
    D --> E[다음 세션 시작 시 로드]:::result
    E --> F[같은 설명 반복 불필요]:::result

    classDef user fill:#FFE082,stroke:#F9A825,color:#000
    classDef agent fill:#80DEEA,stroke:#00ACC1,color:#000
    classDef tool fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef know fill:#CE93D8,stroke:#8E24AA,color:#000
    classDef result fill:#A5D6A7,stroke:#43A047,color:#000

💡 실용 함의: CLAUDE.md 줄을 "Claude가 한 세션이면 알아낼 것"에 낭비하지 마세요. Claude가 첫 세션에 테스트 유틸을 발견해 메모리에 적으면, 그 줄은 CLAUDE.md에 필요 없습니다. /memory로 Claude가 이미 알아낸 걸 확인하면, 무엇이 정말 필요하고 무엇이 중복인지 보입니다.

메모리 계층 구조

여러 곳의 CLAUDE.md·규칙·메모리가 함께 로드되며, 더 구체적인 지침이 더 넓은 지침보다 우선합니다. 작성 시점 기준의 대략적 우선순위(높음→낮음):

flowchart TB
    A[관리 정책 (Managed)<br/>조직 전체 강제]:::danger
    A --> B[프로젝트 메모리<br/>./CLAUDE.md]:::proj
    B --> C[프로젝트 규칙<br/>./.claude/rules/*.md]:::proj
    C --> D[유저 메모리<br/>~/.claude/CLAUDE.md]:::user
    D --> E[유저 규칙<br/>~/.claude/rules/*.md]:::user
    E --> F[로컬 프로젝트 메모리<br/>./CLAUDE.local.md]:::local
    F --> G[자동 메모리<br/>~/.claude/projects/.../memory/]:::know

    classDef danger fill:#EF9A9A,stroke:#E53935,color:#000
    classDef proj fill:#90CAF9,stroke:#1E88E5,color:#000
    classDef user fill:#CE93D8,stroke:#8E24AA,color:#000
    classDef local fill:#A5D6A7,stroke:#43A047,color:#000
    classDef know fill:#FFE082,stroke:#F9A825,color:#000

⚠️ 작업 디렉터리 위쪽 디렉터리의 CLAUDE.md들은 시작 시 전부 로드되고, 상충하면 더 구체적인(가까운) 것이 더 무게를 갖습니다. 다만 이는 엄격한 override가 아니라 소프트 가중치라서, 로드 순서에 기대기보다 모순 없는 규칙을 쓰는 게 안전합니다.

설정 파일: settings.json

메모리(CLAUDE.md)가 "Claude에게 무엇을 알려줄까"라면, settings.json은 "Claude Code 도구 자체를 어떻게 동작시킬까" 입니다. 권한·훅·MCP 서버·기본 모델·기본 권한 모드 등이 여기 들어갑니다. 메모리와 마찬가지로 계층이 있습니다.

대표적인 키 몇 가지(전체는 부록 B):

{
  "model": "sonnet",
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(npm run *)"],
    "deny":  ["Bash(rm *)", "Read(./.env)"]
  },
  "autoMemory": true,
  "plansDirectory": "./docs/plans",
  "outputStyle": "default"
}

설정·메모리가 안 먹힐 때

1. /memory  → 어떤 메모리 파일이 로드됐는지 확인
2. 규칙이 하위 디렉터리의 lazy-load 파일에 있진 않은지 확인
   (그 디렉터리 파일을 아직 안 읽어서 로드 전일 수 있음)
3. 여러 CLAUDE.md 간 상충 지침이 없는지 확인
4. settings.json은 계층 우선순위(정책>프로젝트>유저...)대로 적용됨을 기억
5. claude doctor 로 설정 진단

이 장에서 배운 것

• 두 메모리: CLAUDE.md(내가 쓰는 지침)와 자동 메모리(Claude가 교정·발견을 스스로 기록). 둘 다 매 세션 로드된다.
• 자동 메모리 덕분에 "한 세션이면 알아낼 것"은 CLAUDE.md에 안 적어도 된다. /memory로 점검한다.
• 메모리·설정 모두 계층이 있고 더 구체적인 것이 우선하되, 상충은 소프트 가중치라 모순 없는 규칙이 안전하다.
• settings.json은 도구 동작(권한·훅·MCP·모델·모드)을 제어하며 유저·프로젝트·로컬·정책 범위로 나뉜다.
• 안 먹힐 땐 /memory·상충 점검·claude doctor 순으로 디버깅한다.

✍️ 확인 문제

1. CLAUDE.md와 자동 메모리의 가장 큰 차이(누가, 무엇을)는 무엇인가요?
2. 같은 동작에 대해 두 CLAUDE.md가 다른 지침을 줄 때 안전한 작성 원칙은 무엇인가요?
3. settings.json과 CLAUDE.md는 각각 "무엇"을 제어하나요?

다음 장: 11. 커스텀 슬래시 명령과 출력 스타일 — 반복 작업을 명령으로, 응답 형식을 취향대로.