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

 

kt cloud FE개발팀 강민호 님

 

📝 요약 SUMMARY

이 글에서는 kt cloud VM 위에서 Claude 기반 PR Review Bot을 구축하고
PR 리뷰 자동화 구조를 설계한 실무 사례를 다룹니다.
리뷰 품질 편차와 반복 검증 부담을 줄이고 운영 가능한 자동화 방향을 정리합니다.

#Claude #PRReviewBot #PR리뷰자동화 #ktcloudVM #AI코드리뷰

---

1. 들어가며 — PR 리뷰는 왜 항상 병목이 되는가

PR(Pull Request)은 협업 기반 개발에서 코드 품질을 유지하기 위한 가장 중요한 프로세스 중 하나다.
모든 변경은 PR을 통해 공유되고, 리뷰를 거쳐 병합되며, 이 과정에서 코드의 안정성과 일관성이 확보된다.

 

하지만 실제 개발 환경에서는 PR 리뷰가 이상적으로 동작하지 않는 경우가 훨씬 많다.

 

리뷰어가 일정에 쫓기면 PR은 대기 상태로 쌓이기 시작하고,
프로젝트 맥락을 충분히 이해하지 못한 상태에서는 구조적으로 중요한 변경을 놓치기도 한다.
또한 동일한 코드라도 리뷰어에 따라 판단 기준이 달라지기 때문에, 리뷰 결과 자체가 일관되지 않는 경우도 빈번하게 발생한다.

 

특히 신규 프로젝트에 온보딩되는 시점에서는 이 문제가 더욱 두드러진다.
코드베이스와 아키텍처를 완전히 이해하지 못한 상태에서 PR 리뷰를 수행해야 하며,
그 과정에서 리뷰 품질은 개인의 경험에 크게 의존하게 된다.

PR 리뷰 병목 상황(ChatGPT)

리뷰 대기 상태의 PR이 쌓이며, 리뷰 속도와 품질이 사람의 상황에 따라 달라지는 구조

 

이 시점에서 필요한 것은 단순히 “리뷰를 더 열심히 하는 것”이 아니라,
리뷰를 시작하기 전에 구조적으로 문제를 걸러낼 수 있는 시스템이었다.

---

2. 문제 정의 — PR 리뷰의 본질적인 한계

기존 PR 리뷰의 핵심 문제는 단순히 리뷰가 느리다는 것이 아니다.
보다 본질적인 문제는 모든 판단과 검증이 사람에게 집중되어 있다는 점이다.

 

PR 리뷰 과정에서 반복적으로 수행되는 작업들을 살펴보면 다음과 같다.

• 아키텍처 레이어 의존성 확인
• 네이밍 컨벤션 검증
• 설정 파일 변경에 따른 영향도 판단
• 공통 모듈 변경 여부 확인
• 구조적 리스크 탐지

이러한 작업들은 대부분 규칙 기반으로 처리할 수 있는 영역임에도 불구하고,
현실에서는 모두 사람이 수동으로 수행하고 있다.

 

그 결과, 다음과 같은 문제가 구조적으로 발생한다.

• 리뷰어별 품질 편차
• 반복 검증에 따른 인적 비용 증가
• 시니어 리뷰어에게 집중되는 병목
• 신규 멤버 온보딩 속도 저하

기존 PR 리뷰 흐름(ChatGPT)

Developer → PR → Reviewer → Feedback

모든 검증이 사람에게 집중된 구조

 

이 문제를 해결하기 위해서는 리뷰를 강화하는 것이 아니라,
리뷰의 일부를 시스템으로 전환해야 했다.

---

3. 접근 전환 — AI는 판단하지 않는다

이번 구조를 설계하면서 가장 중요하게 설정한 원칙은 명확했다.

AI는 판단자가 아니라, 규칙 기반 결과를 설명하는 역할만 수행한다

 

일반적으로 AI를 코드 리뷰에 활용하려고 하면, AI에게 “이 코드가 좋은지 나쁜지 판단해달라”는 접근을 하게 된다.
하지만 이 방식은 결과의 신뢰성을 확보하기 어렵다.

 

대신 우리는 역할을 명확히 분리했다.

• 판단 기준 → 사람이 정의
• 검증 로직 → 규칙으로 명시
• 결과 설명 → AI가 수행

역할 분리 구조(ChatGPT)

판단과 실행을 분리한 구조

 

이 접근을 통해 다음과 같은 효과를 기대할 수 있었다.

