컨텍스트 엔지니어링
CLAUDE.md 3계층·subagent

Session 3 · 컨텍스트 엔지니어링 — CLAUDE.md 3계층·subagent

프롬프트 vs 컨텍스트 · 3계층 구조 · memory·@file · subagent 자작

강사 박수현 · 🚀 젠아이랩스(GenAI Labs)

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background split into two mirrored halves. On the left, a tired developer types into a chat prompt — the chat bubble contains NO letters or words, only 3 thin horizontal lines suggesting text, with faded ghost copies of the same blank bubble stacked behind. On the right, a calm developer sits next to a single document labeled 'CLAUDE.md' that emits soft glowing lines connecting to a laptop — that laptop chat bubble also has NO letters, only 3 thin horizontal lines. A vertical accent divider separates the two scenes. Clean editorial style, teal #00b894 and purple #6c5ce7 accents with warm orange highlights, 16:9. CRITICAL: chat bubbles contain no text or letters at all, only thin abstract lines. English only, no Korean, each label EXACTLY ONCE."

세 축의 지도 — 프롬프트 · 컨텍스트 · 하네스

AI 코딩을 다루는 기술은 세 축으로 정리된다. 축마다 초점이 다르고, 뒤의 축이 앞의 축을 감싼다.

오늘 서 있는 자리는 가운데 고리 — 컨텍스트가 프롬프트를 감싸고, LLM 에 판단 재료를 공급한다

PART 1

컨텍스트 엔지니어링이란 — 프롬프트와 무엇이 다른가

프롬프트 vs 컨텍스트 · 판정 기준 · 컨텍스트가 없으면 벌어지는 일 · 3층 구조 뼈대.

프롬프트 vs 컨텍스트 — 성격이 다르다

프롬프트와 컨텍스트는 성격이 다르다. 이 둘을 섞으면 매 요청이 장황해지고 팀원끼리 결과가 다르게 나온다.

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background of a horizontal layered stack rendered as a translucent glass prism labeled 'Context Window' at the top. Inside the prism from bottom to top, five thin horizontal layer bands are stacked with English labels: 'System Prompt', 'CLAUDE.md (Global · Project · Local)', 'Auto Memory', '@file inserts', 'Conversation history'. On the right side of the prism, a vertical gauge with tick marks reads '1M' at the top and '0' at the bottom, showing a fill level roughly two-thirds up. A small secondary badge next to the gauge reads 'or 200K (Sonnet 4.5)' in smaller text. A thin luminous line labels '/compact' with a small arrow suggesting compression toward a smaller shape. Clean editorial illustration style — teal #00b894 for lower stable layers, purple #6c5ce7 accents on Memory, warm orange highlights on inserts, 16:9. CRITICAL: All visible text MUST be in English ONLY. Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

컨텍스트 윈도우 — 무엇이 담기나 (모델별 컨텍스트 크기는 이미지 게이지 참조)

컨텍스트가 없으면 벌어지는 일

컨텍스트 3층 구조 — 이 세션의 뼈대

Claude Code 는 세션 시작 시점에 CLAUDE.md 를 세 위치에서 읽는다. 각 위치는 성격이 다르다.

※ 실행 플로우. CLAUDE.md 는 세션 시작 시 1회 로드되어 시스템 프롬프트에 주입된다 — 매 턴 재주입되지 않는다. 세션이 길어져 컨텍스트가 압박받으면 초반 지시의 효력이 떨어질 수 있다. hook 이 필요한 이유 — 매 턴 주요 규약을 다시 주입하는 축.

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background — three-tier pyramid stack viewed slightly from the side. Bottom wide layer (teal) labeled 'Global' with English tag ~/.claude/CLAUDE.md. Middle layer (purple) labeled 'Project' with English tag <repo>/CLAUDE.md. Top narrow layer (warm orange) labeled 'Local' with English tag <repo>/CLAUDE.local.md. Thin luminous lines flow upward. 16:9. English only, each label EXACTLY ONCE."

PART 2

CLAUDE.md 3계층 — 글로벌·프로젝트·로컬

3계층 총정리 표 · 우선순위 · 글로벌 예시 · 프로젝트 표준 섹션 5개 · 스택별 예시 3종(Python·TS·Go) · 로컬 예시.

