클로드 코드 - 실전

1. 컨텍스트 관리

1-1. 두 개의 기억 — CLAUDE.md와 자동 메모리(/memory)

Claude Code에는 세션을 넘어 지식을 유지하는 두 가지 기억 시스템이 있다.

	CLAUDE.md	자동 메모리 (Auto Memory)
작성 주체	내가 쓴다	Claude가 스스로 쓴다
담는 내용	지시와 규칙	학습한 패턴, 인사이트
공유 범위	레포에 커밋해 팀 공유	내 머신에만 (개인)
용도	컨벤션, 아키텍처, 워크플로우	빌드 명령, 디버깅 교훈, 내 취향

자동 메모리는 기본으로 켜져 있고, Claude가 작업하면서 "다음 세션에도 유용하겠다" 싶은 것을 알아서 기록한다. 동작 방식은 다음과 같다.

• 저장 위치: ~/.claude/projects/<프로젝트>/memory/ — MEMORY.md(인덱스) + 토픽별 파일(debugging.md 등)
• 매 세션 시작 시 MEMORY.md의 처음 200줄(또는 25KB)만 자동 로드되고, 토픽 파일은 필요할 때만 읽습니다
• "기억해줘"라고 말하면 자동 메모리에 저장됩니다 (예: "우리 npm 말고 pnpm 쓰는 거 기억해")
• /memory 명령으로 저장된 내용을 확인·편집하고, 자동 메모리를 켜고 끌 수 있습니다

여기에 더해, 프로젝트에서 배운 것들을 날짜 기반 결정 기록(decision log)으로 직접 남기는 습관도 강력합니다. 프로젝트의 기관 기억(institutional memory)이 됩니다.

## 2024-01-15: 인증 방식 변경
- JWT에서 세션 기반으로 변경
- 이유: 모바일 앱에서 토큰 리프레시 이슈
- 참고: auth/session.ts

1-2. Lazy Loading 제대로 이해하기 ⚠️

CLAUDE.md에 모든 정보를 때려 넣으면 매 세션마다 수천 토큰이 낭비된다. 그래서 "상세 내용은 분리하고 참조만 남기자"는 전략이 나온다.

# ❌ 흔한 오해 — 이건 lazy loading이 아님
## 프로젝트 문서
- API 스펙: @docs/api-spec.md
- DB 스키마: @docs/db-schema.md

@경로 문법은 임포트(import)입니다. 공식 문서가 명시하듯, 임포트된 파일은 세션 시작 시 CLAUDE.md와 함께 전부 로드된다. 파일을 쪼개서 정리 정돈은 되지만, 토큰은 하나도 절약되지 않는다!

진짜 lazy loading을 하는 방법은 세 가지이다.

① 경로를 백틱으로 감싸서 "언급"만 하기

# ✅ 필요할 때만 읽게 하기
## 프로젝트 문서 (필요 시 참고)
- API 스펙: `docs/api-spec.md`
- DB 스키마: `docs/db-schema.md`

백틱(코드 스팬) 안의 @는 임포트로 처리되지 않으므로, 이렇게 쓰면 Claude가 관련 작업을 할 때만 해당 파일을 읽습니다. 임포트할 파일과 언급만 할 파일을 의도적으로 구분하세요.

② 폴더별 CLAUDE.md

src/auth/CLAUDE.md, src/payments/CLAUDE.md처럼 하위 폴더에 두면, 공식 동작상 Claude가 그 폴더의 파일을 읽을 때만 로드됩니다. 도메인별 상세 규칙을 두기에 최적입니다.

③ 경로 스코프 규칙 — .claude/rules/

가장 구조적인 방법 .claude/rules/ 폴더에 주제별 .md 파일을 두고, frontmatter의 paths로 적용 범위를 지정하면 매칭되는 파일을 다룰 때만 규칙이 로드됩니다.

---
paths:
  - "src/api/**/*.ts"
---
# API 개발 규칙
- 모든 엔드포인트에 입력 검증 필수
- 표준 에러 응답 포맷 사용

