결론부터 말씀드리면

Draft PR은 원래 "아직 리뷰하지 마세요"라는 신호였습니다. GitHub Actions도 github.event.pull_request.draft == false로 skip 하는 것이 정석입니다. 저의 GitHub App (Veripsa Core)도 처음에는 동일한 설계로 draft = 분석 대상 제외로 설정했습니다.

하지만 AI agent를 병렬로 실행하는 운용이 보편화되면서, draft의 사용 방식이 바뀌었습니다. "작업하기 전에 다른 PR과 충돌하는지 보고 싶으니까 먼저 draft를 올려둔다" — 즉, scout(정찰)로서 draft가 사용되기 시작한 것입니다.

이 기사는 그 변화에 맞춰 draft도 full analysis의 대상으로 포함하도록 방침을 변경한 이야기와, real PR을 휘말리게 하지 않기 위한 작은 refinement(개선) 설계에 대해 작성합니다.

• 구 설계: draft = 개발자가 반복 작업 중, 방해하지 않음 (reasonable 했음)
• 신 설계: draft도 traffic(트래픽)으로 간주하여 확인. 단, draft ↔ non-draft 간의 간섭은 warn(경고) 수준에서 멈춤
• 계기: AI agent가 "작업하기 전에 충돌 여부를 보고 싶다"는 용도로 빈번하게 draft를 올리게 됨

구 설계가 reasonable 했던 이유

PR을 draft로 제출한다는 것은 본래 "아직 리뷰하지 말아달라", "CI를 돌릴지 여부도 보류하겠다"라는 신호였습니다. GitHub Actions 측에서도 if: github.event.pull_request.draft == false로 skip 하는 것이 정석입니다.

Veripsa Core도 초기 설계에서는 이를 따랐습니다. draft = 개발자가 로컬에서 반복 작업 중이기 때문에,

• 충돌 판정을 실행해도 아직 코드가 확정되지 않음
• 피드백을 주어도 금방 덮어씌워짐
• 리소스 측면에서도 실행해 봤자 낭비

라는 판단이었습니다. 당시의 세계관에서는 이것이 맞았습니다.

AI agent가 전제를 깨뜨렸다

최근 몇 달 사이, 제 repo의 draft PR이 발생하는 양상이 명확히 바뀌었습니다.

• Codex나 Claude Code의 background agent가 브랜치를 생성하고 draft PR을 올림
• 사람이 리뷰하기 전에, 에이전트 스스로가 "이대로 진행해도 되는가"를 확인하고 싶어 함
• 최종 반영이 보장되지는 않지만, **"작업하기 전에 다른 PR과 충돌하는지만 보고 싶다"**는 용도로 draft를 제출함

사람도 똑같은 행동을 합니다. "구현에 들어가기 전에, 비슷한 영역을 건드리고 있는 PR이 없는지 scout(정찰)하고 싶다". 리팩토링 규모가 클수록 이런 행동을 합니다.

즉, draft PR은 이제 단순한 "미완성 저장소"가 아니라, scout window — 최종 반영 전에 공역의 교통 상황을 확인하기 위한 창이 되어 있었습니다.

이 시점에서 Veripsa Core가 draft를 skip 하고 있다면, 바로 가장 사용하고 싶은 타이밍에 침묵하게 되는 것입니다. 이는 product로서 잘못된 것이었습니다.

신 설계: draft도 full analysis, 단 취급을 다르게 함

방침을 변경하여, draft에서도 non-draft와 동일한 full analysis를 돌리도록 했습니다. 다만, real PR을 불필요하게 block(차단)하지 않기 위해 다음과 같은 refinement를 도입했습니다.

1. draft ↔ non-draft의 충돌은 warn 수준으로 제한

verdict(판정)의 severity(심각도)를 2단계로 나누었습니다.

• non-draft ↔ non-draft의 충돌 → 통상적인 verdict (block에 준하는 무게)
• draft가 한쪽에 포함된 충돌 → warn 수준 (정보 제공용이며 merge를 막지 않음)

이유는 draft는 애초에 "최종 반영이 보장되지 않기" 때문입니다.

