이 글은 클라우드 소프트웨어 팩토리를 구축하는 방법을 다루는 제 시리즈의 세 번째 글입니다.

코드 리뷰 에이전트를 만드는 방법, 그리고 이 에이전트가 만들어 내는 리뷰의 품질을 시간이 흐르면서 자동으로 높이는 방법을 설명하겠습니다. 이 글은 앞서 팩토리의 첫 부분으로 트리아지, 스펙, 구현 에이전트를 설정하는 법을 다룬 글들에 이어지는 후속편입니다.

물론 기성 코드 리뷰 플랫폼을 사용할 수도 있습니다. 하지만 코드 리뷰를 클라우드 팩토리 워크플로에 연결하면 좋은 점이 있습니다. 모든 팩토리 에이전트가 비슷한 패턴을 따르며 서로 컨텍스트를 공유할 수 있습니다. 예를 들어 코드 리뷰 에이전트는 스펙 작성 에이전트가 어떤 방식으로 스펙을 쓰는지 알 수 있고, 리뷰 코멘트에서 제안한 내용을 검증 에이전트에게 확인해 달라고 요청할 수도 있습니다. 코드 리뷰 스킬을 완전히 통제하고, 모델을 자유롭게 선택하며, 그 스킬이 시간에 따라 어떤 방식으로 개선될지도 제어할 수 있습니다. 제 생각에는 SDLC의 한 조각만 자동화하기보다 전체 SDLC를 자동화할 수 있도록 기반을 갖추는 편이 더 낫습니다.

이 글을 따라 자신의 저장소에 코드 리뷰를 구현하려면 여기에서 데모 코드를 확인할 수 있습니다.

이제 본격적으로 들어가 보겠습니다. 코드 리뷰 에이전트를 구현하기 위해 다음 세 가지를 만듭니다.

먼저 코드 리뷰 스킬부터 시작하겠습니다. Warp가 코드 리뷰에 사용하는 스킬, 즉 자사의 인기 OSS 저장소에 적용한 것을 바탕으로 만들겠습니다.

review-pr SKILL.md에서 PR diff를 검토해 review.json을 만들고, pr_diff.txt·pr_description.txt·spec_context.md를 컨텍스트로 받는다고 설명한 화면
review-pr 스킬은 저장소와 무관하게 구조화된 review.json을 만들고, 별도 워크플로가 GitHub 게시를 맡도록 설계된다.

이 스킬은 세 가지 입력을 받습니다.

  • PR 설명
  • PR diff
  • 스펙 에이전트가 만든 스펙이 있다면 그 스펙

그리고 review.json이라는 구조화된 결과를 반환합니다.

이 스킬은 Claude Code, Codex, Warp 같은 클라우드 코딩 에이전트가 실행하므로, 코딩 에이전트가 일반적으로 할 수 있는 모든 작업도 활용할 수 있습니다. 파일 읽기, 코드베이스 검색, 코드 빌드, 테스트 작성 등이 그 예입니다. 완전한 기능을 갖춘 에이전트가 코드 리뷰를 담당하면 변경을 제안하기 전에 가설을 시험하고, 제안한 변경이 실제로 빌드되는지 확인하는 등의 일을 할 수 있습니다. 이것이 이 워크플로의 핵심입니다.

스킬 본문은 보안, 정확성, 스타일 등의 관점에서 코드를 검토하라고 에이전트에 지시합니다. 인라인 피드백을 남기는 법, 무엇을 심각한 문제·중요한 문제·사소한 지적으로 분류할지, 어떤 문체로 코멘트를 작성할지 등을 자세히 규정합니다. 스펙이 제공됐다면 코드와 스펙을 비교하고, 자신이 제안하는 모든 변경을 검증하라고도 지시합니다. 마지막으로 review.json을 통해 구조화된 결과를 만드는 스키마를 제공합니다. 덕분에 결과를 GitHub 코멘트 묶음으로 변환할 수 있습니다.

이 스킬은 단순한 텍스트 파일 하나가 아닙니다. 동작을 더 결정론적으로 만들고 비용 효율을 높이는 보조 Python 스크립트 묶음도 포함합니다. 에이전트가 실행 중에 스크립트를 즉석에서 작성하게 하면 토큰을 더 쓰고 비결정성도 생기므로, 이런 스크립트는 스킬 리소스로 함께 배포하기를 권합니다.