정리하면: 항상 필요한 규칙은 CLAUDE.md 본문 또는 @임포트, 가끔 필요한 상세 문서는 백틱 경로 언급 / 폴더별 CLAUDE.md / paths 스코프 규칙. 이 구분이 컨텍스트 다이어트의 핵심이다.

참고로 최신 버전의 /doctor는 CLAUDE.md에서 잘라낼 내용(Claude가 코드베이스에서 스스로 파악 가능한 디렉토리 구조, 의존성 목록 등)을 제안해 준다.

1-3. 컨텍스트 윈도우 관리 — 한 세션 = 한 피처

핵심 원칙: 한 세션 = 한 피처.
하나의 세션에서 여러 기능을 연달아 구현하지 말자!

실전 워크플로우는 다음 4단계의 반복이다!

1. Plan Mode에서 전체 작업을 설계하고 단계를 나눈다
2. /clear 또는 새 세션을 연다
3. 플랜의 첫 번째 단계만 구현한다
4. 완료되면 다시 /clear → 다음 단계로

명령어	역할
/clear	컨텍스트 완전 초기화 (작업이 바뀔 때)
/compact	대화 압축, 맥락 유지 (같은 작업을 이어갈 때)

/compact에 대한 안심 포인트 하나: 프로젝트 루트의 CLAUDE.md는 압축 후에도 디스크에서 다시 읽혀 재주입된다.

1-4. MCP 토큰 모니터링

MCP를 여러 개 연결하면 실제로 쓰지 않아도 도구 설명(tool description)만으로 토큰을 크게 소비한다.

1-5. Mermaid로 아키텍처 정리

아키텍처를 Mermaid 다이어그램으로 정리해 두면 Claude가 프로젝트 구조를 텍스트보다 훨씬 빠르게 파악합니다.

graph LR
    A[클라이언트] --> B[API 게이트웨이]
    B --> C[인증 서비스]
    B --> D[주문 서비스]
    D --> E[결제 서비스]
    D --> F[재고 서비스]

별도 파일(docs/architecture.md)에 정리하되, 로드 전략은 1-2의 원칙대로 선택. 다이어그램이 작고 매 세션 필요하면 @docs/architecture.md로 임포트(상시 로드), 크고 가끔 필요하면 백틱 경로 언급(온디맨드)이 맞다!

---

2. 워크플로우 & 코딩 철학

2-1. Plan Mode 먼저

큰 변경 작업은 반드시 Plan Mode(Shift+Tab)로 시작

1. Plan Mode에서 Claude에게 작업을 설명한다
2. Claude가 계획을 제시한다 — 어떤 파일을 어떻게 수정할지
3. 계획을 리뷰하고 피드백한다
4. 만족하면 실행 모드로 전환한다

Plan 없이 바로 실행하면 Claude가 엉뚱한 방향으로 코드를 대량 수정해버리는 참사가 벌어질 수 있다.

2-2. 작게 바꾸고 자주 커밋 — TDD 기반 루프

핵심 루프: 작은 변경 → 테스트 → 린트 → 커밋 → 반복

1. 기능 하나 추가
2. 테스트 돌려서 확인
3. 린트/포맷 체크
4. 문제 없으면 커밋
5. 다음 기능으로

이렇게 하면 문제가 생겨도 마지막 커밋으로 돌아가면 되니 디버깅이 훨씬 쉽다. 여기에 1편에서 소개한 되감기(Esc×2 → rewind)를 더하면 이중 안전망이 된다.

2-3. Thinking 로그 읽기

Claude가 생각하는 과정을 보여주는 thinking 로그를 무시하지 않는다. 잘못된 가정을 하고 있다면 그 순간 Esc로 중단해야 한다. 잘못된 가정 위에 쌓인 코드는 전부 쓸모없어지므로, 초반에 잡는 것이 핵심이다. Esc로 멈춰도 그때까지의 작업물은 유지되니 부담 없이 끊고 방향을 교정하자.

실전 워크플로우:

