Hermes PR Auto-Review · 개발자 가이드

Hermes Agent · 개발자 가이드

PR 코드 리뷰를 자동화하는 방법
— Hermes `pr-auto-review` lane

GitHub PR 이벤트를 받아 코드 리뷰 초안 작성 → 독립 검증 → 한국어 댓글 자동 게시까지 처리하고, 최종 Approve만 사람이 결정하는 자동 리뷰 파이프라인. 이 문서는 그 동작 원리와 설계 결정을 개발자 관점에서 설명합니다.

Board: pr-auto-review Intake: GitHub Webhook → Hookdeck State: Hermes Kanban (SQLite) 업데이트 2026-06-12

Overview

한 줄 요약

PR이 올라오거나 head가 바뀌면 봇이 알아서 리뷰하고, 확신 있는 지적만 PR 작성자를 멘션해 한국어 댓글로 답니다. 모든 상태·기록은 Kanban DB에 남고, merge를 푸는 APPROVE는 운영자가 직접 카드를 Unblock해야만 실행됩니다.

🎯

실제 metadata 기반

항상 gh pr view로 최신 head·base를 재조회한다. base를 main/master로 가정하지 않는다.

🇰🇷

한국어 수정 지향 댓글

PR author를 직접 멘션하고, 무엇을 어떻게 고칠지 fix direction을 담아 자동 게시.

🔒

high-confidence만 공개

불확실한 finding은 Kanban 내부에만 보관. style-only nit은 게시하지 않는다.

🔁

follow-up 재분류

댓글 이후 새 commit/comment가 생기면 finding 상태를 다시 분류한다.

🙋

Approve는 사람이

GitHub APPROVE는 절대 자동화하지 않는다. 운영자 Unblock이 있을 때만 수행.

📋

전부 감사 기록

모든 상태 전이·댓글·이벤트·실행 결과를 Hermes Kanban DB에 영구 보관.

Architecture

전체 데이터 플로우

PR 수집(intake)은 LLM 없이 결정론적으로 처리하고, LLM은 Kanban worker 단계에서만 호출됩니다. 비용·지연·불안정성을 intake 경로에서 떼어낸 구조입니다.

① Webhook intake (primary · LLM 없음)

GitHub PR event→ Hookdeck Source→ event_receiver.py
localhost · HMAC 검증 · 202 즉시 응답→ event_router.py
dedupe · allowlist · gh pr view→ Kanban board

② Kanban workers (여기서만 LLM 실행)

prreviewer→ prverifier→ prcommenter→ follow-up monitor→ prapprover 🔒

③ Cron fallback (webhook 누락 대비 · 결정론적)

tick.py 10m · flock 직렬· poller fallback 60m· workspace GC 30m

💡

왜 Hookdeck + 로컬 receiver인가? GitHub webhook마다 LLM run을 만들면 비용·지연·불안정성이 커집니다. intake는 payload 검증 + Kanban 카드 생성만 결정론적으로 하고(ADR-001), 실제 코드 리뷰 판단만 LLM worker에게 넘깁니다.

Workers

5개 역할로 분리된 파이프라인

각 단계를 별도 Hermes profile로 나눠 책임을 분리했습니다. 리뷰 초안과 검증을 다른 worker가 맡아 독립 검증(adversarial verify)이 성립합니다.

Profile	역할	핵심 동작
`prmonitor`	인프라 운영	webhook receiver · router · maintenance tick · poller fallback 실행 (LLM 없음)
`prreviewer`	리뷰 초안	격리된 worktree에서 최신 PR head를 점검하고 high-confidence finding 또는 LGTM 작성
`prverifier`	독립 검증	reviewer가 만든 finding을 별도로 재검증. 통과한 것만 게시 대상
`prcommenter`	댓글 게시	검증된 finding을 한국어·author 멘션·수정 지향 댓글로 GitHub에 게시
`prapprover` 🔒	승인 gate	운영자가 approve 카드를 `Unblock`한 경우에만 `gh pr review --approve` 수행

대상 repo allowlist

router가 webhook payload의 repository.full_name으로 대상 여부를 판단합니다(ADR-002). 현재 여러 개의 client repo가 하나의 shared board를 공유하며, 대상은 allowlist로 관리됩니다.

allowlist 기반 라우팅 shared board repository.full_name 매칭

Lifecycle

하나의 PR이 거치는 단계

