AI 간의 handoff를 다층 계약 체크리스트로 만들었다

서론

Codex와 Claude Code를 동일한 리포지토리(Repository)에서 병용하면 작업 인수인계(handoff)가 금방 모호해집니다.

"이 차이점(diff)을 리뷰해줘", "이 계획대로 구현해줘" 정도만으로도 통할 때가 있습니다. 하지만 실제로 몇 번 반복해 보니 다음과 같은 누락이 발생했습니다.

• 어느 파일까지 건드려도 되는지 모호하여, 다른 문서나 다른 기능까지 수정하기 시작함
• published: true, git push, release와 같은 최종 작업을 AI 측에서 판단하려고 함
• 리뷰 관점이 추상적이어서, 사실 확인·기밀 유지·테스트 부족 중 무엇을 우선할지 흔들림
• 실패 시 중단 방식이 정해져 있지 않아, 권한이나 네트워크가 필요한 상황에서도 작업을 계속하려고 함

그래서 AI 간의 handoff를 단순한 전달 사항이 아니라, **다층 작업 계약(multi-layer contract)**으로서 작성하도록 했습니다.

이 기사에서는 Zenn 문서 관리 리포지토리 harness17/zenn-articles와 AI 공동 작업을 위한 harness17/cross-agent-harness에서 사용하는 사고방식을 바탕으로, handoff에 무엇을 적어야 사고를 줄일 수 있는지 체크리스트로 정리합니다.

관련된 선행 기사에서는 AI 2대의 크로스 리뷰(cross-review) 절차와 Codex 및 Claude Code를 상호 호출하는 메커니즘을 다루었습니다. 본 기사에서는 그 전 단계인 "handoff에 무엇을 적어야 다른 AI에게 안전하게 넘길 수 있는가"에 집중합니다.

handoff를 단 한 장의 의뢰문으로 만들지 말 것

처음에는 handoff를 "다음 사람에게 보내는 의뢰문"으로 작성했습니다.

Codex로 기사를 작성했습니다.
Claude Code로 리뷰해 주세요.
문제가 없다면 공개해 주세요.

이것만으로는 부족했습니다.

리뷰 담당자 입장에서는 무엇을 근거로 공개 가능하다고 판단할지, 대상 범위는 어디까지인지, 수정해도 되는 것인지 지적만 하면 되는 것인지, 공개 작업까지 해도 되는지를 알 수 없습니다.

사람 사이라면 문맥으로 보완할 수 있지만, AI 에이전트(Agent)는 "할 수 있을 것 같은 일"을 넓게 실행하는 경향이 있습니다. 특히 로컬 리포지토리를 건드릴 수 있는 상태라면, 리뷰를 의뢰했음에도 본문 수정, 관련 파일 업데이트, git 조작까지 진행해 버릴 수 있습니다.

실제로 기사 리뷰를 의뢰한 작업에서 대상 기사뿐만 아니라 다른 기사의 표현이나 공개 로그까지 정리하려고 했던 적이 있었습니다. 구현 태스크에서도 UI의 소규모 수정을 의뢰했는데, 주변 컴포넌트의 정리까지 제안받는 상황이 있었습니다. 둘 다 악의가 있는 것이 아니라, 의뢰문에 "여기서부터는 건드리지 마라"라고 적지 않았던 것이 원인이었습니다.

따라서 handoff는 한 장의 의뢰문이 아니라, 다음 계층으로 나누어 작성하기로 했습니다.

계층	고정할 내용
목적 계약	무엇을 달성하고 싶은가
...	...

이렇게 나누고 나서부터 AI에게 전달하는 의뢰의 입도(granularity)가 안정되었습니다.

다층 계약 체크리스트

실제로 handoff를 작성할 때는 다음 체크리스트를 사용합니다.

## YYYY-MM-DD HH:mm 추가 (<주제> / <agent> 작성)
- 대상: <branch / worktree / path>
- 작성자: <Codex | Claude Code | user>
...

이 템플릿의 목적은 긴 의뢰문을 쓰는 것이 아닙니다. AI가 멋대로 보완하기 쉬운 부분을 미리 채워두는 것입니다.

특히 효과적이었던 것은 "달성하지 않는 것", "건드려서는 안 되는 범위", "user 명시 시에만" 이 세 가지였습니다.

1. 목적 계약: 할 일보다, 하지 않을 일을 적는다

AI에 대한 의뢰에서는 "무엇을 해주길 원하는가"를 적습니다. 하지만 사고를 줄이기 위해서는 "무엇을 하지 않을 것인가"도 그만큼 중요했습니다.

