OpenClaw로 GitHub PR 코드 리뷰 자동화하기

무엇을 구축하나요

완전한 PR 자동 리뷰 파이프라인을 만듭니다:

1. PR 자동 생성 — 커밋 이력을 기반으로 AI가 규격에 맞는 PR 설명을 작성합니다
2. AI 코드 리뷰 — 코드를 자동 분석하여 버그, 보안 취약점, 스타일 문제를 찾아냅니다
3. 커밋 규격화 — Conventional Commits 형식을 강제합니다
4. 실행 가능한 피드백 — PR에 인라인 리뷰 코멘트를 직접 남깁니다

구축이 완료되면 PR을 열 때마다 AI 리뷰가 자동으로 실행되며, 수동 개입이 필요 없습니다.

AI 기반 코드 리뷰가 필요한 이유

수동 코드 리뷰는 필수적이지만, 실제 운영에서 분명한 한계가 있습니다:

• 리뷰 품질 불안정 — 리뷰어마다 관점이 다릅니다. 네이밍 규칙을 보는 사람, 에러 처리를 보는 사람이 따로 있어 어떤 문제가 발견되는지는 "오늘 누가 리뷰하느냐"에 달려 있습니다
• 리뷰 피로 — 수백 줄의 코드를 검토한 후에는 집중력이 크게 떨어집니다. 연구에 따르면 60분 이상 연속 리뷰 시 효율이 급격히 저하되며, 중요한 버그는 큰 diff의 뒷부분에 숨어 있는 경우가 많습니다
• 대기 시간 — 리뷰어도 자신의 개발 업무가 있습니다. PR이 몇 시간, 심하면 며칠째 방치될 수 있습니다. 이는 작성자를 차단하고, 대규모 PR을 유발하며, 머지 충돌을 일으킵니다
• 확장성 문제 — 팀이 커질수록 리뷰 병목이 심해집니다. 시니어 개발자는 점점 더 많은 시간을 리뷰에 쓰게 되고, 신규 팀원은 코드베이스를 충분히 파악하지 못할 수 있습니다

AI 리뷰는 수동 리뷰를 대체하는 것이 아니라, 체계적인 검사(보안 패턴, 일반적인 버그, 스타일 위반)를 처리하여 수동 리뷰어가 아키텍처 설계와 비즈니스 로직에 집중할 수 있게 합니다. 사람이 보기 전에 기본 품질을 먼저 확인하는 것으로 이해하시면 됩니다.

사전 준비

시작하기 전에 다음을 확인하세요:

• OpenClaw 설치 및 설정 완료 (시작 가이드)
• GitHub CLI (gh) 설치 및 인증 완료 (gh auth login)
• GitHub 저장소 테스트용 (개인 프로젝트도 가능)
• Node.js 18+

1단계: 필요한 Skills 설치

순서대로 세 가지 Skill을 설치합니다:

# 1. GitHub 연동 (기본 기능)
npx clawhub@latest install github

# 2. PR Reviewer (코드 분석)
npx clawhub@latest install pr-reviewer

# 3. Conventional Commits (커밋 포맷팅)
npx clawhub@latest install conventional-commits

설치 확인:

clawhub list

세 가지 Skill 모두 installed로 표시되어야 합니다.

2단계: GitHub 인증 설정

GitHub Skill에는 다음 권한이 포함된 Personal Access Token이 필요합니다:

• repo — 전체 저장소 접근 권한
• read:org — 조직 구성원 정보 읽기 (조직 저장소인 경우, 선택 사항)

이미 gh auth login으로 인증을 완료했다면 Skill이 기존 자격 증명을 자동으로 사용합니다. 그렇지 않은 경우:

# 현재 인증 상태 확인
gh auth status

# 로그인이 필요한 경우
gh auth login

3단계: PR Reviewer 설정

PR Reviewer Skill은 즉시 사용 가능하지만 동작을 커스터마이즈할 수 있습니다:

# 기본 설정 확인
clawhub inspect pr-reviewer

주요 설정 항목:

• 리뷰 깊이: quick (빠른 스캔) 또는 thorough (심층 분석)
• 관심 영역: 보안, 성능, 스타일, 버그, 또는 전체
• 자동 코멘트: PR에 직접 코멘트를 게시할지 여부

4단계: 첫 번째 자동 리뷰 PR 만들기

실제 PR로 전체 워크플로우를 테스트합니다:

4.1 기능 브랜치 생성

git checkout -b feature/test-ai-review

4.2 코드 작성