이 스킬에 빠져 있는 것은 특정 팀이나 저장소의 코딩 관례에 관한 구체적인 컨텍스트입니다. 그 내용을 처음부터 추가하는 대신, 리뷰 에이전트가 계속 실행되는 동안 그러한 관례를 학습하는 두 번째 에이전트를 만들겠습니다. 이에 대해서는 뒤에서 더 설명합니다.

코드 리뷰 스킬

코드 리뷰 스킬을 호출하려면 다음 두 가지가 필요합니다.

GitHub Action 자체는 상당히 단순하며, 깊이 파고들 가치가 크지 않은 배관 작업이 대부분입니다. 개괄적으로 말하면 여러 PR 상태 변경을 계기로 실행되고, PR에 관한 컨텍스트를 모은 다음, 코드 리뷰 스킬과 함께 클라우드 에이전트를 시작합니다.

클라우드 실행에는 이 저장소의 다른 데모와 마찬가지로 GitHub Actions와 Warp 에이전트를 조합해 사용하지만, 선택지는 그 밖에도 많습니다. Warp의 장점은 여러 모델과 여러 하네스를 지원한다는 점입니다. 이는 비용을 관리하는 데 유리하고, 오픈 웨이트 모델도 실행할 수 있습니다. 어떤 인프라에서든 실행하도록 구성할 수도 있습니다.

review-pull-requests.yml이 PR opened·synchronize·reopened·ready_for_review 이벤트에서 실행되고, 에이전트에는 contents와 pull-requests 읽기 권한만 주는 설정 화면
PR 이벤트가 리뷰 작업을 시작하며, 에이전트는 읽기 전용 권한으로 review.json을 만들고 별도 게시 작업이 이를 검증해 코멘트로 올린다.

GitHub Action

에이전트에는 pull request에 대한 읽기 전용 권한만 주고, GitHub Action이 에이전트의 review.json을 프로그래밍 방식으로 GitHub 코멘트로 변환한다는 점에 주목하세요. 에이전트에 쓰기 권한을 주어 GitHub 코멘트를 직접 게시하게 할 수도 있지만, 그렇게 하면 다른 PR에 코멘트를 달거나 심지어 PR을 삭제하는 식의 프롬프트 인젝션 위험이 생깁니다.

다음은 상세한 인라인 코멘트와 수정 제안을 담은 고품질 리뷰 에이전트 결과의 예시입니다.

GitHub Actions 봇의 PR 리뷰가 Overview, Concerns, Verdict로 나뉘고, 고정되지 않은 액션 버전과 디스크에 남은 임시 페이로드 파일을 우려로 지적한 화면
PR 수준 요약: 전체 개요와 우려 사항, 최종 판정을 구조화해 제시한다.
resolve_spec_context.py의 594~599행에 달린 자동 리뷰 코멘트가 이미 가져온 연결 이슈 목록을 재사용해 중복 GraphQL 호출을 줄이라고 제안하는 화면
인라인 코멘트: 특정 코드 위치에서 중복 호출을 없애는 구체적인 수정 방향을 제안한다.

이 코멘트 가운데 하나에 답글을 달고 코드를 다시 푸시하면 리뷰 에이전트가 자동으로 다시 실행되도록 설정돼 있습니다. 에이전트는 이전 컨텍스트와 스레드를 이해하고, 상황에 맞게 다시 리뷰합니다. 정말 그만큼 간단합니다.

여기에서 멈춰도 기능은 하지만 기본적인 수준의 PR 리뷰어는 완성됩니다. 그러나 저는 자기 개선 루프를 이용해 이 리뷰어가 시간이 흐르며 더 나아지도록 설정하는 법까지 보여 주고 싶습니다.

루프는 다음과 같이 작동합니다.

  • 하루 동안 코드 리뷰 에이전트가 모든 PR에서 실행됩니다.
  • 사람 작성자와 리뷰어가 코드 리뷰 에이전트가 남긴 코멘트에 반응하며, 때로는 제안을 바로잡거나 타당하다고 확인합니다.
  • 하루에 한 번 ‘외부 에이전트’가 실행되어 그날 코드 리뷰 에이전트가 검토한 모든 PR을 살펴보고 사람의 피드백을 종합합니다.
  • 외부 에이전트가 이후 실행에서도 기억할 가치가 있는 지식을 발견하면, 코드 리뷰 에이전트 스킬을 업데이트하는 PR을 만듭니다.
  • 다음번 코드 리뷰 에이전트 실행에는 그 학습 내용이 반영됩니다.