예를 들어, 기사 리뷰를 의뢰할 때 다음과 같이 적습니다.

목적 계약:
- `articles/example.md`의 공개 전 리뷰를 수행함
- 중대 지적, 경미 지적, 잔여 리스크를 분류하여 반환함
...

"리뷰해 주세요"라고만 하면 AI는 수정까지 진행할 수 있습니다. 리뷰 전용인지, 수정을 포함하는지를 목적 계약으로 나누면 의뢰 대상의 행동이 안정됩니다.

구현 의뢰에서도 마찬가지입니다.

목적 계약:
- 계획 파일에 적힌 체크박스를 순서대로 구현함
- 기존 설계 방침에 따라 최소한의 차이(diff)로 유지함
...

"덤으로 개선"하는 것을 방지하려면, 하지 않을 일을 명문화할 필요가 있었습니다.

2. 범위 계약: 건드려도 되는 곳을 미리 좁히기

AI 간의 협업에서 가장 무서운 것은, 한쪽이 알지 못하는 차분(diff)을 넓히는 것입니다.

특히 기사 리포지토리(repository)에서는 리뷰 대상인 기사만 볼 생각이었는데, README, 공개 로그, 다른 기사의 표현까지 정리하고 싶어지는 상황이 발생합니다. 코드 리포지토리라면 공통 컴포넌트(component)나 테스트 헬퍼(test helper)까지 범위가 넓어집니다.

그래서 handoff에는 반드시 범위를 작성합니다.

범위 계약:
- 건드려도 되는 범위: `articles/ai-handoff-multi-layer-contract-checklist.md`
- 건드려서는 안 되는 범위: 다른 기사, `README.md`, 공개 로그, git 히스토리

구현 태스크라면 디렉토리 단위가 아니라 파일 단위로 작성할 수 있다면 그 편이 더 안전합니다.

범위 계약:
- 건드려도 되는 범위:
- `src/renderer/hooks/useSchedule.js`
...

여기서 중요한 것은 git status를 확인한 뒤에 작성하는 것입니다. 커밋되지 않은 차분이 있는 상태에서 AI를 다른 쪽으로 넘긴다면, 어떤 것이 자신의 차분이고 어떤 것이 사용자나 다른 에이전트(agent)의 차분인지 구분해 두지 않으면 리뷰나 수정의 경계가 무너집니다.

3. 권한 계약: 최종 조작을 AI에게 넘기지 않는다

handoff에는 편집 권한과 공개 권한을 나누어 작성합니다.

저의 운용 방식에서는 다음 조작은 원칙적으로 user가 명시할 때만 수행합니다.

published: true

git commit

git push

• release
• migration
• 외부 서비스로의 게시

AI가 구현이나 리뷰를 할 수 있더라도, 마지막 공개 판단까지 넘길 필요는 없습니다.

Zenn 기사에서는 published: true로 바꾸고 main에 push하면 공개 단계로 넘어갑니다. 앱 개발에서는 push나 release가 이용자에게 영향을 미칩니다. DB라면 migration이 데이터에 영향을 줍니다.

따라서 handoff에서는 다음과 같이 명시합니다.

권한 계약:
- 편집: 가능
- git add / commit / push: 불가능
...

이 계층을 나눔으로써 "리뷰를 통과했으니 공개해 두겠습니다"와 같은 건너뛰기를 방지하기 쉬워졌습니다.

4. 완성 계약: 완료 조건을 4종류로 나누기

구현 태스크에서는 완성 조건을 "돌아가기만 하면 된다"로 끝내면 누락이 발생합니다.

저는 다음 4종류로 나누고 있습니다.

종류	확인할 것
통상 동작	기대하는 주요 동선이 작동하는가
...

기사의 경우도 같은 사고방식을 적용할 수 있습니다.

완성 계약:
- 통상 동작: 독자가 handoff 체크리스트를 자신의 리포지토리로 옮길 수 있음
- 전제 조건: Codex / Claude Code를 병용하는 독자를 상정함
...

완성 계약을 먼저 작성하면 리뷰 측에서도 보기 편해집니다. 리뷰 담당자는 "문장으로서 좋은가"가 아니라 "완성 계약을 충족하고 있는가"로 판단할 수 있습니다.

5. 검증 계약: 커맨드와 관점을 모두 작성하기

verify 커맨드만으로는 리뷰 관점이 부족합니다. 반면, 관점만 있으면 확인 내용이 모호해집니다.

따라서 검증 계약에서는 커맨드와 관점을 분리합니다.

검증 계약:
- 셀프 verify:
- `npm run test`
...

