세 시간 동안 에이전트와 같이 작업하다 노트북을 닫았는데, 다음 날 다시 켜니 에이전트가 “처음 보는 프로젝트”처럼 행동하는 순간이 있습니다. 어제 왜 그 결정을 했는지, 어디까지 진행했는지 전혀 기억하지 못합니다. AI 에이전트의 근본적 한계 중 하나입니다.

결론부터 말하면, PROGRESS.md + 구조적 커밋 메시지 + **세션 핸드오프 프로토콜(CLAUDE.md 규칙)**의 3조합이 가장 실용적이었습니다. claude --continue와 새 세션 중 무엇을 쓸지는 턴 수보다 같은 작업이 이어지는지, 문맥을 다시 찾는 비용이 커졌는지로 결정합니다.

이 글이 답하는 질문

  • AI 에이전트의 메모리는 몇 가지 종류가 있나?
  • PROGRESS.md는 어떤 구조로 써야 다음 세션이 바로 이어갈 수 있나?
  • claude --continue와 새 세션은 언제 각각 써야 하나?

시리즈 안내 — 이 글은 하네스 엔지니어링 시리즈의 6/8입니다. 시리즈를 처음 본다면 1편 — 7축 로드맵 부터 읽으면 전체 흐름이 깔끔하게 잡힙니다.

AI의 근본적 한계: 세션이 끊기면 잊는다

1시간 동안 작업하다 세션이 끊기면, 다음 세션의 에이전트는 “처음 보는 프로젝트”처럼 행동합니다. 어제 왜 그런 결정을 했는지, 어디까지 진행했는지 전혀 모릅니다.

Anthropic은 이걸 긴 작업의 핵심 문제로 지적하면서, progress 파일과 구조화된 핸드오프가 필요하다고 설명합니다(Claude Code Best Practices — Anthropic).

메모리의 4가지 종류

AI 에이전트 메모리 4계층: 세션 내(현재 대화) → 단기(이번 주) → 장기(프로젝트 전체) → 구조적(영구 저장)

종류시간 범위구현 방법예시 정보
세션 내현재 대화자동 (컨텍스트 윈도우)방금 읽은 파일 내용
단기오늘~이번 주PROGRESS.md, —continue”주문 API L120까지 구현, 다음은 결제 연동”
장기프로젝트 전체docs/decisions/, CLAUDE.md”결제는 Stripe 사용 (2026-04 결정)“
구조적영구git log, 파일 시스템 자체feat(auth): JWT 미들웨어 추가 커밋

가장 효과가 큰 건 단기 메모리(PROGRESS.md)입니다. 이게 없으면 매번 “어디까지 했는지” 다시 파악해야 합니다.

PROGRESS.md — 가장 실용적인 메모리 패턴

PROGRESS.md 세션 핸드오프 타임라인 — 세션 종료 시 결정·진행·다음 액션 3줄을 저장하고 다음 세션이 즉시 복구하는 흐름

# PROGRESS.md

## 현재 상태
- [x] 사용자 인증 (JWT) — 완료
- [x] 사용자 CRUD API — 완료
- [ ] 주문 API 엔드포인트 ← 현재 여기
- [ ] 결제 연동 (Stripe)
- [ ] E2E 테스트

## 마지막 세션 (2026-04-02 오후)
- OrderService의 createOrder, getOrder 완료
- 다음: updateOrderStatus 구현
- 막힌 것: state machine 라이브러리 선택 필요

## 알려진 문제
- PostgreSQL 연결 풀 dev 환경 타임아웃
  → DATABASE_POOL_SIZE=5로 해결

## 중요한 결정
- 2026-04-01: 결제는 Stripe 사용 (팀 경험 + 한국 지원)
- 2026-04-02: 주문 상태는 state machine으로
  (이유: 상태 전이 규칙이 복잡)

## 테스트 상태
- 전체: 24 pass, 0 fail, 3 skip

여기서 핵심은 “다음:” 줄입니다. 다음 세션의 에이전트가 읽고 바로 이어갈 수 있어야 합니다. “계속 구현”이 아니라 “src/services/order.ts의 updateOrderStatus 메서드 구현”처럼 파일 경로와 함수명까지 구체적이어야 합니다.