3계층 총정리 — 위치 · git · 담는 것

우선순위 — 같은 지시가 겹치면

같은 항목이 세 계층에 겹치면 로컬 > 프로젝트 > 글로벌 순으로 이긴다.

로컬 (가장 강함) → 프로젝트 → 글로벌 (가장 약함)

글로벌 예시 — 한 파일 통째로

# ~/.claude/CLAUDE.md — 개인 규약

## 응답 언어
- 한국어로 답한다. 코드 · 명령 · 에러 메시지는 원문 유지.

## 커밋 메시지
- Conventional Commits (`feat:` · `fix:` · `chore:` · `docs:`).
- 본문 명령형 · 요약 50자 이내.

## 로그 규약
- print 대신 표준 로거 (Python `logging` · JS `pino`).
- 레벨은 debug · info · warning · error 넷만.

## 코드 스타일
- Python: 4-space · type hint · f-string.
- 주석은 왜 (why) 만. 무엇 (what) 은 코드에 맡긴다.

프로젝트 계층 — 표준 섹션 5개

프로젝트는 팀 전체가 공유하는 리포 규약 이다. git 커밋되므로 팀원 누구든 이 리포에서 세션을 열면 같은 컨텍스트가 로드된다.

## Stack        (언어 · 프레임워크 · 라이브러리)
## Architecture (디렉토리 구조 · 각 폴더 역할)
## Domain Terms (이 리포에서만 쓰이는 용어)
## Commands    (개발 · 테스트 · 린트 · 빌드)
## Conventions (예외 처리 · 네이밍 · 관례)

🎨 Image Prompt: "Editorial illustration on dark navy #0f1722 background — three small stack badges arranged as a horizontal row in the upper-right corner of the composition, each rendered as a rounded rectangular chip. Left chip shows a stylized 'Py' glyph labeled 'Python'. Middle chip shows angle brackets glyph labeled 'TypeScript'. Right chip shows a gopher-silhouette glyph labeled 'Go'. Below the badges, a single centered document card labeled 'CLAUDE.md' with five thin horizontal lines suggesting the five standard sections. Thin luminous connectors flow from each badge down to the document — teal #00b894 and purple #6c5ce7 accents, 16:9. CRITICAL: All visible text MUST be in English ONLY. Each label appears EXACTLY ONCE. No mirrored text."

프로젝트 예시 — Python FastAPI

# CLAUDE.md — leads-service

## Stack
- Python 3.11 · FastAPI · SQLAlchemy 2.0 · Postgres 15 · Redis 7
- Test: pytest · Ruff · Mypy (strict)

## Architecture
- `app/api/` — HTTP 핸들러 (얇게, 로직 금지)
- `app/services/` — 비즈니스 로직 (트랜잭션)
- `app/repositories/` — DB 접근 (SQLAlchemy 세션은 여기서만)
- `app/models/` — Pydantic v2 스키마

## Domain Terms
- **Lead** — 예약 확정 전 잠재 고객. status: new · qualified · converted · lost
- **Booking** — 확정된 예약. Lead 가 converted 되면 생성
- **Slot** — 예약 가능 시간대. 매일 자정 배치 생성

## Commands
- 개발: `make dev` · 테스트: `make test` · 마이그레이션: `alembic upgrade head`

## Conventions
- 새 API 는 `app/api/vN/` 아래에
- 모든 서비스 함수는 `async def`
- 예외는 `app/exceptions.py` 도메인 예외로 감싼다

프로젝트 예시 — TypeScript Next.js

# CLAUDE.md — dashboard-web

## Stack
- TypeScript 5.4 · Next.js 15 (App Router) · React 19 · Tailwind 4
- 상태: Zustand · 데이터: TanStack Query · Auth: NextAuth

## Architecture
- `app/` — App Router (RSC 우선, "use client" 는 명시적으로만)
- `components/ui/` — shadcn 원본, 수정 금지
- `lib/` — 순수 함수 · API 클라이언트

## Domain Terms
- **Widget** — 대시보드 카드 1개 (sm · md · lg)
- **Layout** — Widget 배치, 사용자별 저장

## Commands
- `pnpm dev` · `pnpm typecheck` · `pnpm test` · `pnpm e2e`

