2026-11-18 기준으로 고쳤습니다. 처음 쓴 날은 2026-08-04 이고, 명령과 옵션은 Claude Code 2.1.326 에서 확인했습니다.
Claude Code 실전 가이드 마지막 5편입니다. 1편에서 시작하기와 CLAUDE.md, 2편에서 컨텍스트 관리, 3편에서 서브에이전트와 병렬 처리, 4편에서 MCP 로 인프라를 도구화하는 이야기를 했습니다. 이번 편은 그 넷을 한 루프로 묶습니다. 이슈 하나를 등록하는 순간부터 실제로 배포된 서비스를 URL 로 확인하는 순간까지 사람 개입 없이 얼마나 돌릴 수 있는지 — 그리고 어디서는 반드시 사람이 서명해야 하는지를 정리합니다.
실제로 도는 루프
제가 지금 쓰는 루프는 대략 이렇습니다.
- GitLab 이슈 등록 (누가 결과를 판정하는지 본문에 포함)
- 배치 브랜치 생성 (
batch/claude-<날짜>-<8자리 hex>. 다른 에이전트와 겹칠 때만 worktree 에서) - 구현
- 타입체크·빌드 로컬 검증
- 이슈별로 커밋 (제목
[<모델>] <type>: <설명> (#N), 작성자는 에이전트 전용 계정) - MR 생성, 본문에
Closes #N포함 - CI 파이프라인을 끝까지 폴링
- 통과하면 merge commit 으로 머지 (squash 하지 않음)
- 머지 후 배포 파이프라인이 따로 있으면 그것도 끝까지 폴링
- 배포된 실물에서 방금 머지한 커밋이 서비스되고 있는지 확인
- 정리 (기본 브랜치로 돌아와 로컬 브랜치 삭제, worktree 를 썼다면 remove)
- 완료 알림 (Stop 훅이 알림 큐에 넣고, 디스코드로 도착)
이 열두 단계 중 사람이 미리 승인해야 하는 건 처음 한 번뿐입니다. “이 이슈 해도 됨” 이라는 신호가 떨어지면, 실패해서 되돌아오지 않는 한 사람이 다시 개입할 지점이 없습니다. 그런데 이 마지막 문장이 이번 편의 핵심입니다. “실패해서 되돌아오지 않는 한” 을 보장하는 게 자율주행에서 제일 어려운 부분입니다.
연재를 쓴 2026-08 과 달라진 점이 세 가지 있습니다. 첫째, 브랜치는 이슈마다가 아니라 세션 단위로 하나를 만들고 MR 하나로 묶습니다. 둘째, squash 대신 merge commit 으로 머지합니다. 이슈별 커밋이 이력에 그대로 남아야 이슈 하나만 git revert 로 되돌릴 수 있기 때문입니다. 셋째, 이슈 등록부터 머지 뒤 CI 추적까지는 스킬 하나(yd-git-ship)에 들어 있습니다. 전역 지침에는 핵심 규칙 몇 줄과 “git/GitLab 에 올릴 때는 이 스킬을 쓴다"는 포인터만 둡니다. 커밋 제목 형식은 레포마다 설치한 commit-msg 훅이 검사합니다.
사람이 서명해야 하는 지점
몇 번 사고를 겪고 나서 정리한 경계입니다.
시작 승인은 사람 — 이슈를 만드는 것과 그 이슈에 착수하는 것은 별개입니다. 이슈 등록까지는 자동으로 해도 되지만, “이거 지금 진행해” 라는 명시적 신호(번호 지정이든 “ㄱㄱ” 든) 없이 바로 코드를 건드리기 시작하면 안 됩니다. 특히 범위가 처음 이슈보다 커질 것 같으면(파일 몇 개 고칠 줄 알았는데 스키마까지 건드려야 한다든가) 거기서 한 번 더 확인받는 게 낫습니다. 자동 진행 자체가 문제가 아니라, 스코프가 조용히 불어나는데 사람이 모르고 넘어가는 게 문제입니다.
파괴적 작업은 항상 사람 — git push --force, git reset --hard, 프로덕션 DB 의 삭제성 쿼리, 서비스 강제 재시작 같은 건 루프 안에 있어도 자동 실행 대상이 아닙니다. 되돌릴 수 없는 조작과 되돌릴 수 있는 조작을 구분해서, 후자만 자율주행 범위에 넣는 게 기준입니다. 공식 문서도 CLAUDE.md 는 강제 설정이 아니라 맥락이라고 적습니다. 꼭 막아야 하는 동작은 PreToolUse 훅(도구 실행 직전에 도는 훅)으로 막으라고 안내합니다. 제 작업 호스트 가운데 한 곳에는 이 훅을 걸어, force push·commit --amend·reset --hard·rebase·branch -D·clean -f 를 실행 전에 거부합니다. 정말 필요하면 에이전트는 명령만 보여 주고, 실행은 사람 몫입니다.
prod 인프라 변경은 정확한 명령을 사람에게 넘기는 게 기본 — 셀프호스팅 환경이다 보니 “배포” 안에 실제로는 서버 설정 변경, 리버스프록시 룰 수정처럼 되돌리기 까다로운 작업이 섞여 있을 수 있습니다. 애플리케이션 코드 배포 파이프라인은 CI 가 검증하고 자동으로 흘러가도 됩니다. 하지만 그 파이프라인 자체를 바꾸는 일(새 서비스 추가, nginx 설정, systemd 유닛 변경)은 별도 확인 대상으로 뗍니다.
맡겨도 되는 지점
반대로 실패해도 되돌리기 쉽고, 검증 가능한 구간은 사람이 매번 지켜볼 필요가 없습니다.
- 브랜치 생성, 커밋, MR 생성 — 전부 로컬/원격에서 되돌리기 쉬운 조작입니다.
- 타입체크·빌드·린트 — 실패해도 실패 상태로 남을 뿐 아무것도 망가뜨리지 않습니다.
- CI 파이프라인 대기 — 폴링 자체는 읽기 전용 조회입니다.
- merge commit 머지 — MR 을 되돌릴 수 있고(revert), 이슈별 커밋 단위로도 되돌립니다.
- 워크트리 정리 — 로컬 작업 디렉터리 정리는 원격에 아무 영향이 없습니다.
- 완료 알림 큐 insert — 알림 테이블에 행 하나 넣는 것뿐이라 위험이 없습니다.
이 구분의 기준은 결국 하나입니다. “잘못됐을 때 원상복구가 쉬운가.” 쉬우면 자동으로 흘러가게 두고, 어려우면 그 앞에서 멈춥니다.
자율주행이 무너지는 전형적 패턴
몇 번 겪어본 실패 패턴입니다.
검증 없이 완료 보고
CI 큐에 파이프라인이 등록된 걸 보고 “MR 올렸습니다” 라고 끝내버리는 패턴입니다. 파이프라인은 등록된 것과 통과한 것이 다릅니다. 등록만 확인하고 손을 떼면, 그 뒤에 타입 에러나 테스트 실패로 막혀 있어도 아무도 모릅니다. CI 는 트리거한 뒤 끝까지 폴링해서 성공 또는 실패를 실제로 확인해야 합니다. 특히 머지 뒤에 별도 배포 파이프라인이 있다면 MR 의 head 커밋 SHA 로 폴링하면 안 됩니다. merge commit 이든 squash 든 머지가 끝나면 기본 브랜치에 새 커밋 SHA 가 하나 생깁니다. 배포 파이프라인은 그 SHA 를 기준으로 돌기 때문에, head SHA 로만 계속 지켜보면 검증 단계만 성공으로 보이고 배포는 영원히 안 뜹니다.
폴링 방식 자체도 한 번 데인 적이 있습니다. 상태 조회 명령을 매번 새 프로세스로 띄우는 셸 루프는 중간에 한 번 실패하면 거기서 끊깁니다. 조회와 종료 조건 판정을 한 프로세스 안에서 도는 스크립트로 만들어두는 편이 안정적이었습니다. 그 스크립트를 백그라운드로 돌릴 때도 셸에서 완전히 떼어내면(disown) 세션 쪽에서 종료를 감지하지 못해 “다 됐다” 는 신호가 영영 안 옵니다. 폴링은 붙잡아 두고 끝을 봐야 하는 작업입니다.
머지됐다고 이슈가 자동으로 닫혔다고 단정
MR 본문에 Closes #N 을 넣어두면 머지 시점에 이슈가 자동으로 닫힙니다. 제 셀프호스팅 GitLab 에서도 실제로 자동 클로즈가 동작하는 걸 확인했습니다. 문제는 이 동작이 트래커 설정과 머지 방식에 따라 달라질 수 있다는 점입니다. 한 번 확인한 결과를 계속 사실로 들고 다니는 게 위험합니다. 그래서 루프에는 “머지 직후 이슈 상태를 조회한다” 를 그대로 남겨뒀습니다. 닫혀 있으면 거기서 끝이고, 열려 있으면 그 자리에서 코멘트를 남기고 수동으로 닫습니다. 확인 한 번에 드는 비용은 조회 한 번인데, 안 하면 처리된 이슈가 열린 채로 조용히 쌓입니다.
브랜치 확인 없이 main 에 커밋
세션 도중 어떤 자동화 절차가 기본 브랜치로 checkout+pull 을 해버리면, 작업 브랜치를 만들어놓고도 커밋이 기본 브랜치 위에 얹힙니다. 3편에서 다룬 worktree 를 쓰면 이 사고가 구조적으로 줄지만, 지금은 혼자 하는 작업을 정식 클론에서 하므로 그 보호가 늘 있지는 않습니다. 루프 관점에서 중요한 건 그다음입니다. 자율주행 루프는 “커밋 → MR → CI” 가 한 호흡으로 이어지기 때문에, 커밋 대상이 틀렸다는 사실이 CI 가 엉뚱한 브랜치에서 돌기 시작한 뒤에야 드러납니다. 그래서 커밋 직전에 현재 브랜치를 한 번 확인하는 단계를 루프 안에 넣어뒀습니다. 사람이 지켜보는 작업이면 눈에 띄었을 실수가, 무인 구간에서는 몇 단계 뒤에야 드러난다는 게 자율주행의 대가입니다.
SHA 가 다른 걸 보고 유실됐다고 단정
squash 머지를 쓰던 때 겪은 일입니다. squash 머지하면 작업 브랜치의 커밋이 기본 브랜치에서는 새 커밋 하나로 합쳐집니다. 이때 원래 커밋 SHA 는 기본 브랜치 이력에 없습니다. SHA 비교나 git log A..B 만 보고 “커밋이 사라졌다” 고 판단하면 멀쩡한 머지를 되돌리는 사고로 이어집니다. SHA 가 다르다는 건 SHA 가 다르다는 뜻일 뿐이고, 확인해야 하는 건 내용입니다. git show --stat <머지커밋> 으로 파일 목록을 보고, 의심되면 실제 파일 내용을 열어서 변경분이 들어갔는지 확인하는 게 맞습니다. 지금은 merge commit 으로 머지해서 작업 브랜치의 커밋이 그대로 남습니다. 그래도 머지를 검증하는 기준은 여전히 SHA 가 아니라 내용입니다.
낡은 전제를 확인 없이 사용
2편에서 영속 메모리가 낡는다는 이야기를 했는데, 무인 루프에서는 그 대가가 더 큽니다. “이 레포의 배포는 이 브랜치에서 돈다”, “이 서비스는 이 포트를 쓴다” 같은 전제가 하나 어긋나면 틀렸다는 게 몇 단계 더 진행된 뒤에야 드러납니다. 사람이 중간에 화면을 보고 있지 않으니 그 전제 위에서 작업이 계속 흘러가기 때문입니다. 루프를 돌리기 전에 이번에 쓸 전제 한두 개(배포 대상 브랜치, 확인할 엔드포인트)는 파일이나 설정으로 한 번 확인하고 들어가는 편이 결국 빠릅니다.
실물 확인이 마지막 관문인 이유
CI 가 통과하고 배포 파이프라인도 성공으로 끝났다고 해서 작업이 끝난 게 아닙니다. 캐시가 안 갱신됐거나, 리버스프록시가 이전 컨테이너를 계속 물고 있거나, 정적 자산 경로가 어긋나 있는 경우가 실제로 있었습니다. 파이프라인의 성공 상태는 “배포 절차가 끝까지 실행됐다” 는 증거이지 “지금 서비스되는 게 내 변경분이다” 는 증거가 아닙니다.
그래서 루프의 마지막 검증은 배포된 실물에서 직접 얻은 증거로 둡니다. 사람이라면 브라우저로 열어보고 끝낼 일입니다. 하지만 무인 루프에는 눈으로 보는 단계가 없으니 기계가 판정할 수 있는 형태여야 합니다. 다음 절은 그걸 어떻게 만들어뒀는지 다룹니다.
실사례 — 이 블로그 레포의 한 바퀴
지금 이 글이 올라와 있는 레포가 그 루프를 그대로 씁니다. GitLab CI 는 스테이지가 둘뿐입니다. validate 는 컨테이너 이미지를 빌드하고, 그 빌드 안에서 Hugo 빌드와 Go 검사(gofmt·go vet·go test)를 돌립니다. 기본 브랜치에 푸시가 들어왔을 때만 deploy 가 붙습니다. 배포 스크립트는 운영 호스트의 러너에서 컨테이너 이미지를 빌드하고, Quadlet 유닛을 설치합니다. 이어서 사용자 systemd 서비스를 재시작하고, 헬스 엔드포인트가 200 을 돌려줄 때까지 기다립니다. 여기까지 실패하면 배포 잡 자체가 실패로 끝나서 루프가 그 자리에 멈춥니다.
무인 루프에서 실제로 도움이 된 건 커밋 SHA 를 .app_version 파일로 이미지에 넣고, 애플리케이션이 그걸 헬스 응답에 그대로 노출하게 만든 부분입니다.
curl -s http://127.0.0.1:<포트>/api/health
# {"status":"ok","uptime":41.6,"version":"001fb9a"}
이 version 이 방금 머지된 커밋 SHA 와 같으면, 지금 트래픽을 받는 컨테이너가 내 변경분으로 빌드됐다는 게 한 줄로 증명됩니다. “파이프라인이 초록색이다” 와는 증명력이 다릅니다. 배포 스크립트 자체가 /healthz 의 200 을 재시도하며 기다린 뒤, 이 version 을 방금 빌드한 커밋과 비교합니다. 그래서 컨테이너가 뜨다 말았거나 이전 이미지가 그대로 살아 있으면 잡 실패로 드러납니다.
연재를 쓴 2026-08 에 작업 하나가 이 루프를 돈 모습은 이렇습니다. 기술스택 글에 레포 전체 언어 분포를 덧붙이는 이슈(#13)를 등록합니다. feat/13-blog-tech-stack-repos 브랜치를 워크트리로 따서 글을 고치고, 커밋 제목에 이슈 번호를 박고, MR 을 올려 validate 통과를 확인한 뒤 squash 머지합니다. 머지되면 기본 브랜치에서 deploy 가 돌고, 헬스 응답의 version 이 새 SHA 로 바뀐 걸 확인합니다. 그 자리에서 워크트리와 로컬 브랜치를 지우고, 알림 큐에 완료 레코드를 넣습니다. 사람이 개입한 지점은 맨 처음 “이거 진행” 한 번입니다.
지금은 브랜치와 머지 방식이 다릅니다. 2026-11-18 에 올린 블로그 글(#44)은 batch/claude-20261118-0568ff82 브랜치에서 커밋 하나로 작업했습니다. 커밋 제목은 [Claude Fable 5.2] docs: 블로그 글 추가 — Go 와 Rust 를 쓰면 좋은 점 (#44) 이고, 작성자는 에이전트 전용 계정입니다. MR 본문의 Closes #44 로 머지 때 이슈가 닫혔고, 머지는 merge commit 369b5ff 로 남았습니다. 다음 배포 전에 헬스 응답을 조회하니 version 이 369b5ffc 였습니다. 그때 트래픽을 받던 컨테이너가 그 머지 커밋으로 빌드됐다는 뜻입니다.
알림은 나중에 읽어도 이해되게 쓴다
루프의 마지막 단계인 알림은 사소해 보이지만 실제로 제일 자주 손본 부분입니다. 초기에는 “배포 완료” 같은 한 줄만 큐에 넣었습니다. 그런데 몇 시간 뒤 텔레그램에서 그 알림을 보면 무슨 작업이었는지 알 수가 없었습니다. 그 세션의 대화 맥락 없이 읽는다는 걸 감안하지 않은 겁니다.
그 뒤로는 알림 하나에 무슨 작업이었는지(제목), 어느 레포의 어느 이슈·MR 이었고 결과가 무엇인지, 남은 후속 조치가 있는지를 줄로 나눠 담았습니다. 약어나 내부 코드명은 풀어서 썼고, 이 형식을 전역 CLAUDE.md 에 규칙으로 두었습니다.
2026-11-18 지금은 방식이 바뀌었습니다. 알림은 이제 에이전트가 아니라 Claude Code 의 Stop 훅이 씁니다. Stop 훅은 응답이 끝날 때마다 도는 훅입니다. 훅은 마지막 요청과 응답을 로컬 LLM 에 넘겨 45자 안팎의 한 문장으로 요약합니다. 그 앞에 [레포 이름] 을 붙여 큐에 넣고, 알림은 레포별 디스코드 채널로 옵니다. 그 레포 채널이 없으면 기본 채널로 갑니다. 알림 형식 규칙은 전역 지침에서 빠졌습니다. 무인으로 도는 루프일수록 사람이 보는 창구는 이 알림 하나뿐입니다. 여기서 요약이 부실하면 자동화 결과를 사람이 확인할 방법이 사라집니다.
시리즈를 관통하는 원칙
다섯 편을 쓰면서 반복해서 확인한 건 결국 하나입니다. 에이전트에게 넘겨도 되는 일과 사람이 서명해야 하는 일의 경계는 “되돌릴 수 있는가” 로 갈린다는 것입니다.
- CLAUDE.md(1편)는 그 경계와 규율을 매 세션 처음부터 다시 설명하지 않기 위한 장치입니다.
- 컨텍스트 관리(2편)는 그 경계를 판단할 때 필요한 정보가 실제로 에이전트 눈앞에 있게 만드는 일입니다.
- 서브에이전트와 병렬 처리(3편)는 독립된 일을 동시에 처리해 속도를 내되, 서로 다른 작업이 같은 자리를 밟지 않게 격리하는 문제입니다.
- MCP(4편)는 에이전트가 추측이 아니라 실제 도구 호출로 사실을 확인하게 만드는 통로입니다.
- 이번 5편의 자율주행 루프는 그 넷을 다 갖췄을 때 비로소 “이슈에서 배포까지” 를 사람 개입 최소로 돌릴 수 있다는 걸 보여주는 자리였습니다. 동시에 그 자동화가 무너지는 지점 — 검증 생략, 상태 오판, 낡은 가정 — 을 어디서 끊어야 하는지 정리하는 자리이기도 했습니다.
자율주행이라는 말이 주는 인상과 달리, 실제로 안정적으로 도는 루프는 “사람 없이 다 한다” 가 아니라 “사람이 봐야 할 지점만 정확히 남기고 나머지를 걷어낸다” 에 가깝습니다. 그 경계를 코드와 CLAUDE.md 에 명시적으로 박아두는 일이, 다섯 편에 걸쳐 결국 하고 싶었던 이야기입니다.
Codex 와 agy(구글 Antigravity CLI)에서 같은 경계를 긋는 법은 자매 연재에서 이어 갑니다. Codex 실전 가이드와 agy 실전 가이드입니다.