GitHub Action으로 AI 코드 리뷰어를 만들며 배운 점

소프트웨어 엔지니어링 팀에서 시간을 보내보셨다면, 풀 리퀘스트 (Pull Request) 리뷰가 궁극적인 병목 현상이라는 것을 알고 계실 것입니다. 리뷰는 느리고, 일관성이 없으며, 마감 압박 속에서 종종 완전히 생략되기도 합니다. 리뷰어들은 피로를 느끼고, 형식적인 승인(rubber-stamp approvals)이 관례가 되며, 갑자기 미묘한 버그들이 코드베이스에 스며듭니다. 아키텍처 정렬을 위해서는 인간의 리뷰가 필수적이지만, 명백한 코드 스멜 (Code Smells)이나 논리적 결함을 잡아내는 일은 우리가 항상 가지고 있지 않은 정신적 에너지에 크게 의존합니다.

한편, LLM (Large Language Models)의 능력은 폭발적으로 성장했습니다. LLM은 diff를 읽고, 문맥을 이해하며, 문제를 지적하는 데 진정으로 뛰어납니다. 저는 거대한 기업용 구독이나 번거로운 셀프 호스팅 러너 (Self-hosted runners)를 요구하지 않고도, 이 강력한 기능을 활용할 수 있는 매우 단순하고 즉시 사용 가능한(plug-and-play) GitHub Action이 출시되기를 계속 기다려 왔습니다. 하지만 주변을 둘러보니, 별도의 설정 없이 바로 작동하는 가볍고 오픈 소스인 도구를 만든 사람은 아무도 없었습니다. 그래서 제가 직접 만들었습니다.

Argus를 소개합니다. Argus는 풀 리퀘스트에 대한 자동화된 1차 검토 역할을 하는 GitHub Action입니다. 개발자가 PR을 오픈, 동기화 또는 다시 오픈할 때마다 Argus가 해당 이벤트에 트리거되어, diff를 가져오고, 각 수정된 파일의 문맥을 Groq의 Llama 3.3 70B 모델로 지능적으로 전송합니다. 그러면 LLM이 잠재적인 버그, 보안 취약점 또는 성능 병목 현상에 대해 코드를 분석합니다.

Argus는 방대한 양의 텍스트를 단일 댓글로 쏟아붓는 대신, 모델의 구조화된 출력을 파싱하여 문제가 되는 라인에 직접 구체적인 인라인 리뷰 댓글 (Inline review comments)을 게시합니다. 각 댓글은 high, medium, 또는 low와 같은 심각도 레이블로 분류되어 개발자가 무엇에 즉각적인 주의를 기울여야 하는지 정확히 알 수 있게 합니다. 설정 방법은 믿기지 않을 정도로 쉽습니다. 워크플로 (Workflow)에 다음 스니펫을 넣기만 하면 됩니다:

name: Argus Code Review
on:
  pull_request:
...

정말로 저를 놀라게 했던 점은 Llama 3.3 70B가 diff(변경 사항)를 읽고 이해하는 능력이 예외적일 정도로 뛰어나다는 것이었습니다. 오픈 웨이트 (open-weights) 모델이 고립된 코드 변경 사항의 미묘한 차이를 처리할 수 있을지 회의적이었지만, 제 생각이 틀렸음이 증명되었습니다. 테스트 과정에서 Argus는 제가 실수로 커밋한 하드코딩된 API 비밀 키를 잡아냈고, 심각한 레이스 컨디션 (race condition)을 유발할 수 있었던 비동기 함수에서의 await 누락을 지적했으며, 제 코드 내의 사용되지 않는 변수도 찾아냈습니다. 일반적인 조언을 환각 (hallucination)하는 것이 아니라, 깨진 코드를 푸시하는 상황을 막아줄 수 있는 매우 날카롭고 문맥을 파악한 피드백을 제공했습니다.

아이러니하게도 병목 현상은 AI가 아니라 파이프라인 (plumbing)이었습니다. Argus를 구축하며 가장 어려웠던 부분은 모델이 구조화된 JSON 출력을 안정적으로 반환하도록 프롬프트 엔지니어링 (prompt engineering)을 하는 것이었습니다. 그래야만 모든 댓글이 GitHub PR diff의 정확한 줄 번호와 매핑될 수 있기 때문입니다. GitHub API는 매우 엄격하기로 유명합니다. 수정되지 않은 줄에 댓글을 게시하려고 하면 API가 에러를 발생시키고 액션 (action)이 실패합니다. LLM이 완벽한 줄 번호 상관관계를 가진 유효한 JSON을 일관되게 반환하도록 만드는 데에는 수많은 반복 작업과 엄격한 폴백 (fallback) 로직이 필요했습니다.

또 다른 큰 장애물은 .argus/config.yml 시스템을 구축하는 것이었습니다. 저는 팀마다 자동화된 피드백에 대한 허용 범위가 크게 다르다는 것을 빠르게 깨달았습니다. 만약 봇이 사소한 스타일 선택 하나하나에 댓글을 단다면, 개발자들은 짜증을 느끼고 이를 무시할 것입니다. 그래서 팀들이 자신의 리포지토리에서 직접 액션의 동작을 미세 조정할 수 있도록 설정 시스템을 구현했습니다. 심각도 임계값(severity thresholds, 예: high 심각도 이슈만 표시)을 설정하고 특정 파일 경로를 무시함으로써, 팀들은 실제 사용 환경에서 매우 중요한 노이즈 대비 신호 비율 (noise-to-signal ratio)을 쉽게 제어할 수 있습니다.

만약 제가 이 프로젝트를 처음부터 다시 만든다면, 모든 것을 하드코딩(hardcoding)하는 대신 첫날부터 설정 시스템 (config system)부터 시작할 것입니다. 초기 버전에서는 모든 가정, 임계값 (thresholds), 그리고 무시할 경로 (ignored paths)를 핵심 로직에 직접 구워 넣었습니다 (baked in). 서로 다른 코드베이스 (codebases)에 걸쳐 테스트를 시작했을 때, 이러한 하드코딩된 규칙들은 즉시 무너졌습니다. 프로젝트 후반부에 .argus/config.yml 파일을 읽고 파싱하도록 액션 (action)을 리팩터링 (refactoring)하는 과정은 매우 지저분했습니다. 처음부터 사용자 설정 (user configuration)을 염두에 두고 구축했다면 엄청난 양의 기술 부채 (technical debt)를 줄일 수 있었을 것입니다.

PR (Pull Request)이 리뷰 지옥 (review purgatory)에 머물러 있는 것에 지쳤거나, 코드에 대해 빠르고 자동화된 '두 번째 눈'을 원한다면 Argus를 사용해 보세요. 리포지토리 (repo)는 https://github.com/Rozer402/argus에서 찾을 수 있습니다. 이 프로젝트는 무료이며 오픈 소스 (open source)이고, Groq의 관대한 무료 티어 (free tier)를 사용하므로 고품질의 코드 리뷰를 받기 위해 API 비용이 쌓일 걱정을 할 필요가 없습니다. 워크플로 (workflow)에 도입하고, 설정을 조정하며, AI가 힘든 일을 처리하게 하세요.

팀이 아키텍처 (architecture)에 집중할 수 있게 하고, 버그는 Argus가 잡게 하세요.