AI 출력 계약 운영법

AI 에이전트가 24시간 움직일 때 가장 자주 생기는 문제는 실행 능력 부족이 아니라 출력의 흔들림입니다. 같은 작업을 해도 어떤 날은 테스트 결과만 쓰고, 어떤 날은 판단 근거 없이 완료라고 말하며, 어떤 날은 공개 페이지에 올리면 안 되는 내부 표현을 섞습니다. 출력 계약은 에이전트가 마지막에 무엇을 반드시 남겨야 하는지, 무엇은 절대 남기면 안 되는지, 어떤 증거가 있어야 완료라고 부를 수 있는지를 미리 정하는 운영 장치입니다.

출력 계약은 문서 양식이 아닙니다. 다음 자동화와 다음 사람에게 넘길 수 있는 안전한 인터페이스입니다. 헤르메스가 DB-only 콘텐츠를 업로드하든, 배포 검증을 하든, Q&A 공개 화면을 살피든, 최종 출력이 일정해야 운영자는 빠르게 상태를 판단할 수 있습니다.

왜 출력 계약이 24시간 운영의 안전장치인가

자동화는 작업을 빠르게 끝내지만, 잘못된 완료 보고도 빠르게 쌓습니다. 특히 cron-run 환경에서는 사용자가 옆에서 질문을 받아 주지 않습니다. 에이전트는 스스로 범위를 정하고, 실행하고, 검증하고, 실패하면 멈춰야 합니다. 이때 출력 계약이 없으면 보고서는 친절한 말투의 감상이 됩니다. 출력 계약이 있으면 보고서는 재현 가능한 운영 기록이 됩니다.

좋은 출력 계약은 세 가지를 고정합니다. 첫째, 상태입니다. 정상, 주의, 장애, 보류 중 어디에 속하는지 한 줄로 말해야 합니다. 둘째, 증거입니다. 어떤 명령, 어떤 라이브 경로, 어떤 콘텐츠 marker를 확인했는지 남겨야 합니다. 셋째, 경계입니다. 민감정보, 내부 인증값, 운영자용 문구, 공개 금지어를 출력하지 않았다는 사실을 검증해야 합니다.

출력 계약이 없을 때 자주 보이는 실패는 “완료했습니다”라는 문장뿐인 보고입니다. 운영자는 무엇을 완료했는지, 어디까지 검증했는지, 어떤 위험이 남았는지 다시 물어봐야 합니다. 24시간 자동화에서는 이 재질문이 곧 지연이고, 지연이 누적되면 운영 신뢰도가 무너집니다.

출력 계약의 기본 구조

출력 계약은 길 필요가 없습니다. 다만 빠지면 안 되는 칸이 있어야 합니다. 작업 범위, 변경 대상, 실행 결과, 검증 결과, 공개 안전 스캔, 남은 위험, 다음 행동을 고정하면 대부분의 운영 보고가 안정됩니다.

핵심은 사람에게 읽기 좋은 형식과 기계가 다시 검사하기 쉬운 형식을 동시에 만족시키는 것입니다. 예를 들어 콘텐츠 업로드 보고라면 slug, 검증 명령, 업로드 성공 여부, revalidate 결과, live smoke 경로, 원본 JSON 정리 여부가 항상 있어야 합니다.

운영 순서

1단계: 시작 전에 출력부터 설계한다

작업을 시작하기 전에 마지막 보고서의 칸을 먼저 정합니다. “이번 작업은 Hermes 팁 1건 DB-only 업로드이며, 최종 보고에는 slug, validation, upload, revalidate, live smoke, 임시 원본 정리, git working tree 상태가 들어간다”처럼 선언합니다. 출력 칸을 먼저 정하면 실행 중에 필요한 증거를 놓치지 않습니다.

이 단계에서 하지 않을 일도 정합니다. 예를 들어 DB-only 운영이라면 코드 배포, 커밋, 푸시, 새 cron job 생성은 범위 밖입니다. 범위 밖 행동이 명확해야 에이전트가 문제를 발견했을 때 무리하게 코드를 고치거나 배포하지 않습니다.

