긴 작업 checkpoint, 중단 후 어떻게 이으나
긴 에이전트 작업은 세션이 끊기거나 한도가 차거나, 사람이 탭을 닫거나, 서브에이전트가 끝나도 목표가 남습니다. 그때 대화 스크롤을 다시 읽는 것보다 레포(또는 합의된 작업 디렉터리)에 남긴 checkpoint 파일을 열어 재개하는 편이 안전합니다. checkpoint는 “채팅 백업”이 아니라 다음 턴이 같은 목표·같은 Next를 이어갈 최소 상태입니다.
이 글은 어디에 남기나 · 재개 프롬프트는 · 컨텍스트 유실은만 다룹니다. 매 턴 무엇을 요약할지·progress 템플릿 필드는 agent-context-budget 축이고, opencode의 --continue / --session / /compact 는 opencode-session-resume 축입니다. 여기서는 제품 세션 ID에 의존하지 않는, 파일 기반 중단·재개에 초점을 둡니다. 요금·플랜·토큰 숫자는 없습니다.
어디에 남기나?
한 줄 답: 채팅이 아니라 작업 트리 안의 합의 경로(예: docs/progress/, .agent/, 티켓 ID 파일)에 한 파일로 남깁니다. 시크릿·긴 로그 본문은 넣지 않고, Goal · Done · Next · Blocked · Paths만 고정합니다.
권장 위치(팀에서 하나를 고릅니다):
| 위치 | 언제 | 주의 |
|---|---|---|
docs/progress/<ticket>.md | PR·리뷰와 같이 보이게 할 때 | 머지 전 정리·삭제 규칙이 필요 |
.agent/checkpoint-<slug>.md | IDE/에이전트 전용, 사람 PR에는 안 넣고 싶을 때 | .gitignore 여부 합의 |
| 이슈/티켓 본문 첨부 | 레포 밖 협업이 클 때 | 에이전트가 못 읽으면 경로를 프롬프트에 명시 |
worktree 루트 CHECKPOINT.md | git-worktree-agent로 격리한 작업 | worktree 삭제 전 백업 |
남기는 시점(체크포인트 트리거):
- 의미 있는 파일 변경 직후(생성·수정·삭제 한 묶음이 끝날 때)
- 테스트/빌드가 통과·실패한 직후(명령·결과 한 줄)
- 방향을 바꾼 직후(Decision 한 줄)
- 중단 직전(한도·퇴근·탭 닫기·서브에이전트 핸드오프)
매 도구 호출마다 쓰지 않습니다. 노이즈가 쌓이면 재개 시 오히려 길을 잃습니다.
최소 스키마(복붙용):
# Checkpoint — <ticket-or-slug>
Updated: <ISO date or local stamp>
## Goal
- …
## Done
- [x] …
- [ ] … → Next로 옮길 것
## Next (exactly one)
- …
## Blocked
- none | 재현 한 줄 / 대기 중인 사람·이슈
## Decisions
- …
## Paths / commands
- `path` — why
- `command` — last good / failing
## Do not re-do
- 이미 검증된 우회·폐기한 접근agent-context-budget과의 한 줄 경계: 그 글은 세션이 길 때 매 턴 요약 필드이고, 이 절은 중단 이벤트에 대비해 그 상태를 어디에 고정할지입니다. 필드 이름만 빌려 오고, 파일 경로·트리거·재개 계약이 이 글의 핵심입니다.
재개 프롬프트는?
한 줄 답: 새 채팅(또는 새 세션)에서 checkpoint 경로를 먼저 읽게 하고, Goal·Next만 복창한 뒤 Next 한 스텝만 실행하게 합니다. “이어서 알아서”는 금지에 가깝습니다.
재개 프롬프트 템플릿:
Read `PATH/TO/CHECKPOINT.md` first. Do not scan the whole chat history.
1) Restate Goal and Next in one sentence each.
2) Execute ONLY the Next step. Do not expand scope.
3) After the step (or on block), update the same checkpoint file:
Done / Next / Blocked / Paths.
4) Stop and report: what changed, how to verify, what is still open.실무 규칙:
- 경로를 절대·상대 모두 적기 — worktree·서브디렉터리에서 cwd가 달라지면 상대만으로는 실패합니다.
- “이어서”만 쓰지 않기 — 모델이 이전 채팅을 가정하면 환각이 납니다. 파일이 단일 진실입니다.
- Next가 두 개 이상이면 재개 전에 사람이 하나로 줄이기 — checkpoint가 비대하면 재개 품질이 떨어집니다.
- 서브에이전트 핸드오프 — 부모는 checkpoint 경로 + 성공 기준만 넘기고, 대화 전문을 붙이지 않습니다(subagent-brief 축과 맞물림).
opencode 등 제품 세션 재개와의 한 줄 경계: opencode-session-resume은 같은 도구의 세션 ID로 대화를 붙이는 방법입니다. 세션이 없거나 다른 제품으로 옮길 때는 이 글의 파일 checkpoint + 재개 프롬프트가 필요합니다. 둘을 같이 써도 됩니다(세션 이어쓰기 + 파일 동기화).
컨텍스트 유실은?
한 줄 답: 중단 후 사라지기 쉬운 것은 도구 로그·중간 탐색·미확정 가설이고, checkpoint에 없어도 복구할 수 있는 것은 git 상태·테스트 명령·이슈 링크입니다. 결정·미완 Next·실패 재현이 파일에 없으면 유실로 칩니다.
유실 표:
| 유실되기 쉬운 것 | checkpoint에 남길 것 | 복구 단서 |
|---|---|---|
| 긴 도구 출력·스택 | 에러 한 줄 + 재현 명령 | 로그 파일 경로만 |
| “어디를 열어봤는지” 탐색 | Paths에 핵심 파일만 | git status / diff |
| 채팅 속 합의(“그건 나중에”) | Decisions / Do not re-do | PR·이슈 댓글 |
| 부분 적용된 편집 | Done에 “적용됨/미검증” 구분 | git diff |
| 시크릿·토큰 | 절대 금지 (경로·이름만) | 시크릿 매니저 |
재개 직후 컨텍스트 감사 체크리스트:
[ ] Checkpoint 파일이 열리고 Updated가 최근인가?
[ ] Goal이 티켓/PR과 같은가?
[ ] Next가 하나인가? 두 개면 사람이 줄였는가?
[ ] Blocked가 있으면 사람/이슈 대기인가, 에이전트가 풀 수 있는가?
[ ] Paths의 명령이 그대로 재현되는가? (cwd 확인)
[ ] git status가 Done 주장과 맞는가? (주장만 있고 dirty/clean 불일치면 정정)
[ ] 시크릿·.env 본문이 checkpoint에 없는지?유실이 이미 났을 때: 채팅을 복원하지 말고 (1) git status / git diff / 최근 커밋, (2) 실패 명령을 다시 돌려 재현, (3) Goal을 티켓에서 다시 한 줄로 고정한 뒤 새 checkpoint를 다시 씁니다. “기억나는 대로 이어서”는 두 번째 사고를 만듭니다.
FAQ
agent-context-budget 글과 무엇이 다른가요?
그 글은 긴 세션에서 매 턴 남길 최소 요약 필드·progress 위치입니다. 이 글은 중단·한도·핸드오프 이후 파일로 재개하는 계약(경로·프롬프트·유실 감사)입니다. 템플릿 필드는 겹칠 수 있으나 축이 다릅니다.
opencode-session-resume 글과 무엇이 다른가요?
그 글은 opencode CLI/TUI의 세션 ID·--continue·/compact 입니다. 이 글은 제품에 묶이지 않은 checkpoint 파일입니다. 세션 재개가 되면 편하고, 안 되면 파일이 폴백입니다.
checkpoint를 git에 커밋해야 하나요?
팀 규칙에 따릅니다. 리뷰에 보이게 하려면 docs/progress/에 커밋하고, 로컬만이면 .gitignore된 .agent/를 씁니다. 시크릿이 들어가지 않았는지만 커밋 전에 확인합니다.
에이전트가 checkpoint를 안 갱신하고 끝나면?
재개 프롬프트에 **“스텝 끝·블록 시 같은 파일을 갱신하라”**를 넣고, 사람 게이트에서 파일이 비었으면 Done을 git diff로 채운 뒤 다시 맡깁니다. 빈 파일로 재개하지 않습니다.
출처 (Sources)
- 팀 관행: 작업 트리 checkpoint 파일, 재개 시 경로 우선 읽기, Next 단일 스텝 — 본문 템플릿
- 인접 글 축: agent-context-budget(매 턴 요약 필드), opencode-session-resume(제품 세션 ID), subagent-brief(핸드오프 브리프), git-worktree-agent(격리 트리)