AI 코딩 에이전트 실전 (1/5) — Claude Code 워크플로우: CLAUDE.md·스킬·메모리·세션 복원

-
AI 코딩 에이전트 실전 (1/5) — Claude Code 워크플로우: CLAUDE.md·스킬·메모리·세션 복원

같은 모델로도 워크플로우 설계가 결과를 가른다. Claude Code의 4가지 핵심 구성요소를 실전 패턴으로 정리한다.

핵심 요약

  • 다루는 4가지: CLAUDE.md (정체성) / 스킬 (작업 모듈) / 메모리 (세션 간 지속성) / 세션 복원
  • 1차 자료: Anthropic Claude Code 공식 docs (code.claude.com)
  • 핵심 원리: "에이전트는 모델 + 그 위에 올라가는 모든 것"이고, 그 모든 것을 어떻게 짜는지가 곧 워크플로우다
  • 결과: 같은 작업도 워크플로우가 잘 짜이면 토큰 비용·재시도 횟수·디버깅 비용이 모두 줄어든다

1. 왜 워크플로우 설계가 모델보다 중요해졌는가

코딩 에이전트가 처음 등장했을 때는 "더 강한 모델"이 답이었다. 2026년 시점에는 같은 Sonnet 4.6 / Opus 4.7로도 워크플로우에 따라 결과가 크게 갈린다. 모델은 강해진 만큼 정확한 컨텍스트를 요구한다. 컨텍스트가 부정확하면 강한 모델일수록 더 자신 있게 잘못된 답을 내놓는다.

Claude Code는 워크플로우 설계를 위한 4가지 구성요소를 제공한다. 이 글은 각각의 원리와 실전 패턴을 정리한다.

2. CLAUDE.md — 에이전트의 정체성

역할. 프로젝트 루트에 두는 마크다운 파일. 에이전트가 모든 세션 시작 시 자동으로 읽는다. "이 프로젝트가 무엇이고, 어떤 규칙으로 일하는가"를 한 번에 전달.

작성 원칙. - Read First 섹션: 추가로 읽어야 하는 핵심 문서 경로를 명시한다. 에이전트가 컨텍스트를 빠르게 흡수하도록 안내한다. - Hard Rules: "절대 하지 말아야 할 것"을 명문화한다 — 외부 발행, 자격 정보 수정, 광범위 재작성 등. - Workflow: 작업 규모별 진입 패턴 ("3+ step → brainstorming → writing-plans → 실행 → verification") 같은 룰을 적는다. - Scope/Surface: 디렉터리 구조와 각 디렉터리의 책임을 정리한다.

자주 하는 실수. - 너무 길게 쓴다. CLAUDE.md는 항상 컨텍스트에 들어가는 비용이 든다. 핵심만 간결하게. - "이 프로젝트는 무엇을 하는가"를 빼먹는다. 에이전트가 첫 세션에서 가장 먼저 알아야 할 것이다. - 변경이 잦은 정보를 넣는다. 자주 바뀌는 것은 별도 docs/ 파일로 빼고 CLAUDE.md에서 링크만 한다.

검증. "다음 세션을 시작했을 때 이 CLAUDE.md만 읽고도 에이전트가 이 프로젝트의 규칙을 따를 수 있는가"를 자문해 본다.

3. 스킬 — 작업 단위 모듈화

역할. .claude/skills/<skill-name>/SKILL.md 파일에 정의되는 재사용 가능한 작업 패키지. 하나의 스킬은 하나의 작업 종류에 대응한다 (예: publish, verify, git-commit, compile).

언제 스킬로 빼는가. - 같은 종류의 작업을 반복적으로 한다. (블로그 발행, 커밋, 회의록 정리 등) - 작업이 여러 단계로 나뉜다. (입력 검증 → 처리 → 출력 → 보고) - 팀이 공유해야 하는 절차다.

작성 원칙. - 트리거 명시: "이 키워드를 사용자가 말하면 스킬을 호출하라"는 트리거 단어를 명확히 한다. - 단계 구조: 입력 → 검증 → 처리 → 출력 → 보고를 차례로 적는다. - Hard rules: 이 스킬에서 절대 하지 말아야 할 것 (예: "사용자 컨펌 없이 발행 금지"). - 출력 형식: 결과를 사용자에게 어떤 형태로 전달할지 (마크다운 표, JSON, 디스코드 메시지 등).

중복 방지. 비슷한 스킬이 둘 이상이면 통합한다. 스킬이 많아지면 에이전트가 어떤 것을 골라야 할지 헷갈린다. 5~15개 정도가 운영하기 편한 범위.

4. 메모리 — 세션 간 지속성

역할. 한 세션이 끝나도 다음 세션에서 다시 활용해야 하는 정보를 저장하는 영역. Claude Code의 메모리 시스템은 보통 3계층으로 운영된다:

  • 사용자 프로필 (memory/user_profile.md, feedback_*.md): 사용자의 역할·선호·과거 피드백.
  • 프로젝트 메모리 (memory/project_*.md): 진행 중인 결정·이정표·외부 시스템 ID.
  • 레퍼런스 (memory/reference_*.md): 외부 시스템 정보의 위치(예: Linear 프로젝트 키, Grafana 대시보드 URL).