• 결과의 재현성 확보
• 리뷰 기준의 명시화
• AI 환각(Hallucination) 최소화
• 리뷰 신뢰도 향상

---

4. 왜 kt cloud VM 위에 직접 만들었는가

이 프로젝트의 핵심은 단순히 AI를 활용했다는 것이 아니다.
AI 리뷰 시스템을 직접 구축했다는 점에 있다.

 

당시 상황을 보면 선택지는 명확하지 않았다.

• Claude는 PR 리뷰 기능을 제공하지 않았고
• GitHub Copilot의 유료 기능은 조직 차원에서 바로 도입하기 어려웠으며
• 팀 내부에서는 코드 품질을 일정 수준 이상으로 유지해야 하는 요구가 있었다

이 상황에서 선택한 방법은 단순했다.

필요한 기능이 없다면, 직접 만든다

kt cloud VM 생성

kt cloud VM 목록

VM 생성, 네트워크 설정, 보안 구성 화면 등등 구성

 

kt cloud VM을 활용함으로써 다음을 동시에 해결할 수 있었다.

• 사내 접근 제어 (방화벽 / IP allowlist)
• GitHub 연동 환경 구성
• 지속 실행 가능한 서버 확보
• 로그 및 실행 상태 관리

즉, 단순한 테스트 환경이 아니라
실제 운영 가능한 AI 실행 환경을 구축한 것이다.

---

5. 전체 구조 — PR Review Bot은 어떻게 동작하는가

PR Review Bot은 단순한 스크립트가 아니라,
여러 구성 요소가 결합된 하나의 실행 시스템이다.

전체 시스템 구조(ChatGPT)

이 구조에서 중요한 점은 “자동 실행”이다.

 

poller 스크립트는 일정 주기로 PR을 확인하고, 새로운 PR이 발견되면 diff를 수집한 뒤 Claude Code Agent를 호출해 리뷰를 수행한다.

이 과정은 사람이 개입하지 않아도 지속적으로 반복된다.

 

즉, PR 리뷰는 더 이상 사람이 시작하는 작업이 아니라, 시스템이 먼저 수행하는 작업으로 전환된다.

---

6. PR Review Agent 아키텍처

PR Review Agent는 단순히 AI 모델을 호출하는 구조가 아니라,
규칙 기반 검증 로직과 Claude Code 실행 환경이 결합된 형태로 설계되었다.

 

전체 구조는 다음과 같이 3개의 레이어로 구성된다.

3-Layer 구조(ChatGPT)

각 레이어의 역할은 명확하다.

• Signals
  git diff를 기반으로 변경된 파일 목록, 코드 변경 내용, 영향 범위를 수집한다.
  이 단계에서는 어떠한 해석도 하지 않고, 순수하게 “사실 데이터”만 확보한다.
• Policy Engine
  .claude/architecture/architecture-rules.json에 정의된 규칙을 기반으로
  아키텍처 위반 여부, 의존성 방향, 네이밍 컨벤션 등을 검증한다.
  이 단계에서 모든 판단이 이루어진다.
• Claude Code Agent
  Claude Code에 로그인된 실행 환경에서 Agent가 동작하며,
  Policy Engine의 검증 결과를 기반으로 PR 리뷰 코멘트를 생성한다.
  이 과정에서 Claude는 새로운 판단을 내리는 것이 아니라,
  이미 도출된 검증 결과를 사람이 이해하기 쉬운 형태로 정리하고 설명하는 역할을 수행한다.

---

7. 아키텍처 규칙을 코드로 정의한다

PR 리뷰를 자동화하기 위해 가장 먼저 해야 할 일은
리뷰를 대신 수행하는 시스템을 만드는 것이 아니라,
리뷰 기준을 명확하게 정의하는 것이다.

 

많은 팀이 PR 리뷰 자동화를 시도하지만 기대만큼의 효과를 얻지 못하는 이유는
검증 로직보다 먼저 정의되어야 할 “기준”이 명확하지 않기 때문이다.

7.1. 리뷰 기준은 존재하지만 실행되지 않는다

대부분의 조직에서 아키텍처 규칙과 컨벤션은 이미 존재한다.
다만 그 형태가 문서, 구두 전달, 개인 경험에 머물러 있기 때문에
항상 동일하게 적용되지는 않는다.

 

결국 PR 리뷰는 다음과 같은 상태에 머무른다.