프로젝트에서 파일을 수정합니다. 테스트를 위해 리뷰어가 잡아낼 수 있는 일반적인 문제를 의도적으로 넣어 봅니다:

async 호출에 await 누락 (비동기 버그):

// Bug: async 호출에 await 누락
function getUserData(userId) {
  const response = fetch(`/api/users/${userId}`);  // await 누락
  return response.json();  // TypeError: response.json is not a function
}

SQL 인젝션 취약점:

# 보안 문제: 사용자 입력이 SQL 쿼리에 직접 삽입됨
def get_user(user_id):
    query = f"SELECT * FROM users WHERE id = '{user_id}'"  # SQL 인젝션 위험
    return db.execute(query)

하드코딩된 시크릿:

// 보안 문제: API 키가 소스 코드에 노출됨
const stripe = require('stripe')('sk_live_abc123secretkey');

N+1 쿼리 문제:

# 성능 문제: N+1 쿼리 — 주문마다 데이터베이스 쿼리가 한 번씩 실행됨
def get_orders_with_items(user_id):
    orders = Order.objects.filter(user_id=user_id)
    for order in orders:
        order.items = OrderItem.objects.filter(order_id=order.id)  # N+1!
    return orders

4.3 Conventional Commits로 커밋

커밋 메시지를 직접 작성하지 않고 OpenClaw가 생성하도록 합니다:

git add .
# OpenClaw가 Conventional Commits 규격에 맞는 커밋 메시지를 자동 생성합니다
# 예: "feat(api): add getUserData function for user data retrieval"

4.4 PR 생성 및 리뷰

# OpenClaw가 PR을 자동 생성하고 AI 설명을 작성합니다
# 이후 PR Reviewer가 자동으로 diff를 분석합니다

몇 초 안에 다음을 확인할 수 있습니다:

• 변경 사항을 자동 요약한 규격화된 PR 설명
• 특정 코드 라인에 대한 리뷰 코멘트
• 전체 평가와 개선 제안이 담긴 요약 코멘트

리뷰 코멘트 예시:

🔒 보안 문제 (14번 줄, auth.py):
  사용자 입력이 SQL 쿼리 문자열에 직접 삽입되어 있습니다.
  SQL 인젝션 공격에 취약합니다.
  권장 수정: 파라미터화된 쿼리를 사용하세요.

  - query = f"SELECT * FROM users WHERE id = '{user_id}'"
  + query = "SELECT * FROM users WHERE id = %s"
  + return db.execute(query, (user_id,))

⚡ 성능 문제 (8번 줄, orders.py):
  N+1 쿼리가 감지되었습니다 — OrderItem.objects.filter()가
  루프 안에서 주문마다 한 번씩 호출됩니다.
  select_related() 또는 prefetch_related()를 사용하여
  하나의 쿼리로 통합하세요.

  - orders = Order.objects.filter(user_id=user_id)
  + orders = Order.objects.filter(user_id=user_id).prefetch_related('items')

🐛 버그 (3번 줄, api.js):
  fetch()가 Promise를 반환하지만 await가 없습니다.
  response.json()은 response가 Response 객체가 아닌
  pending Promise이므로 실패합니다.

  - const response = fetch(`/api/users/${userId}`);
  + const response = await fetch(`/api/users/${userId}`);

5단계: 리뷰 워크플로우 커스터마이즈

보안 우선 리뷰

보안에 민감한 저장소의 경우 PR Reviewer가 보안 검사에 집중하도록 설정합니다:

• SQL 인젝션 패턴
• 하드코딩된 자격 증명 또는 API 키
• 안전하지 않은 데이터 처리 (미검증 입력, 필터링 누락)
• 의존성 취약점
• 프런트엔드 코드의 XSS 취약점
• 안전하지 않은 역직렬화 패턴

성능 중심 리뷰

성능에 민감한 서비스의 경우 리뷰어가 성능 패턴에 집중하도록 합니다. 예를 들어 React 프로젝트에서 불필요한 리렌더링을 감지합니다:

// 성능 문제: 렌더링할 때마다 새 객체 참조가 생성되어 자식 컴포넌트 리렌더링 발생
function ParentComponent({ items }) {
  return (
    <ChildComponent
      style={{ margin: 10 }}        // 렌더링마다 새 객체
      onClick={() => doSomething()}  // 렌더링마다 새 함수
    />
  );
}

팀 전체 설정

팀에서 리뷰 설정을 공유합니다:

