짧은 작업은 이런 고민이 필요 없습니다. 실패하면 다시 시키면 됩니다. 문제는 한 시간 넘게 걸리는 작업입니다.

세션은 여러 이유로 끊깁니다. 컨텍스트가 차거나, 실행 환경이 회수되거나, 사람이 중간에 멈추거나, 네트워크가 끊깁니다. 끊기는 것 자체는 막을 수 없습니다. 막아야 할 건 끊겼을 때 진행분이 통째로 사라지는 것입니다.

1. 진짜 문제는 진행 상황이 대화에만 있다는 것

기본 상태에서 "여섯 편까지 끝났다"는 사실은 어디에 있을까요? 대화 기록에만 있습니다. 세션이 끝나면 같이 사라집니다.

더 나쁜 건 작업 결과물도 같이 사라진다는 것입니다. 에이전트가 여섯 편을 다 쓰고 마지막에 한 번 커밋하려 했다면, 다섯 편 반쯤에서 끊길 때 남는 건 아무것도 없습니다.

이렇게 하면 중단 = 전부 손실 1편 작성 → 2편 작성 → ... → 8편 작성 → 커밋 → 푸시 ↑ 여기서 끊기면 0편 이렇게 하면 중단 = 진행분 보존 1편 → 검증 → 커밋+푸시 2편 → 검증 → 커밋+푸시 ... ↑ 여기서 끊겨도 앞의 것은 남는다

원칙은 간단합니다. 완료된 단위는 즉시 영구 저장소에 남긴다. 에이전트 작업에서는 그게 커밋과 푸시입니다.

2. 계획을 먼저 커밋한다

여기서 한 걸음 더 나갑니다. 결과물보다 계획을 먼저 남깁니다.

이 블로그의 예약 게시 글은 에이전트가 회차 단위로 미리 씁니다. 그 에이전트가 가장 먼저 하는 일은 글쓰기가 아니라 .content-queue.md를 만들어 커밋하는 것입니다.

## 회차 2026-08-06 | # | 발행일 | 갈래 | slug | 완료 | |---|---|---|---|---| | 1 | 2026-08-22 | A | eleventy-scheduled-publishing | [x] | | 2 | 2026-08-25 | B | claude-md-agent-rules | [x] | | 3 | 2026-08-27 | C | zone2-cardio-heart-rate-guide | [ ] | | 4 | 2026-08-30 | A | locale-symmetry-build-guard | [ ] |

이 파일이 있으면 다음 세션이 대화 기록 없이도 상태를 복원합니다. 무엇을 하기로 했는지, 어디까지 했는지, 뭐가 남았는지가 전부 저장소 안에 있습니다.

부수 효과도 큽니다. 계획을 먼저 적으면 에이전트가 중간에 주제를 바꾸지 못합니다. 계획 없이 시작하면 6편쯤에서 원래 의도와 다른 글을 쓰고 있는 경우가 생깁니다.

계획은 결과물보다 싸고 먼저 사라집니다.

글 한 편은 다시 쓰면 되지만, "왜 이 여덟 편을 이 순서로 골랐는가"는 다시 만들어내기 어렵습니다. 싸고 사라지기 쉬운 것부터 저장하세요.

3. 커밋 단위 = 작업 항목 단위

커밋을 언제 하느냐가 핵심입니다. 규칙은 하나입니다. 한 항목이 검증을 통과하면 그 자리에서 커밋하고 푸시합니다.

중요한 건 같은 커밋에 결과물과 진행 표시를 함께 넣는 것입니다.

git add src/ko/posts/{slug}.njk \ src/en/posts/{slug}.njk \ .content-queue.md ← 체크박스도 같은 커밋에 git commit -m "feature: ..." git push

따로 커밋하면 둘이 어긋나는 순간이 생깁니다. 글은 커밋됐는데 체크박스는 안 된 상태에서 끊기면, 다음 세션은 그 글을 다시 씁니다. 하나의 커밋이면 그 틈이 없습니다.

푸시도 매번 합니다. 실행 환경이 통째로 회수되는 경우엔 로컬 커밋도 같이 사라지기 때문입니다. 로컬 커밋은 체크포인트가 아닙니다.

4. START와 RESUME을 나눈다

재개를 제대로 하려면 에이전트가 지금이 새 작업인지 이어받는 작업인지 알아야 합니다. 그래서 실행 모드를 명시적으로 나눴습니다.

MODE: START 미완료 회차가 있으면 그것부터 끝낸 뒤 새 회차를 시작한다. 없으면 새 회차를 계획한다. MODE: RESUME 미완료 회차가 없으면 → 아무것도 하지 않고 즉시 종료한다. 있으면 → 그 브랜치를 체크아웃하고 미완료 항목부터 이어서 한다. 이미 완료 표시된 항목은 절대 다시 하지 않는다.