규칙은 있지만, 일관되게 실행되지는 않는다.

7.2. 규칙을 실행 대상으로 바꾼다

이 문제를 해결하기 위해 우리는 규칙을 문서가 아니라
시스템이 직접 실행할 수 있는 형태로 정의했다.

 

즉,

• 문서 → 사람이 읽는 대상
• 규칙 파일 → 시스템이 실행하는 대상

으로 전환한 것이다.

 

이 순간부터 PR 리뷰는 사람이 확인하는 작업이 아니라
규칙을 실행하는 과정으로 바뀐다.

7.3. PR 리뷰는 규칙을 실행하는 과정이 된다

레이어 의존성, 네이밍 컨벤션, 설정 변경 영향도와 같은
반복적인 검증 요소들은 모두 규칙으로 정의할 수 있다.

 

이렇게 되면 PR 리뷰는 더 이상
코드를 눈으로 확인하는 작업이 아니라,

정의된 기준을 기반으로 검증하는 작업으로 전환된다.

7.4. 리뷰 기준이 팀 자산이 된다

규칙을 코드로 정의하는 순간,
리뷰 기준은 개인의 경험이 아니라 팀의 자산이 된다.

 

모든 PR이 동일한 기준으로 검증되고,
규칙은 코드로 관리되며,
변경 이력 또한 추적 가능해진다.

7.5. 왜 이 방식이 중요한가

이 구조는 단순 자동화가 아니라
다음 세 가지를 동시에 해결한다.

• 일관성: 모든 PR이 동일한 기준으로 검증된다
• 재현성: 언제나 동일한 결과를 얻을 수 있다
• 확장성: 팀이 커져도 품질을 유지할 수 있다

---

8. 운영 구성 — 실제 실행 환경

PR Review Bot은 단순히 한 번 실행되는 스크립트가 아니다.
팀의 코드 품질을 지속적으로 관리하기 위해서는,
이 Bot이 항상 동작하는 운영 시스템 형태로 구성되어야 한다.

 

즉, 이 구조의 핵심은 “자동 실행”이 아니라
“지속 실행 가능한 상태를 유지하는 것”이다.

운영 구조(ChatGPT)

8.1. 실행 환경 — kt cloud VM 기반 운영

PR Review Bot은 kt cloud VM 위에서 실행된다.
이 VM은 단순 테스트 환경이 아니라,
PR 리뷰 자동화를 지속적으로 수행하는 전용 실행 노드 역할을 한다.

 

이 환경을 선택한 이유는 명확하다.

• 항상 켜져 있는 실행 환경 필요
• 사내 접근 제어 및 보안 정책 적용 가능
• GitHub allowlist 연동 가능
• 로그 및 상태 관리 가능

즉, 로컬 실행이 아닌 팀 단위 운영 환경을 구성하는 것이 목적이었다.

8.2. poller 구조 — “이벤트 기반”이 아닌 “지속 감지 방식”

GitHub Webhook 기반 이벤트 처리 대신,
이번 구조에서는 poller.sh를 활용한 주기적 감지 방식(Polling)을 사용했다.

tmux new -s poller
bash ~/projects/ai-team/scripts/schedules/pr_review/poller.sh

poller는 일정 주기로 다음 작업을 수행한다.

1. GitHub CLI를 통해 PR 목록 조회
2. 신규 PR 또는 변경된 PR 감지
3. 해당 PR의 diff 수집
4. Claude Code Agent 실행
5. 리뷰 결과 생성 및 기록

이 방식의 장점은 다음과 같다.

• 별도 이벤트 서버 구성 불필요
• 네트워크/웹훅 장애에 영향 적음
• 단순한 구조로 유지보수 용이

즉, 복잡한 이벤트 기반 시스템이 아니라
안정성을 우선한 단순한 반복 실행 구조를 선택한 것이다.

8.3. tmux — 장기 실행을 위한 핵심 구성

PR Review Bot은 한 번 실행하고 끝나는 프로세스가 아니다.
서버 재시작, SSH 종료, 세션 단절과 같은 상황에서도
지속적으로 실행되어야 한다.

 

이를 위해 tmux를 사용했다.

tmux 실행 화면

poller가 지속적으로 실행되는 환경

 

tmux를 활용하면:

• SSH 세션 종료 후에도 프로세스 유지
• 백그라운드 실행 가능
• 언제든지 세션 재접속 가능

# 세션 생성
tmux new -s poller

