Deepseek ArtifactsDeepseek Artifacts
11단계 완전 그림 워크스루

Claude Code memory 가이드: /init, CLAUDE.md, # 단축키 (그림 포함)

기억을 주지 않으면 Claude Code는 세션마다 잊어버립니다. 이 워크스루는 실제 Next.js 프로젝트에서 /init을 실행하고, 생성된 CLAUDE.md를 읽고, # 단축키로 채팅에서 규칙을 추가하고, Claude가 실제로 지키는지 검증합니다 — 매 단계 스크린샷으로 확인.

워크스루 시작FAQ로 이동

TL;DR — Claude Code memory 4줄 요약

  • 프로젝트마다 한 번 /init 실행: Claude가 저장소 — 폴더 구조, 스크립트, 상태 관리 — 를 훑고 루트에 구조화된 CLAUDE.md를 씁니다.
  • 이 파일은 이후 모든 세션의 컨텍스트에 자동으로 들어가므로, 여기 쓴 방침이 앞으로의 모든 코드 생성을 형성합니다.
  • 채팅에서 #에 이어 규칙을 입력하면 그 자리에서 기억합니다. 저장 위치를 고르세요: 프로젝트 메모리(커밋됨), 로컬 프로젝트 메모리, 사용자 메모리(~/.claude/CLAUDE.md).
  • 구조나 스택이 바뀌면 파일도 갱신하세요 — 낡은 기억은 Claude를 잘못된 방향으로 이끕니다 — 그리고 /memory로 언제든 메모리 파일을 다시 열 수 있습니다.

Claude Code Tutorial #2 - CLAUDE.md Files & /init

채널:Net Ninja12:18

시청

The CLAUDE.md file

채널:Claude (official Anthropic channel)3:01

시청

Claude Code's Memory System: The Full Guide

채널:DIY Smart Code5:05

시청

Manage Claude's memory — Claude Code documentation

문서:code.claude.com

시청

프레임은 Net Ninja의 CLAUDE.md 강의(깔끔한 VS Code 녹화)에서 왔습니다. 워크스루 글은 독자적으로 작성됐고 Anthropic 공식 memory 문서와 공식 CLAUDE.md 해설과 대조 검증했습니다.

스크린샷의 저작권은 제작자에게 있으며, 시각 문서로 출처를 밝혀 사용합니다. 각 단계는 원본 영상의 해당 시점으로 딥링크됩니다.

기억 제로에서 'Claude가 이 프로젝트를 아는' 상태까지

1 · /init으로 CLAUDE.md 생성

  1. 1

    /init부터 시작

    Claude Code를 프로젝트에 처음 들일 때는 코드를 요청하기 전에 /init을 먼저 실행하세요. 툴팁이 정확히 말해 줍니다: 코드베이스 문서와 함께 새 CLAUDE.md 파일을 초기화한다고. Claude가 먼저 프로젝트를 읽어 두면 이후 세션은 다시 읽을 필요가 없습니다.

    Slash command /init typed in Claude Code with the tooltip “Initialize a new CLAUDE.md file with codebase documentation”
    /init — 새 저장소에서 무엇보다 먼저 실행할 한 줄.0:30에 시청
  2. 2

    쓰기 전에 탐색하는 Claude 보기

    /init은 감으로 때우지 않습니다. 스스로 todo 목록을 만듭니다: 저장소 구조 탐색, package.json과 소스 코드 분석, 기존 문서 확인, 그리고 발견을 담아 CLAUDE.md 생성. 항목이 실시간으로 체크되므로 이 파일은 실제 읽은 것의 요약이지 템플릿 빈칸 채우기가 아닙니다.

    Claude Code working through its Update Todos list while initializing CLAUDE.md — exploring repository structure, reading source files, then creating the file
    초기화 중의 Update Todos 목록 — 탐색하고, 분석하고, 그다음 쓴다.1:42에 시청
  3. 3

    써 준 가이던스 헤더와 명령어 읽기

    생성된 파일은 Claude Code를 위한 가이던스 헤더로 시작하고, package.json에서 그대로 뽑은 Development Commands — dev, build, lint, start — 가 이어집니다. Claude가 자기만의 워크플로를 지어내는 걸 막는 게 바로 이 섹션입니다: 실제 스크립트가 컨텍스트 안에 있으니까요.

    Generated CLAUDE.md in VS Code showing the guidance header for Claude Code plus Development Commands with npm run dev, build, lint and start
    파일의 첫머리: Claude Code 가이던스 + 프로젝트의 실제 npm 스크립트.2:56에 시청
  4. 4

    아키텍처와 구조 섹션 확인하기

    아래로 스크롤하면 아키텍처 개요(이 프로젝트: React 19와 Tailwind를 쓰는 Next.js 15 블로그), 새 파일의 자리를 알려 주는 Project Structure 맵, Hygraph CMS 계층의 데이터 영속성 메모가 기록돼 있습니다. 새 세션은 저장소를 다시 읽지 않고 이 모든 걸 상속합니다.

    Project Structure section of a generated CLAUDE.md with app router paths selected and a Data Persistence note describing the Hygraph CMS layer
    경로가 선택된 Project Structure와 Hygraph 데이터 영속성 메모.2:30에 시청