1. Skill 설정을 저장소의 .openclaw/ 디렉터리로 내보냅니다
2. 코드 저장소에 커밋합니다
3. 팀원이 동일한 설정으로 설치합니다 — Skill이 프로젝트 수준 설정을 자동으로 읽습니다

고급: 리뷰 포커스 가이드

자연어 지시를 통해 PR Reviewer의 리뷰 방향을 조정할 수 있습니다.

언어별 가이드

리뷰 실행 시 Agent에게 집중할 부분을 알려줍니다:

• Python: 맨 except: 블록, 누락된 타입 힌트, Django ORM N+1 쿼리 확인
• JavaScript/TypeScript: 남아 있는 console.log, async 호출의 await 누락, 하드코딩된 시크릿 표시
• Rust: 프로덕션 코드의 .unwrap() 표시, 올바른 Result 처리 제안

디렉터리별 가이드

디렉터리마다 다른 리뷰 수준을 설정합니다:

• 핵심 비즈니스 로직 (src/core/) — 보안, 버그, 성능을 포괄하는 전면 리뷰
• 테스트 파일 (src/tests/) — 정확성만 빠르게 확인
• 문서 (docs/) — 가벼운 스타일 리뷰
• 스크립트 (scripts/) — 보안과 버그에 집중

커스텀 규칙

리뷰어에게 프로젝트 특화 안티 패턴을 표시하도록 합니다:

• API 라우트에서 Repository 계층을 거치지 않고 데이터베이스에 직접 접근
• 페이지 컴포넌트에 Error Boundary 누락
• API 엔드포인트에 속도 제한 없음

CI/CD 연동

모든 PR에서 자동 리뷰를 실행하려면 PR Reviewer를 CI/CD 파이프라인에 통합합니다.

GitHub Actions

.github/workflows/ai-review.yml에 워크플로우 파일을 생성합니다:

name: AI PR Review
on:
  pull_request:
    types: [opened, synchronize]

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

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install OpenClaw and skills
        run: |
          npm install -g clawhub@latest
          clawhub install pr-reviewer

      - name: Run AI Review
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          OPENCLAW_API_KEY: ${{ secrets.OPENCLAW_API_KEY }}
        run: |
          clawhub run pr-reviewer \
            --pr ${{ github.event.pull_request.number }} \
            --repo ${{ github.repository }} \
            --auto-comment

리뷰 트리거 조건 제어

AI 리뷰를 특정 조건에서만 실행하도록 제한하여 비용을 절감합니다:

on:
  pull_request:
    types: [opened, synchronize]
    paths-ignore:
      - '*.md'
      - 'docs/**'
      - '.github/**'

또는 라벨이 추가된 후에만 리뷰를 실행합니다:

- name: Check for review label
  if: contains(github.event.pull_request.labels.*.name, 'ai-review')
  run: clawhub run pr-reviewer --pr ${{ github.event.pull_request.number }}

기타 CI 플랫폼

Node.js를 지원하는 모든 CI 플랫폼에서 동일한 방식을 사용할 수 있습니다. 핵심 단계:

1. clawhub와 pr-reviewer Skill 설치
2. OPENCLAW_API_KEY를 환경 변수로 설정
3. PR 번호와 저장소 정보 전달
4. CI Bot이 Pull Request에 쓰기 권한을 가지고 있는지 확인

실제 효과

이 워크플로우를 사용하는 팀에서 일반적으로 확인되는 결과:

• PR 처리 속도 40% 향상 — AI가 명확한 문제를 먼저 처리하여 수동 리뷰 부담 감소
• 일관된 리뷰 품질 — 모든 PR이 동일한 기준으로 분석됨
• 깔끔한 커밋 이력 — Conventional Commits로 변경 로그가 자동화됨
• 프로덕션 버그 감소 — AI가 사람이 놓치기 쉬운 문제를 포착함

문제 해결

"GitHub CLI not found"

gh가 설치되어 있고 PATH에 포함되어 있는지 확인합니다:

# macOS
brew install gh

# Linux
sudo apt install gh

# Windows
winget install GitHub.cli

PR 생성 시 "Permission denied"

Token 권한을 확인합니다:

gh auth status

repo 권한이 포함되어 있는지 확인하세요. 필요한 경우 재인증합니다:

gh auth login --scopes repo

PR Reviewer가 코멘트를 남기지 않음

Skill 설치 및 설정을 확인합니다:

clawhub inspect pr-reviewer

OpenClaw AI 제공자가 설정되어 있고 사용 가능한 크레딧이 있는지 확인하세요.