이 글과 함께 보는 홈랩 구축 체크리스트 — 로컬 LLM + Tailscale 20단계를 A4 한 장으로. 받기 →

tstack: PR 병합까지 맡기는 코딩 에이전트 스킬 분해와 변경 증명 설계

홈랩 구축 체크리스트 — 로컬 LLM을 세우고 Tailscale로 안전하게 잇는 20단계를 A4 한 장으로 정리했습니다.
체크리스트 받기 →

tstack은 Theo Browne이 Claude Code와 Codex에서 매일 쓰는 워크플로우를 MIT 라이선스로 공개한 9종의 에이전트 스킬 묶음이다. 변경 증명, 리뷰 봇 대응, PR 병합까지를 코딩 에이전트가 사용자 개입 없이 수행하도록 설계되었다. 이 글은 하나의 긴 프롬프트 대신 에이전트 워크플로우를 단계별 스킬로 쪼갤 때, 각 단계의 완료 조건과 병합 게이트를 어디에 둘지 tstack의 구조를 기준으로 정리한다.

tstack의 구성: 9개 스킬과 의존 관계

모든 스킬은 PR을 아이디어에서 병합까지 끌고 가는 작업을 중심으로 한다. 각 스킬의 description은 "full send" 같은 짧은 문구에 반응하도록 작성되어 있어, 사용자는 스킬 이름을 외우지 않고 자연어 트리거로 호출한다.

스킬 호출 문구 역할
full-send "full send" 수정, 증명, 리뷰, PR 생성, 감시, 병합, 보고까지 무인 수행
full-stop "full stop" full-send와 같은 파이프라인이되 병합 직전에 멈춤
sol-loop "sol loop" 다른 제공자 모델과 두 에이전트가 합의할 때까지 반복 리뷰
council "council" 서로 다른 세 제공자의 모델이 병렬 리뷰하고 합의까지 반복
file-pr "file a PR" 변경 목록이 아니라 문제에서 시작하는 짧은 PR 작성
babysit-pr "babysit" CI와 리뷰 봇을 감시하고 실제 지적 사항만 수정
takeover "take over" 타인의 PR이나 브랜치를 원저자 크레딧을 유지하며 마무리
modernize "modernize" 오래된 PR을 리베이스하고 존속 가치를 판단
leaving-pr-comments 자동 적용 에이전트가 사용자 이름으로 남기는 댓글의 형식 지정

스킬 간 의존은 조합형이다. full-send는 sol-loop, file-pr, babysit-pr를 호출하고, full-stop은 full-send를 재사용하며, takeover는 modernize, file-pr, babysit-pr, leaving-pr-comments를 호출한다. 실행 전제는 인증된 gh CLI, babysit-pr의 대기 스크립트용 python3, 그리고 다른 제공자 모델을 서브에이전트로 띄울 수 있는 하네스다.

flowchart TD
    A["(1) 최소 수정"] --> B["(2) 변경 증명"]
    B --> C["(3) sol-loop 리뷰"]
    C --> D["(4) file-pr 생성"]
    D --> E["(5) babysit-pr 감시"]
    E --> F{"병합 게이트 통과?"}
    F -->|"아니오"| E
    F -->|"예: full-send"| G["(6) 병합"]
    F -->|"예: full-stop"| H["사용자 병합 대기"]
    G --> I["(7) 결과 보고"]

단계별 완료 조건의 위치

스킬을 쪼갤 때 핵심은 각 스킬이 "언제 끝났다고 말할 수 있는가"를 스스로 정의하게 하는 것이다. tstack은 완료 조건을 세 층으로 나눈다.

  • 파이프라인 층(full-send): 7단계를 모두 마치고 보고까지 해야 끝난다. 스킬은 턴을 끝내면 작업이 멈춘다는 점을 명시해, CI나 봇이 대기 중이면 에이전트가 계속 감시하도록 강제한다.
  • 리뷰 층(sol-loop, council): 두 에이전트 또는 세 위원이 합의해야 끝난다. council은 10점 만점 점수를 라운드별 표로 PR 설명에 남기고, 점수가 없는 위원은 "no score"로 적으며 값을 지어내지 않는다. 세 제공자에 접근할 수 없으면 대체하지 않고 실행 불가를 보고한다.
  • 작업 층(file-pr): PR 생성과 최신 기본 브랜치 기준 리베이스가 끝나면 끝난다.

완료 조건을 파이프라인에 몰지 않고 각 스킬에 분산하면, 개별 스킬을 단독으로 호출해도 종료 시점이 모호해지지 않는다. 다만 babysit-pr나 modernize처럼 공개된 설명에 종료 조건이 명시되지 않은 스킬은 실제 SKILL.md를 읽어 확인해야 한다.

