요약: AI 에이전트에게 풀 리퀘스트(PR)를 리뷰하게 하려면 별도의 지침(instruction)과 자체 체크아웃 환경을 갖추고, 가능하다면 다른 모델을 사용하는 두 번째 에이전트에게 리뷰를 맡기세요. 작업이 리뷰 상태에 도달하면 자동으로 실행되도록 설정하고, 테스트를 직접 돌려 PASS 또는 CHANGES REQUIRED 판정을 남기게 한 다음, 실패 시 작성자(builder) 에이전트에게 다시 돌려보내도록 만듭니다. 최종 머지(merge)는 여전히 사람이 담당합니다.
사람이 직접 보기 전에 AI 에이전트가 PR을 먼저 리뷰해야 하는 이유
에이전트가 작성한 모든 풀 리퀘스트는 결국 한 사람의 책상, 즉 여러분 앞으로 모입니다. 에이전트 하나가 한 시간에 PR 하나를 올릴 때는 괜찮습니다. 하지만 에이전트 5개가 동시에 돌아가기 시작하면 diff(변경 사항)를 채 다 읽기도 전에 대기열이 쌓이고, 1차 검토가 심각한 병목이 됩니다.
리뷰어 에이전트는 바로 이 1차 검토를 대신 수행합니다. 사용자의 판단을 완전히 대체하는 것은 아닙니다. 테스트를 통과하지 못했거나, 작업 범위를 벗어났거나, 비밀 정보(시크릿)를 유출한 PR을 미리 걸러내어, 여러분이 검토할 가치가 있는 PR만 도달하게 만듭니다. Sharkly에서는 추가 에이전트 1개와 자동화(Automation) 2개만으로 이를 구축할 수 있으며, 본 가이드에서 각 단계를 차근차근 살펴보겠습니다.
자동화된 코드 리뷰의 한계점을 먼저 확인하고 싶다면 AI 코드 리뷰 에이전트가 검증할 수 있는 것과 없는 것을 읽어보세요. 이 글에서는 설정 방법에 집중합니다.
에이전트가 자신이 작성한 코드를 직접 리뷰하면 안 되는 이유
코드를 작성한 에이전트는 그 코드에 대한 맥락과 논리도 함께 만들어냅니다. 자신이 한 작업을 직접 확인하라고 요청하면, 자신이 세운 논리를 다시 읽고 그대로 수긍해 버립니다. 버그를 만들어낸 바로 그 맹점이 리뷰까지 진행하게 되는 셈입니다.
이런 문제는 테스트에서 가장 흔히 발생합니다. 빌더(builder) 에이전트가 테스트를 통과시키지 못하면 단언문(assertion)을 완화해 놓고 작업을 완료했다고 선언할 수 있습니다. 이런 패턴은 코딩 에이전트의 테스트 조작을 잡아내는 방법에서 다룬 바 있습니다. 결과에 대한 이해관계가 없는 별도의 리뷰어는 diff를 냉정하게 읽으며 다른 질문을 던집니다. '이 변경 사항이 작업에서 요구한 내용만 정확히 수행하고 있는가?'
DeepSeek Harness 팀의 슈퍼 에이전트 설계 에세이에서도 이와 유사한 역할 분리를 제시합니다. 동일한 PR에 연결된 여러 Worker가 PR의 이벤트를 모두 공유하며 자체적으로 충돌을 해결하는 방식입니다. 실제 출시된 제품이 아니라 프로토타입 설계에 관한 설명이지만, 그 개념은 여전히 유효합니다. 리뷰어가 완전히 분리된 주체일 때 코드 리뷰는 훨씬 더 효과적입니다.
1단계: 빌더와 리뷰어 분리하기
에이전트 하나에 두 가지 모드를 주는 대신, 에이전트 두 개를 별도로 생성하세요. 각 에이전트는 고유한 지침(instructions), 리포지토리, 실행 대상(execution target)을 가집니다.
| 빌더 에이전트 | 리뷰어 에이전트 | |
|---|---|---|
| 역할 | 작업 구현, PR 생성 | 작업 요구사항 대비 PR 평가 |
| 코드 작성 | 예 | 아니요 |
| 푸시 | 피처 브랜치로 푸시 | 절대 하지 않음 |
| 런타임 | 예: Claude Code | 이상적으로는 다른 런타임(예: Codex) |
| 출력 결과 | 브랜치, PR, 요약 코멘트 | 판정 코멘트 |
Sharkly 에이전트에는 별도의 모델 선택기가 없습니다. 실행 대상은 컴퓨터와 해당 컴퓨터에서 감지된 런타임의 조합이므로, “다른 모델을 사용한다”는 것은 리뷰어를 다른 런타임에 바인딩한다는 뜻입니다. 두 번째 런타임을 사용하면 diff를 분석할 때 서로 다른 관점과 패턴을 적용할 수 있습니다. 또한 Sharkly는 토큰을 직접 판매하지 않으므로, 각 실행 비용은 해당 런타임에 이미 연결된 요금제를 기준으로 청구됩니다.
리뷰어의 작업 디렉터리는 임시(Temporary) 모드로 설정하세요. 컴퓨터 문서에서 설명하듯, 이렇게 설정하면 실행할 때마다 격리된 디렉터리가 제공되며 리포지토리 실행 시 새로운 Git worktree를 준비할 수 있습니다. 리뷰어는 독립된 복사본에서 PR 브랜치를 체크아웃하므로 빌더의 파일을 덮어쓰거나 훼손하지 않습니다. 여러 에이전트가 리포지토리를 공유할 때 이것이 왜 중요한지는 격리된 worktree 환경의 병렬 에이전트 포스트를 참고하세요.
2단계: 리뷰어 지침 작성하기
에이전트 지침(instructions)에는 역할, 검사항목, 보고 형식이 포함됩니다. 작업별 구체적인 세부사항은 작업 태스크에 남겨둡니다. 리뷰어의 지침은 간결하고 테스트 가능하도록 유지하세요.
You are the code reviewer for this Space. You never push, merge or edit files.
1. Read the triggering task. If it is not a code task in this Space, reply "not mine" and stop.
2. Find the linked pull request (the task ID appears in its title, description or branch).
3. Check out the PR branch in your worktree. Run the test command from the repo README.
4. Compare the diff to the task's acceptance criteria.
5. Post one verdict comment on the task in the format below. Nothing else.
첫 번째 단계는 겉보기보다 훨씬 중요합니다. 현재 상태 트리거와 코멘트 트리거는 조직(Organization) 전체를 대상으로 일치 항목을 찾기 때문에, 지침에서 작업을 실행하기 전에 해당 작업이 맞는지 반드시 확인해야 합니다. 자동화 문서에서도 이 점을 명시하고 있습니다.
3단계: 트리거 선택하기
Sharkly 자동화는 지침, 에이전트 또는 크루(Crew), 그리고 하나 이상의 트리거를 결합합니다. PR 리뷰의 경우 두 가지 트리거가 적합합니다.
작업 상태 변경. Space 워크플로에 In Review와 같은 상태를 추가합니다. 빌더가 PR을 생성한 후 작업을 해당 상태로 이동하면 리뷰어가 시작됩니다. 상태 트리거로 실행되면 해당 작업에 대화(conversation)가 생성되므로 판정 결과와 토큰 사용량이 작업 내역에 그대로 유지됩니다.
위 스크린샷은 이 블로그가 자체 초안에 적용하고 있는 게이트입니다. 작업이 Ready for Release 상태에 도달하면 리뷰어 에이전트가 이를 이어받습니다. 코드 리뷰에서도 패턴은 완전히 동일합니다.
웹훅(Webhook). 작업 보드 외부에서 PR이 생성되는 경우, GitHub의 pull_request 웹훅을 자동화의 웹훅 URL로 지정하세요. 서명 검증을 활성화하면 Sharkly는 GitHub의 X-Hub-Signature-256 헤더도 지원하므로, 서명 시크릿을 GitHub의 Secret 필드에 붙여넣기만 하면 됩니다. 웹훅 기반 실행은 작업 태스크에 연결되지 않으므로, 리뷰어는 대신 GitHub CLI를 사용하여 PR에 직접 판정 결과를 남깁니다.
실제 운영에 적용하기 전에 Run now 기능으로 두 방식 중 하나를 꼭 테스트해 보세요.
4단계: 리뷰어에게 체크리스트 제공하기
체크리스트가 없는 리뷰어는 장황한 글을 쓰지만, 체크리스트가 있으면 핵심 발견 사항(finding)을 정리해 냅니다. 대부분의 에이전트 PR은 다음 5가지 질문으로 검토할 수 있습니다.
- 테스트가 실행되고 통과하는가? 리뷰어는 빌더의 요약 내용을 절대 맹신하지 않고, 테스트를 직접 실행합니다.
- 작업 범위가 잘 지켜졌는가? 작업과 무관하게 수정된 파일은 변경 사항이 무해해 보이더라도 지적 사항(finding)이 됩니다.
- 노출된 비밀 정보(시크릿)가 있는가? diff나 로그에 포함된 토큰, 키,
.env값 등이 있는지 확인합니다. - 호출부(caller)에 장애를 유발하는 변경 사항이 있는가? 함수 시그니처 변경, 엔드포인트 제거, 롤백 없는 마이그레이션 등을 점검합니다.
- 테스트가 약화되지 않았는가? 단언문 삭제, 새로운 테스트 스킵(skip), 기대값 완화 등을 확인합니다.
여러 리뷰어 에이전트가 이 목록을 공유하는 경우 Skill로 관리하면, 한 번의 수정으로 모든 에이전트에 일괄 적용할 수 있습니다.
5단계: 판정 결과 포맷 고정하기
사람이 10초 만에 훑어볼 수 있는 간결한 판정문이, 너무 길어서 그냥 지나치게 되는 상세한 리뷰보다 낫습니다. 일관된 고정 형식을 사용하세요.
VERDICT: CHANGES REQUIRED
Tests: 41 passed, 2 failed (test_refund_rounding, test_refund_zero)
Scope: OK, 3 files, all under billing/
Secrets: none found
Breaking changes: refund() now raises on amount=0; two callers in api/ not updated
Weakened tests: none
Required:
1. Handle amount=0 in refund() or update both callers.
2. Fix the rounding in test_refund_rounding; do not change the expected value.
PASS 판정도 동일한 필드를 사용하며 Required 목록만 비워둡니다. 이렇게 형식을 고정하면 판정 결과를 수치화할 수도 있습니다. 각 검사항목이 얼마나 자주 실패하는지 파악하여 빌더의 지침을 그에 맞게 보완할 수 있습니다.
6단계: 빌더에게 피드백 루프 연결하기
CHANGES REQUIRED 판정이 나오면 사람이 일일이 전달하지 않아도 빌더가 다시 작업을 시작해야 합니다. 특정 키워드에 반응하는 코멘트 트리거를 사용하여 빌더 에이전트에 할당된 두 번째 자동화를 생성하세요.
코멘트 매칭은 대소문자를 구분하지 않으며, 코멘트 내 어느 위치에든 해당 문구가 나타나면 트리거됩니다. 아무도 실수로 입력하지 않을 고유한 문구를 선택하고, 리뷰어가 CHANGES REQUIRED 줄에만 그 문구를 작성하도록 지시하세요. 빌더가 답변에서 이 문구를 그대로 인용하면 스스로를 다시 트리거할 수 있으므로, 해당 문구를 절대 반복해서 쓰지 않도록 지침에 명시해야 합니다.
루프 반복 횟수에는 제한을 두어야 합니다. 리뷰와 수정을 최대 2회까지만 반복하도록 제한하고, 그 후에는 리뷰어가 최종 판정 결과를 첨부하여 사람에게 작업을 넘기도록 설정하세요.
여전히 사람의 몫으로 남는 영역
머지 권한은 여전히 사람에게 있습니다. Sharkly의 GitHub 연동에서는 PR 제목의 작업 ID를 통해 PR과 작업 태스크를 연결하며, 머지하더라도 작업 상태가 자동으로 변경되지 않습니다. 에이전트가 PASS라고 판정했다고 해서 코드가 자동으로 배포되는 일은 없습니다.
GitHub에서도 이를 확실히 뒷받침하세요. 사람의 필수 승인을 요구하는 보호된 브랜치(protected branches)를 설정하면, 자신만만한 리뷰어 에이전트가 최후의 방어선이 되는 위험을 방지할 수 있습니다. 또한 체크리스트로는 판단할 수 없는 정성적인 평가, 즉 '이 설계가 올바른가?'나 '애초에 이 변경이 필요한가?'와 같은 최종 결정은 사람이 직접 내려야 합니다. 검토 대상 PR의 우선순위를 정하는 방법은 에이전트 PR 대기열 우선순위 지정하기와 인간의 검토가 병목이 되는 이유를 참고하세요.
마치며
두 번째 에이전트가 1차 검토를 맡아주면 에이전트가 생성한 PR이 쌓여가는 문제를 해결할 수 있습니다. 빌더와 리뷰어를 분리하고, 리뷰어에게 독립된 worktree와 런타임을 부여하며, 상태 변경이나 웹훅을 통해 실행하고, 고정된 형식으로 5가지 정해진 질문에 답하도록 설정하세요. 실패 시 특정 코멘트 문구를 통해 빌더에게 피드백을 전달하되 루프는 2회로 제한하고, 최종 머지 권한은 사람이 유지하세요.
이미 동시에 10개의 코딩 에이전트를 운영하고 있다면, 이제 추가해야 할 다음 단계는 바로 이 구성입니다. Sharkly에서 무료로 시작하여 리뷰어 에이전트부터 만들어 보세요.
자주 묻는 질문 (FAQ)
AI 에이전트가 자신이 올린 PR을 직접 리뷰할 수 있나요?
가능은 하지만 놓치는 부분이 많아집니다. 에이전트가 코드를 작성할 때 가졌던 가정과 전제를 그대로 공유하기 때문입니다. 자체 지침을 가지고, 이상적으로는 다른 런타임을 사용하는 별도의 리뷰어가 diff를 검토해야 이러한 편향 없이 문제를 발견할 수 있습니다.
리뷰어는 빌더와 다른 모델을 사용해야 하나요?
가능하다면 그렇게 하는 것이 좋습니다. Sharkly에서 모델은 런타임에 의해 결정되므로, 리뷰어 에이전트를 빌더와 다른 런타임에 연결하세요. 예를 들어 Claude Code가 작성한 작업을 Codex가 리뷰하도록 구성할 수 있습니다.
AI 코드 리뷰어는 무엇을 가장 먼저 확인해야 하나요?
테스트입니다. 테스트 스위트를 직접 실행하여 통과 및 실패 건수를 보고하도록 하세요. 그 다음 작업 범위, 비밀 정보(시크릿), 호환성 문제(breaking changes), 약화된 테스트 순서로 확인해야 합니다.
리뷰어 에이전트가 PR을 승인하고 머지까지 할 수 있나요?
그렇게 설정하지 않는 것을 권장합니다. 브랜치 보호 설정을 통해 머지 권한은 사람에게만 남겨두세요. 리뷰어는 판정 코멘트만 남기고, 최종 결정은 사람이 내려야 합니다.
리뷰 루프가 무한히 반복되는 것을 어떻게 방지하나요?
리뷰어의 지침에서 루프를 2회로 제한하고, 빌더가 절대 따라 하지 않을 코멘트 문구를 트리거로 사용하세요. 제한 횟수에 도달하면 리뷰어가 사람에게 작업을 인계하도록 합니다.
Sharkly 외부에서 열린 GitHub 풀 리퀘스트에도 적용할 수 있나요?
네, 가능합니다. GitHub 웹훅을 자동화의 웹훅 트리거에 연결하면 됩니다. 서명 검증을 켜두면 Sharkly가 GitHub의 서명 헤더를 정상적으로 인식합니다.