1. 하루 시작 — 할 일을 TODO.md에 체크리스트로 작성
2. Claude에게 "TODO.md 읽고 첫 번째 항목부터 시작해" 지시
3. Agent Teams / 서브에이전트로 독립적인 태스크를 병렬 처리
4. 세션 종료 시 "TODO.md 업데이트해줘" → 진행 상황 자동 반영

"한 세션 = 한 피처" 원칙(1-3) 때문에 세션을 자주 초기화하게 되는데, TODO.md가 세션 간 작업의 연속성을 이어주는 다리 역할을 한다. 자동 메모리가 "Claude의 학습 노트"라면 TODO.md는 "명시적 작업 큐"이다.

2-4. WAT 프레임워크 — 복잡한 프로젝트 관리 방법론

유튜버 Nate Herk가 제안한 프레임워크로, 복잡한 프로젝트를 AI 에이전트와 함께 안정적으로 굴리는 사고 틀이다.

구성 요소	의미	핵심
Workflows	작업 흐름 정의	plain English로 단계를 명확히 정의
Agents	AI 에이전트 활용	Self-healing + 서브에이전트 병렬 처리
Tools	도구 조합	작고 원자적인 도구들을 조합

W — Workflows: 10분 투자로 수 시간의 삽질을 줄인다

코드를 쓰기 전에 작업 흐름을 글로 먼저 정의하세요. Plan Mode(2-1)와 자연스럽게 연결됩니다.

1. DB 스키마에 due_date, notification_sent 컬럼 추가
2. 마감일 설정 UI 컴포넌트 구현
3. 크론잡으로 마감 24시간 전 알림 발송 로직 작성
4. 알림 발송 후 notification_sent 플래그 업데이트
5. 각 단계마다 테스트 작성 후 통과 확인

A — Agents: Self-Healing이 핵심

Claude Code는 에러가 나면 스스로 로그를 읽고, 원인을 파악하고, 코드를 수정하고, 다시 실행합니다. 여기에 서브에이전트로 역할을 분리하면 병렬 처리가 가능해집니다.

• 서브에이전트 A → 테스트 작성 및 실행
• 서브에이전트 B → 관련 문서 업데이트
• 서브에이전트 C → 코드 린트 및 타입 체크

하나의 Claude가 순차적으로 10분 걸릴 작업을, 3개의 서브에이전트가 동시에 돌리면 3~4분 수준으로 줄어듭니다.

T — Tools: 작은 도구가 큰 도구를 이긴다

Tool Atomicity(도구의 원자성) — 하나의 거대한 스크립트보다 작은 단위의 스크립트 여러 개가 훨씬 낫습니다. Claude가 조합하고 디버깅하기 쉬워지기 때문입니다.

# ❌ 나쁜 예: deploy-all.sh (200줄짜리 괴물)
# ✅ 좋은 예: 원자적 도구들의 조합
scripts/build.sh        # 빌드만
scripts/test.sh         # 테스트만
scripts/migrate.sh      # DB 마이그레이션만
scripts/deploy.sh       # 배포만
scripts/notify.sh       # 알림만

실전 도구의 세 축은 Bash 스크립트(반복 작업), MCP 서버(외부 API 연동), Hooks(커밋·저장 시 자동 린트/테스트)이다.

종합 예시 — "블로그에 댓글 기능 추가"를 WAT로 풀면:

• W: "댓글 기능을 추가해줘. ① comments 테이블 설계·마이그레이션 ② CRUD API 구현 ③ 프론트 컴포넌트 구현 ④ 단계마다 테스트 통과 확인" — 순서를 명시한 워크플로우로 지시
• A: Claude가 코디네이터로서 서브에이전트에 작업 분배. API 구현 중 다른 에이전트가 테스트를 미리 설계하고, 에러 시 self-healing으로 복구
• T: scripts/migrate.sh로 마이그레이션, MCP로 GitHub PR 생성, Hooks로 커밋마다 테스트 자동 실행

핵심은 AI의 추론과 실행의 분리입니다. Claude에게 생각하게 하고 실행은 별도 도구에 맡기면, 복잡한 워크플로우도 안정적으로 관리됩니다.