AI 에이전트 컨텍스트 예산, 세션이 길 때 무엇을 요약하나

AI 에이전트 컨텍스트 요약은 “채팅 전체를 압축한다”가 아니라 다음 턴·다음 세션이 같은 목표를 이어가게 할 최소 상태를 남기는 일입니다. 긴 작업에서는 도구 로그·실패 스택·중간 탐색이 쌓이면서, 목표·결정·미완 항목이 묻히기 쉽습니다. 모델·제품마다 창 크기·자동 요약 동작은 다르므로, 이 글은 숫자(요금·토큰·창 한도)를 가정하지 않고 실무 워크플로만 고정합니다.

다루는 것은 세 가지입니다. 매 턴 남길 최소 정보 · 요약·체크리스트 파일 위치 · 다시 시작할 프롬프트 예시. “컨텍스트가 잘리면 알아서 기억한다”에 기대지 않고, 레포에 읽을 수 있는 progress를 두는 쪽을 기본으로 합니다.

매 턴 남길 최소 정보는?

한 줄 답: 대화 전문이 아니라 목표 한 줄 · 방금 확정된 것 · 다음에 할 한 가지 · 막힌 점 · 건드린 경로입니다. 실험 로그·긴 도구 출력은 요약에 넣지 않습니다.

에이전트에게 “매 의미 있는 단계 끝에 progress를 갱신하라”고 규칙으로 고정하면, 세션이 잘려도 사람·다음 에이전트가 같은 체크리스트를 이어갑니다.

필드	넣을 것	넣지 말 것
Goal	이번 작업의 완료 조건 1–2문장	배경 스토리 전체
Done	이미 검증된 결과(커밋·테스트·파일)	“대충 본 것” 추측
Next	바로 다음 한 스텝만	열린 아이디어 나열
Blocked	재현 한 줄·에러 핵심·대기 중인 사람	전체 스택 덤프
Decisions	되돌리기 비싼 선택(API·분기·범위)	취향 수준의 잡담
Paths	핵심 파일·명령의 경로·이름	시크릿·긴 로그 본문

실무에서 잘 동작하는 최소 템플릿입니다.

# Progress — <ticket-or-topic>

## Goal
- …

## Done
- [x] …
- [ ] … (아직이면 Next로)

## Next (one step)
- …

## Blocked
- … (없으면 "none")

## Decisions
- …

## Paths / commands
- `path/to/file` — why it matters
- `command` — last known good / failing

갱신 타이밍: 파일을 의미 있게 바꾸거나, 테스트가 통과/실패한 직후, 방향을 바꾼 직후. 매 도구 호출마다 쓰지 않습니다. 노이즈가 쌓이면 요약 자체가 컨텍스트를 잡아먹습니다.

버린 정보: 이미 Done에 반영된 탐색 과정, 중복된 실패 로그, “아마 ~일 것” 가설. 가설이 필요하면 Decisions에 채택/기각만 한 줄로 남깁니다.

요약 파일 위치는?

한 줄 답: 채팅 창이 아니라 레포 안, 작업 단위로 찾을 수 있는 한곳에 둡니다. 팀이면 티켓/브랜치와 같은 이름 규칙을 쓰고, 개인이면 워크트리당 하나의 progress면 충분합니다.

위치는 도구보다 검색 가능성이 우선입니다. 에이전트 규칙에 “긴 작업이면 docs/progress/ 또는 티켓 폴더의 PROGRESS.md를 읽고 갱신”이라고 쓰면, 새 세션도 같은 파일을 @로 붙이거나 경로만 주면 됩니다.

위치 패턴	언제 쓰나	주의
`docs/progress/<slug>.md`	여러 날·여러 PR에 걸친 주제	슬러그는 티켓/키워드와 맞춤
`tickets/ABC-123/PROGRESS.md`	이슈 트래커와 1:1	이슈 닫을 때 Done으로 접기
워크트리 루트 `PROGRESS.md`	단기 실험·혼자 쓰는 브랜치	머지 전 삭제 또는 docs로 이동
PR 본문 체크리스트만	변경이 작고 하루 안에 끝남	긴 세션이면 파일로 승격

채팅 전용 메모의 한계: 세션이 바뀌거나 클라이언트가 요약을 바꾸면 사라지거나 변형됩니다. 핸드오프는 파일 + (선택) PR/이슈 링크가 안전합니다.

체크리스트와 요약의 역할 나누기

체크리스트(Done / Next) — 실행 상태. 에이전트가 매 단계 갱신.
짧은 Decisions — “왜 이렇게 했는지”만. 장문 회고 금지.
소스·테스트 — 진실의 원천. progress는 포인터이지 코드 복사본이 아님.

시크릿·토큰·개인 데이터는 progress에도 넣지 않습니다. 경로는 두고 값은 env/시크릿 저장소에 둡니다.

에이전트 규칙 한 줄 예시:

Long tasks: maintain docs/progress/<topic>.md (Goal/Done/Next/Blocked/Decisions/Paths).
Update after each meaningful step. Do not paste secrets or full tool dumps into it.
New chat: read that file first, then continue from Next only.

다시 시작할 프롬프트 예시는?

한 줄 답: 새 채팅에서는 progress 경로를 주고, Goal을 재진술하고, Next 한 스텝만 실행하라고 합니다. “이어서”만 적으면 모델이 옛 가설을 다시 발명하기 쉽습니다.

최소 재시작 프롬프트

Continue from the progress note — do not re-explore from scratch.

1) Read `docs/progress/<slug>.md` (and only the Paths listed there if needed).
2) Restate Goal in one sentence; confirm Done items still hold (quick check).
3) Execute ONLY the current Next step.
4) Update the progress note (Done/Next/Blocked) before stopping.
5) If blocked, stop with a one-line Blocked entry — no speculative refactors.

범위를 조일 때

Same progress file. Scope lock: do not change files outside <dir-or-list>.
Ignore prior chat hypotheses not recorded under Decisions.
Prefer failing test / existing command in Paths over new tooling.

사람 핸드오프용 한 블록

작업 중간에 사람이 넘겨받을 때는 progress의 Goal·Next·Blocked만 복사해도 됩니다. 채팅 스크롤 전체를 넘기지 않습니다.

상황	프롬프트에 넣을 것	빼 둘 것
같은 브랜치·새 채팅	progress 경로 + Next 실행	어제 대화 전문
리뷰 후 재개	Decisions 유지, Next를 리뷰 지적으로 교체	“전부 다시”
막힌 뒤 재개	Blocked 재현 한 줄 + 허용된 조사 범위	무제한 탐색
다른 에이전트/도구	같은 파일 형식 유지	도구별 UI 클릭 경로 발명

성공 기준: 새 세션이 progress만 보고도 같은 Next를 고르고, 불필요한 재탐색 없이 한 스텝을 끝낸 뒤 노트를 갱신하는 것입니다. 창이 얼마나 남았는지·토큰이 얼마인지는 이 글에서 다루지 않습니다. 예산은 남길 정보의 종류로 관리합니다.

마무리

긴 에이전트 세션의 컨텍스트 예산은 요금표가 아니라 상태 설계입니다. 매 턴에는 Goal·Done·Next·Blocked·Decisions·Paths만 남기고, 그 내용은 레포의 progress/체크리스트 파일에 둡니다. 다시 시작할 때는 그 파일을 읽게 한 뒤 Next 한 스텝만 실행하게 합니다. 토큰·창 크기·가격 숫자는 제품·시점에 따라 달라지므로 여기서 가정하지 않습니다.