2 · 기억을 추가하고 정착을 증명하기

  1. 5

    기억이 행동을 바꾸는 걸 증명하기

    검증입니다: '재사용 hook은 전부 이 hooks 폴더에 넣는다'를 파일에 추가한 뒤 테마 선호 hook을 요청 — 단, 아직 어디에도 쓰지 말라고 분명히 말합니다. Claude의 todo는 src/hooks/use-theme에 hook을 만들었고, 마지막에 'hook은 사용할 준비가 됐지만 요청대로 아직 어디에도 통합하지 않았습니다'로 마무리합니다. 기억이 들어가고 행동이 나옵니다.

    Claude Code creating a use-theme hook inside src/hooks as the CLAUDE.md folder rule requires and leaving it unintegrated as the prompt requested
    hook은 메모리 파일이 지정한 폴더에 착지 — '아직 연결 금지' 지시도 지켰습니다.6:40에 시청
  2. 6

    채팅에서 #로 새 규칙 기억하기

    파일을 손으로 고칠 필요 없습니다. 메시지를 #로 시작하세요 — 예: '# 새 페이지 컴포넌트를 만들 때는 항상 헤더에 그 페이지로 가는 링크를 추가' — Claude Code는 이걸 저장할 기억으로 인식하고 어디에 둘지 묻습니다: 프로젝트 메모리, 로컬 프로젝트 메모리, 사용자 메모리 중에서.

    Claude Code # memory shortcut asking where a new “always add a header link” rule should be saved: project memory, local project memory, or user memory
    # 단축키와 그것이 띄우는 세 목적지 피커.7:30에 시청
  3. 7

    네 가지 메모리 타입 구분하기

    Anthropic 문서의 표가 지도입니다: 조직용 엔터프라이즈 정책 메모리, 프로젝트 메모리(./CLAUDE.md, 커밋해서 팀과 공유), 사용자 메모리(~/.claude/CLAUDE.md, 개인 전역 설정), 그리고 로컬 프로젝트 메모리(./CLAUDE.local.md, 개인용이며 비추적) — 문서는 후자를 비추천 처리하고 프로젝트 메모리에서 비추적 파일을 임포트하는 방식을 권하지만, 피커에는 여전히 나타납니다.

    Anthropic documentation table of Claude Code memory types — enterprise, project, user and local project memory with locations and sharing scope
    공식 메모리 타입 표: 위치, 용도, 누구와 공유되는 파일인지.10:50에 시청
  4. 8

    규칙이 파일에 실제로 들어갔는지 확인

    프로젝트 메모리를 고르면 규칙이 프로젝트의 CLAUDE.md에 추가됩니다 — 파일 맨 아래에 그대로 있습니다: '새 페이지 컴포넌트를 만들 때는 항상 헤더에 그 페이지로 가는 링크를 추가.' 다음 세션부터 이 한 줄이 컨텍스트에 자동으로 실려 다닙니다.

    New “when making new page components, always add a link in the header” rule saved at the bottom of the project CLAUDE.md file
    새 규칙이 커밋된 CLAUDE.md 맨 아래에 저장된 모습.11:48에 시청

