예약 실행 코딩 에이전트: 스모크 테스트와 큐에 세우는 병합

정해진 시각에 일을 시작하는 예약 실행의 실제 성격, 격리된 실행과 스모크 테스트, 제안에서 큐가 끝내는 병합까지 밤사이 맡기는 일의 뼈대를 정리한 개념 글이다.

고친 내용: 초판

문제: 밤사이 맡긴 일의 아침

코딩 에이전트에 밤사이 일을 맡기는 선택이 있다. 아침에 와서 보면 고침이 나와 있고, 사람은 검토만 하면 된다. 말로는 깔끔하지만 아침의 모습은 제각각이다. 일이 시작조차 안 했거나, 중간에 멈췄거나, 고침은 나왔으되 믿을 수 없거나, 믿을 만한데 병합의 차례를 기다리는 경우도 있다.

이 글은 밤사이 맡기기를 한 기술이 아니라 여러 겹의 설계로 본다. 정해진 시각에 일을 시작하는 예약, 일을 돌리는 실행 자리, 고침이 도는지를 보는 스모크 테스트, 변경을 제안하는 풀 리퀘스트, 사람의 승인 뒤 큐가 끝내는 병합이다. 예약의 실행은 될 수 있을 때 돌리는 최선형이며, 정시를 보장하지 않는다. 각 겹의 실제 성격을 알면 아침의 경우의 수가 읽힌다.

이 절의 근거 S36 · S38 · S32 · S33 · S34

예약의 실제 성격: 약속이 아니라 소망에 가깝다

GitHub Actions의 schedule은 cron으로 시각을 정한다. 다섯 칸의 POSIX cron 서식이며, 기본은 UTC이고 시간대를 고를 수도 있다. 가장 짧은 간격은 5분이다. 예약 흐름은 기본 브랜치의 최신 커밋에서 돈다.

그러나 예약은 정시를 보장하지 않는다. 문서가 적는 주의가 세 가지다. 첫째, 실행이 몰리는 때에는 예약이 늦어질 수 있고, 부하가 크면 줄 서 있던 일이 떨어질 수도 있다. 매시 정각 같은 몰리는 때를 피하라는 것이다. 둘째, 예약 흐름은 기본 브랜치에서만 돈다. 셋째, 공개 저장소에서 60일 동안 움직임이 없으면 예약이 자동으로 꺼진다. 정시에 시작한다는 믿음 위에 설계를 얹으면, 늦은 아침부터 설계가 어긋난다.

이 절의 근거 S36

실행 자리와 격리: 누구의 기계에서 도는가

일은 실행기에서 돈다. 깃허브가 주는 실행기도 있고, 팀이 직접 두는 셀프호스티드 실행기도 있다. 직접 둘 때는 저장소나 조직, 기업 단위로 달 수 있으며, 달기 전에 그 기계를 쓸 수 있어야 한다.

격리의 핵심은 문서의 경고에 있다. 포크한 공개 저장소의 풀 리퀘스트가 셀프호스티드 실행기에서 위험한 코드를 돌릴 수 있으므로, 셀프호스티드 실행기는 비공개 저장소에만 쓰라고 권한다. 믿을 수 없는 코드와 비밀, 그리고 실행기가 한 자리에 모이면 사고가 난다. 어느 비밀을 주고 어느 권한으로 돌릴지, 실패한 자리를 어떻게 치울지를 정하는 일은 팀의 설계 몫이다. 격리는 도구의 기본값이 아니라 팀의 결정이다.

이 절의 근거 S37

스모크 테스트: 고른 핵심 경로의 기대 동작부터 본다

밤사이 난 고침이 도는지를 보는 가장 싼 방법이 스모크 테스트다. Playwright의 프로젝트는 같은 설정의 묶음이다. 브라우저와 기기, 로그인 여부와 환경, 타임아웃과 재시도를 묶음마다 다르게 두고, 전체를 돌리거나 특정 묶음만 돌릴 수 있다. 문서의 예시는 Smoke 묶음이 작은 부분집합을 재시도 없이 돌리고, 기본 묶음이 나머지를 재시도와 함께 도는 모양이다.

준비 일의 분리도 된다. 프로젝트 의존으로 setup 묶음을 먼저 돌리게 하여 로그인 같은 준비를 묶음 밖으로 뺀다. 스모크의 자리는 분명하다. 고른 핵심 경로가 도는지, 기대한 대로 동작하는지부터 빨리 보고, 깨진 아침을 일찍 알리는 일이다. 다만 고른 묶음의 범위를 벗어나면 보지 못하므로, 전체가 옳다는 증명이 되지는 않는다. 범위의 한계를 알면서 쓰는 것이 스모크다.

이 절의 근거 S38

제안과 검토: 에이전트의 산출물은 제안이다

에이전트가 밤사이 낸 고침은 병합이 아니라 제안이다. 풀 리퀘스트의 자리에서 대화와 검사와 바뀐 파일이 모이고, 사람은 그 제안을 읽고 논한다. 초안으로 내면 병합할 수 없으며 코드 소유자에게 자동으로 검토를 청하지도 않으므로, 사람의 눈이 필요할 때는 정식으로 내어 소유자의 검토를 청한다.

검토의 강제 조건은 보호 브랜치가 맡는다. 승인 수와 코드 소유자, 낡은 승인의 기각, 상태 검사와 대화 해결이다. 에이전트가 낸 제안이라고 조건이 가벼워지지 않는다. 오히려 낸 주체가 사람이 아니므로, 승인 수와 소유자 검토를 그대로 두는 편이 안전하다. 이 판단은 이 글의 편집자 관점이다.

이 절의 근거 S32 · S33

보호된 병합과 재시도: 큐가 끝내는 일