이 시스템이 완벽한 것은 아닙니다. 그래도 팀의 선호에 관한 관련 정보가 더 많이 스킬에 들어갈수록 리뷰 품질은 시간이 지나며 좋아집니다. 그 정보는 코드 스타일일 수도 있고, 코드베이스의 특정 함정일 수도 있으며, 리뷰 에이전트가 제안을 어떤 방식으로 검증해야 하는지에 관한 내용일 수도 있습니다.

이 방식을 제대로 작동시키려면 코드 리뷰에 얼마를 쓰는지, 몇 번의 사이클이 필요한지, 리뷰어가 얼마나 자주 교정을 받는지를 파악할 수 있도록 메트릭과 평가를 함께 운영해야 합니다. 이런 루프를 위한 평가를 만드는 법은 다음 글에서 보여 드리겠습니다.

improve-review-pr SKILL.md가 하루 한 번 사람의 자동 리뷰 반응을 읽고 지속 가능한 조직 지식을 추출해 다음 review-pr 실행을 개선한다고 설명하는 화면
외부 루프는 사람의 검증과 교정에서 지속 가능한 조직 지식만 추출하며, 제품 코드를 다시 리뷰하거나 일회성 의견을 옮기지 않는다.

외부 루프 개선 스킬

제 샘플 PR에는 에이전트 코멘트에 긍정적인 피드백과 부정적인 피드백을 모두 추가했습니다. 그런 다음 외부 에이전트가 앞으로 이를 고려하도록 코드 리뷰어를 어떻게 조정하는지 관찰했습니다.

먼저, 코멘트를 추가하기보다 구조적인 코드 변경을 우선하라고 에이전트에 요청한 부정적인 피드백입니다.

봇이 parents[4]라는 매직 넘버에 설명 주석을 추가하자, 작성자가 주석보다 경로를 객체로 파싱해 필드 이름으로 접근하는 구조적 변경이 낫다고 답한 GitHub 코멘트 화면
부정 피드백: 단순히 주석을 보태기보다 의미가 드러나는 구조적 코드 변경을 선호한다.

그리고 HTTP 요청에 타임아웃을 추가하라고 제안한 것에 대한 긍정적인 피드백입니다.

봇이 urllib.request.urlopen 호출에 timeout 매개변수가 없어 CI가 오래 멈출 수 있다고 지적하고 timeout=30을 제안하자, 작성자가 항상 타임아웃을 추가하라고 긍정한 화면
긍정 피드백: urlopen을 사용할 때는 항상 타임아웃을 두라는 반복 가능한 규칙을 확인한다.

다음은 두 피드백을 반영해 ‘외부 루프’ 에이전트가 PR에서 제안한 코드 리뷰 스킬 조정입니다. 이제 이후 리뷰어 실행은 더 나아집니다.

review-pr SKILL.md에 타임아웃이나 행 중단 보호가 없는 외부 네트워크·서브프로세스 호출을 지적하고, 코멘트 전용 지침보다 구조적 수정을 선호하라는 두 규칙이 추가된 diff
스킬 조정: 타임아웃 누락을 점검하고, 가능하면 코멘트보다 구조적인 수정안을 우선하도록 리뷰 규칙을 갱신한다.

이 내용이 여러분에게 유용하기를 바랍니다. 직접 시험해 보려면 에이전트에게 클라우드 팩토리 데모 저장소에 있는 PR Review 및 Improve PR Review 스킬과 GitHub 워크플로를 추가하라고 요청하세요.

이 시리즈를 더 이어 갈수록, 에이전트를 하나씩 보태 완전한 팩토리를 만드는 데 점점 가까워질 것입니다. 다음 글에서는 컴퓨터 사용을 통해 변경 사항이 사용자 관점에서 올바른지 확인하는 검증 에이전트를 추가하는 법을 보여 드리겠습니다.

Warp에서는 이 과정을 더 바로 쓸 수 있는 형태로 만들고 있습니다. 하지만 시작 단계에서는 에이전트를 직접 설정하는 방법을 배우는 데 실제로 큰 가치가 있다고 생각합니다.

피드백이나 질문이 있다면 알려 주세요!