인계 브리프(handoff brief): 코딩 에이전트가 시작하기 전에 작성해야 할 것

대부분의 실패하는 에이전트 실행은 코드에서 실패하지 않습니다. 인계 과정에서 실패합니다. 작업이 누군가의 머릿속에 존재했고, 프롬프트는 그중 절반만을 전달했습니다. 반환되는 diff는 우리가 의도했던 질문과 약간 다른 것을 답변합니다. 이를 검토한다는 것은 출력(output)으로부터 의도(intent)로 역추적하는 것을 의미하며, 이는 느린 방향입니다.

따라서 Codex나 Claude Code 같은 곳에 어떤 사소하지 않은 작업이라도 맡기기 전에, 우리는 짧은 인계 브리프를 작성합니다. 검토는 비교가 됩니다: 이 실행이 브리프에서 말한 것만 수행했고, 그 이상은 하지 않았는가?

브리프에 포함되어야 할 내용

• 목표(Goal): 방법론이 아닌, 한두 문장으로 표현하는 결과물.
• 범위(Scope): 에이전트가 변경할 수 있는 경로(paths) 또는 모듈(modules).
• 금지 사항(Off limits): 생각컨대 건드려야 할 것 같더라도 절대로 만져서는 안 되는 파일과 동작 방식.
• 확인 사항(Checks): 변경이 작동함을 증명하는 정확한 명령어들.
• 완료(Done): 작업을 종료시키는 관찰 가능한 상태(observable state).
• 보고 내용(Report back): 요약에 포함되어야 할 내용.
• 추측하지 말고 에스컬레이션(Escalate, don't guess): 인간의 판단이 필요한 결정 사항들.

마지막 항목이 가장 많은 일을 합니다. 에이전트가 모호성(ambiguity)에 부딪히면, 보통 어떤 식으로든 해결하려고 할 것입니다. 만약 모호성을 미리 명시한다면, 침묵하는 추측은 보고서 속의 질문이 됩니다.

템플릿

## Goal
<작업 완료 시 참이어야 하는 것들> 

...

간결하게 유지하세요. Codex 문서는 사용량 관리와 관련하여 프롬프트 크기를 제어하고 AGENTS.md의 크기를 줄일 것을 조언합니다. 같은 논리는 가독성에도 적용되는데, 코드를 재진술하는 브리프는 건너뛰기 쉽기 때문입니다. 지속적인 프로젝트 규칙은 도구가 이미 읽고 있는 지침 파일(AGENTS.md, CLAUDE.md)에 포함되어야 하며, 브리프는 오직 이 작업만을 다룹니다. Claude Code가 새로운 작업을 시작할 때 /clear를 사용하라는 안내는 여기에 잘 맞습니다: 컨텍스트를 지우고, 그 다음 브리프를 붙여넣으세요.

모호한 브리프와 더 나은 브리프

작업: 작은 내부 서비스가 여전히 HTTP 클라이언트 래퍼의 사용 중단된 fetchLegacy 메서드를 호출합니다.

모호한 버전:

더 이상 사용되지 않는 fetchLegacy 호출을 새로운 클라이언트 API로 대체하고 모든 것이 여전히 작동하는지 확인하세요.

이 브리프는 네 가지 질문을 남깁니다:

• 어떤 파일들이 포함되나요?
• 재시도(retry) 동작은 유지되어야 하나요?
• "모든 것"이란 무엇을 의미하나요?
• 새로운 API가 지원하지 않는 옵션을 전달하는 호출 지점들(call sites)에게는 무슨 일이 일어나나요?

에이전트가 이 네 가지 질문 모두에 답할 것입니다. 단지 diff를 읽기 전까지는 어떻게 되는지 알 수 없을 뿐입니다.

더 나은 버전:

목표 (Goal): src/에서 fetchLegacy 호출이 남아있지 않게 합니다; 호출자(callers)의 동작은 변경되지 않습니다.
범위 (Scope): src/clients/와 src/handlers/. 제외되는 영역 (Off limits): src/generated/, 의존성 매니페스트 및 락파일, migrations/.
확인 (Check): 단위 테스트(unit tests)와 타입 검사기(type-checker)가 통과하며, 테스트가 건너뛰거나 삭제된 것이 없습니다.
완료 (Done): src/에서 fetchLegacy를 검색했을 때 그 정의만 발견되며, 이는 후속 조치를 위해 유지됩니다.
보고 (Report): 변경된 각 호출 지점과 재시도가 현재 어떻게 처리되는지.
에스컬레이션 (Escalate): 새로운 API가 지원하지 않는 옵션을 사용하는 모든 호출 지점. 이들은 변경되지 않은 채로 두고 목록화합니다.

같은 작업이지만, 이제 검토자는 diff를 열기 전에 어떤 것이 올바른 diff인지 알고 있습니다.

실행 후 (When the run comes back)

1. 먼저 diff, 나중에 요약. 요약은 작업에 대한 설명이고, diff가 실제 작업입니다. 파일 목록을 범위(Scope) 및 제외 영역(Off limits)과 비교하세요.
2. 직접 검사 실행: 브리프에서 나온 명령어를 사용하여 깨끗한 상태(clean state)에서 직접 검사를 다시 수행하세요. 보고서의 "테스트 통과"는 증거가 아니라 주장입니다.
3. 조용한 범위 확장 (silent scope creep) 찾기: 재포맷된 파일, 이름이 바뀐 헬퍼 함수, 근처의 정리 작업, 느슨해진 단언(assertion), 새로운 의존성 등. 각각은 괜찮을 수 있습니다. 하지만 아무것도 놀라움이어서는 안 됩니다.
4. 에스컬레이션 답변 작성: 에스컬레이션 사항들에 답하고 그 내용을 문서로 남기세요.
5. 결정 기록: 다음 브리프가 거기서 시작할 수 있도록, 결정 사항을 브리프, 커밋 메시지 또는 PR 설명에 기록하세요.

도구 간 컨텍스트 손실 지점 (Where context gets lost between tools)

약점은 거의 한 번의 실행 내부에는 없습니다. 실행과 실행 사이에 존재합니다:

계획 수립 채팅(planning chat)에서 도출된 추론 과정은 에이전트에게 전달되지 않습니다.
에스컬레이션(escalation) 관련 질문은 하나의 터미널에서 답변을 받고 끝난 후 잊힙니다.
후속 조치는 이전의 결정 사항과 아무런 연결 없이 다른 도구에서 시작됩니다.

각 도구는 자체적인 세션 기록(session history)을 유지합니다. 파일에 보관하고, 돌아온 결과로 업데이트하는 브리프(brief)만이 모든 도구를 가로질러 정보를 전달할 수 있는 유일한 것입니다. 이를 코딩하듯이 취급하세요: 버전을 관리하고, 검토하며, 재사용해야 합니다.

이 게시물은 Tutuo, Inc.의 Octuo 팀에서 작성했습니다. 코딩 에이전트 운영에 관한 더 많은 노트는 저희 블로그에서 확인하실 수 있습니다.

AI의 도움을 받아 초안 작성됨; 언급된 도구 동작은 게시 전 Codex 및 Claude Code 문서를 기반으로 확인되었습니다.