2단계: 증거 marker를 수집한다

작업 중에는 증거 marker를 짧게 모읍니다. 콘텐츠라면 slug와 제목, 업로드 응답의 성공 여부, 목록과 상세 페이지에서 보이는 안정적인 문구가 marker입니다. 배포 검증이라면 대표 경로, HTTP 상태, 페이지 제목, 차단어 스캔 결과가 marker입니다. 브라우저 확인이 필요한 작업이라면 console error 개수와 사용자 흐름도 marker가 됩니다.

marker는 긴 로그가 아닙니다. 운영자에게 필요한 것은 전체 출력 덤프가 아니라 판단 가능한 신호입니다. 긴 로그에는 불필요한 내부 문구나 민감한 값이 섞일 수 있으므로 요약된 증거만 남기는 편이 안전합니다.

3단계: 검증과 보고를 분리한다

검증은 시스템을 확인하는 행위이고, 보고는 사람에게 상태를 전달하는 행위입니다. 둘을 섞으면 “검증한 것처럼 보이는 보고”가 됩니다. 먼저 validation, 품질 스캔, 업로드, live smoke를 실제로 실행합니다. 그다음 실행한 결과만 보고합니다. 실행하지 못한 항목은 미실행으로 적어야 합니다.

예를 들어 live smoke를 못 했다면 “네트워크 제한으로 미실행”이라고 남겨야 합니다. “아마 반영됨”은 출력 계약 위반입니다. 출력 계약은 추측을 줄이고 증거를 늘리는 규칙입니다.

4단계: 끝나기 전에 정리 상태를 확인한다

DB-only 콘텐츠 run은 특히 정리 상태가 중요합니다. 임시 JSON을 업로드한 뒤 그대로 남기면 다음 run의 중복 검사나 git 상태 판단을 흐립니다. 성공한 원본은 무시되는 archive 위치로 옮기고, 실패한 원본은 draft 위치로 옮깁니다. 마지막 보고에는 content 경로에 새 untracked 파일이 남지 않았는지 포함해야 합니다.

상황별 예시

Hermes 팁 DB-only 업로드

상황: 에이전트가 새로운 Hermes 운영 글을 하나 작성해 DB에 올립니다. 출력 계약은 “slug, 품질 검사, 업로드, revalidate, 목록/상세 live smoke, 원본 이동, git 상태”입니다. 이 계약이 있으면 에이전트는 글을 쓰는 데서 멈추지 않고, 실제 공개 확인까지 이어갑니다.

좋은 보고는 이렇게 구성됩니다. “slug는 무엇이고, validation 통과, 품질 스캔 통과, 업로드 성공, revalidate 정상, /hermes와 상세 경로 200, title marker 확인, 차단어 없음, 원본 archive 이동, content untracked 없음.” 이 정도면 다음 운영자가 같은 페이지를 다시 확인하지 않아도 현재 상태를 판단할 수 있습니다.

배포 검증 run

상황: 코드가 이미 배포되었는지 확인해야 합니다. 출력 계약은 “커밋 식별자, 배포 상태, 대표 경로, 브라우저 콘솔, 단일 H1, 공개 안전 스캔”입니다. 단순히 사이트가 열린다는 말은 부족합니다. 홈, 주요 목록, 대표 상세 페이지가 200인지, 새 기능 marker가 있는지, 공개 페이지에 내부 문구가 없는지까지 확인해야 합니다.

이 계약은 롤백 판단에도 도움이 됩니다. 대표 경로 중 하나가 500이면 장애입니다. 목록은 열리지만 새 marker가 없으면 배포 지연 또는 캐시 문제입니다. 페이지는 열리지만 브라우저 콘솔에 치명적 오류가 있으면 주의 또는 장애로 분류합니다.

모바일 원격 운영

상황: 운영자가 휴대폰으로 최종 보고만 보고 판단해야 합니다. 출력 계약이 없으면 긴 로그를 스크롤하다가 핵심을 놓칩니다. 모바일 보고용 계약은 첫 줄에 상태, 둘째 줄에 한 일, 셋째 줄에 검증 증거, 넷째 줄에 남은 위험을 둡니다.

