AI 에이전트도 지치고(Token Limit), 인간도 지칩니다(퇴근). 성공적인 프로젝트는 "우리가 어디까지 했더라?"라는 질문을 어떻게 없애느냐에 달려있습니다.
Handoff(교대)란 무엇인가?
Handoff는 특정 작업의 주도권이 AI 에이전트에서 인간 개발자로, 혹은 그 반대로 넘어가는 과정을 의미합니다. 에이전트가 코드를 절반만 짜다가 에러에 막혀 멈췄을 때, 인간이 개입하여 논리적 막힘을 풀어준 뒤 다시 에이전트에게 구현을 맡기는 흐름이 전형적인 Handoff입니다.
1. Agent -> Human (퇴근 전 AI가 남겨야 할 유산)
에이전트에게 어려운 조사나 리팩터링을 시켜놓았지만, 시간이 너무 늦었거나 에이전트가 컨텍스트의 한계에 부딪혔을 때 어떻게 해야 할까요?
AI 세션을 종료(ctrl+c)하기 전에, 에이전트 스스로 현재 상태를 문서화하게 만듭니다.
사용자: "오늘 작업은 여기까지 할게. 내일 아침에 내가(혹은 네가 새로 열린 세션에서) 바로 이어서 작업할 수 있도록
현재까지의 진행 상황, 해결되지 않은 이슈 2가지, 그리고 내일 가장 먼저 해야 할 일 1가지를
프로젝트 루트의 `HANDOFF.md` 파일에 기록해줘."이렇게 하면 터미널 창을 닫아도 에이전트의 "단기 기억"이 파일 시스템에 안전하게 보존됩니다.
2. Human -> Agent (출근 후 AI 깨우기)
다음 날 아침, 인간 개발자가 출근하여 새로운 Gemini 세션을 엽니다. 어제의 에이전트는 이미 메모리에서 사라졌습니다. 하지만 유산이 남아있습니다.
gemini "@HANDOFF.md 이 파일을 읽고 어제 진행 상황을 파악해.
여기에 적힌 '해결되지 않은 이슈 1번'부터 이어서 작업을 진행할 계획을 나에게 말해줘."이 간단한 흐름으로 에이전트는 지난밤의 컨텍스트를 즉시 복원합니다.
3. 마이크로 Handoff: 에러 해결 시
가장 자주 일어나는 Handoff는 에이전트가 특정 에러(예: 설정 파일 권한 문제, 외부 API 서비스 장애)를 스스로 해결하지 못할 때입니다.
이때 AI는 무한 루프에 빠지며 run_shell_command를 반복할 수 있습니다. 즉시 인터럽트(ctrl+c)하고 주도권을 가져오세요.
- 인간의 개입: 인간 개발자가 브라우저를 열어 권한을 수정하거나, AWS 콘솔에서 설정을 변경합니다.
- 명시적 피드백: "내가 AWS 콘솔 들어가서 IAM 권한 수정했어. 이제 S3 접근 가능할 거야. 다시 빌드해봐."
- 에이전트 재시작: 에이전트는 이 피드백을 받아들여 기존의 삽질을 멈추고 다음 단계로 전진합니다.
4. Git을 메모리로 활용하기 (Commit Handoff)
HANDOFF.md보다 더 강력한 메모리는 Git Commit Message입니다.
에이전트에게 특정 단위 작업이 끝날 때마다 상태를 커밋하게 하세요.
"작업을 완료할 때마다 커밋을 남기되, 본문(Body)에 다음 단계에 대한 힌트(예:
Next step: UI 스타일링 필요)를 반드시 적어."
새로운 에이전트는 git log -n 1을 읽는 것만으로도 이전 에이전트의 의도를 완벽히 파악할 수 있습니다.
다음에 읽으면 좋은 글
- 이 모든 과정을 여러 브랜치에서 안전하게 하려면 Gemini Git Worktrees
- 전역적인 컨텍스트를 지배하는 법은 GEMINI.md Mastery