01. 클로드 코드 똑똑하게 쓰기 – 컨텍스트·메모리·스킬 실습

작성자:

이 문서는 Claude Code(이하 클로드 코드)를 써 봤지만 대화가 길어지면 답이 흐려지는 경험을 한 사람을 위한 자료다. 컨텍스트 개념을 잡은 뒤 CLAUDE.md로 규칙을 남기고, 오토메모리와 컨텍스트 관리 커맨드를 익히고, 마지막으로 나만의 스킬 하나를 만드는 것까지 이어진다. 끝까지 따라 하면 프로젝트 폴더에 CLAUDE.md·.claude/rules/·.claude/skills/가 만들어지고, 다음 세션부터 같은 설명을 반복하지 않아도 된다.

시작하기 전에 컴퓨터에 클로드 코드가 설치돼 있어야 한다. 실습용 폴더 하나(예: 바탕화면의 claude_practice)와 텍스트 편집기(메모장·VS Code 등)를 준비한다.

1 – 왜 클로드 코드는 쓸수록 답이 흐려질까

클로드 코드가 대화 후반에 앞서 결정한 내용을 잊거나 없는 파일을 있다고 답하는 이유는 기억을 담는 공간이 유한하기 때문이다. 이 공간을 컨텍스트 윈도우라고 한다. 여기서는 컨텍스트 윈도우 개념을 잡고, 답이 흐려지는 두 가지 원인을 구분한다.

1.1 – 실습 환경 준비

뒤에서 계속 사용할 실습 폴더를 준비한다. 앞으로 만드는 파일이 모두 이 폴더에 쌓인다.

  1. 바탕화면에 실습용 폴더 claude_practice를 만든다.
  2. 터미널을 연다.
  3. Windows: Win+R → cmd 실행
  4. macOS: ⌘+Space → terminal 실행
  5. 실습 폴더로 이동한다.
  6. Windows: cd %USERPROFILE%Desktopclaude_practice
  7. macOS: cd ~/Desktop/claude_practice
  8. 클로드 코드 버전을 확인한다: claude --version. 2.1.59 이상이면 뒤에서 다룰 오토메모리를 쓸 수 있다.

Note: claude --version이 command not found로 뜨면 설치가 필요하다. npm install -g @anthropic-ai/claude-code로 설치한 뒤 다시 확인한다.

1.2 – 컨텍스트와 컨텍스트 윈도우 구분하기

컨텍스트는 지금까지 클로드와 주고받은 대화 전부를 가리킨다. 컨텍스트 윈도우는 그 대화를 담아 두는 공간의 크기다. 이 공간은 유한해서, 꽉 차면 앞쪽 대화부터 밀려나 잊힌다. 클로드가 후반에 앞서 한 약속을 잊는 것은 이 때문이다.

답이 흐려지는 원인은 크게 두 가지다. 하나는 대화가 너무 길어져 컨텍스트가 공간을 넘친 경우이고, 다른 하나는 세션을 새로 열어 지난 세션 내용을 읽지 못하는 경우다. 앞의 경우는 컨텍스트를 압축·초기화하는 커맨드로 다루고, 뒤의 경우는 공간 밖에 기억을 두는 파일 즉 CLAUDE.md와 오토메모리로 다룬다.

Tip: 같은 내용을 다시 묻기 시작하는 순간이 공간이 차기 시작했다는 신호다. 새 창에서 시작했더니 지난 결정을 기억하지 못한다면 세션이 나뉜 경우다.

2 – CLAUDE.md로 매번 설명하지 않기

앞에서 정리한 "공간 밖에 기억 두기"의 첫 번째 방법이 CLAUDE.md다. 이 파일을 프로젝트 폴더에 두면 클로드 코드가 세션을 열 때마다 자동으로 먼저 읽는다. 매번 프로젝트 설명과 규칙을 다시 알려 줄 필요가 없다. 여기서는 실습 폴더에 CLAUDE.md를 만들어 세션 시작 때 실제로 읽히는지 확인한다.

2.1 – 첫 CLAUDE.md 만들기