모바일 원격 운영에서는 특히 “다음 행동”이 중요합니다. 정상이라면 다음 run까지 대기, 주의라면 어떤 항목을 수동 확인, 장애라면 어떤 조건에서 자동화를 멈춰야 하는지 명확해야 합니다. 운영자가 작은 화면에서 즉시 판단할 수 있어야 24시간 자동화가 실제 운영 체계가 됩니다.

크론/스킬/메모리 운영

상황: 여러 cron-run이 서로 다른 스킬을 사용해 콘텐츠와 점검을 수행합니다. 출력 계약은 “이번 run에서 사용한 운영 기준, 장기 기억으로 남기지 않은 임시 사실, 다음 run에 넘길 증거”를 분리해야 합니다. 모든 진행 상황을 기억에 저장하면 오히려 다음 세션이 과거 임시 상태에 끌려갑니다. 반대로 반복 절차의 개선점은 스킬이나 운영 문서로 남겨야 합니다.

이때 출력 계약은 메모리와 보고의 경계를 지킵니다. 보고에는 이번 run의 결과를 남기고, 장기적으로 반복될 절차만 스킬 개선 후보로 분리합니다. 민감한 값이나 임시 파일 경로는 장기 기억에도 최종 보고에도 남기지 않습니다.

권한과 보안 경계

출력 계약에서 가장 강하게 지켜야 하는 경계는 민감정보입니다. 에이전트는 검증 과정에서 환경 설정의 존재 여부를 확인할 수 있지만, 실제 값은 출력하지 않아야 합니다. 인증, DB 연결, 재검증 비밀, 외부 서비스 자격 정보는 상태만 보고합니다. “있음/없음”, “구성됨/미구성”, “요청 성공/실패”처럼 판단 가능한 수준이면 충분합니다.

두 번째 경계는 공개 언어입니다. 운영자에게는 자연스러운 내부 표현도 방문자에게는 불안하게 보일 수 있습니다. 공개 페이지에 관리자 조작, 숨김 처리, 재시도 버튼, 내부 노트처럼 보이는 말이 나타나면 콘텐츠 품질 문제가 아니라 운영 안전 문제입니다. 출력 계약은 live smoke에서 공개 문구를 확인하고, 내부 언어를 방문자 언어로 바꿨는지 보고해야 합니다.

세 번째 경계는 권한 확대입니다. 출력 계약은 이번 run이 가진 권한 안에서만 완료를 선언해야 합니다. DB-only 콘텐츠 run이 코드 문제를 발견했다고 해서 자동으로 코드를 수정하고 배포하면 범위가 바뀝니다. 범위를 넘는 문제는 “후속 조치 필요”로 보고하고 멈추는 편이 안전합니다.

검증 방법

출력 계약의 검증은 네 층으로 나눕니다. 첫째, 소스 검증입니다. JSON 형식, 필수 필드, FAQ 개수, 본문 깊이, 금지 문구, 렌더러 위험을 확인합니다. 둘째, 업로드 검증입니다. DB 반영이 성공했는지, revalidate가 정상적으로 수행되었는지 확인합니다. 셋째, 라이브 스모크입니다. 목록과 상세 페이지가 200을 반환하고, slug 또는 제목 marker가 보이는지 확인합니다. 넷째, 사용자 관점 검증입니다. 브라우저 콘솔 오류, 단일 H1, 공개 문구, 화면 흐름을 봅니다.

모든 run에서 네 층을 다 할 필요는 없지만, 어떤 층을 했고 어떤 층을 못 했는지는 반드시 보고해야 합니다. 예를 들어 코드 변경이 없는 DB-only 콘텐츠라면 전체 빌드보다 소스 검증, 업로드 검증, live smoke가 더 중요합니다. 반대로 레이아웃 변경이라면 빌드와 브라우저 smoke가 더 중요합니다.

검증 결과는 “통과/실패”만으로 끝내지 않습니다. 어떤 marker가 보였는지 적어야 합니다. 상세 페이지에서 제목이 보였는지, 목록에서 새 카드가 보였는지, API 응답에서 slug를 찾았는지, 차단어 스캔이 새 글 객체에 대해 통과했는지처럼 재검증 가능한 문장으로 남깁니다.