기사 리포지토리에서는 npm run test와 같은 테스트가 없는 경우도 있습니다. 그럴 때는 문체, 필수 요소, 기밀 유지, 링크, front matter를 검증 계약에 넣습니다.

검증 계약:
- 셀프 verify:
- front matter에 `published: false`가 남아 있음
...

"무엇을 확인하면 OK인가"를 적어 두면, 다른 AI에게 넘겨도 리뷰 결과의 형식이 통일됩니다.

6. 실패 계약: 계속하기보다 멈추는 조건을 작성하기

AI 에이전트는 실패했을 때 다른 경로를 찾아 진행하려고 합니다. 이는 편리한 면도 있지만, 권한, 네트워크, 외부 서비스, 파괴적인 조작이 얽히면 위험합니다.

그래서 handoff에는 멈추는 조건을 작성합니다.

실패 계약:
- 네트워크 액세스가 필요해지면 정지할 것
- 확인되지 않은 핵심 주장이 나오면 단정하지 말고, 확인 대기 상태로 되돌릴 것
...

이 계층을 도입한 이후로, "어떻게든 진행한다"보다 "안전하게 멈춘다"는 결과가 늘어났습니다.

특히 외부 API, 공개 기사, DB migration, GitHub Releases와 같이 외부 영향이 있는 작업에서는 실패 계약 (failure contract)이 없으면 AI가 너무 많은 대체 수단을 찾으려 합니다. 어떻게 멈춰야 하는지를 적어두면, 다음 인간의 판단으로 넘기기가 훨씬 수월해집니다.

간이 체크를 스크립트화하기

6개 계층을 매번 수동으로 확인하는 것만으로는 바쁠 때 놓치기 쉽습니다. 내용의 정확성은 리뷰를 통해 확인하더라도, 구조적인 누락만큼은 기계적으로 잡아낼 수 있도록 했습니다.

handoff의 품질은 모든 것을 자연어 리뷰에 맡기는 것보다, 최소한의 구조라도 기계적으로 확인하는 편이 더 안정적입니다.

예를 들어, Markdown handoff에 필요한 헤더(heading)가 있는지 확인하는 정도라면 다음과 같은 PowerShell로 확인할 수 있습니다.

$path = "CLAUDE_CODE_HANDOFF.md"
$content = Get-Content -Raw -Path $path
$required = @("목적 계약:", "범위 계약:", "권한 계약:", "완성 계약:", "검증 계약:", "실패 계약:")
...

이것은 내용의 정확성까지는 확인하지 않습니다. 그럼에도 불구하고 "권한 계약을 쓰는 것을 잊었다"라거나 "실패 계약이 없다"와 같은 사고는 잡아낼 수 있습니다.

throw를 사용하여 중단시키는 이유는, CI나 pre-commit hook에 통합했을 때 계약 섹션이 없는 handoff를 그대로 통과시키지 않기 위해서입니다. 로컬에서 수동으로 확인하는 용도라면, Write-Warning으로 변경하여 경고 표시만 남겨두어도 좋습니다.

실제 운용에서는 이러한 가벼운 구조 체크와 AI에 의한 의미 리뷰 (semantic review)를 조합하는 것이 적절하다고 느낍니다.

요약

AI 간의 handoff는 대화의 연속으로 작성하면 모호해집니다.

저의 운용 방식에서는 handoff를 다음의 6개 계층으로 나눔으로써 작업 경계가 상당히 명확해졌습니다.

• 목적 계약 (objective contract): 무엇을 달성하고, 무엇을 하지 않을 것인가
• 범위 계약 (scope contract): 어디까지 건드려도 되는가
• 권한 계약 (authority contract): 편집, commit, push, publish를 누가 판단할 것인가
• 완성 계약 (completion contract): 정상 동작, 전제 조건, 에러 처리, no-regression
• 검증 계약 (verification contract): verify 명령어와 리뷰 관점
• 실패 계약 (failure contract): 어디서 멈추고, 무엇을 보고할 것인가

Codex와 Claude Code를 연결할수록 필요해지는 것은 강력한 자동화보다는, 멈추는 조건까지 포함된 작업 계약이었습니다.

참고 링크

• harness17/zenn-articles: 본 기사를 작성하고 있는 기사 관리 리포지토리 (repository)
• harness17/cross-agent-harness: AI 공동 작업의 handoff와 리뷰 동선을 분리해낸 리포지토리 (repository)
• 관련 기사: Codex와 Claude Code를 상호 호출하는 하네스(harness)를 구축했다
• 관련 기사: AI 2대 교차 리뷰로 기술 기사의 맹점을 찾아내기

Discussion