코딩 에이전트 핸드오프 템플릿: 역할, 상태, 리뷰 게이트

코딩 에이전트가 작업을 끝낼 때마다 똑같은 공백이 생긴다. diff와 "완료했습니다"라는 반가운 말은 받지만, 무엇이 바뀌었는지, 무엇이 빠졌는지, 무엇이 테스트되었는지, 에이전트가 아직 확신하지 못하는 부분이 무엇인지는 알 수 없다. 그래서 diff를 다시 읽고, 테스트를 직접 다시 돌리고, 에이전트가 작업을 넘길 때 답할 수 있었을 질문을 다시 던진다. 에이전트를 두 개 돌리면 그 비용은 두 배가 된다. 문제는 작업 자체가 아니다. 문제는 핸드오프다. 즉, 요청한 사람과 작업을 수행한 에이전트 사이에 무엇이 오가고, 무엇이 돌아오는가다.

코딩 에이전트 핸드오프 템플릿은 작업이 주체를 바꿀 때 어떤 정보를 담는지에 대한 고정된 구조다. 즉, 할당 시점에 사람에서 에이전트로, 리뷰 시점에 에이전트에서 사람으로 넘어갈 때를 말한다. 매번 넘길 때마다 그 형태를 즉흥적으로 정하는 대신, 항상 같은 필드를 채운다. 에이전트는 시작하기 전에 "완료"의 의미를 알고, 당신은 작업이 멈췄을 때 동일한 요약, 근거, 미해결 질문을 받는다.

이 글에서는 실무에서 통하는 두 가지 템플릿을 Sharkly 워크플로를 통해 살펴본다. Sharkly는 코딩 에이전트 위에 얹히는 레이어로, 요청부터 릴리스까지 컨텍스트, 진행 상황, 블로커, 결과, 사람의 리뷰를 눈에 보이게 유지한다. 이미 코딩 에이전트는 있다. Sharkly는 그것들을 팀으로 만들어 주고, 핸드오프 템플릿은 각 전달이 추측이 아닌 기록이 되도록 만든다.

코딩 에이전트 핸드오프 템플릿이란

핸드오프 템플릿은 체크리스트를 구조화한 것이다. 이는 빈약한 diff가 절대 답하지 않는 세 가지 질문에 답한다. 무엇을 요청했는가, 무슨 일이 일어났는가, 지금은 누구 차례인가. 이 세 가지가 함께 이동하면, 다음 작업자는 세 가지를 재구성하는 대신 하나의 기록을 읽는다.

템플릿으로 만들 만한 핸드오프는 두 가지다. 서로 반대 방향으로 흐르고 서로 반대되는 것을 담기 때문이다:

• 할당 핸드오프 (사람 또는 리더 에이전트 → 에이전트): 작업이 시작되기 전에 전달되는 목표, 경계, 완료 정의.
• 리뷰 핸드오프 (에이전트 → 사람): 작업이 멈췄을 때 전달되는 변경 사항, 작동한다는 근거, 사람이 여전히 판단해야 할 부분.

둘 다 템플릿화하는 것이 핵심이다. 대부분의 팀은 대충 티켓을 쓰고 돌아오는 길에는 아무것도 템플릿화하지 않아서, 모든 리뷰가 심문처럼 시작된다. 시간이 절약되는 곳은 돌아오는 길을 고치는 데 있다.

템플릿이 담고 있는 운영 모델

템플릿은 그 밑에 깔린 운영 모델만큼만 좋다. 네 가지 동사가 각 이음새를 누가 소유하는지 결정한다. 누가 할당하는가, 누가 실행하는가, 누가 리뷰하는가, 누가 수락하는가. 에이전트는 조사하고, 실행하고, 테스트하고, 보고한다. 사람은 방향을 정하고, 권한을 부여하고, 결과를 수락한다. 자동화는 팀의 판단이 필요한 지점에서 멈춘다.

그 계약이 바로 두 템플릿이 서로 다른 필드를 담는 이유다. 에이전트는 수락이 어떤 모습인지 절대 추측해서는 안 되므로, 할당 템플릿은 요청자가 그것을 적어 넣도록 강제한다. 사람은 초록불이 안전을 의미하는지 절대 추측해서는 안 되므로, 리뷰 템플릿은 에이전트가 자기 작업을 보여주도록 강제한다. 다음은 복사해 붙여넣을 수 있는 할당 핸드오프 블록이다:

## Assignment handoff
Task ID:        SH-###
Goal:           one sentence, in plain language
In scope:       the specific files, endpoints, or behaviors to touch
Out of scope:   what to leave alone (auth, billing, public contracts)
Definition of done:
  - [ ] observable acceptance criterion 1
  - [ ] observable acceptance criterion 2