# 세션 분리
Ctrl + B, D

# 세션 재접속
tmux attach -t poller

이 구조 덕분에 PR Review Bot은
사람의 개입 없이 계속 동작할 수 있다.

8.4. 로그 관리 — 운영 시스템의 필수 요소

자동화 시스템에서 가장 중요한 것은
“잘 돌아가는 것”이 아니라 “문제가 발생했을 때 추적 가능한 것”이다.

 

이를 위해 모든 실행 결과는 로그로 남긴다.

tail -f ~/logs/pr-review.log

즉, 로그는 단순 기록이 아니라
운영 시스템의 신뢰성을 보장하는 핵심 요소다.

8.5. 운영 관점에서의 핵심 설계 포인트

이 구조에서 중요한 것은 기술이 아니라 설계다.

 

다음 세 가지를 기준으로 설계했다.

 

✔ 지속 실행 가능성

• tmux 기반 장기 실행
• poller 기반 반복 구조
• 사람이 개입하지 않아도 계속 동작

✔ 단순성

• Webhook 대신 Polling
• 최소한의 구성 요소
• 장애 포인트 최소화

✔ 관측 가능성

• 로그 기반 상태 추적
• 실행 결과 기록
• 디버깅 가능 구조

---

9. 효과 — PR 리뷰의 출발점이 바뀐다

이 구조의 가장 큰 변화는 속도가 아니다.

 

리뷰의 “출발점”이 바뀐 것이다.

Before / After(ChatGPT)

기존	이후
사람이 분석	Bot이 분석
경험 의존	규칙 기반
편차 존재	항상 동일

 

기존에는 리뷰어가 PR을 열고, 어디를 중점적으로 봐야 할지 스스로 판단해야 했다.

이제는 Bot이 먼저 분석하고, 위험 요소와 구조적 문제를 정리해준다.

 

그 결과 사람은 반복 검증이 아닌, 비즈니스 로직과 설계 판단에 집중할 수 있게 된다.

---

10. 권장 협업 모델

PR Review Bot은 사람을 대체하기 위한 시스템이 아니다.
오히려 사람 리뷰어가 더 중요한 판단에 집중할 수 있도록 돕는 보조 실행 구조에 가깝다.

 

기존의 PR 리뷰는 모든 검증과 판단이 사람에게 집중되어 있었기 때문에,
리뷰어의 경험, 컨디션, 프로젝트 이해도에 따라 결과 품질이 달라질 수밖에 없었다.

 

반면 PR Review Bot을 도입한 이후에는 리뷰의 구조 자체가 다음과 같이 변화한다.

협업 구조(ChatGPT)

이 구조에서 가장 중요한 변화는 역할의 명확한 분리다.

10.1. Bot의 역할 — 반복 검증의 자동화

PR Review Bot은 다음과 같은 작업을 담당한다.

• 아키텍처 규칙 위반 여부 검증 (FSD 레이어, 의존성 방향 등)
• 네이밍 컨벤션 및 코드 스타일 체크
• 설정 파일 및 공통 모듈 변경 감지
• 변경 범위 및 영향도 분석
• 구조적 리스크 탐지 및 요약

이러한 작업들은 모두 규칙 기반으로 수행 가능하며,
사람이 반복적으로 수행하기에는 비용이 높은 영역이다.

 

Bot이 이 역할을 수행함으로써 얻는 가장 큰 이점은 다음과 같다.

• 모든 PR에 대해 동일한 기준 적용
• 검증 누락 없는 완전한 체크 수행
• 리뷰어의 반복 작업 제거
• 리뷰 시작 전 구조적 리스크 사전 제거

즉, Bot은 “빠르고 정확하게 반복 작업을 수행하는 실행 계층”이다.

10.2. 사람 리뷰어의 역할 — 맥락 기반 판단

반면 사람 리뷰어는 다음과 같은 영역에 집중하게 된다.

• 비즈니스 로직의 적절성 판단
• 설계 의도와 구현 방식의 정합성 검토
• 트레이드오프(성능 vs 유지보수성 등) 판단
• 사용자 경험(UX) 관점 검토
• 예외 상황 및 정책 미정 영역에 대한 판단

이러한 영역은 규칙으로 완전히 정의하기 어렵고,
프로젝트 맥락과 도메인 이해가 필요한 부분이다.

 

PR Review Bot이 1차 검증을 수행함으로써,
사람 리뷰어는 더 이상 “기계적인 체크”에 시간을 쓰지 않고,
가치 있는 판단에 집중할 수 있게 된다.