PR 이벤트 또는 head 변경 감지부터 Approve gate, archive까지의 Kanban task 생명주기입니다.

intake

Root / Review 카드 생성

PR event 또는 poller가 새 head를 감지하면 root metadata 카드를 ensure하고, 해당 head 기준 review 카드를 만든다.

prreviewer

격리 worktree에서 리뷰

최신 PR head를 detached git worktree에 펼쳐 점검(ADR-009). high-confidence finding 초안 또는 LGTM 결과를 낸다. target repo는 read-only.

prverifier

finding 독립 검증

finding이 있으면 별도 worker가 재검증한다. 검증을 통과해야 게시 후보가 된다.

prcommenter

한국어 댓글 자동 게시

검증된 finding을 PR author 멘션·수정 지향 한국어 댓글로 게시. 게시 직전 최신 headRefOid를 재확인하고, 바뀌었으면 재검토.

monitor

follow-up 추적

새 commit/comment/review를 감시하고, closure verifier가 finding 상태를 재분류(해결/미해결).

LGTM

open finding 없음 → 최종 요약

open finding이 모두 닫히면 LGTM final-summary 카드를 만든다.

approve gate 🔒

blocked approve 카드 생성

prapprover 카드는 blocked·unassigned로 생성된다. 운영자 Unblock 전까지 아무 일도 일어나지 않는다.

prapprover

Unblock 시 재검증 후 Approve

운영자가 Unblock하면 최신 metadata/head/checks를 재조회하고, 조건을 모두 만족할 때만 gh pr review --approve. 이후 done cleanup이 카드를 archive.

Comment vs Approve

댓글은 자동, Approve는 사람 게이트

자동화 가치가 큰 댓글은 빠르게 자동 게시하고, merge unblock side-effect가 큰 Approve는 사람이 최종 결정합니다(ADR-005).

댓글 게시 AUTO

verifier-confirmed finding만 게시
한국어 · PR author 직접 멘션
fix direction(어떻게 고칠지) 포함
idempotency marker로 중복 게시 방지
latest head 변경 시 게시 보류 후 재검토

GitHub Approve HUMAN-GATED

approve 카드는 blocked·unassigned로 생성
운영자 Unblock 이벤트가 있어야만 실행
실행 직전 head·open finding·stale·required checks·중복 승인 재확인
조건 미충족 시 approve하지 않고 block/comment/archive
promoted/ready는 승인 신호가 아님 — unblocked 이벤트 필수

⚠️

공개 GitHub 댓글에는 dry-run, 드라이런, 아직 게시하지 않음, review_state 같은 내부 운영 용어를 절대 노출하지 않습니다(ADR-006). 내부 handoff 포맷은 게시 전에 sanitize됩니다.

Idempotency

중복 방지의 핵심: OWNER/REPO + head

multi-repo가 하나의 board를 공유하므로 PR 번호만으로 dedupe하면 충돌합니다. 모든 키에 OWNER/REPO를 포함하고, head가 바뀌면 다른 키를 씁니다.

# Root PR 카드
pr-auto-review:<OWNER>/<REPO>#<PR_NUMBER>

# head 단위 review 카드
pr-auto-review:<OWNER>/<REPO>#<PR_NUMBER>:review:<HEAD_SHA>

원칙: ① 항상 OWNER/REPO 포함 ② PR 번호만으로 dedupe 금지 ③ head 변경 시 새 키 ④ GitHub comment/approve 직전 headRefOid 재조회.

Design Decisions

주요 설계 결정 (ADR)

왜 이렇게 만들었는지 — 펼쳐서 배경/결정/결과를 확인하세요.

001 Hookdeck + 로컬 결정론 receiver (Hermes built-in webhook 미사용)›

배경: webhook마다 LLM run을 만들면 비용·지연·불안정성이 커진다. 결정: GitHub → Hookdeck → 로컬 receiver → router → Kanban 구조. 결과: intake가 빠르고 예측 가능하며, LLM은 worker 단계에서만 사용된다.

002 여러 repo를 하나의 shared board · 단일 Hookdeck source로 처리›

배경: 3개 repo를 같은 흐름으로 리뷰해야 한다. payload에 repository.full_name이 있으므로 route를 나눌 필요가 없다. 결과: 운영 포인트가 단순해지는 대신, 모든 idempotency 키에 OWNER/REPO를 반드시 포함해야 한다.

003 신규 repo onboarding 시 기존 open PR backfill 금지›