병합의 끝은 큐가 맡는다. 바쁜 기본 브랜치라면, 사람은 풀 리퀘스트를 읽고 승인한 뒤 쓰기 권한으로 머지 큐에 넣는다. 큐는 목표 브랜치의 최신과 줄 앞의 변경을 합친 상태로 검사를 돌리고, 정해둔 요구 검사가 모두 통과하면 자동으로 병합한다. 사람이 직접 병합 단추를 누르는 자리가 아니다. GitHub Actions로 요구 검사를 구현한 흐름은 merge_group 사건을 추가로 걸어야 하며, 빠뜨리면 검사가 보고되지 않아 큐가 멈춘다. 제삼자 CI는 gh-readonly-queue/로 시작하는 임시 브랜치에 밀려 올라오는 커밋에 반응하게 맞춘다. 자동화의 역할은 정의한 검사 범위에서 합친 상태가 도는지를 확인하는 일에 머문다.

재시도 정책은 팀의 선택이다. 실패한 예약을 곧바로 다시 돌릴지, 아침에 사람이 보고 돌릴지, 몇 번까지 돌릴지는 정해진 답이 없다. 다만 정하지 않은 재시도는 두 가지로 망가진다. 돌리지 않아 아침이 비는 경우와, 무한히 돌려 자원과 비밀을 쓰는 경우다. 재시도의 횟수와 간격, 멈춤의 조건을 미리 적어두는 일이 예약 설계의 일부다.

이 절의 근거 S34

따라가기: 가상의 새벽 흐름

아래는 실행하지 않은 가상의 따라가기다. 어떤 팀은 평일 새벽에 작은 고침 일을 맡긴다. 예약은 사람이 적은 시각을 골라 cron으로 걸고, 실행은 격리된 자리에서 최소 권한으로 돈다. 에이전트는 고침을 내고 스모크 묶음을 먼저 돌리며, 스모크가 깨지면 그 자리에서 멈추고 아침의 기록에 남긴다. 아래 코드는 워크플로 전체가 아니라 on 아래 schedule을 꺼낸 실행 조건 발췌이며, 실제 일을 정의하는 부분은 생략했다.

스모크를 통과한 고침만 풀 리퀘스트로 정식 제안되고, 코드 소유자의 승인과 상태 검사를 거쳐 쓰기 권한이 있는 사람이 머지 큐에 넣는다. 정해둔 요구 검사가 모두 통과하면 큐가 자동으로 병합한다. 아침의 확인 순서는 정해져 있다. 예약이 제때 시작했는지, 실행이 멈춘 곳은 없는지, 스모크의 결과가 무엇인지, 제안이 검토를 받았는지다. 검증되지 않은 속도·성능 주장은 이 따라가기에 없다. 잴 수 있는 것은 기다림과 통과율과 사람의 손이 간 시간뿐이다.

on:
  schedule:
    - cron: "20 4 * * 1-5"

실패 양상과 한계

밤사이 맡기기의 실패는 겹마다 다르다. 예약은 늦거나 떨어지고, 실행 자리는 권한과 비밀의 사고가 나며, 스모크는 범위를 벗어난 고장을 못 보고, 제안은 검토 없이 쌓이며, 병합은 큐에서 멈춘다. 어느 겹의 실패인지 알려면 겹마다 기록이 있어야 하며, 예약의 시작 시각과 실행의 끝, 스모크의 결과와 제안의 상태가 한눈에 보여야 한다.

한계도 분명하다. 스모크의 통과는 고른 핵심 경로가 기대대로 동작한다는 뜻이지, 전체가 옳다는 증명이 아니다. 스모크는 정해둔 묶음의 범위만 보며, 범위 밖의 고장은 못 본다. 예약의 정시는 보장이 아니라 기대다. 그리고 사람의 검토와 승인은 그대로 남는다. 큐가 자동으로 병합해도 검토의 속도를 대신하지 못하므로, 밤사이의 속도를 낮의 검토가 따라가지 못하면 제안이 쌓여 아침이 무거워진다. 맡기는 일의 범위를 검토의 속도에 맞추는 일이 설계의 핵심이다.

이 절의 근거 S36 · S37 · S38 · S32 · S34

측정과 검증 계획

맡기는 팀은 다음을 잰다. 예약의 정시 시작률(제때 시작한 예약이 전체 예약에서 차지하는 비율), 실행의 완주율(끝까지 돈 실행의 비율), 스모크의 적중률(실제 고장을 잡아낸 스모크 실패의 비율), 제안의 병합률(병합까지 간 제안의 비율), 그리고 사람의 손이 간 시간이다. 특히 사람의 손이 간 시간은 자동화의 최종 점수다. 그 시간이 줄지 않으면 밤사이의 일은 사람의 일을 미룬 것에 불과하다.

검증의 또 다른 축은 사고의 기록이다. 권한 밖의 접근이 있었는지, 비밀이 새지는 않았는지, 떨어진 예약이 있었는지를 본다. 사고 없이 돈다는 것은 사고가 없다는 뜻이 아니라 사고를 못 본다는 뜻일 수 있으므로, 감시의 눈을 먼저 둔다.

결론: 맡기되, 눈을 떼지 않는다

이 글의 원칙은 세 마디다. 예약의 성격을 알고, 격리된 자리에서 최소로 돌리며, 사람의 승인 뒤 큐의 자동 병합으로 끝낸다. 스모크는 도는지를 빨리 보고, 기록은 겹마다 남긴다.

재시도의 횟수와 맡기는 일의 범위는 팀의 선택이다. 서가가 줄 수 있는 것은 횟수가 아니라 횟수를 정하는 기준뿐이다. 예약과 실행의 낮 시간 버전은 도메인 경계 글에, 병합 앞의 문지기는 검토 게이트 글에 있으니 함께 읽기를 권한다.