10.3. 조직 관점에서의 효과

이 협업 구조는 개인이 아니라 팀 단위에서 큰 효과를 만든다.

 

✔ 리뷰 품질의 표준화

 

모든 PR이 동일한 규칙으로 검증되기 때문에
리뷰어에 따른 품질 편차가 사라진다.

 

✔ 병목 해소

 

시니어 리뷰어에게 집중되던 부담이 줄어들고,
리뷰 처리 속도가 안정적으로 유지된다.

 

✔ 협업 비용 감소

 

“이건 괜찮은가?” 같은 반복 질문이 줄어들고,
리뷰 커뮤니케이션이 더 명확해진다.

실제 PR Review Bot이 달고 있는 리뷰들(꼭 확인해주세요.)

실제 PR Review Bot이 달고 있는 리뷰들(꼭 확인해주세요.)

실제 PR Review Bot이 달고 있는 리뷰들(한번 봐주세요.)

실제 PR Review Bot이 달고 있는 리뷰들(좋아요!)

실제 PR Review Bot이 달고 있는 리뷰들(이런 건 어떨까요?)

---

11. 정리 — 없으면 만드는 것도 기술력이다

이 사례의 핵심은 단순하다.

AI 기능이 없으면, 직접 만들어서 쓰면 된다

이건 단순 자동화가 아니다.

• 팀의 기준을 시스템으로 만들고
• 클라우드 위에서 실행하며
• 지속적으로 운영하는 구조를 설계한 것이다

---

결론 — PR 리뷰는 실행 시스템이 된다

PR 리뷰는 더 이상 사람이 시작하는 작업이 아니다.

시스템이 먼저 수행하고, 사람이 완성한다

 

이번 사례는 kt cloud 서비스를 기반으로 Claude, GitHub, Script를 결합해 만든

 

👉 실제 운영 가능한 AI 자동화 시스템이다

 

이번 PR Review Bot 구축은 FE개발팀과 협업을 통해 방향을 구체화할 수 있었다.

 

특히 아키텍처 규칙 정의 및 정책 설계 과정에서 김시엽님의 자동화 관점이 큰 도움이 되었으며,
이를 기반으로 실무에 적용 가능한 자동화 구조를 완성할 수 있었다.

 

함께 고민하고 방향을 만들어주신 점에 감사드린다.

 

---

❔자주 묻는 질문 FAQ

Q 왜 PR Review Bot을 직접 만들었는가?

A PR 리뷰는 팀 품질을 지키는 핵심 절차지만, 모든 리뷰를 사람이 직접 수행하면 리뷰어의 경험, 일정, 컨텍스트에 따라 품질 편차가 생긴다. 또한 GitHub Copilot 유료 기능을 팀 차원에서 바로 활용하기 어려운 상황에서는, 내부 환경에서 직접 운영 가능한 자동화 구조가 필요했다. 그래서 kt cloud VM 위에 Claude Code와 GitHub CLI를 조합해 팀 전용 PR Review Bot을 구성했다.

Q 왜 kt cloud VM 위에 구성했는가?

A 단순 로컬 실행이 아니라 팀에서 지속적으로 운영하려면 항상 켜져 있는 실행 환경이 필요했다. kt cloud VM을 사용하면 사내 접근 제어, GitHub allowlist, 전용 계정, 로그 관리, tmux 기반 장기 실행 구조를 구성할 수 있어 실무형 운영 환경에 적합했다.

Q Claude Code는 어떤 역할을 하는가?

A Claude Code는 PR diff를 읽고, 사전에 정의한 architecture-rules.json을 기준으로 변경 사항을 분석한 뒤 사람이 이해하기 쉬운 리뷰 결과로 정리한다. 중요한 점은 Claude가 임의로 판단하는 것이 아니라, 사람이 정의한 규칙을 기반으로 설명하는 역할을 맡는다는 점이다.

Q 이 구조의 가장 큰 가치는 무엇인가?

A 가장 큰 가치는 리뷰 품질의 표준화다. 리뷰어가 바뀌어도 동일한 기준으로 1차 검토가 가능하고, 신규 멤버도 팀의 아키텍처 규칙을 빠르게 이해할 수 있다. 결과적으로 PR 리뷰는 개인 역량에만 의존하는 절차에서, 팀의 품질 기준을 실행하는 시스템으로 확장된다.

---