[AI활용] Claude 실무편 - kt cloud VM에서 PR 리뷰 자동화하기

KT Cloud FE개발팀이 PR 리뷰 병목 문제를 해결하기 위해 Claude 기반 자동화 시스템을 구축한 사례를 다룬다. "판단 기준은 사람이 정의하고, 검증 로직은 규칙으로 명시하며, 결과 설명은 AI가 수행한다"는 역할 분리 원칙 하에, kt cloud VM에서 poller 스크립트로 지속 실행하는 구조를 완성했다.

핵심 포인트

3-Layer 아키텍처: git diff 수집(Signals) → JSON 규칙 실행(Policy Engine) → Claude Code Agent가 코멘트 생성
리뷰 기준을 `.claude/architecture/architecture-rules.json`으로 코드화해 문서가 아닌 실행 대상으로 변환
tmux + poller.sh로 SSH 세션 종료 후에도 지속 실행, Webhook 대신 polling 방식으로 구조 단순화
AI는 아키텍처 위반·네이밍·공통모듈 변경 등을 검증하고 사람은 비즈니스 로직·트레이드오프 판단에 집중
결과: 리뷰어별 편차 제거, 시니어 병목 해소, 신규 멤버 온보딩 속도 향상

상세 정리

문제 정의: 아키텍처 의존성 확인·네이밍 컨벤션·공통모듈 변경 감지·구조적 리스크 탐지 등 반복 검증이 사람에게 집중돼 리뷰어별 품질 편차와 시니어 병목 현상 발생
핵심 원칙 "AI는 판단하지 않는다": 기준은 팀이 규칙으로 명시하고 AI는 그 결과를 사람이 이해하기 쉬운 형태로 정리 — hallucination 최소화와 재현성 확보
Signals 레이어: git diff 기반으로 파일 목록·코드 변경·영향 범위를 사실 데이터로 수집
Policy Engine 레이어: `architecture-rules.json`에 정의된 규칙을 실행해 아키텍처 위반·의존성 방향·네이밍 컨벤션을 자동 검증
Claude Code Agent 레이어: Policy Engine 결과를 사람이 읽기 쉬운 PR 코멘트로 변환해 게시
kt cloud VM 선택 이유: 사내 접근 제어·방화벽·GitHub 연동·지속 실행 서버·로그 관리 등 운영 가능한 전용 환경 필요
운영 구조: tmux 세션에서 `poller.sh` 스크립트를 지속 실행, SSH 종료 후에도 백그라운드 동작 유지
Polling 선택 이유: 별도 이벤트 서버 불필요, 네트워크 장애 영향 최소, 단순 구조로 유지보수 용이
로그 관리: `tail -f ~/logs/pr-review.log`로 실행 상태 추적 — 잘 돌아가는 것보다 문제 발생 시 추적 가능성이 운영 신뢰성의 핵심
규칙의 팀 자산화: JSON 규칙 파일은 변경 이력 추적 가능, 신입 온보딩 시 리뷰 기준을 코드로 전달