에이전트가 아무것도 잊지 않는다는 것 — 그것이 문제입니다. 세션을 인계 노트로 종료하세요

코딩 에이전트를 이용한 긴 세션은 종종 익숙한 형태를 따릅니다. 첫 한 시간은 매우 집중적입니다. 몇 시간이 지나면 컨텍스트는 막다른 길들로 가득 차게 됩니다. 열었다가 거부한 파일, 시도했다가 포기한 접근 방식, 롤백한 리팩토링 등이 그렇습니다. 에이전트는 여전히 이 모든 것을 컨텍스트에 담고 있지만, 유용한 상태가 오래된 탐색 과정 속에 묻히면서 답변의 질은 떨어지는 경향을 보입니다.

일반적인 해결책들은 투박합니다. /clear는 노이즈와 함께 상태를 모두 버립니다. /compact는 모델 스스로 요약하게 하고, 다음 세션은 그 요약본부터 시작하지만, 이 과정에서 무엇이 빠졌는지는 알 수 없습니다. 처음부터 다시 시작하는 것은 보통 컨텍스트를 손으로 재설명해야 함을 의미합니다.

더 효과적인 작은 습관이 있습니다. 초기화하기 전에, 다음 세션이 실행할 수 있는 형식으로 상태를 기록하는 것입니다.

유용한 인계 노트에 포함되어야 할 내용

전체 대본(transcript)도 아니고, 발생한 모든 것의 요약도 아닙니다. 다섯 가지가 있습니다:

1. 목표 상태 (Goal state) — 무엇을 하려고 했는지, 그리고 얼마나 진행되었는지.
2. 이유를 포함한 결정 (Decisions, with reasons) — 특히 다음 세션에서 재시도하지 않도록 거부했던 접근 방식들.
3. 수정된 파일 목록 (Files touched) — 무엇이 변경되었고, 무엇이 중간에 멈춰 있는지.
4. 열린 루프 (Open loops) — 검증되지 않은 가정, 실패한 테스트, 아직 아무도 답하지 못한 질문들.
5. 다음 행동 (Next action) — 가능성의 목록이 아닌, 구체적인 한 단계.

세션이 끝날 때 이것을 기록하는 것이 다음 세션 시작 시 처음부터 재추론하는 것보다 빠릅니다. 그리고 이 노트가 일반 텍스트(plain text)이기 때문에, '다음 세션'이 다른 에이전트일지, 아니면 다음 주에 진행될지는 상관없이 동일하게 작동합니다.

해결책이 아닌 스킬로 만들기

기억해야 하는 습관은 보통 일주일 정도밖에 지속되지 않습니다. 그래서 저는 이 루틴을 설치 가능한 에이전트 스킬인 Session Handoff Kit (무료, MIT)으로 패키징했습니다.

여기에는 세 개의 파일이 포함되어 있습니다:

• SKILL.md — 스킬 자체입니다. 컨텍스트가 가득 차거나 세션이 종료될 때, 에이전트는 위에서 설명한 5가지 부분 형식으로 구조화된 인계 노트(handoff note)를 생성합니다.
• context-hygiene-checklist.md — 한 페이지 분량의 의사 결정 가이드입니다: 언제 /clear를 할지, 언제 /compact를 할지, 언제 새로 시작할지, 그리고 어떤 초기화(reset) 전에 실행해야 하는 2분 루틴이 포함되어 있습니다.
• handoff-template.md — 스킬 없이 작업할 때 사용할 수 있도록 섹션별 가이드가 담긴 채우기식 템플릿입니다.

스킬 CLI를 사용하여 설치하세요:

npx skills add alapha888/session-handoff-kit

또는 SKILL.md 파일을 에이전트의 스킬 디렉터리 내 session-handoff 폴더로 복사하세요. 이 키트는 Claude Code, Codex, Cursor 스타일의 스킬 설정에서 작동합니다.

키트는 skills.sh에 등록되어 있으며, 소스 코드는 GitHub에 있습니다: alapha888/session-handoff-kit. 피드백과 이슈는 그곳에서 환영합니다.

또한 이 체크리스트를 단독으로 Gist로 읽을 수 있습니다: Context Hygiene Checklist for AI Coding Agents.

핵심은 도구 자체가 아닙니다 — 일반 텍스트 파일로도 충분합니다. 핵심은 작업 순서입니다: 다음 세션이 모든 것을 다시 물어보지 않고 작동할 수 있도록, 리셋하기 전에 상태를 포착하는 것입니다.