에이전트 A가 “작성을 완료했습니다”라고 말해도 에이전트 B가 필요한 파일과 필드가 있다는 보장은 없습니다. 실제 블로그 자동화에서도 비슷한 이름의 필드 하나가 달라 정상 이미지가 발행 단계에서 차단된 적이 있습니다.
완료의 의미를 기계가 읽게 합니다
요청과 결과에 같은 작업 ID를 넣고 상태는 진행 중, 완료, 실패, 차단처럼 제한된 값만 허용합니다. 완료 상태에는 최종 원고, 메타데이터와 이미지의 정확한 위치가 있어야 합니다. 중간 파일은 최종 결과로 인정하지 않습니다.
필드 이름은 하나만 허용합니다
finalImage와 final_image를 모두 적당히 받아 주면 잠시 편하지만 생산자와 소비자의 오류가 숨습니다. 하나의 JSON 스키마를 정본으로 두고 대소문자, 자료형과 필수 여부를 검사합니다. 변경이 필요하면 계약 버전을 올립니다.
자연어가 아니라 검증기를 통과시킵니다
생산자는 결과를 쓰고 곧바로 검증기를 실행합니다. 소비자도 작업을 시작하기 전에 같은 검증기를 다시 실행합니다. 파일 존재만 보지 않고 본문 길이, 이미지 크기, 상태 값과 작업 ID 일치까지 확인합니다.
원본과 파생물을 구분합니다
조사 자료, 편집용 원고, 최종 공개 결과의 관계를 기록합니다. 실패한 이미지나 이전 작업의 원고를 현재 작업의 대체물로 복사하지 않습니다. 빠른 복구처럼 보여도 출처와 주제가 섞이는 사고가 생길 수 있습니다.
런타임까지 계약의 일부입니다
검증기가 개발 환경에서 성공해도 실제 자동화 환경의 언어 버전에서 실행되지 않을 수 있습니다. 배포 대상과 같은 런타임에서 최소 표본과 실패 표본을 모두 시험해야 합니다.
필드명 하나 때문에 멈춘 날
실제 운영에서 생산자는 이미지 검수를 통과했다고 기록했지만 소비자는 최종 이미지 포인터를 찾지 못했습니다. 사람이 보면 같은 뜻처럼 보이는 필드명이었지만 대소문자와 구조가 달랐습니다. 결과 파일은 눈앞에 있는데 계약상 사용할 수 없어 발행을 막아야 했습니다.
처음에는 지나치게 엄격하다고 느꼈습니다. 그래도 비슷한 이름을 임의로 허용하면 다음에는 중간 이미지나 다른 작업의 파일을 집을 수 있다고 판단했습니다. 그 뒤로 자연어 지시를 더 길게 쓰기보다 생산자와 소비자가 같은 검증기를 실행하도록 바꿨습니다.
좋은 인수인계 계약은 에이전트를 더 영리하게 만드는 장치가 아닙니다. 제가 잠든 사이에도 “완료”라는 낙관적인 보고를 검증 가능한 사실로 바꾸는 장치입니다.