배경: 새 repo의 기존 open PR을 모두 리뷰하면 대량 noise·비용. 결정: 기존 open PR head는 seen으로 seed하고, 이후 신규 PR 또는 head 변경부터 리뷰. 결과: 초기 폭주를 피하지만, 이미 열린 PR은 head가 바뀌기 전까지 대상 아님.

004 Cron fan-out 대신 serialized tick›

배경: 여러 no-agent cron이 같은 SQLite DB를 동시 write → corruption/timeout 위험. 결정: poller/comment/follow-up/LGTM/approve/cleanup을 tick.py 하나로 묶어 process-level flock 직렬 실행(10m). poller는 60m fallback, workspace GC는 30m 분리. 결과: DB write 충돌·API 호출량 감소.

005 댓글은 자동, Approve는 human-gated›

결정: prcommenter는 verifier-confirmed finding을 자동 게시. prapprover 카드는 blocked/unassigned로 생성하고, 운영자가 Unblock해야만 실행. 결과: 댓글은 빠르게, 승인은 여전히 사람이 최종 결정.

006 공개 댓글은 한국어·수정 지향·내부 용어 금지›

배경: 내부적으로 dry-run/review_state metadata를 써도 public comment에 노출되면 안 된다. 결정: 한국어·fix-oriented·author mention 형식. dry-run 등 운영 용어 금지. 결과: candidate builder가 오래된 handoff format을 sanitize한다.

007 stale head approve는 반복 unblock 대신 latest-head review로 대체›

배경: approve 카드 Unblock 후 head가 바뀌면 그 카드는 더 이상 실행 불가. 결정: stale approve 카드는 superseded 코멘트를 남기고 archive, current head 기준 review를 ensure. 결과: 운영자가 stale 카드를 반복 처리하지 않는다.

008 Done lane은 비우고 완료 카드는 모두 archive›

배경: high-volume board에서 done 카드가 쌓여 UX 악화. 결정: status='done' 카드는 전부 archive. approve 카드도 완료 후엔 audit record일 뿐. 결과: Done lane은 0개 유지가 정상. 기록은 DB에 남는다.

009 review workspace는 git clone 대신 git worktree›

배경: clone copy가 workspace·yarn cache를 폭증시킴(archived 하나가 ~701MB). 결정: 기존 local object store를 공유하는 detached worktree 생성. 결과: packfile/object 중복 감소(한 client repo 기준 worktree ~46MB).

010 prreviewer Yarn Berry cache를 shared cache로 이동›

배경: profile-local cache가 ~2.8GB까지 증가. 결정: YARN_GLOBAL_FOLDER를 shared 경로로 지정하고, running task가 없을 때만 old cache 삭제. 결과: active review를 방해하지 않고 cache 정리 가능.

For Developers

개발자가 알아둘 점

내 PR에 봇 댓글이 달리려면?: allowlist에 등록된 client repo에 PR을 올리거나 새 commit을 push하면, 봇이 최신 head 기준으로 리뷰합니다. 단, 신규 onboarding repo의 이미 열려 있던 PR은 head가 바뀌기 전까지는 대상이 아닙니다(ADR-003).
모든 지적이 다 댓글로 달리나요?: 아닙니다. high-confidence이고 actionable한 finding이, 게다가 verifier 검증까지 통과해야 게시됩니다. style-only nit이나 불확실한 finding은 공개되지 않고 Kanban 내부에만 남습니다.
봇이 내 브랜치를 건드리나요?: 아니요. review worker는 target repo를 read-only로 다룹니다. 파일 수정·commit·push·branch 생성을 하지 않으며, 격리된 detached worktree에서만 코드를 봅니다.
봇이 자동으로 Approve해서 merge되나요?: 아니요. GitHub APPROVE는 절대 자동화하지 않습니다. 운영자가 Kanban approve 카드를 직접 Unblock해야만, 그것도 최신 head·checks 재검증을 통과해야만 승인됩니다.
댓글을 반영해 push하면?: follow-up monitor가 새 commit/comment를 감지하고 closure verifier가 finding 상태를 재분류합니다. head가 바뀌면 기존 finding은 latest head 기준으로 다시 검토됩니다.
봇 댓글에 내부 용어가 보이면?: 버그입니다. 공개 댓글에는 dry-run/review_state 등 운영 용어가 나오면 안 됩니다(ADR-006). 발견 시 운영자에게 알려주세요.