## Conventions
- 함수형 · named export 만 (default export 금지)
- 서버 컴포넌트 기본, 필요 시에만 "use client"

프로젝트 예시 — Go 마이크로서비스

# CLAUDE.md — payments-gateway

## Stack
- Go 1.22 · Gin · sqlx · Postgres 15 · Kafka · testify

## Architecture
- `cmd/server/` — main.go
- `internal/handler/` — HTTP 핸들러
- `internal/service/` — 도메인 로직
- `internal/repo/` — DB · Kafka 어댑터

## Domain Terms
- **Charge** — 카드 결제 시도 1건 (authorized · captured · voided · refunded)
- **Idempotency Key** — 재시도 방지 UUID · 헤더 `Idempotency-Key`

## Commands
- `make run` · `make test` · `golangci-lint run`

## Conventions
- 에러는 `fmt.Errorf("%w", err)` 로 래핑
- `context.Context` 는 모든 요청 경로 첫 인자

로컬 계층 — <repo>/CLAUDE.local.md

로컬은 개인이 이 리포에서만 유지하고 싶은 규약 이다. git 에 커밋되지 않으므로 팀원과 공유되지 않는다.

# CLAUDE.local.md — 개인 규약

## 개인 명령
- alias: `dev` = `make dev` · `t` = `make test -x`

## 개인 서버
- 개인 스테이징: https://staging-$USER.internal.co.kr
- 개인 DB 덤프: `~/dumps/leads-*.sql`

## 실습 규약
- 실험 코드는 `experiments/YYYY-MM-DD/` 아래에

# .gitignore
CLAUDE.local.md
.claude/settings.local.json

PART 3

Memory · @file · /compact vs /clear — 동적 컨텍스트

memory 자동 fact 저장 · @file·@folder·@URL · /compact 와 /clear 의 성격 차이.

memory — 자동 fact 저장

memory 는 CLAUDE.md 와 다른 축이다. CLAUDE.md 가 정적 규약 이라면, memory 는 세션 중 사용자가 명시한 fact 를 자동 저장하는 동적 기억 이다.

> 내 이메일은 me@example.com 이야. 기억해둬.
Claude: 저장했습니다. ~/.claude/projects/.../memory/MEMORY.md 에 추가됨.

> 이 리포의 스테이징은 stg-leads.co.kr 이야.
Claude: 저장했습니다.

> 내 계정 이메일 me@example.com 이야.
Claude: 알겠습니다. (저장 안 됨 · "기억해둬" 명시 문구 없어 이번 세션에만 유지)

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background split into two mirrored halves. Left half labeled 'Short-term Memory' shows a Claude icon at top surrounded by three floating chat message bubbles that fade progressively toward the bottom. A small clock icon and dashed line labeled 'Session ends' cross the bottom, and the fading bubbles suggest disappearance after a session. Right half labeled 'Long-term Memory' shows a stable stack of three document cards: 'CLAUDE.md', 'MEMORY.md', 'notes/*.md'. A ribbon at the top of the right half reads 'Survives sessions' with an arrow pointing to a small silhouette outline of the next session. A vertical accent divider separates the two halves. Clean editorial illustration style — teal #00b894 for the right half (persistent), warm orange #f39c12 fading gradient on the left half (ephemeral), purple #6c5ce7 accents. 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

단기 vs 장기 메모리 — 세션이 끝나면 사라지는 것 vs 남는 것

@file · @folder/ · @URL — 즉시 로드

@ 는 프롬프트 안에서 파일 · 폴더 · URL 을 즉시 로드 하는 문법이다. Claude 가 스스로 파일을 찾는 것보다 명시적 @ 참조가 훨씬 빠르고 정확하다.

@README.md                        # 파일 하나
@src/                             # 폴더 재귀
@https://docs.python.org/3/       # URL 읽기 전용

💡 실전 팁 — @ 뒤 tab 으로 파일명 자동완성.

CLAUDE.md 안에서 @ 임포트 — 파일 얇게 유지

CLAUDE.md 가 커지면 섹션을 문서로 나누고 @ 로 임포트한다.

## Stack        → @docs/stack.md
## Architecture → @docs/architecture.md
## Domain Terms → @docs/domain.md