RESUME의 첫 줄이 특히 중요합니다. 할 일이 없으면 아무것도 하지 않고 끝나야 합니다.

이걸 명시하지 않으면 에이전트는 뭔가를 합니다. 빈손으로 끝내는 것보다 일을 만드는 쪽이 도움이 된다고 판단하기 때문입니다. 그래서 아무도 요청하지 않은 회차가 새로 시작됩니다. 자동으로 도는 작업에서는 이게 조용히 반복됩니다.

"할 일이 없으면 즉시 종료한다"는 반드시 명시적으로 적어야 합니다.

이건 에이전트의 기본값이 아닙니다. 무해해 보이는 빈 실행이 몇 번 반복되면 계획에 없던 결과물이 쌓입니다.

5. 완료 판정은 관찰 가능해야 한다

재개가 되려면 "이 항목이 끝났는가"를 대화 기록이 아니라 파일에서 판정할 수 있어야 합니다.

여기서는 두 가지가 서로를 뒷받침합니다.

  • 체크박스 — 큐 파일의 [x]가 1차 근거입니다.
  • 파일 존재 — src/{ko,en}/posts/{slug}.njk가 있으면 실제로 만들어진 겁니다.

둘이 어긋나면 파일 쪽을 믿습니다. 체크박스는 기록이고 파일은 사실이니까요. 어긋나는 경우 자체가 드물긴 합니다 — 같은 커밋에 넣기 때문에요.

이 구조는 멱등성도 줍니다. 같은 세션을 두 번 돌려도 두 번째는 이미 완료된 항목을 건너뜁니다. 자동으로 도는 작업에서는 중복 실행이 반드시 생기니, 이건 선택이 아닙니다.

6. 검증도 항목 단위로

커밋을 항목 단위로 쪼갰으면 검증도 같이 쪼개야 합니다. 여덟 편을 다 쓰고 마지막에 빌드를 돌리면, 실패했을 때 어느 편이 원인인지 찾는 데 시간이 걸립니다. 더 나쁜 건 중단됐을 때 검증 안 된 결과물이 남는다는 것입니다.

1편 작성 → npm run build → 통과 → 커밋+푸시 ↘ 실패 → 고치고 다시 → 통과해야 커밋

규칙은 통과하지 못한 항목은 커밋하지 않는다입니다. 이러면 저장소의 모든 커밋이 빌드가 통과하는 상태고, 어느 지점에서 끊겨도 남은 것은 전부 정상입니다.

이 사이트는 빌드에 검증 가드가 들어 있어서 이게 특히 잘 맞습니다. 검증이 명령 하나로 끝나면 항목마다 돌리는 비용이 거의 없습니다.

7. 규칙 문서에 무엇을 적을까

이 구조를 굴리는 데 필요한 규칙은 생각보다 적습니다. 에이전트 규칙 문서에 적어둔 건 이 정도입니다.

- 계획을 먼저 커밋한다. 결과물보다 계획이 먼저다. - 한 항목이 검증을 통과하면 그 자리에서 커밋하고 푸시한다. 여러 항목을 몰아서 커밋하지 마라. - 같은 커밋에서 큐 파일의 해당 항목을 완료로 표시한다. - 이미 완료 표시된 항목은 절대 다시 하지 않는다. - RESUME 인데 미완료 항목이 없으면 즉시 종료한다.

두 번째 줄의 "몰아서 커밋하지 마라"가 없으면 에이전트는 대체로 몰아서 커밋합니다. 그게 사람 기준으로는 깔끔한 이력이니까요. 하지만 중단을 전제하면 깔끔한 이력보다 잦은 체크포인트가 낫습니다.

8. 정리

결국 오래된 원칙들입니다. 배치 작업에 체크포인트를 두고, 작업 단위를 원자적으로 만들고, 재실행이 안전하게 만드는 것. 에이전트라고 다르지 않습니다.

  • 진행 상황을 저장소에 남긴다. 대화에만 있으면 세션과 함께 사라집니다.
  • 계획을 결과물보다 먼저 커밋한다. 재생성하기 가장 어려운 게 계획입니다.
  • 항목 하나 = 검증 하나 = 커밋 하나 = 푸시 하나. 결과물과 진행 표시는 같은 커밋에.
  • 완료 판정을 파일에서 할 수 있게 한다. 그래야 재실행이 안전합니다.
  • 할 일이 없으면 종료하라고 명시한다. 이건 기본값이 아닙니다.

에이전트에게 긴 작업을 맡기고 있다면, 지금 세션이 끊겼을 때 무엇이 남는지 한번 확인해보세요. 답이 "아무것도"라면 작업 내용보다 그 구조부터 고칠 차례입니다.