Field Log · Entry
[Claude Code] AI 에이전트 메모리 패턴 — PROGRESS.md와 --continue로 세션 이어가기 (6/8)
세 시간 동안 에이전트와 같이 작업하다 노트북을 닫았는데, 다음 날 다시 켜니 에이전트가 “처음 보는 프로젝트”처럼 행동하는 순간이 있습니다. 어제 왜 그 결정을 했는지, 어디까지 진행했는지 전혀 기억하지 못합니다. AI 에이전트의 근본적 한계 중 하나입니다.
결론부터 말하면, PROGRESS.md + 구조적 커밋 메시지 + **세션 핸드오프 프로토콜(CLAUDE.md 규칙)**의 3조합이 가장 실용적이었습니다. claude --continue는 짧은 이탈에만, 20턴 이상의 세션은 새 세션 + PROGRESS.md가 더 안정적입니다.
이 글이 답하는 질문
- AI 에이전트의 메모리는 몇 가지 종류가 있나?
- PROGRESS.md는 어떤 구조로 써야 다음 세션이 바로 이어갈 수 있나?
claude --continue와 새 세션은 언제 각각 써야 하나?
AI의 근본적 한계: 세션이 끊기면 잊는다
1시간 동안 작업하다 세션이 끊기면, 다음 세션의 에이전트는 “처음 보는 프로젝트”처럼 행동합니다. 어제 왜 그런 결정을 했는지, 어디까지 진행했는지 전혀 모릅니다.
Anthropic은 이걸 긴 작업의 핵심 문제로 지적하면서, progress 파일과 구조화된 핸드오프가 필요하다고 설명합니다(Claude Code Best Practices — Anthropic).
메모리의 4가지 종류
| 종류 | 시간 범위 | 구현 방법 | 예시 정보 |
|---|---|---|---|
| 세션 내 | 현재 대화 | 자동 (컨텍스트 윈도우) | 방금 읽은 파일 내용 |
| 단기 | 오늘~이번 주 | PROGRESS.md, —continue | ”주문 API L120까지 구현, 다음은 결제 연동” |
| 장기 | 프로젝트 전체 | docs/decisions/, CLAUDE.md | ”결제는 Stripe 사용 (2026-04 결정)“ |
| 구조적 | 영구 | git log, 파일 시스템 자체 | feat(auth): JWT 미들웨어 추가 커밋 |
가장 효과가 큰 건 단기 메모리(PROGRESS.md)입니다. 이게 없으면 매번 “어디까지 했는지” 다시 파악해야 합니다.
PROGRESS.md — 가장 실용적인 메모리 패턴
# 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 --session "auth" | 이름 붙인 세션 | 여러 기능 동시 개발 |
claude --fork "auth" | 세션 복제 후 분기 | 실험적 시도 |
| 새 세션 + PROGRESS.md | 깨끗한 시작 | 대화 20턴 이상일 때 |
실무 팁: 대화가 20턴 이상이면 --continue보다 새 세션 + PROGRESS.md가 더 안정적입니다. --continue는 편하지만 대화가 쌓이면 컨텍스트가 무거워집니다.
Git을 메모리로 쓰기
별도 파일 없이도 git 자체가 강력한 메모리입니다. 핵심은 커밋 메시지를 잘 쓰는 것입니다 (Conventional Commits 표준).
# 나쁜 커밋 — 에이전트가 읽어도 모름
fix bug
update code
wip
# 좋은 커밋 — 에이전트가 역사를 파악
feat(auth): JWT 인증 미들웨어 추가
- 모든 /api/* 경로에 인증 필요
- refresh token은 httpOnly 쿠키
- 세션 쿠키 대신 JWT 선택 (stateless)CLAUDE.md에 커밋 규칙을 넣으면(CLAUDE.md의 규칙 설계 원칙은 (3/8) 지식 구조화 참고) 에이전트가 매번 이 형식으로 커밋합니다. 자동으로 구조적 메모리가 쌓이는 셈입니다.
세션 핸드오프 프로토콜 — 끊길 때 반드시 하는 3가지
CLAUDE.md에 넣어두면 에이전트가 자동으로 따릅니다. 핸드오프 규칙은 (8/8) 검증과 반복의 ‘실패를 기록하라’와 결합하면 더 강력합니다.
## 세션 종료 규칙
- 작업을 끝내기 전에 반드시:
1. 변경사항을 커밋한다 (wip 커밋도 OK)
2. PROGRESS.md를 업데이트한다
3. 테스트가 통과하는 상태를 유지한다
- "다음에 할 일"은 파일 경로까지 구체적으로 적는다커밋 → PROGRESS.md 업데이트 → 깨끗한 상태 확인. 이 3단계가 습관이 되면, “어디까지 했는지 다시 파악하는” 시간이 거의 사라집니다.
도구별 메모리 비교
| Claude Code | OpenCode | OpenClaw | |
|---|---|---|---|
| 세션 이어가기 | --continue, --session | --continue, --session, --fork | 세션 라우팅 |
| 파일 메모리 | PROGRESS.md (수동) | PROGRESS.md (수동) | MEMORY.md + daily memory (자동) |
| 자동 기억 | ~/.claude/CLAUDE.md 자동 로드, /memory 명령 | — | memory/YYYY-MM-DD.md 최근 기록 자동 로드 |
| 구조적 | git log | git log | git + state 디렉터리 |
OpenClaw는 memory/YYYY-MM-DD.md 형태로 일일 기록을 자동 관리합니다. 세션 시작 시 최근 며칠의 기록을 자동 로드하므로 PROGRESS.md를 수동으로 업데이트하지 않아도 “어제까지 뭘 했나”가 맥락에 들어갑니다.
이 접근의 트레이드오프는 명확합니다. 자동 로드 = 편리함 vs 수동 기록 = 통제력. 초보자·1인 프로젝트는 자동형, 팀 프로젝트나 재현성이 중요한 연구는 수동 PROGRESS.md가 더 안정적입니다.
Claude Code는 두 접근을 혼합 가능합니다. ~/.claude/CLAUDE.md에 auto memory 관련 선호를 써두면 사용자 전역 메모리로 로드되고, 프로젝트별 .claude/CLAUDE.md에 PROGRESS.md 규칙을 두면 세션 단위로 관리됩니다.
흔한 실수
- PROGRESS.md 안 쓰고 —continue만 의존 → 20턴 넘으면 성능 저하
- “다음에 할 일”을 모호하게 → “계속 구현” 대신 파일 경로까지 구체적으로
- 깨진 상태로 세션 종료 → 다음 세션이 “수리”부터 시작해야 함
- “왜”를 안 적음 → 에이전트가 이전 결정을 뒤집으려 함
내가 실제로 부딪힌 문제와 해결 (1인칭 경험)
세션을 끊었다가 다음 날 다시 들어오면, 어제 왜 그 결정을 했는지 스스로도 잠깐 멈칫할 때가 많았습니다. 특히 시리즈 글 순서, 이미지 자산 경로, 사이트맵 처리처럼 작아 보이지만 나중에 다시 봐야 하는 결정은 대화창에만 남겨두면 금방 사라졌습니다. 실제로 블로그 구조를 손보면서도, 어디까지 끝냈고 다음에 무엇을 검증해야 하는지를 따로 적어두지 않으면 같은 점검을 반복하게 됐습니다.
그래서 저는 PROGRESS.md 같은 문서를 거창한 기록이 아니라, 내일의 나와 다음 세션의 에이전트를 위한 짧은 인수인계서로 보게 됐습니다. 파일 경로, 현재 상태, 다음 검증 한 줄만 적어도 맥락 복구 속도가 달라졌습니다. 제 경험상 메모리 패턴의 핵심은 많이 적는 것이 아니라, 다음 판단에 꼭 필요한 고정값을 남기는 것입니다.
자주 묻는 질문 (FAQ)
Q1. claude --continue와 --session "name"은 언제 각각 쓰나요?
--continue는 마지막 대화 그대로 이어가는 “짧은 이탈 후 복귀”용입니다. --session "auth"는 이름 붙인 독립 세션을 유지합니다. 여러 기능을 동시에 개발 중이면 세션 이름을 분리하는 편이 컨텍스트가 덜 오염됩니다. 20턴 이상 대화가 쌓였다면 둘 다 말고 새 세션 + PROGRESS.md가 더 안정적입니다.
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는 “다음 세션이 읽고 바로 이어갈 수 있는” 수준으로 구체적이어야 합니다.
- 20턴 넘으면
--continue대신 새 세션 + PROGRESS.md를 쓰는 편이 더 안정적입니다.
다음에 읽으면 좋은 글
- (3/8) CLAUDE.md 작성 가이드 — 영구 규칙 문서 설계
- (7/8) Subagent 역할 분리 — 세션 분할 후 역할 분리
- (8/8) 검증과 반복 — 실패 로그로 메모리 강화