CLAUDE.md는 특별한 도구가 아니라 마크다운 파일이다. 규칙을 한국어로 적어 두면 된다.

  1. 실습 폴더(claude_practice)에서 텍스트 편집기로 새 파일을 만든다.
  2. 아래 내용을 붙여 넣는다.
# 클로드 연습 프로젝트

이 폴더는 Claude Code를 익히기 위한 연습 공간이다.

## 규칙
- 답변은 한국어로 한다.
- 코드 예시는 항상 파일명과 함께 준다.
- 파일을 새로 만들기 전에 이미 있는지 먼저 확인한다.
  1. CLAUDE.md라는 이름으로 실습 폴더에 저장한다.
  2. 터미널에서 claude를 입력해 세션을 연다.
  3. 세션에 이 프로젝트 규칙 요약해줘라고 물어본다.

붙여 넣은 규칙 세 줄이 그대로 요약되어 나오면 CLAUDE.md가 자동으로 읽힌 것이다. 이때부터는 세션을 새로 열어도 같은 규칙을 다시 설명할 필요가 없다.

Note: 파일 이름은 반드시 대문자 CLAUDE.md여야 한다. 소문자 claude.md는 읽지 못한다. Windows 메모장에서 저장할 때 확장자가 .md.txt로 붙으면 읽히지 않으므로, 저장 창에서 파일 형식을 모든 파일로 바꿔 .md로 저장한다.

2.2 – 적을 것과 안 적을 것

CLAUDE.md에 내용을 많이 넣을수록 그만큼 컨텍스트 공간을 차지한다. 공식 문서는 200줄 안쪽을 권한다. 넣을 것과 뺄 것의 예로 기준을 잡는다.

  1. "이 프로젝트는 개인 블로그다" — 넣는다(프로젝트 설명).
  2. "매번 API 호출 전에 입력을 검증해 줘" — 넣는다(자주 쓰는 규칙).
  3. "오늘 오후 4시까지 로그인 페이지 만들어 줘" — 넣지 않는다(오늘만 필요한 요청).
  4. "함수는 화살표 함수로 써 줘" — 넣는다(굳어진 취향).
  5. "이 파일은 useState를 쓴다" — 넣지 않는다(코드를 보면 아는 것).

기준은 세 가지다. 프로젝트 전반에 두고두고 쓸 것, 매번 반복해 알려 주는 취향, "항상 이렇게 해 줘"라고 말해 온 것이다. 오늘 하루만 필요한 요청, 자주 바뀌는 임시 내용, 코드가 이미 말해 주는 것은 넣지 않는다.

Warning: 200줄을 넘기면 오히려 클로드의 성능이 떨어진다. 200줄이 넘으면 다음 절에서 다룰 방식으로 규칙을 쪼갠다.

2.3 – 프론트매터로 규칙 켜고 끄기

한 규칙 파일을 특정 상황에서만 적용되게 하려면, 파일 맨 위에 프론트매터라는 짧은 설정을 붙인다. 프론트매터는 ---와 --- 사이에 적는 몇 줄짜리 설정이다. 지금 만들 규칙 파일은 뒤에서 만들 .claude/rules/에 놓고 프론트매터로 조건을 건다.

  1. 텍스트 편집기에서 새 파일을 만든다.
  2. 아래 내용을 붙여 넣는다.
---
paths:
  - "src/api/**"
---

# API 규칙
- 모든 API는 입력 검증을 넣는다.
- 실패 응답은 항상 `{ ok: false, error: "..." }` 형태로 준다.
  1. 파일 이름을 api.md로 저장한다(저장 위치는 3.1에서 정한다).