Constraints:    frameworks, patterns, or limits to respect
Assignee:       the exact Agent that owns this

"범위 밖"과 "완료 정의" 항목이 가장 중요한 역할을 한다. 이것이 없으면 에이전트는 의도한 결과가 아니라 통과하는 diff에 맞춰 최적화한다. 이것이 있으면, 코드 한 줄이 존재하기 전에 수락 기준이 작성된다.

리뷰 핸드오프: 무엇이 돌아오는가

돌아오는 템플릿은 대부분의 워크플로가 건너뛰는 것이자, 당신의 오후를 구해 주는 것이다. 에이전트가 작업을 끝내면, "준비됐습니다"라는 말과 링크로 당신을 부르면 안 된다. 채워진 구조를 돌려줘야 한다:

## Review handoff
Task ID:        SH-###
Summary:        what changed, in 2-3 sentences
Acceptance:     each definition-of-done item, checked with how it was verified
Tests:          typecheck / unit / build results, pasted or linked
Diff:           the PR or worktree branch
Known limits:   what this does NOT cover, and any risky assumption
Open questions: decisions left for a human

"알려진 한계"와 "미해결 질문" 항목이 진짜 핸드오프와 초록 체크 표시의 벽을 구분한다. 정직한 한계("Redis 카운터는 단일 리전을 가정한다")는 눈먼 병합을 정보에 기반한 병합으로 바꾼다. 이는 작업 수준의 근거로 AI 생성 코드를 리뷰하는 방법 뒤에 있는 것과 같은 원리다. 리뷰어는 diff와 기대가 아니라, 주장과 그 증거를 읽는다.

분명히 짚을 만한 경계가 있다. 리뷰 핸드오프는 병합 요청이 아니다. 리뷰 요청이다. 에이전트는 제시하고, 사람이 결정한다. 이 두 행위를 분리해 두는 것이 리뷰되지 않은 작업이 배포되는 것을 막는다.

상태와 리뷰 게이트: 템플릿이 사는 곳

스크롤백 버퍼에 사는 템플릿은 아무도 읽지 않는 템플릿이다. 핸드오프는 공유되는 무언가에 붙어 있어야 하고, 상태는 그 자연스러운 집이다. 모든 Task는 하나의 레인을 통과하며, 각 상태 변경은 템플릿이 첨부된 핸드오프다:

이것을 읽기 쉽게 만들어 주는 규칙: 에이전트는 Task를 리뷰 준비(Ready for review)로 옮기고, 사람은 그것을 완료(Done)로 옮긴다. 에이전트는 자기 작업을 스스로 완료로 표시하지 않으며, 사람은 무슨 일이 있었는지 재구성할 필요가 없다. 리뷰 핸드오프가 이미 Task에 붙어 있기 때문이다. Sharkly에서는 실행, 블로커, 결과, 후속 논의가 Task 타임라인으로 돌아오므로, 열 개의 에이전트가 돌아가고 있을 때 당신은 열 개의 터미널이 아니라 보드를 읽는다. 이것이 에이전트가 완료한 작업을 추적하는 것과 나중에 커밋 로그가 설명해 주기를 바라는 것의 차이다. 자율 작업이 멈춰야 하는 지점 자체가 하나의 설계 선택이며, 이는 승인 게이트를 어디에 둘지에서 다룬다.

실제 예시: 티켓에서 병합된 PR까지

실제 같은 Task, SH-441을 보자. "리포트 페이지에 CSV 내보내기 추가." 코드가 아니라 템플릿이 채워지는 과정을 지켜보자.

사람이 SH-441을 열고, 리더 에이전트가 할당 핸드오프를 완성한다. 목표("사용자가 현재 리포트를 CSV로 다운로드할 수 있게 한다"), 범위 내(리포트 컨트롤러와 새 내보내기 모듈 하나), 범위 밖(인증, 기존 리포트 쿼리), 그리고 검증 가능한 세 항목으로 이루어진 완료 정의(다운로드 버튼, 쉼표와 따옴표의 올바른 이스케이프 처리, 1만 행 픽스처를 사용한 테스트). 담당자는 백엔드 에이전트다. 템플릿이 모호함을 허용하지 않았으므로 아무것도 모호하지 않다.

백엔드 에이전트가 Task를 맡아 격리된 워크트리에서 작업해 다른 작업과 절대 충돌하지 않게 하고, 완료 정의 항목을 자기 체크리스트 삼아 실행한다. 타입체크, 유닛 테스트, 빌드가 모두 통과하면, SH-441을 리뷰 준비로 옮기며 리턴 템플릿을 채운다. 짧은 요약, 각 수락 항목이 어떻게 검증되었는지와 함께 체크된 상태, diff, 그리고 하나의 알려진 한계("10만 행을 넘는 내보내기는 메모리에 버퍼링되며, 스트리밍은 구현되지 않음")다.