/compact vs /clear — 성격이 완전히 다르다

컨텍스트 창이 한계에 가까워지면 두 명령 중 하나를 고른다.

체크포인트 · /rewind — 프롬프트 단위 되감기

Accept All 로 편집을 연달아 수락하다 코드가 어긋나는 순간을 대비한 세션 단위 안전장치. 별도 명령 없이 자동으로 쌓인 스냅샷으로 프롬프트 단위 되감기가 된다.

설정 키는 fileCheckpointingEnabled · 기능이 목록에 안 보이면 이 값과 클라이언트 버전을 확인한다.

PART 4

Subagent — 격리된 하위 세션

정의 · 왜 필요한가 · 표준 subagent 3종 · frontmatter 5필드 · 개인 subagent 자작 예시 2종 · 오답 노트.

subagent 정의 · 왜 필요한가

subagent 는 개별 시스템 프롬프트 · 개별 도구 세트 · 개별 모델 로 격리된 하위 세션이다. 메인 세션이 특정 태스크를 위임하면, subagent 는 자기만의 컨텍스트에서 작업을 마치고 결과만 되돌려준다.

subagent = 시스템 프롬프트
         + 허용 도구 세트
         + 사용 모델

🎨 Image Prompt: "Editorial illustration on dark navy #0f1722 background — on the left, a large central node labeled 'Main Session' as a rounded panel with soft glow. Three thin luminous branches fan out to the right to three separate smaller nodes stacked vertically. Top branch reaches a node labeled 'code-reviewer' with two chip labels 'Read' and 'Grep' underneath and a model badge 'Opus'. Middle branch reaches a node labeled 'korean-comment-cleaner' with chips 'Read' and 'Edit' and a model badge 'Haiku'. Bottom branch reaches a node labeled 'explore' with chips 'Read', 'Grep', 'Glob' and a model badge 'Sonnet'. Small return arrows from each subagent back to Main Session carrying tiny 'Result' document icons. Clean editorial style — teal #00b894 and purple #6c5ce7 accents, 16:9. English ONLY, each label EXACTLY ONCE, no mirrored text."

표준 subagent 3종 — 기본 제공

Claude Code 는 몇 개의 표준 subagent 를 기본 제공한다. 자기 subagent 를 만들기 전에 이 표준부터.

// SDK/JSON 레벨 표기 — CLI 사용자는 자연어 or /agents
Task(subagent="explore", prompt="이 리포 아키텍처 3줄 요약")
  → 결과 스니펫: "cmd/server → handler → service → repo. Kafka 이벤트 발행..."
메인 세션이 요약만 받아 계속 진행

개인 subagent — 파일 위치·형태

