Codex와 Claude Code를 동일한 리포지토리(repository)에서 사용하다 보면, 한쪽 AI에서 다른 쪽 AI로 작업을 넘겨주고 싶은 상황이 발생합니다.

처음에는 handoff를 "다음에 해주었으면 하는 일"에 대한 메모로 작성했습니다. 하지만 의뢰문만으로는 다음과 같은 괴리가 발생합니다.

• 어떤 파일을 건드려도 되는지가 모호함
• commit이나 push까지 진행해도 되는지가 모호함
• 실패했을 때 멈출 것인지, 대안으로 진행할 것인지가 모호함
• 완료 조건이 "적당히 고치기"가 되어, 리뷰 관점이 남지 않음

이 기사에서는 AI 간의 handoff를 단순한 인수인계가 아니라, 작업 계약(contract)으로서 작성하기 위한 체크리스트를 정리합니다.

handoff에 "이 기사를 리뷰해줘", "이 기능을 구현해줘"라고만 적으면, 받는 쪽의 AI는 부족한 조건을 추측합니다.

예를 들어 기사 리뷰라면, 본문만 보면 되는지, 관련 링크의 실재 여부까지 확인해야 하는지, 프론트매터(frontmatter)를 수정해도 되는지를 알 수 없습니다.

구현 작업이라면, 대상 파일의 외부까지 리팩터링(refactoring)해도 되는지, 테스트 추가까지 포함하는지, 실패 시 다른 접근 방식으로 전환해도 되는지가 모호해집니다.

AI는 모호한 의뢰라도 어떻게든 진행합니다. 따라서 의뢰문이 빈약할수록 "해주길 바라는 일"이 아니라 "AI가 보완한 내용"이 늘어납니다.

원인은 handoff에 필요한 정보를 한 종류의 문장으로 취급했기 때문이었습니다.

실제로는 AI에게 작업을 넘길 때 필요한 정보가 여러 개 있습니다.

이 6가지를 나누지 않으면, 받는 쪽의 AI는 부족한 부분을 대화의 문맥(context)에서 추측합니다. 세션(session)이 바뀌면 그 문맥은 사라집니다.

저의 운용 방식에서는 handoff에 다음과 같은 형식을 두도록 했습니다.

목적 계약:
- 달성하고 싶은 것:
- 이번에 하지 않을 것:
...

포인트는 모든 것을 장문으로 쓰지 않는 것입니다. 빈칸이 있다면 그 부분이 미정의 상태임을 알 수 있습니다.

기사 리뷰를 다른 AI에게 넘기는 경우에는 다음과 같이 쓸 수 있습니다.

목적 계약:
- 대상 기사가 공개 전 체크를 견딜 수 있는지 리뷰한다
- 본문의 전면 리라이트(rewrite)는 하지 않는다
...

구현 의뢰라면, 건드려도 되는 파일과 검증 커맨드(command)를 구체화합니다.

범위 계약:
- 건드려도 되는 파일: src/renderer/hooks/useSchedule.js
- 건드리지 않는 파일: src/main/**, package-lock.json
...

이것만으로도 AI가 관계없는 인접 파일로 범위를 넓힐 확률을 낮출 수 있습니다.

내용의 정확성은 인간이나 다른 AI의 리뷰가 필요합니다. 다만, 필요한 헤더(heading)가 있는지만 확인하는 것이라면 기계적으로 검사할 수 있습니다.

$path = "CLAUDE_CODE_HANDOFF.md"
$text = Get-Content -Raw -Path $path
$required = @(
...

throw를 사용하는 이유는 CI나 pre-commit hook에 넣었을 때 멈추게 하기 위해서입니다. 로컬에서 확인만 한다면 Write-Warning으로 해도 무방합니다.

이 템플릿은 AI의 판단 실수를 제로로 만드는 것이 아닙니다. 효과가 있는 것은 작업 경계와 멈추는 조건을 명시하는 것입니다.

특히 다음 작업에서는 실패 계약(failure contract)을 생략하지 않는 것이 좋습니다.

• 외부 API나 비용이 연관된 작업
• DB migration이나 영구 데이터를 다루는 작업
• publish, push, release 등 외부로 반영되는 작업
• 개인정보나 기밀 정보를 포함할 가능성이 있는 작업

"할 수 없다면 대안으로 진행할 것인지", "멈춰서 보고할 것인지"를 미리 적어두면, AI가 멋대로 리스크가 높은 회피책을 선택하는 것을 억제할 수 있습니다.

AI 간의 handoff는 의뢰문만으로는 받는 쪽의 추측이 늘어납니다.

저의 운용 방식에서는 handoff를 다음 6가지로 나눔으로써 작업 경계를 상당히 명확하게 할 수 있었습니다.

• 목적 계약
• 범위 계약
• 권한 계약
• 완성 계약
• 검증 계약
• 실패 계약

여러 AI를 사용할 때 필요한 것은 강력한 자동화보다, 어디까지 진행하고 어디서 멈출지를 공유할 수 있는 작업 계약이었습니다.