Claude Code 기본기 쌓기
메모리 구조 파악하기 (CLAUDE.md)
클로드 코드의 기본 메모리 구조와 CLAUDE.md 이해하기
얻어갈 것
- 에이전트의 컨텍스트 개념을 이해합니다.
- Claude Code에 같은 맥락을 매번 다시 설명하지 않는 방법을 이해합니다.
- 현재 대화 세션,
CLAUDE.md, Auto memory의 역할을 구분합니다.
컨텍스트 먼저 이해하기
- 토큰(Token)은 모델이 글을 읽고 쓸 때 사용하는 기본 단위입니다. 단어 하나가 토큰 하나일 때도 있지만, 단어 일부나 기호, 한국어 문장의 일부가 따로 토큰이 되기도 합니다.
- 컨텍스트(Context)는 하나의 세션 안에서 Claude가 참고하는 정보 묶음입니다. 지금까지의 대화, 멘션한 파일, 읽은 문서,
CLAUDE.md같은 지침이 여기에 들어갑니다. - 모델마다 한 번에 담을 수 있는 컨텍스트의 최대 크기가 다릅니다. 이 한도를 보통 컨텍스트 윈도우라고 부릅니다.
- 대화가 길어지거나 파일을 많이 읽히면 컨텍스트 사용량도 늘어납니다. 사용량이 많아질수록 중요한 지시가 묻히기 쉬워지고, 어느 시점에는
/compact로 정리하는 편이 좋습니다.
에이전트에게 기억이 필요한 이유
- 에이전트는 프로젝트 목표, 규칙, 금지사항을 처음부터 알고 있지 않습니다.
- 그래서 반복되는 지시를 작업 시작 전에 넣거나, 이전 결정을 남겨둘 장치가 필요합니다.
- 이 기억이 없으면 같은 설명을 계속 반복하고, 프로젝트 규칙을 놓치기 쉽습니다.
- 코드베이스가 커질수록 "이 프로젝트에서는 이렇게 한다"는 맥락이 결과 품질을 크게 좌우합니다.
클로드 코드의 컨텍스트 구조 파악하기
Claude Code가 작업할 때 참고하는 컨텍스트는 세 층으로 나눠 보면 됩니다.
- 현재 대화의 세션: 지금 주고받는 메시지와 도구 사용 기록입니다. 세션 사이의 내용은 자동으로 공유되지 않습니다.
CLAUDE.md: 사람이 직접 작성하는 프로젝트 지침입니다. 세션이 시작될 때 Claude의 컨텍스트에 들어갑니다.- Auto memory: Claude가 작업 중 배운 패턴, 자주 쓰는 명령, 디버깅 힌트, 사용자 선호를 스스로 기록합니다.
수업에서는 "지금 대화 안에서만 유지되는 맥락"과 "다음 세션에도 들어가는 기억"을 나눠서 봅니다. 계속 써야 하는 규칙은 세션 로그에만 남기지 말고 CLAUDE.md에 작성해두는 편이 좋습니다.
- User level:
~/.claude/CLAUDE.md에 둡니다. 내 모든 프로젝트에 적용되는 개인 선호입니다. - Project level:
./CLAUDE.md또는./.claude/CLAUDE.md에 둡니다. 이 저장소에서 팀과 공유할 규칙입니다. - Folder/rules level: 하위 폴더의
CLAUDE.md나.claude/rules/에 둡니다. 특정 파일/폴더에만 적용되는 세부 규칙을 담습니다.
CLAUDE.md에 넣을 것
- 프로젝트가 무엇인지, 어떤 기술 스택을 쓰는지, 어떤 명령으로 검증하는지.
- 절대 하지 말아야 할 일, 권한/보안처럼 실수하면 영향이 큰 규칙.
- 폴더별 작성 규칙이나 작업 방식처럼 에이전트가 매번 참고해야 하는 기준.
처음 만들 때는 Claude Code에서 /init을 실행하면 됩니다. /init은 코드베이스를 훑고, 빌드/테스트 명령과 프로젝트 규칙 후보를 찾아 CLAUDE.md 초안을 만들어줍니다.
좋은 CLAUDE.md는 문서 백과사전이라기보다 작업 전 체크리스트에 가깝습니다.
- "테스트를 잘하기"보다 "
pnpm verify:mdx-components를 실행한다"처럼 씁니다. - "코드를 깔끔하게"보다 "content MDX에는 지원되는 컴포넌트만 쓴다"처럼 씁니다.
- "보안 조심"보다 "private 본문은 권한 확인 전에 서버에서 렌더하지 않는다"처럼 씁니다.
Claude Code가 현재 세션에서 어떤 기억을 읽고 있는지 확인하려면 /memory를 엽니다. 여기서 로드된 CLAUDE.md, local memory, rules를 확인하고 auto memory도 관리할 수 있습니다.
길어졌을 때의 정리법
CLAUDE.md가 길어지면 모든 내용을 한 파일에 계속 밀어넣지 않습니다.docs/에 상세 문서를 두고,CLAUDE.md에는 "언제 어떤 문서를 읽을지"만 남깁니다.- 이렇게 하면 에이전트에게 필요한 맥락만 열어줄 수 있습니다.
예를 들어 CLAUDE.md에는 이렇게 짧게 남기고, 세부 내용은 별도 문서로 뺄 수 있습니다.
'OOO 상황에서는 OOO를 읽어라'라고 하는 것을 Progressive Disclosure라고 합니다.
## 콘텐츠 작업
- 강의 MDX를 수정할 때는 docs/course-writing.md를 먼저 읽습니다.
- figure를 만들 때는 figures/FIGURE.md를 따릅니다.
(참고) Rules로 더 좁게 적용하기
모든 규칙이 매번 필요하지는 않습니다. 특정 폴더나 확장자에만 필요한 규칙은 .claude/rules/에 나눠둘 수 있습니다.
---
paths:
- "content/courses/**/*.mdx"
---
# Course MDX Rules
- 지원되는 MDX 컴포넌트만 사용합니다.
- 새 Figure는 chapter assets에 둡니다.
- 레슨 본문은 자연스러운 한국어 존댓말로 씁니다.
paths에는 glob 패턴을 쓸 수 있습니다.- 특정 확장자, 폴더, 테스트 파일처럼 필요한 범위만 지정합니다.
- 모든 작업에 필요한 규칙은
CLAUDE.md, 특정 파일군에만 필요한 규칙은.claude/rules/에 두면 됩니다.
실습하기: 회의록 프로젝트 기억 남기기
마지막으로 이 챕터에서 만든 것들을 한 프로젝트로 묶어 기억에 남깁니다. 앞 Skill 레슨에서 만든 회의록 정리와 앞 MCP 레슨에서 다룬 Google Calendar 준비 작업을 하나의 작업 폴더로 CLAUDE.md에 적어두면, 다음 세션에서도 같은 Skill과 도구 사용 규칙으로 이어갈 수 있습니다.
CLAUDE.md에 이 프로젝트를 설명하는 내용을 추가해줘. 포함할 것: - 이 폴더는 회의록을 정리하고, Google Calendar로 이번 주 업무를 준비하는 작업 폴더다 - 새 회의록은 meetings/ 폴더에 YYYY-MM-DD-topic.md 형식으로 넣는다 - 회의록은 결정된 것, 해야 할 일, 아직 정해지지 않은 것으로 나눈다 - Google Calendar는 읽기 전용으로만 쓰고, 일정 생성·수정은 사람이 확인한 다음에 한다 - 담당자나 날짜가 애매하면 추측하지 말고 질문으로 남긴다
마무리
- 컨텍스트는 지금 세션에서 Claude가 참고하는 정보이고, 기억은 다음 작업에서도 반복해서 가져갈 기준입니다.
CLAUDE.md에는 모든 설명을 길게 넣기보다, 에이전트가 매번 놓치면 안 되는 규칙과 읽어야 할 문서만 남기는 편이 좋습니다.