PROJECT: AI CODE REVIEW SERVICE

┌──────────────────────────────────────────┐
│   PROJECT: AI CODE REVIEW SERVICE        │
└──────────────────────────────────────────┘

kwt@portfolio:~/projects/ai-code-review$ describe

AI Code Review Service

GitHub Webhook Review Bot

GitHub Pull Request 변경분을 LLM으로 분석하고, 문제 가능성이 있는 코드 라인에 리뷰 코멘트를 남기도록 적용한 AI 코드 리뷰 서비스입니다. 단순히 LLM API를 호출하는 PoC에서 끝내지 않고, GitHub webhook, GitHub App 인증, PR-level context 구성, 리뷰 라인 매핑, 오탐 튜닝까지 포함해 실제 개발 workflow에 붙일 수 있는 형태로 만들었습니다.

기간: 2026.01 ~ 2026.03
역할: 설계 및 개발 / 백엔드 1인
상태: 중요 서비스 대상 PoC 및 운영 적용 완료

Problem

변경량이 많은 PR이나 운영 영향도가 높은 서비스에서는 사람이 모든 리스크를 빠르게 잡기 어렵습니다. 정적 분석만으로는 비즈니스 맥락과 변경 의도를 충분히 보지 못하고, LLM 단독 리뷰는 오탐과 라인 매핑 오류가 발생할 수 있습니다. 이 프로젝트의 목표는 LLM을 사람 리뷰의 대체물이 아니라 운영 리스크를 먼저 드러내는 보조 리뷰어로 연결하는 것이었습니다.

Review Flow

PR Event

GitHub Pull Request opened / synchronize / reopened 이벤트를 webhook으로 수신하고 draft PR은 제외합니다.

Webhook Gate

X-Hub-Signature-256 HMAC 검증 후 즉시 응답하고, 실제 리뷰 처리는 비동기 작업으로 분리합니다.

Context Builder

PR 파일 목록, diff의 추가 라인, 변경 라인을 감싸는 메서드, 호출 메서드 구현체를 수집합니다.

PR-level Review

파일별 호출 대신 PR 전체 변경 파일을 단일 프롬프트로 묶어 LLM 리뷰를 수행합니다.

GitHub Feedback

응답을 파일/라인별 코멘트로 변환하고 GitHub App 권한으로 PR 인라인 리뷰와 요약을 작성합니다.

GitHub PR
  -> Webhook Signature Validation
  -> Async Review Worker
  -> GitHub API: PR files / diff / file content
  -> Changed Lines + Method Context
  -> PR-level LLM Review
  -> Response Parser / Line Mapper
  -> GitHub App Review Comment

What I Built

- Spring Boot 기반 GitHub webhook 수신 API와 수동 리뷰용 웹 UI 구성
- GitHub App 인증으로 봇 전용 아이덴티티를 분리하고 Installation Access Token을 캐싱/갱신
- Gemini / GLM provider를 설정으로 전환할 수 있는 LLMService 인터페이스 구조 구현
- diff의 추가 라인만 L번호 형식으로 추출해 리뷰 대상 범위와 토큰 사용량을 줄임
- PR-level 단일 프롬프트 리뷰로 파일 간 맥락을 포함하고 API 호출 수를 줄임
- MethodContextExtractor로 변경 코드에서 호출한 메서드 구현체와 변경 라인을 감싸는 메서드 바디를 프롬프트에 포함
- LLM 응답의 파일명/라인 번호를 GitHub patch 범위와 매핑하고 유효하지 않은 코멘트는 제외
- 심각도별 HIGH / MEDIUM / LOW 기준과 리뷰 제외 경로, 파일 크기, PR당 파일 수 제한을 설정화

Guardrails

- 지원 이벤트: pull_request opened / synchronize / reopened
- 제외 조건: draft PR, 삭제 파일, 제외 경로, 변경량이 큰 파일, 지원하지 않는 확장자
- 보안: webhook HMAC 검증, GitHub App 권한, 웹 UI 로그인, 환경 변수 기반 secret 관리
- 운영성: webhook 타임아웃 방지를 위한 비동기 처리, 토큰 사용량 로깅, 리뷰 결과 요약

False Positive Tuning

운영 적용에서 중요한 부분은 LLM을 붙이는 것보다 오탐을 줄이는 과정이었습니다. 리뷰가 너무 자주 틀리면 개발자가 무시하게 되므로, 실제 코멘트를 수집하고 프롬프트와 컨텍스트 구성을 조정했습니다.

- 중요도가 높은 서비스를 대상으로 PoC 적용 후 실제 리뷰 코멘트 품질을 확인
- 파일별 독립 리뷰에서 발생한 맥락 부족과 오탐을 PR-level 통합 리뷰로 개선
- 메서드 내부의 사전 검증 로직을 LLM이 보지 못해 생기는 null/예외 처리 오탐을 메서드 컨텍스트로 줄임
- 코드 스타일보다 null 처리, 예외 처리, 보안/권한 누락, 성능 저하 가능성 등 운영 리스크 중심으로 기준 조정
- 이슈가 없을 때는 불필요한 인라인 코멘트를 남기지 않고 요약 코멘트만 작성하도록 처리

Before / After

Before

- 리뷰 품질이 사람의 가용 시간과 서비스 이해도에 크게 의존
- 단순 LLM 호출 방식은 파일 간 맥락 부족으로 오탐 발생
- 봇과 사람의 리뷰 주체가 명확히 구분되지 않음
- 라인 매핑 오류가 발생하면 실제 PR 코멘트로 연결하기 어려움

After

- PR 생성/갱신 시 자동으로 변경 코드 리뷰 수행
- PR 단위 context와 메서드 context로 오탐 감소
- GitHub App을 통해 봇 전용 리뷰 아이덴티티 적용
- 유효한 파일/라인만 인라인 코멘트로 남기고 결과를 요약

Positioning

이 서비스는 AI가 코드를 최종 승인하는 구조가 아닙니다. AI는 변경 diff를 빠르게 읽고 위험 가능성이 있는 지점을 제안하며, 사람은 그 결과를 참고해 최종 판단합니다. 백엔드 관점에서는 webhook, 인증, 비동기 처리, provider adapter, prompt/context 구성, 리뷰 결과 검증을 묶어 사내 개발 workflow에 AI를 안전하게 연결한 프로젝트입니다.