설치했다. 그다음은?

여러 AI 에이전트 (AI Agent)를 병렬로 실행하면서, "머지(Merge)한 후에야 충돌을 깨닫는 상황"을 줄이고 싶어서, PR 간의 충돌을 머지 전에 조언해 주는 GitHub App을 설치했습니다. 설치는 클릭 한 번이면 끝납니다. 이후 모든 PR에 조언 체크가 자동으로 붙습니다. 여기까지는 순식간이었습니다.

그런데 시간이 흐른 뒤 깨달았습니다. 나는 체크를 「그저 바라보고만」 있었다는 것을.

PR에 체크와 코멘트가 달립니다. 나는 그것을 힐끗 보고, "뭐, 괜찮겠지" 하며 머지합니다. 에이전트들은 여전히 별도의 브랜치에서 묵묵히 PR을 계속 만듭니다. 어렵사리 "B를 먼저 넣는 것이 좋다"라고 알려주고 있는데도, 그것을 읽는 것은 머지한 후에 컨플릭트 (Conflict)로 두들겨 맞은 후였습니다.

체크는 달려 있었습니다. 내가 사용하지 못했을 뿐입니다.

도구를 들여놓기만 하고 일을 했다고 착각하고 있었다는 이야기입니다. 그리고 이를 해결한 방법은 에이전트 설정 파일에 한 줄을 추가한 것뿐이었습니다. 이하, 그 한 줄과 실제 운용 패턴을 남겨둡니다 (이 앱을 사용하지 않더라도, 병렬 에이전트 운용의 방법론으로서 사용할 수 있을 것입니다).

무엇이 부족했는가 — 「읽는 주체」가 없었다

냉정하게 생각하면 당연한 일이었습니다.

체크와 코멘트는 나를 향해 나옵니다. 하지만 실제로 브랜치를 따고, 커밋하고, 머지까지 실행하고 있는 것은 에이전트입니다. 내가 바라보고 있는 동안, 에이전트는 아무것도 읽지 않습니다. 인간이 병목 (Bottleneck)이며, 게다가 인간은 모든 PR의 코멘트를 매번 정독하지 않습니다.

즉, "조언이 나오고 있다"와 "조언이 사용되고 있다" 사이에는, "에이전트가 조언을 읽고 나서 움직인다"라는 한 수가 빠져 있었습니다.

나오는 조언는 다음과 같습니다 (실제로 나오는 코멘트의 헤드라인·상태명입니다).

Clear to land— 현재 다른 오픈 PR과 충돌하지 않음. 착륙(Land)해도 OK.
Heads up— 같은 부분을 건드리고 있는 PR이 있음. 조언 수준의 주의.
Wait in line— 다른 PR과 같은 코드를 직접적으로 충돌하고 있음. 이 PR은 다른 PR의 뒤로 줄을 서는 것이 재작업(Retake)을 줄이는 길임.
Unknown— 판단할 재료가 부족함 (= "충돌 없음"이 아니라 "판단 불가").

이것을 머지 전에, 그것도 인간이 아니라 에이전트가 읽도록 하면 됩니다. 방법은 허탈할 정도로 단순했습니다.

추가한 한 줄 (실물)

Claude Code라면 CLAUDE.md에, Codex라면 AGENTS.md에, 머지 전 규칙으로서 다음을 붙였습니다. 실제로 리포지토리에 두고 있는 내용 그대로입니다.

## 머지 전 규칙 (Veripsa의 조언 읽기)
PR을 머지하기 전에, 반드시 Veripsa의 조언 체크와 코멘트를 읽을 것.
1. `gh pr checks <PR번호>`로 Veripsa 체크 상태를 확인한다.
...

gh pr checks도 gh pr view --comments도 그저 명령어일 뿐입니다. 에이전트는 명령어를 실행하여 그 출력을 읽을 수 있습니다. 따라서 "조언을 읽고 나서 움직인다"를 에이전트의 절차 그 자체에 심을 수 있습니다. 이것이 효과가 있었습니다.

붙인 직후부터 동작이 바뀌었습니다. 에이전트가 머지 전에 스스로 코멘트를 읽고, "Wait in line이라고 나옵니다. PR-12를 먼저 넣어야 한다고 적혀 있으므로, 이쪽은 기다리겠습니다"라고 스스로 말하기 시작했습니다. 내가 모든 PR을 정독하지 않아도, 조언이 소비되기 시작했습니다.

바뀐 운용 패턴 (한 줄 너머에 있는 것)

한 줄을 추가한 뒤, 실제로 정착된 사용법 몇 가지입니다.

1. 충돌이 발생하면, 나온 순서대로 줄을 선다 (멋대로 앞서나가지 않는다)

가장 효과가 컸던 것이 이것입니다. Wait in line에서 "PR-A 앞에 PR-B를 넣는 것이 재작업이 적다"라고 착륙 순서가 나왔을 때, 그 순서대로 넣습니다. 한쪽 에이전트가 다른 쪽 위에 rebase 하여 순서대로 착륙합니다.