이제 핸드오프가 방향을 바꾼다. 사람은 스크롤백이 아니라 하나의 기록을 읽는다. 이스케이프 테스트를 확인하고, 메모리 한계를 실제 리포트 크기와 견주어 저울질하고, 일단 수락한 뒤 SH-441을 완료로 옮기면 병합이 트리거된다. 티켓에서 병합된 PR까지, 양쪽 이음새에 채워진 템플릿과 각 구간을 누가 소유했는지에 대한 기록이 남는다. 이것이 요구사항에서 코드까지 추적 가능하게 만든 경로를 끝에서 끝까지 구현한 것이다.

템플릿이 과한 경우

템플릿에는 비용이 따르므로, 여기 정직한 판단 기준 두 가지를 제시한다. 한 에이전트가 한 번에 끝내는 작고 잘 정의된 작업, 즉 Task 제목만 봐도 목표와 수락 기준이 명백한 경우에는 전체 템플릿을 건너뛰어라. 중요한 이음새를 넘는 순간, 즉 하나의 목표에 여러 에이전트가 붙거나, 공개 계약을 바꾸거나, 인증·결제·되돌리기 어려운 데이터를 건드리는 경우에는 템플릿을 꺼내 들어라. 템플릿은 컨텍스트 유실에 대비한 보험이고, 손실이 아플 만한 곳에 보험을 든다.

공유 보드와 규율만으로 이 모든 것을 수작업으로 운영할 수 있다. 에이전트, 태스크, 저장소의 수가 늘어나 규율이 가장 먼저 무너지기 전까지는 말이다. 이미 여러 에이전트를 돌리고 있다면, Sharkly가 그들의 태스크와 결과를 관리할 한 곳을 제공한다. 할당 및 리뷰 핸드오프를 담는 공유 Task, Task별 담당자, 격리된 워크트리, 그리고 에이전트는 리뷰 준비에 도달하고 사람은 완료를 결정하는 상태 레인이다. 이미 사용 중인 코딩 에이전트는 그대로 유지하라. 에이전트 사이의 이음새가 작업보다 더 많은 비용을 잡아먹기 시작하면 Sharkly를 다운로드하라.

FAQ

코딩 에이전트 핸드오프 템플릿이란 무엇인가? 작업이 주체를 바꿀 때 무엇을 담는지에 대한 고정된 구조다. 두 가지가 있다. 할당 핸드오프(사람에서 에이전트로: 목표, 범위, 완료 정의)와 리뷰 핸드오프(에이전트에서 사람으로: 요약, 근거, 알려진 한계). 매번 같은 필드를 채우는 것이 작업자 사이에서 컨텍스트가 증발하지 않게 지켜 준다.

왜 티켓뿐 아니라 돌아오는 길도 템플릿화해야 하는가? 대부분의 팀은 티켓을 쓰고 돌아오는 길에는 아무것도 템플릿화하지 않아서, 모든 리뷰가 심문처럼 시작된다. 요약, 검증된 수락 항목, 알려진 한계로 이루어진 리뷰 핸드오프가 템플릿이 시간을 가장 많이 절약해 주는 지점이다. 휴먼 인 더 루프 코딩 에이전트를 참고하라.

에이전트가 자기 작업을 완료로 표시해야 하는가? 아니다. 에이전트는 리턴 템플릿을 채워 Task를 리뷰 준비로 옮기게 하고, 완료로 옮기는 것과 병합 결정은 사람에게 맡겨라. "제시됨"과 "수락됨"을 분리하는 것이 리뷰되지 않은 코드가 배포되는 것을 막는다.

템플릿은 어디에 두어야 하는가? 한 에이전트만 본 터미널이 아니라, 상태 변경에 첨부되어 공유 Task에 있어야 한다. 핸드오프가 템플릿이 첨부된 상태라면, 다음 작업자는 자기에게 무엇이 기다리고 있는지 정확히 본다. 이는 또한 여러 에이전트가 한꺼번에 끝날 때 리뷰가 병목이 되는 것을 막아 준다.

이걸 위해 도구가 필요한가, 아니면 수작업으로 할 수 있는가? 공유 보드와 규율만으로도 운영할 수 있다. 전용 레이어는 여러 저장소에 걸쳐 여러 에이전트를 조율하고 수동 추적이 곧 작업이 되기 시작할 때 값을 한다. 범용 에이전트 작업용 AI 태스크 매니저와 비교해 보라.