CLI 세션 관리

명령용도적합한 상황
claude --continue마지막 대화를 이어감짧은 이탈 후 복귀
claude --resume "auth"이름 또는 ID로 저장된 세션 재개특정 기능의 작업으로 복귀
claude --resume "auth" --fork-session재개한 대화를 새 session ID로 분기기존 대화를 보존하며 실험
새 세션 + PROGRESS.md명시적 상태 기록으로 시작작업 목표가 바뀌거나 문맥 재구성 비용이 클 때

세션 이름은 대화 안에서 /rename auth로 붙일 수 있습니다. 위 명령은 Claude Code 기준입니다. 새 세션으로 전환할 보편적인 턴 수는 없습니다. 현재 목표·남은 검증을 짧게 정리할 수 있고 이전 대화가 더 이상 필요하지 않을 때 전환합니다.

Git을 메모리로 쓰기

별도 파일 없이도 git 자체가 강력한 메모리입니다. 핵심은 커밋 메시지를 잘 쓰는 것입니다 (Conventional Commits 표준).

# 나쁜 커밋 — 에이전트가 읽어도 모름
fix bug
update code
wip

# 좋은 커밋 — 에이전트가 역사를 파악
feat(auth): JWT 인증 미들웨어 추가

- 모든 /api/* 경로에 인증 필요
- refresh token은 httpOnly 쿠키
- 세션 쿠키 대신 JWT 선택 (stateless)

CLAUDE.md에 커밋 규칙을 넣으면(CLAUDE.md의 규칙 설계 원칙은 (3/8) 지식 구조화 참고) 에이전트에게 일관된 기록 형식을 제공할 수 있습니다. 실제 diff와 commit message를 확인해 기록 누락을 점검합니다.

세션 핸드오프 프로토콜 — 끊길 때 반드시 하는 3가지

CLAUDE.md에 적어도 실행을 보장하지는 않습니다. 종료 시 파일과 테스트 결과를 실제로 확인해야 합니다. 핸드오프 규칙은 (8/8) 검증과 반복의 ‘실패를 기록하라’와 결합하면 더 강력합니다.

## 세션 종료 규칙
- 작업을 끝내기 전에 반드시:
  1. PROGRESS.md에 상태와 남은 검증을 적는다
  2. 승인된 변경만 자기 브랜치에 커밋한다
  3. 테스트 결과와 미완료 작업을 명시한다
- "다음에 할 일"은 파일 경로까지 구체적으로 적는다

PROGRESS.md 업데이트 → 승인 범위의 변경을 커밋 → 현재 상태 확인. 이 3단계가 습관이 되면, “어디까지 했는지 다시 파악하는” 시간이 거의 사라집니다.

세션 재개는 Claude Code CLI reference의 --continue/--resume을 기준으로 확인합니다. 자동 memory와 프로젝트 지시 파일은 역할이 다릅니다. 아래 표는 파일 기반 핸드오프의 관점을 정리한 것이며 도구별 최신 메모리 기능을 빠짐없이 열거한 표는 아닙니다.

도구별 메모리 비교

Claude CodeOpenCodeOpenClaw
세션 이어가기--continue, --resume--continue, --session, --fork세션 라우팅
파일 메모리PROGRESS.md (수동)PROGRESS.md (수동)MEMORY.md + daily memory (자동)
자동 기억auto memory의 MEMORY.md와 명시적 CLAUDE.md를 구분; /memory로 관리설치 버전의 memory/plugin 확인workspace 설정에 따른 일일 기록 로드
구조적git loggit loggit + state 디렉터리

OpenClaw는 memory/YYYY-MM-DD.md 형태로 일일 기록을 자동 관리합니다. 세션 시작 시 최근 며칠의 기록을 자동 로드하므로 PROGRESS.md를 수동으로 업데이트하지 않아도 “어제까지 뭘 했나”가 맥락에 들어갑니다.

이 접근의 트레이드오프는 명확합니다. 자동 로드 = 편리함 vs 수동 기록 = 통제력. 초보자·1인 프로젝트는 자동형, 팀 프로젝트나 재현성이 중요한 연구는 수동 PROGRESS.md가 더 안정적입니다.

Claude Code의 공식 memory 문서는 사용자가 작성하는 CLAUDE.md와 Claude가 기록하는 auto memory를 구분합니다. ~/.claude/CLAUDE.md는 사용자 지시 파일이며 auto memory 저장 파일 자체는 아닙니다. PROGRESS.md는 이름만으로 자동 로드된다고 가정하지 말고 프로젝트 지시 파일에 읽는 시점과 기록 책임을 명시합니다.

흔한 실수

  • PROGRESS.md 안 쓰고 —continue만 의존 → 결정 이유와 다음 검증이 대화에만 남음; 20턴을 공식 성능 임계값으로 삼지 않음
  • “다음에 할 일”을 모호하게 → “계속 구현” 대신 파일 경로까지 구체적으로
  • 깨진 상태로 세션 종료 → 다음 세션이 “수리”부터 시작해야 함
  • “왜”를 안 적음 → 에이전트가 이전 결정을 뒤집으려 함

내가 실제로 부딪힌 문제와 해결 (1인칭 경험)

세션을 끊었다가 다음 날 다시 들어오면, 어제 왜 그 결정을 했는지 스스로도 잠깐 멈칫할 때가 많았습니다. 특히 시리즈 글 순서, 이미지 자산 경로, 사이트맵 처리처럼 작아 보이지만 나중에 다시 봐야 하는 결정은 대화창에만 남겨두면 금방 사라졌습니다. 실제로 블로그 구조를 손보면서도, 어디까지 끝냈고 다음에 무엇을 검증해야 하는지를 따로 적어두지 않으면 같은 점검을 반복하게 됐습니다.

그래서 저는 PROGRESS.md 같은 문서를 거창한 기록이 아니라, 내일의 나와 다음 세션의 에이전트를 위한 짧은 인수인계서로 보게 됐습니다. 파일 경로, 현재 상태, 다음 검증 한 줄만 적어도 맥락 복구 속도가 달라졌습니다. 제 경험상 메모리 패턴의 핵심은 많이 적는 것이 아니라, 다음 판단에 꼭 필요한 고정값을 남기는 것입니다.

자주 묻는 질문 (FAQ)

Q1. claude --continue와 --resume "name"은 언제 각각 쓰나요? --continue는 현재 디렉터리에서 가장 최근 대화를 재개하고, --resume "auth"는 이름이나 ID로 특정 대화를 선택합니다. 새 작업으로 전환할 때는 PROGRESS.md에 상태와 검증을 남긴 뒤 새 세션을 시작할 수 있습니다. 20턴 같은 고정 전환 기준은 없습니다.

Q2. PROGRESS.md를 git에 커밋해야 하나요? 네, 권장합니다. 커밋하면 “이 기능은 언제 어디까지 갔는가”를 git blame으로 추적 가능하고, 팀 핸드오프에도 쓰입니다. 민감 정보가 섞인다면 docs/progress/<기능명>.md로 분할해 민감 파일만 .gitignore.

Q3. CLAUDE.md와 PROGRESS.md의 역할은 어떻게 다른가요? CLAUDE.md는 프로젝트 전역·영구 규칙((3/8) 지식 구조화), PROGRESS.md는 현재 기능 단위·단기 상태입니다. 기능이 끝나면 PROGRESS.md의 “중요한 결정” 섹션만 docs/decisions/로 이관하고 PROGRESS.md 본문은 다음 기능 템플릿으로 갈아끼웁니다.

마무리

  • 메모리는 세션 내 / 단기(PROGRESS.md) / 장기(CLAUDE.md·ADR) / 구조적(git) 4계층입니다.
  • PROGRESS.md는 “다음 세션이 읽고 바로 이어갈 수 있는” 수준으로 구체적이어야 합니다.
  • 같은 작업의 재개에는 --continue/--resume, 목표가 바뀌는 인수인계에는 검증된 PROGRESS.md를 선택합니다.

다음에 읽으면 좋은 글

참고자료