실패 시 중단 기준

출력 계약은 성공 보고뿐 아니라 멈춤 보고를 위해 존재합니다. 다음 상황에서는 자동으로 계속하지 말고 중단해야 합니다. 품질 스캔이 본문 깊이 부족을 지적했는데 보강 없이 업로드하려는 경우, validation이 실패한 경우, 업로드는 되었지만 live smoke에서 상세 페이지가 열리지 않는 경우, 공개 페이지에 민감정보나 내부 조작 문구가 보이는 경우, 이번 작업 범위를 넘는 코드 수정이 필요한 경우입니다.

중단 보고는 짧지만 구체적이어야 합니다. “품질 미달”보다 “상황별 예시가 없고 본문 깊이가 기준보다 낮아 draft로 이동, 업로드 안 함”이 좋습니다. “라이브 실패”보다 “상세 경로 200 미확인, 목록 marker 미노출, revalidate 재확인 필요”가 좋습니다. 이 정도로 남기면 다음 run이 같은 실패를 반복하지 않습니다.

또 하나의 중단 기준은 충돌입니다. 작업 시작 전부터 다른 파일이 수정되어 있거나, 동시 작업이 같은 영역을 만지고 있다면 DB-only 작업은 더 조심해야 합니다. 직접 되돌리거나 정리하지 말고, 이번 run이 만든 파일만 정리한 뒤 기존 dirty 상태를 별도 위험으로 보고합니다. 출력 계약은 남의 작업을 침범하지 않는 경계이기도 합니다.

작은 팀을 위한 도입 방법

처음부터 거대한 운영 양식을 만들 필요는 없습니다. 매일 반복되는 작업 하나를 골라 출력 계약을 붙이면 됩니다. 예를 들어 “콘텐츠 업로드 보고는 항상 slug, validation, upload, revalidate, live smoke, archive, git status를 포함한다”는 규칙부터 시작합니다. 다음에는 “배포 검증 보고는 대표 경로와 브라우저 콘솔을 포함한다”를 추가합니다.

중요한 것은 계약을 실제로 검사하는 습관입니다. 보고서에 validation이 있다고 쓰여 있으면 실제 명령이 실행되어야 합니다. live smoke가 있다고 쓰여 있으면 실제 HTTP 확인이 있어야 합니다. 출력 계약은 말투가 아니라 증거의 약속입니다.

검증 체크리스트

• 작업 범위와 비범위를 첫 단계에서 정했는가?
• 최종 보고에 들어갈 필수 칸을 미리 정했는가?
• 증거 marker가 짧고 재검증 가능한가?
• 민감정보와 내부 인증값을 값이 아닌 상태로만 보고했는가?
• 공개 페이지에서 내부 조작 문구와 공개 금지어를 확인했는가?
• validation, 품질 스캔, 업로드, revalidate, 라이브 스모크를 실제로 수행했는가?
• 실패한 항목을 성공처럼 포장하지 않았는가?
• 이번 run이 만든 임시 원본을 정리했는가?
• 다음 운영자가 이어받을 수 있는 중단 기준과 재개 조건을 남겼는가?

다음 단계

출력 계약은 모든 Hermes 자동화의 공통 언어가 될 수 있습니다. 콘텐츠 run, 배포 run, Q&A run, 품질 감사 run이 서로 다른 일을 해도 마지막 보고가 같은 구조를 가지면 운영자는 빠르게 비교하고 우선순위를 정할 수 있습니다. 다음 단계는 자주 반복되는 run별로 최소 출력 계약을 하나씩 정리하는 것입니다.

가장 먼저 DB-only 콘텐츠 run에 적용하고, 그다음 배포 검증 run, 모바일 원격 운영 보고, 크론 충돌 보고로 확장하면 좋습니다. 작은 계약이 쌓이면 헤르메스는 단순히 일을 많이 하는 에이전트가 아니라, 증거를 남기고 안전하게 멈출 줄 아는 운영 파트너가 됩니다.