이전의 저(와 에이전트)는 눈에 띄는 순서대로 머지하고, 나중에 거대한 컨플릭트를 수동으로 해결하곤 했습니다. 착륙 순서를 따르는 것만으로 그 수작업이 통째로 사라졌습니다. "선착순 머지"를 "가르쳐준 순서대로 착륙"으로 바꾸는 것뿐입니다.

veripsa-ack는 "의식적인 결정"이지 반사가 아니다

2. Wait in line

를 인지한 상태에서 진행하기로 결정했다면 veripsa-ack 라벨을 붙입니다. 이것은 "이 스냅샷의 충돌을 확실히 확인한 후, 의도적으로 진행한다"는 기록이며, 승인(Approval)도 pardon도 아닙니다. 그렇기 때문에 CLAUDE.md에 굳이 "인간이 명시적으로 결정했을 때만"이라고 적어둔 것입니다.

에이전트(Agent)에게 맡기면, 이런 종류의 라벨은 "체크를 침묵시키는 주문"으로서 반사적으로 붙기 쉽습니다. 여기서 핵심은 이를 "일시 정지가 발생했다 → 일단 ack"라는 자동 반응으로 만들지 않는 것이었습니다. 참고로 겹치는 내용이 바뀌면 조언(Advisory)은 다시 일시 정지되므로, ack는 "한 번 붙이면 조용해지는" 스위치가 아닙니다.

3. PR은 작게, 하나의 관심사(Concern)로 유지하기

조언의 정밀도는 PR의 입도(Granularity)에 정직하게 영향을 받습니다. 하나의 PR이 10개의 파일을 건드리고 있다면 "어디가 충돌하고 있는지"가 흐릿해집니다. 하나의 관심사로 좁힐수록 "여기가 겹치고 있다"는 점이 구체적이 됩니다. 병렬 에이전트 운용에서는 PR을 작게 유지해야 할 이유가 하나 더 늘어난 셈입니다.

4. 게이트(Gate)로 만들지는 별개의 문제 (조언 상태로도 가치는 있음)

솔직히 말씀드리면, 이 조언은 그 자체로는 머지(Merge)를 중단시키지 않습니다 (Advisory입니다). 일시 정지를 "실제로 머지를 중단시키도록" 만들고 싶다면, GitHub의 브랜치 보호(Branch protection)에서 Veripsa 체크를 **필수 체크(Required status check)**로 지정하면 됩니다. 그렇게 하면 Wait in line이 ack 될 때까지 머지 버튼이 막힙니다.

단, 브랜치 보호의 필수 체크는 GitHub 측의 기능이며, 프라이빗 리포지토리(Private repository)에서는 유료 플랜(Pro / Team / Enterprise)이 필요합니다 (퍼블릭 리포지토리는 무료). 따라서 "무료 플랜의 프라이빗 리포지토리에서는 조언(Advisory)으로만" 작동합니다.

하지만 제가 느낀 바로는, 게이트로 만들지 않더라도 머지 전에 "B를 먼저 넣어라"라고 알 수 있다는 사실 자체가 가치의 대부분이었습니다. 막아주는 것보다, 착륙하기 전에 교통 정리가 보이는 것이 더 효과적입니다. 하드 게이트(Hard gate)는 필요해진 다음에 추가하면 되는 사후적인 제약 장치입니다.

content-free에 대하여 한마디

조언에 사용되는 것은 최소한의 운영 메타데이터이며, 파일 본문은 보유하지 않습니다 (무엇을 다루고 무엇을 버리는지는 veripsa.com/trust에서 확인 가능). "머지 전에 충돌 징후를 알고 싶다"는 이유로 소스 코드를 맡길 필요는 없다는 설계입니다. 에이전트 설정에 통합할 때, 이 경계가 명확하다는 점은 은근히 안심이 되는 요소였습니다.

요약 — 도구는 "읽는 절차"에 심었을 때 비로소 작동한다

설치는 클릭 한 번이면 끝났습니다. 하지만 가치가 나타난 것은 그 지점이 아니라, 에이전트의 루프(Loop)에 "머지 전에 조언을 읽는다"라는 내용을 단 한 줄로 포함시킨 순간이었습니다.

• CLAUDE.md 또는 AGENTS.md에 머지 전 규칙을 한 줄 추가합니다 (실제 내용은 위 블록 참조).
• 조언 상태에 따라 행동합니다: Clear to land는 진행, Wait in line은 착륙 순서에 따라 대기, Unknown은 확인.
• veripsa-ack는 인간의 의식적인 결정일 때만 사용합니다.
• PR은 작게 유지합니다. 게이트는 필요할 때 추가합니다.

저는 "체크를 도입했다"는 사실에 만족하며 한동안 그것을 바라만 보고 있었습니다. 바라보는 것을 멈추고 에이전트에게 읽게 하기 시작하자, 마침내 에이전트들끼리 알아서 순서를 양보하기 시작했습니다. 도구를 도입하는 것은 입구일 뿐이며, 사용법은 그 너머에 있다 —— 이번에는 그것을 단 한 줄의 설정 파일로 뼈저리게 느꼈습니다.

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

병렬로 에이전트를 실행하고 계신 분이라면, CLAUDE.md에 한 줄을 추가하는 실험을 꼭 해보시고 피드백을 주세요.

Discussion