개인 subagent 는 ~/.claude/agents/*.md 에 마크다운 파일로 정의한다. YAML frontmatter 로 이름·설명·도구·모델을 지정하고 본문에 시스템 프롬프트.

~/.claude/agents/*.md

<repo>/.claude/agents/*.md

frontmatter 필드 — 5개 · 필수는 2개

개인 subagent 예시 ① — security-reviewer

---
name: security-reviewer
description: 보안 관점 코드 리뷰.
  인증·인가·세션·입력 검증 관련
  코드 작성 후 자동 호출.
tools: Read, Grep, Glob
model: opus
---

당신은 보안 코드 리뷰어다.

## 검토 기준
- 인증·인가 우회 · SQL 인젝션 · XSS · CSRF
- 세션 관리 · 토큰 보관 · 시크릿 하드코딩

## 출력 형식
- 심각도 (Critical·High·Medium·Low)
- 파일·라인·재현·수정 제안

## 금지
- 파일 수정·실행 (Read·Grep·Glob 만)

🎨 Image Prompt: "Editorial illustration on dark navy #0f1722 background — two rounded card panels placed side by side and separated by a thin vertical accent divider. Left card carries a shield glyph at the top and a title 'security-reviewer'. Beneath the title, three small chips read 'Read', 'Grep', 'Glob' and one model badge reads 'Opus'. A small padlock icon sits at the bottom of the left card. Right card carries a broom-and-sparkle glyph and a title 'korean-cleaner'. Beneath, three chips read 'Read', 'Edit', 'Grep' and a model badge reads 'Haiku'. A small pencil icon sits at the bottom of the right card. Above the two cards, a single centered caption reads 'Task shapes Tools and Model'. Clean editorial illustration style — teal #00b894 for the left card and purple #6c5ce7 for the right card, 16:9. CRITICAL: All visible text MUST be in English ONLY. Each label appears EXACTLY ONCE. No mirrored text."

개인 subagent 예시 ② — korean-comment-cleaner

---
name: korean-comment-cleaner
description: 파이썬·TS 코드의 한글 주석을
  IT 전문서 문체로 정리.
  리팩토링·문서화 태스크에 자동 호출.
tools: Read, Edit, Grep
model: haiku
---

당신은 한국 IT 전문서 편집자다.

## 정리 규칙
- 번역체 금지 ("본인" · "당신의")
- AI 말투 금지 ("자, 이제")
- 구어체 금지 (강조 부사 남발)
- 단정 · 명사 중심 · 한 문장 1주제

## 작업 흐름
1. 대상 파일 Read
2. 주석만 대상, 코드 로직 변경 금지
3. Edit 으로 한 군데씩 수정
4. 변경 라인 수 보고

# 자, 이제 유저의 입력값을 본인이
# 검증해봅시다. 여기서는 정말 중요한데,
# 당신의 세션 토큰이 만료되었는지 체크.
def validate(user_input, session):
    ...

# 사용자 입력 검증.
# 세션 토큰 만료 여부 확인.
def validate(user_input, session):
    ...

subagent 오답 노트 — 처음 만들면 잘 저지르는 실수 4

PART 5

미니 실습 — 4단계 세팅

글로벌 CLAUDE.md · 프로젝트 CLAUDE.md · 개인 subagent · @file 확인.

실습 1·2 — 글로벌 + 프로젝트 CLAUDE.md

mkdir -p ~/.claude
$EDITOR ~/.claude/CLAUDE.md

cd ~/my-repo
claude
> /init

실습 3·4 — 개인 subagent + @file

mkdir -p ~/.claude/agents
$EDITOR ~/.claude/agents/security-reviewer.md

> /agents
> Task 로 security-reviewer 를 띄워서
  app/auth/ 아래를 리뷰해줘

> @~/.claude/CLAUDE.md 이 파일 요약해줘
> @./CLAUDE.md 이 리포 규약 요약해줘

PART 6

정리 — 컨텍스트 3층 지도·한 문장

세션 전체를 한 장 지도로 요약하고, 축을 한 문장에 담는다.

컨텍스트 3층 지도 — 한 장 요약

┌─────────────────────────────────────────────────┐
│  로컬    <repo>/CLAUDE.local.md                 │  ← 가장 강함
│         (개인 실험 · gitignore)                 │
├─────────────────────────────────────────────────┤
│  프로젝트 <repo>/CLAUDE.md                       │
│         (팀 공유 · 스택 · 도메인 · 관례)         │
├─────────────────────────────────────────────────┤
│  글로벌  ~/.claude/CLAUDE.md                    │  ← 가장 약함
│         (개인 취향 · 30줄 이하)                  │
└─────────────────────────────────────────────────┘

동적:
  memory    자동 fact              /compact  같은 태스크 · 압축
  @file     즉시 로드              /clear    다른 태스크 · 리셋

subagent:
  ~/.claude/agents/*.md         (개인)
  <repo>/.claude/agents/*.md    (팀 공유)

마무리 — 한 문장으로

여기까지 마치면 참여자 노트북에 CLAUDE.md 3계층이 갖춰지고, 개인 subagent 하나가 정의되고, @file · /compact · /clear 를 상황에 맞게 골라 쓸 수 있다.

자기 워크플로에서 세 번 이상 반복하는 지시 가 있으면, 그 지시가 어느 축에 놓일지부터 먼저 정한다.

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background of a clean minimalist workspace scene. In the center, a stylized document labeled 'CLAUDE.md' floats with soft glow. Three thin luminous lines connect from the document outward to three small icons: a folder labeled 'Static', a spinning arrow labeled 'Dynamic', and a small branching node labeled 'Delegate'. A subtle English caption at the bottom reads 'Write the rule once'. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents with warm orange highlights, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."