저장 vs 저장하지 않을 것. - 저장: 사용자가 명시적으로 요청한 규칙, 잘못된 접근에 대한 교정, 비-자명한 결정의 이유, 외부 시스템 좌표. - 저장하지 않음: 코드에서 도출 가능한 사실, git log로 충분한 변경 이력, 일회성 작업 디테일, 이미 CLAUDE.md에 있는 내용.

MEMORY.md 인덱스. 모든 메모리는 MEMORY.md라는 인덱스 파일을 통해 진입한다. 인덱스는 항상 컨텍스트에 로드되므로 짧고 스캔 가능해야 한다. 줄당 150자 미만, 200줄 미만 권장.

유효성 검증. 메모리는 시간이 지나면 낡는다. 추천하기 전에 현재 코드/시스템 상태를 한 번 더 확인하는 것을 룰화한다.

5. 세션 복원 — 안전한 재개

문제. Claude Code 세션은 컨텍스트 한도, 사용자 종료, 시스템 재시작 등으로 종료된다. 어디까지 했는가를 잃지 않고 다음 세션에서 그 지점부터 이어 받는 메커니즘이 필요하다.

3가지 영구 저장소. - tasks/plan.md: 현재 마일스톤·완료된 항목·다음 행동. 세션 시작 시 가장 먼저 읽는 단일 진입점. - tasks/lessons.md: "잘 됐던 것 / 안 됐던 것 / 그 이유" 표. 다음 세션에서 같은 실수를 피한다. - tasks/sessions/YYYYMMDD-HHMMSS.md: 한 세션의 스냅샷. 세션 종료 시 변경 파일·의사결정·다음 단계를 적는다.

세션 시작 훅. Claude Code는 SessionStart 훅으로 위 3개를 자동 주입할 수 있다. 결과적으로 새 세션 = 이전 컨텍스트가 이미 보강된 상태에서 시작하는 것과 같다.

복원 시 주의. - "이전 세션에서 만들었다고 주장하는 파일·기능"이 실제로 존재하는지 확인한다. 메모리는 시점 관찰일 뿐. - 오래 멈춘 작업은 외부 상태(브랜치, 의존성, 데이터)가 바뀌어 있을 수 있다. 이어 받기 전에 git status / 의존성 확인을 한 번 돌린다.

6. 통합 워크플로우 — 실제 패턴

위 4가지가 어떻게 결합되는지를 한 사이클로 보면 다음과 같다:

  1. 사용자 요청 → 에이전트가 트리거 키워드를 인식해 Skill을 호출
  2. Skill 진입 → CLAUDE.md의 룰 + 메모리 + 현재 상태를 확인
  3. 3+ step 작업이면 → brainstorming → writing-plans → execution → verification 게이트를 통과
  4. 세션 종료 → 변경 파일 + 결정 + 다음 단계를 tasks/sessions/에 기록
  5. 다음 세션 시작 → 자동으로 plan.md / lessons.md / 최신 session.md 주입 → 즉시 이어 작업

이 사이클이 잘 돌아가는가의 신호. - 같은 질문을 두 번 받지 않는다 (메모리가 작동한다는 증거). - "이전 세션에서 어디까지 했지?"를 사용자가 묻지 않는다 (세션 복원이 작동한다는 증거). - 사용자 컨펌 없이 외부 발행/파괴적 변경이 일어나지 않는다 (Hard Rules가 작동한다는 증거).

7. 한눈에 정리

구성요소 위치 핵심 1줄 흔한 실수
CLAUDE.md 프로젝트 루트 정체성 + Hard Rules + Workflow 너무 길다 / 변경 잦은 정보 포함
스킬 .claude/skills/<name>/SKILL.md 작업 단위 모듈, 트리거 + 단계 + 출력 너무 많이 만들어 충돌
메모리 memory/MEMORY.md 인덱스 + 개별 파일 세션 간 비-자명한 정보만 코드에서 도출 가능한 사실 저장
세션 복원 tasks/plan.md + lessons.md + sessions/ 다음 세션이 어디서 이어 받을지 파일 존재만 믿고 검증 안 함

다음 편

다음 편(2/5)은 Cursor 3 vs Claude Code vs GitHub Copilot 2026-05 실측 비교다. 같은 코딩 에이전트 카테고리지만 디자인 철학이 다른 세 도구를 가격·기능·실제 워크플로우 측면에서 정렬한다.

참고 자료

  • Anthropic, Claude Code Documentation. code.claude.com (2026-05-05 확인).
  • Anthropic, Hooks and Skills Reference. code.claude.com/docs/hooks (2026-05-05 확인).
  • 시리즈 4편(하네스 엔지니어링이란) 1차 자료가 워크플로우 설계의 이론적 배경을 제공한다.

이 글은 AI 코딩 에이전트 실전 시리즈의 1/5 편입니다.

댓글

댓글 쓰기