변경 증명: 세션에서 직접 관찰한 증거

tstack에서 증명은 에이전트가 해당 세션에서 직접 관찰한 증거만 뜻한다. 선호 순서는 다음과 같다.

  1. 원래 문제를 재현하고, 수정 후 같은 재현이 통과하는지 확인한다.
  2. 저장소의 CI 체크(타입 검사, 린트, 테스트)를 실행한다.
  3. 수정 전에는 실패하고 수정 후에는 통과하는 테스트를 추가한다.
  4. UI나 실행 동작은 앱을 직접 띄워 확인한다. 모의 객체로 만든 녹색 테스트만으로는 사용자 경험이 동작한다는 증거가 되지 못한다.

검증 방법을 찾지 못하면 에이전트는 확신이 없다고 판단하고 사용자에게 질문한다. 증명이 "있다/없다"가 아니라 "diff 전체를 덮는가"로 판정되는 점이 병합 게이트와 연결된다.

병합 게이트: 최신 커밋 기준 다섯 조건

병합 게이트는 마지막 커밋 기준으로 다섯 조건을 모두 충족해야 열린다.

  • 증명이 diff 전체를 포함한다.
  • 필수 체크가 모두 통과한다.
  • 리뷰 봇이 끝났고, 지적 사항은 수정되었거나 이유와 함께 기각되었다.
  • 사람의 리뷰에 변경 요청이 없고 팀원이 막고 있지 않다.
  • 브랜치가 최신이며 GitHub가 병합 가능하다고 표시한다.

병합은 저장소의 기본 방식과 브랜치 보호 규칙을 따르고 --admin 같은 우회는 쓰지 않는다. 리베이스 후에는 --force-with-lease로 푸시할 수 있다. 게이트를 "최신 커밋 기준"으로 평가하는 이유는, 수정 푸시 이후 이전 커밋에서 받은 통과 결과가 무효가 되기 때문이다.

리뷰 봇 대응 설계

babysit-pr는 에이전트가 sleep 루프를 직접 만들지 못하게 하고, T3 Code에서는 watch_pull_request, 다른 하네스에서는 pr-wait 스크립트로 이벤트가 있을 때만 에이전트를 깨운다. 봇별 취급도 달라서, Greptile과 Macroscope는 기다리고 CodeRabbit은 참고용으로 두며 github-actions와 Vercel 댓글은 건너뛴다. 수정 기준은 실제 버그만 고치는 것이고, 불필요한 테스트, 일어나지 않을 경우를 위한 가드, 추가 호환성 코드는 이유를 적어 기각한다. sol-loop의 지적은 blocker, should, nit으로 나누며, 리뷰 후 diff가 커졌다면 먼저 줄인다.

도입 시 고려사항

  • GitHub 종속: GitLab이나 PR 없는 팀이라면 여러 부분을 다시 써야 한다.
  • 롤백 체계: full-send는 빠른 롤백이 있을 때 안전하다. 원저자는 6시간마다 nightly 빌드를 배포해 문제를 빨리 발견한다고 설명한다.
  • 수치의 해석: 32건 중 27건이 재확인 없이 병합되었다는 수치는 원저자의 로그 기준이며 일반화된 벤치마크가 아니다.
  • 자동 병합 위험: 사람의 검토가 필요하다는 자동 리뷰를 에이전트가 확신할 때 무시할 수 있다는 규칙은 팀 정책에 맞게 조정해야 한다. 처음에는 full-stop으로 시작해 신뢰가 쌓인 뒤 full-send로 넘어가는 편이 안전하다.

마무리

tstack은 PR 병합이라는 긴 작업을 증명, 리뷰, 감시, 병합의 스킬로 분해하고 각 단계에 종료 조건을 붙인 사례다. 핵심 설계는 세션에서 직접 관찰한 증거만 인정하는 변경 증명과, 최신 커밋 기준 다섯 조건으로 구성된 병합 게이트다. 병합 권한을 어디까지 위임할지는 full-stop과 full-send의 선택으로 조절할 수 있으므로, 팀의 롤백 능력에 맞춰 단계적으로 도입하는 것이 바람직하다.

Keywords

coding agent, agent skills, merge gate, proof of change, review bot, 코딩 에이전트, 에이전트 스킬, 병합 게이트, 변경 증명, 리뷰 봇

Sources

홈랩 구축 체크리스트를 A4 한 장으로 드립니다

로컬 LLM을 세우고 Tailscale로 안전하게 잇는 20단계. 이메일을 남기면 바로 보내드립니다. 광고 없이, 언제든 수신거부.

체크리스트 받기 →

+ Recent posts