3 · 메모리 파일 일상 관리

  1. 9

    새 작업으로 기억 검증하기

    이제 About 페이지를 요청하고 계획을 보세요: '메모리 지시에 따라 새 About 페이지를 만들고 헤더에 링크를 추가하겠습니다' — todo에는 'Add About page link to header navigation'이 별도 항목으로 있습니다. 두 단계 전에 #로 기억한 규칙이 한 번도 반복되지 않은 작업을 이끌고 있는 겁니다. (영상의 솔직한 경고: Claude는 언급하지 않은 페이지에도 링크를 덧붙일 수 있습니다 — 이 범위 확장은 같은 파일에 한 줄 써서 잡을 수 있습니다.)

    Claude Code todo list for a new About page that includes adding the About link to the header navigation because the CLAUDE.md memory instructs it
    '…메모리 지시에 따라' — todo 목록이 규칙이 작동 중임을 증명합니다.9:37에 시청
  2. 10

    /memory로 메모리 파일 다시 열기

    /memory 명령은 모든 메모리 파일과 위치를 나열합니다: ./.CLAUDE.md의 커밋된 프로젝트 메모리, gitignore된 ./.CLAUDE.local.md의 로컬 메모리, ~/.claude/CLAUDE.md의 전역 사용자 파일. 하나를 고르면 에디터에서 열립니다 — 이 프로젝트의 파일에는 11개의 메모리가 세어 나왔습니다.

    Claude Code /memory command showing the Select memory to edit picker with project, gitignored local and global user CLAUDE.md options
    Select memory to edit — 세 스코프를 피커 하나로.11:22에 시청
  3. 11

    다른 파일처럼 편집하기

    Claude Code는 'Opened project memory at ./.CLAUDE.md'라고 확인하고 VS Code로 열어 주며 팁을 붙입니다: $EDITOR 또는 $VISUAL 환경 변수를 정하면 다른 에디터를 쓸 수 있다고. /init부터 일상 관리까지, 메모리란 정직하게 유지하는 하나의 markdown 파일일 뿐입니다.

    Claude Code confirming “Opened project memory at ./.CLAUDE.md” with the hint to set $EDITOR or $VISUAL for a different editor
    'Opened project memory at ./.CLAUDE.md' — 편집하고 최신으로 유지하세요.12:06에 시청

메모리의 계층과 각 파일의 위치

파일 넷, 스코프 넷 — 제대로 고르면 Claude Code 메모리는 더 이상 감이 아닙니다:

  • 1프로젝트 메모리 — 저장소 루트의 ./CLAUDE.md. git에 추적되고 프로젝트의 모든 개발자와 공유. 프로젝트 관련 이야기만 쓰세요: 구조, 규약, 명령어, 프레임워크.
  • 2로컬 프로젝트 메모리 — ./CLAUDE.local.md. 이 저장소에서의 개인 메모(내 도구, 내 단축키)로 비추적 상태. 문서상 비추천 — 권장은 프로젝트 메모리에서 비추적 파일 임포트 — 이지만 촬영 시점엔 # 피커에 여전히 옵션이 보입니다.
  • 3사용자 메모리 — 홈 디렉터리의 ~/.claude/CLAUDE.md. 이 머신의 모든 프로젝트에 걸치는 전역 설정: 코드 스타일, 응답 언어, 개인 워크플로.
  • 4CLAUDE.md 너머 — 최신 Claude Code 빌드에는 자동 메모리 시스템(~/.claude/projects/ 아래의 MEMORY.md와 토픽 파일)이 추가돼 Claude가 지시 파일과 별개로 스스로 관리합니다. @ 임포트로 다른 문서를 컨텍스트로 당겨올 수도 있습니다. 지시 파일만 원하면 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1로 끄세요.

어떤 계층을 쓰든 영상의 습관은 같습니다: 메모리는 만들고 잊는 게 아닙니다. 구조, 패키지, 규약이 바뀌면 파일을 갱신하세요 — 낡은 기억은 없는 것보다 나쁩니다. Claude는 자신만만하게 그걸 따르니까요.

Claude Code memory FAQ

관련 가이드

Claude Skills 튜토리얼: 만들고, 실행하고, 공유하기Claude Code hooks 튜토리얼Claude Projects 튜토리얼Claude Code 서브에이전트 튜토리얼Claude Code 상태줄(statusline) 튜토리얼