프론트매터 안의 paths는 이 규칙을 언제 켤지 정하는 조건이다. src/api/**라고 적었으므로, 클로드가 src/api/ 아래 파일을 만질 때만 이 규칙이 켜진다. 다른 폴더 파일을 만질 때는 규칙이 켜지지 않아 컨텍스트 공간을 차지하지 않는다.

여기서 헷갈리기 쉬운 점이 있다. paths는 규칙 파일을 어디서 불러올지가 아니라, 이 규칙이 적용될 대상 파일의 조건이다. 규칙 파일 자체는 .claude/rules/에 두되, paths는 클로드가 만지는 실제 소스 파일 경로를 가리킨다.

Tip: 프론트매터가 없는 규칙 파일은 조건 없이 항상 켜진다. paths에 여러 패턴을 넣으려면 - "src/api/" 아래 줄에 - "src/lib/"처럼 이어 붙인다.

3 – 규칙 쪼개기와 오토메모리

CLAUDE.md 한 파일에 규칙을 다 담으면 금방 200줄을 넘긴다. 여기서는 규칙을 .claude/rules/ 폴더에 쪼개 두는 방법과, 클로드가 스스로 적어 두는 기억인 오토메모리를 다룬다. 앞에서 만든 api.md를 이제 제자리에 넣는다.

3.1 – .claude/rules/ 폴더에 규칙 넣기

규칙 파일을 이 폴더에 두면 세션 시작 때 함께 읽힌다. 프로젝트가 커져도 CLAUDE.md는 짧게 유지된다.

  1. 실습 폴더로 이동한다.
  2. .claude 폴더를 만든다. Windows 탐색기는 .으로 시작하는 폴더를 만들기 번거로우니 터미널에서 mkdir .claude로 만든다.
  3. 그 안에 rules 폴더를 만든다: mkdir .claude/rules(Windows는 경로 구분자로 를 쓴다).
  4. 2.3에서 만든 api.md를 .claude/rules/ 폴더로 옮긴다.
  5. 텍스트 편집기에서 .claude/rules/design.md를 새로 만들고 아래 내용을 붙여 넣어 저장한다.
---
paths:
  - "src/components/**"
---

# 디자인 규칙
- 색은 항상 CSS 변수 `--color-*`를 쓴다.
- 컴포넌트 파일 이름은 PascalCase로 짓는다.

이제 폴더는 아래 모양이 된다.

claude_practice/
  CLAUDE.md
  .claude/
    rules/
      api.md
      design.md

세션을 새로 열면 CLAUDE.md가 로드된 뒤, 만지는 파일이 src/api/면 api.md가, src/components/면 design.md가 함께 켜진다. CLAUDE.md를 200줄 안으로 유지하면서도 규칙 총량은 늘려 갈 수 있다.

특정 폴더에서만 쓰는 규칙은 다른 방법도 있다. 예를 들어 frontend/ 폴더 안에 또 다른 CLAUDE.md를 두면, 클로드가 그 폴더 파일을 만질 때 상위 CLAUDE.md와 폴더 안 CLAUDE.md를 합쳐 읽는다. 프로젝트 전반 규칙은 .claude/rules/에, 특정 공간에만 쓰는 규칙은 그 공간 폴더의 CLAUDE.md에 나눠 두면 관리하기 쉽다.

Note: 두 방식은 대체재가 아니라 함께 쓰는 것이다. .claude/rules/는 세션 시작 시 항상 읽히고, 폴더별 CLAUDE.md는 그 폴더 파일을 만질 때만 켜진다.

3.2 – 나만 쓰는 규칙은 로컬로 두기

팀 프로젝트에서는 CLAUDE.md가 깃(Git)에 올라간다. 팀원 모두가 내 개인 취향까지 물려받으면 곤란하므로, 개인 취향 규칙은 로컬에 따로 둔다.

  1. 실습 폴더에서 텍스트 편집기로 새 파일을 만들고 아래 내용을 붙여 넣는다.
# 나만의 클로드 규칙(로컬)
- 응답 앞에 이모지를 붙이지 않는다.
- 파일 저장 전에는 항상 diff를 먼저 보여 준다.
  1. CLAUDE.local.md라는 이름으로 저장한다.
  2. 실습 폴더에 .gitignore 파일이 없으면 새로 만들고, 아래 한 줄을 적어 저장한다.
CLAUDE.local.md

이렇게 하면 팀에 공유되는 것은 CLAUDE.md뿐이고, 내 취향인 CLAUDE.local.md는 로컬에만 남는다. 세션 시작 때는 둘 다 함께 읽힌다.

3.3 – 오토메모리 확인하기

오토메모리는 클로드가 스스로 필요하다고 판단해 저장하는 기억이다. CLAUDE.md가 내가 직접 적는 규칙이라면, 오토메모리는 클로드가 대신 적는 기억이다. 팀에 공유되지 않고 나에게만 남으며, 2.1.59 이상에서 기본으로 켜져 있다.

  1. 세션을 켠 상태에서 같은 지적을 두 번 반복한다.
  2. 처음: 답할 때 마지막에 "다음 단계 뭐 할까?"라고 물어보지 마.
  3. 두 번째: 또 그러네. 다음 단계 뭐 할까 물어보지 마.
  4. 몇 번 반복하면 클로드가 이 지적을 오토메모리에 담는다.
  5. /memory를 입력해 저장된 기억을 확인한다.
  6. 저장된 항목은 그 자리에서 지우거나 끌 수 있다.

/memory는 무엇을 기억했는지 보고, 지우고, 끄는 통합 창이다. 오토메모리는 조용히 쌓이므로 가끔 열어 원치 않는 항목을 정리한다.

Warning: /memory 목록이 아예 안 뜨면 클로드 코드 버전이 낮은 것이다. claude --version으로 확인해 2.1.59 미만이면 npm update -g @anthropic-ai/claude-code로 올린다.

4 – 컨텍스트 관리 커맨드

CLAUDE.md와 오토메모리로 세션 밖에 기억을 두는 법을 익혔다. 이번에는 세션 안에서 대화가 공간을 얼마나 채우고 있는지 보고, 필요하면 줄이거나 초기화하는 커맨드 다섯 개를 익힌다. 실습 폴더에서 열려 있는 세션을 그대로 이어 쓴다.

4.1 – /context로 사용량 보기

지금 세션이 공간을 얼마나 썼는지부터 확인한다. 숫자를 보아 두면 나머지 커맨드를 왜 쓰는지 이해하기 쉽다.

  1. 세션에 /context를 입력한다.
  2. 표시된 컨텍스트 사용률을 확인한다.
  3. 클로드에게 이 실습 폴더 구조 전부 자세히 설명해 줘처럼 조금 긴 답을 요구한다.
  4. 답을 받은 뒤 다시 /context로 사용률이 얼마나 올라갔는지 본다.

두 숫자의 차이가 방금 대화가 차지한 공간이다. 대화가 오갈 때마다 공간이 이렇게 채워진다.

4.2 – /compact로 앞 대화 접기

대화가 길어져 앞부분이 필요 없어졌을 때 압축하는 커맨드다. 앞 대화를 요약해 공간을 되찾는다. 초기화가 아니라 접기이므로 방금까지의 흐름은 이어진다.

  1. /compact를 입력한다.
  2. 압축이 끝나면 다시 /context로 사용률이 얼마나 내려갔는지 본다.
  3. 압축 뒤에 방금까지 만든 규칙 파일 이름 다 얘기해 줘처럼 조금 뒤로 돌아가는 질문을 던져 본다.

압축은 앞 대화를 요약본으로 갈아 끼우는 방식이라, 세세한 단어까지 남지는 않지만 결정 사항 위주로 이어진다. 자동 압축을 켜 두면 이 판단을 클로드가 알아서 한다.

  1. /config를 입력한다.
  2. 설정에서 Auto-compact 항목을 true로 바꾼다.

이제 컨텍스트가 어느 정도 차면 자동으로 접힌다.

Note: 자동 압축은 편하지만 접힌 앞 대화의 세부를 다시 확인하기 어렵다. 정확한 문구까지 되짚어야 하는 작업 중이면 자동 압축을 잠깐 끄는 편이 낫다.

4.3 – /clear로 세션 초기화

지금 대화 흐름이 끝났고 새로운 주제로 넘어갈 때 쓴다. 대화가 화면에서 사라지지만 완전히 없어지는 것은 아니고, 디스크에 남아 필요하면 다시 부를 수 있다.

  1. /clear를 입력하면 세션이 새로 열린다.
  2. 이 프로젝트 규칙 요약해 줘라고 다시 물어본다.

앞서 나눈 대화는 사라졌지만 CLAUDE.md가 다시 자동으로 읽혀 규칙은 그대로 요약된다. 공간 밖에 기억을 두는 이유가 여기서 다시 확인된다. /clear로 지워도 기본 규칙은 잃지 않는다.

4.4 – /statusline으로 사용량 상시 표시

/context를 매번 입력하는 것은 번거롭다. 입력창 아래에 상태 줄을 붙여 두면 사용률을 늘 볼 수 있다.

  1. /statusline을 입력한다.
  2. 안내가 뜨면 사용 모델 + 디렉토리 위치 + 컨텍스트 사용량 %를 넣어서 만들어 줘라고 답한다.
  3. 상태 줄이 생성되면 창 아래에 사용 모델과 사용률 퍼센트가 상시 표시된다.
  4. 아무 질문이나 던진 뒤, 상태 줄의 사용률이 오르는 것을 확인한다.

상시 표시가 있으면 압축할 시점을 판단하기 쉽다.

5 – 나만의 첫 스킬 만들기

이제 반복해서 시키는 작업 하나를 스킬(Skill)로 등록해 명령 한 번으로 부르는 실습을 한다. 스킬은 .claude/skills/스킬명/SKILL.md 파일 하나로 만들어진다.

5.1 – 스킬 폴더 만들기

먼저 스킬이 놓일 자리를 만든다.

  1. 실습 폴더에서 터미널을 연다.
  2. .claude/skills 폴더를 만든다: mkdir .claude/skills.
  3. 그 안에 스킬 이름 폴더를 만든다. 이 실습에서는 한국어 요약 스킬을 만든다: mkdir .claude/skills/article-summary.

폴더 이름이 곧 스킬 이름이 된다. 하나의 폴더 안에 그 스킬의 SKILL.md가 들어간다.

5.2 – SKILL.md 작성하기

이 파일이 스킬의 몸통이며 세 부분으로 구성된다. 이름(name), 언제 부르는지(description), 무엇을 하는지(본문).

  1. 텍스트 편집기로 .claude/skills/article-summary/SKILL.md를 새로 만든다.
  2. 아래 내용을 그대로 붙여 넣고 저장한다.
---
name: article-summary
description: 웹 기사·블로그 글·긴 문서를 한국어로 구조화 요약하는 스킬. 사용자가 "요약해 줘", "정리해 줘", "핵심만 뽑아 줘", "TL;DR" 같은 말을 하거나, URL·긴 텍스트를 던지며 빠르게 내용을 알고 싶어 하는 의도가 보이면 자동으로 부른다.
---

# 아티클 요약

긴 글을 읽고 항상 한국어로 아래 고정 형식 요약을 만든다.

## 입력 가져오기
- URL이면 본문만 읽는다. 광고·내비게이션·댓글은 뺀다.
- 페이월 등으로 못 읽으면 지어내지 말고 원문을 붙여 달라고 요청한다.

## 출력 형식
1. 한 줄 요약(30자 안).
2. 핵심 3줄.
3. 인용할 만한 문장 1개(원문 그대로).
4. 이 글이 유용한 사람 한 줄.

프론트매터의 name은 스킬 폴더 이름과 똑같이 맞춘다. description은 클로드가 이 스킬을 부를지 판단하는 근거라서, 언제 부르는지를 구체적으로 적을수록 잘 켜진다. 본문에는 그 스킬이 실제로 어떻게 일할지 순서를 적는다.

5.3 – 스킬 불러 써 보기

스킬이 실제로 켜지는지 확인한다.

  1. 세션을 닫았다면 /clear나 claude로 다시 연다.
  2. 아무 뉴스 기사 URL을 하나 골라 이 글 요약해 줘 https://...처럼 요청한다.
  3. 응답이 방금 만든 네 항목 형식으로 오면 스킬이 켜진 것이다.

description에 "요약해 줘"라는 표현을 넣어 두었기 때문에, 이 말이 들어간 요청이 오면 클로드가 이 스킬을 자동으로 부른다.

Note: 스킬은 대화 중에 자동으로 켜진다는 점에서 슬래시로 부르는 커맨드와 다르다. 스킬이 잘 안 켜지면 description 문구가 너무 뭉뚱그려져 있을 가능성이 크다. 사용자가 실제로 쓸 표현("요약", "정리", "TL;DR")을 명시적으로 넣는다.

5.4 – 스킬과 서브 에이전트 구분만 알기

서브 에이전트는 실습 대신 구분만 잡고 넘어간다. 스킬은 메인 세션에서 대화 중 자동으로 도구처럼 켜지고, 서브 에이전트는 자기만의 컨텍스트 창을 따로 갖고 일한 뒤 결과만 메인으로 넘긴다. 코드 리뷰나 QA처럼 중간 과정을 메인에서 보지 않아도 되는 무거운 작업이 서브 에이전트의 자리다. 서브 에이전트 파일은 .claude/agents/에이전트이름.md에 놓는다.

정리하면 다음과 같다.

  1. 스킬 — 대화 중 자연스럽게 부르고, 과정도 함께 보고 싶을 때.
  2. 서브 에이전트 — 결과만 받으면 되고, 과정은 격리해 메인 창을 덜 채우고 싶을 때.

6 – 여기서 어디로 더 갈지

앞의 다섯 장을 마쳤으면 CLAUDE.md·.claude/rules/·.claude/skills/가 실습 폴더에 만들어져 있고, 세션 관리 커맨드 다섯 개가 손에 익었다. 이 마지막 장은 이 매뉴얼에서 다루지 못한 두 갈래를 지도로만 남긴다.

6.1 – 공식 플러그인 두 개 알아 두기

플러그인은 스킬·커맨드·에이전트를 하나로 묶어 배포하는 꾸러미다. 클로드 코드 세션에서 /plugin을 입력하면 스토어처럼 골라 설치할 수 있고, 설치 뒤에는 /reload-plugins로 새로고침한다. 오늘 다룬 주제와 이어지는 공식 플러그인은 두 개다.

  1. session-report — 최근 일주일 토큰 사용을 HTML 리포트로 뽑아 준다. 어떤 대화가 공간을 많이 차지하는지 확인하고, 그 부분을 규칙·컨텍스트로 줄이는 데 쓴다.
  2. claude-md-management — /revise-claude-md로 이번 세션에서 규칙으로 추가할 후보를 뽑고, /claude-md-improver로 CLAUDE.md를 여섯 항목별로 채점한다. 200줄 다이어트가 필요할 때 유용하다.

이 두 가지는 프로젝트가 커져 CLAUDE.md가 길어질 때 먼저 켜면 된다.

6.2 – 서드파티 앱은 MCP로 붙인다는 큰 그림

노션·지라·슬랙·구글 드라이브 같은 외부 서비스를 클로드가 직접 들여다보게 하는 통로가 MCP다. 회의록 50건을 파일로 다 가져오지 않고, 필요한 액션아이템만 뽑아 오는 식으로 컨텍스트를 아낀다. 예를 들어 노션을 연결하는 명령은 아래 한 줄이다.

claude mcp add --transport http notion https://mcp.notion.com/mcp

붙인 다음에는 CLAUDE.md에 "회의록은 노션 DB에서 찾아라, 이 저장소에 통째로 붙여 넣지 마라" 같은 규칙을 함께 적어 둔다. 그러면 클로드가 노션을 창고로 쓰고, 프로젝트 폴더는 가볍게 유지된다. 서드파티 앱은 크게 네 유형으로 나뉜다.

  1. 지식 문서형 — 노션·옵시디언·구글 드라이브.
  2. 데이터베이스형 — 슈퍼베이스 등.
  3. 커뮤니케이션형 — 지메일·슬랙.
  4. 업무 이슈형 — 지라·리니어.

자기 업무에서 반복해 여는 도구를 하나 골라 붙이는 것이 다음 단계다.