비대칭적인 케이스를 생각하면 이해하기 쉽습니다. real PR을 제출한 입장에서는 "draft인 phantom PR과 충돌하니까 merge할 수 없습니다"라는 말을 들으면 납득하기 어렵습니다. draft는 다음 주에 삭제될지도 모르는 것이니까요. 따라서, draft가 섞인 verdict는 real PR을 block하지 않는 설계로 만들었습니다.

구현 측면에서는, 충돌 대상이 draft인지 여부를 verdict 생성 시점에 체크하여 severity(심각도)를 한 단계 낮추고 있습니다.

2. (draft) 표기

render 단계에서 partner를 GitHub Check Run 본문에 표시하여 충돌 대상의 PR 번호를 보여줄 때, 상대가 draft라면 명시적으로 (draft)를 뒤에 붙입니다.

Co-change risk with #482 (draft): src/auth/session.py

이를 보는 사람은 "아, 아직 iterating (반복 작업) 중인 PR이구나, 당분간은 지켜봐도 되겠네"라고 읽을 수 있습니다. 반대로 (draft)가 없다면 "이것은 landing imminent (곧 반영될 예정)이므로 지금 즉시 조정해야 한다"라고 읽히게 됩니다.

단순한 표기일 뿐이지만, verdict를 읽는 쪽의 판단 비용을 낮추기 위해서는 이 4글자가 효과적입니다.

3. phantom holder의 처리

co-change 그래프 업데이트 시, draft PR의 변경 사항을 일시적으로 보관해두는 phantom holder를 real PR과는 별도의 bucket에 넣도록 하고 있습니다.

이렇게 하면 draft가 나중에 close 되거나, force-push로 인해 히스토리가 변경되더라도 real PR 측의 verdict 이력을 오염시키지 않습니다.

dogfood 실증

fourfold-echoes라는 별도의 repo에서, Codex의 background agent가 draft PR을 올렸습니다. 이번 변경 전이었다면, Veripsa Core는 아무런 반응이 없었을 것입니다.

변경 후에는, 해당 draft PR에도 verdict가 생성되게 되었습니다. 생성된 verdict는 "같은 파일을 건드리는 다른 draft와는 충돌하지만, real PR에는 영향 없음 (warn 수준)"이었습니다.

에이전트의 side 입장에서는 "인간이 리뷰하러 오기 전에 충돌할 가능성이 있는 상대가 있는지"를 볼 수 있고, 인간의 입장에서는 real PR의 신호가 draft에 의해 오염되지 않습니다. 양립에 성공했습니다.

대국적 관점: traffic control의 대상을 확장하다

Veripsa Core의 wedge(핵심 가치)는 "main을 공유하는 여러 workstream의 real-time traffic control (실시간 교통 제어)"입니다.

지금까지는 "traffic = real PR"이라고 좁게 정의했습니다. 하지만 실제 공역(airspace)에는 다음과 같은 3개 층이 존재합니다.

• real PR (착륙 예정)
• draft PR (scout / 검토 중 / 착륙 미정)
• background agent의 WIP (인간이 모르는 사이에 비행 중)

traffic control을 표방한다면, 전부를 봐야 합니다. 전부를 본 뒤에 각각의 "무게"를 조절하면 됩니다.

이번 draft 허용은 그 첫걸음이었습니다. 다음에는 agent가 빈번하게 push하는 업데이트의 rate를 보고, "이것은 scout용인가, 아니면 진심으로 착륙시키고 싶은 것인가"를 verdict 측에서 hint(힌트)를 주는 단계까지 확장할 예정입니다.

요약

• draft PR을 skip 하던 기존 설계는 AI agent 시대에 obsolete (구식)가 되었다.
• draft는 "scout window"로 사용되고 있다. Veripsa Core는 그것을 보아야 한다.
• 단, real PR을 휘말리게 하지 않기 위해 draft 관련 verdict는 warn 수준으로 제한 + (draft) 표기 적용.
• dogfood 실증 완료. 공역의 가시 범위가 확장되었다.

Veripsa Core는 오픈 소스로 사용할 수 있습니다.

• 설치: https://github.com/apps/veripsa-core
• 사이트: https://veripsa.com

draft로 scout 해보세요.

Discussion