GitHub Actions 기반 AI 코드 리뷰 봇 구축: PR 비용 방어와 정적 분석 분리 실무

풀 리퀘스트(PR) 검토 과정에서 단순한 네이밍 규칙, 누락된 에러 처리, 반복적인 보일러플레이트 점검은 리뷰어의 인지 피로도를 크게 높입니다. GitHub Actions를 활용해 LLM 기반의 AI 코드 리뷰 파이프라인을 구축하면 이러한 기계적인 반복 점검을 자동화할 수 있습니다.

하지만 무턱대고 모든 PR 변경 사항을 LLM에 전송하면 package-lock.json이나 자동 생성 파일로 인해 수십만 개의 불필요한 토큰이 소모되고, 리뷰 봇의 무분별한 코멘트 공해로 개발자 경험이 저하됩니다. 본 가이드에서는 정적 분석 도구와의 명확한 역할 분담과 토큰 비용 방어 가드레일을 포함한 실무 파이프라인 구성법을 살펴봅니다.

정적 분석 도구와 AI 리뷰 봇의 역할 분담

AI 모델은 문법적 일관성을 잡는 린터가 아닙니다. 비용 효율적인 CI를 구축하려면 결정론적 도구와 확률론적 LLM의 역할을 철저히 구분해야 합니다.

팀 차원의 상세한 리뷰 원칙은 팀 협업을 위한 AI 생성 코드 리뷰 규칙을 참고할 수 있으며, 자동화된 단위 테스트 연계는 AI 생성 코드 테스트 검증 워크플로우에서 다룹니다.

4단계 AI 코드 리뷰 파이프라인 구축 절차

효율적이고 비용 안전한 AI 코드 리뷰 봇을 구성하기 위한 표준 절차는 다음과 같습니다.

1. 사전 검증 통과 여부 확인: 단위 테스트와 린터가 실패한 PR은 AI 리뷰를 실행하지 않고 조기 종료하여 토큰 소모를 방지합니다.
2. Diff 추출 및 노이즈 필터링: 빌드 산출물, 잠금 파일, 정적 에셋을 제외하고 실제 소스 코드 변경 분량만 추출합니다.
3. 토큰 한도 초과 가드레일 적용: 변경 라인 수가 임계값을 초과할 경우 청킹 분할을 수행하거나 경고 메시지만 남깁니다.
4. 구조화된 코멘트 인라인 게시: 파일별 라인 번호와 연계된 GitHub PR Review Comment API를 호출하여 리뷰를 등록합니다.

1단계: GitHub Actions 워크플로우 YAML 정의

.github/workflows/ai-code-review.yml 파일에 워크플로우를 정의합니다. 정적 분석 통과 후 실행되도록 의존성(needs)을 설정합니다.

name: AI PR Code Review

on:
  pull_request:
    types: [opened, synchronize]
    paths-ignore:
      - '**/*.md'
      - '**/package-lock.json'
      - '**/pnpm-lock.yaml'
      - 'dist/**'

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run lint
      - run: npm test

  ai-review:
    needs: lint-and-test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Generate Diff and Run Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          node scripts/ai-pr-reviewer.js

2단계: Diff 필터링 및 비용 제어 스크립트 작성

대용량 파일이나 무의미한 공백 변경을 걸러내고 LLM에 정제된 Diff만 전달하는 노드 스크립트 핵심 로직입니다.

// scripts/ai-pr-reviewer.js
const { execSync } = require('child_process');

// 1. 제외할 확장자 및 디렉터리 목록
const EXCLUDE_PATTERNS = [':!*.lock', ':!*.json', ':!dist/*', ':!public/*'];

// 2. base 브랜치 대비 실제 변경된 Diff 추출
const diffCommand = `git diff origin/${process.env.GITHUB_BASE_REF || 'main'}...HEAD -- . ${EXCLUDE_PATTERNS.join(' ')}`;
const diff = execSync(diffCommand, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });

// 3. 토큰 보호 가드: 변경 사항이 1,500줄 초과 시 요약 리뷰로 전환
const lineCount = diff.split('\n').length;
if (lineCount > 1500) {
  console.log(`[WARN] Diff 크기(${lineCount} lines)가 임계값을 초과하여 상세 분석을 건너뜁니다.`);
  process.exit(0);
}

운영 안정성을 위한 프롬프트 엔지니어링 원칙

AI 리뷰어가 과도하게 트집을 잡거나 무의미한 칭찬성 코멘트를 남기지 않도록 시스템 프롬프트에 엄격한 제약을 부여해야 합니다.

1. 지적 항목 제한 (Max 3 Items): 하나의 PR에 남기는 총 코멘트 수를 최대 3~5개로 제한하여 리뷰 피로도를 통제합니다.
2. 코드 제안 포함 강제 (Actionable Feedback): 단순 지적에 그치지 않고 구체적인 수정 전후 코드 블록(Unified Diff 포맷)을 반드시 제공하도록 지정합니다.
3. 심각도 라벨링: 코멘트 서두에 [Critical], [Warning], [Suggestion] 태그를 붙여 개발자가 우선순위를 즉시 판단할 수 있도록 지원합니다.

# 권장 시스템 프롬프트 가이드라인
당신은 엄격한 시니어 백엔드 엔지니어입니다.
문법 스타일, 네이밍 취향 등 ESLint가 해결할 수 있는 문제는 절대 언급하지 마십시오.
다음 영역에만 집중하여 최대 3개의 핵심 개선점을 제시하십시오:
1. 잠재적 레이스 컨디션 및 동시성 에러
2. unhandled Promise rejection 및 누락된 에러 핸들링
3. N+1 쿼리 또는 비효율적 메모리 누수 가능성