본문으로 건너뛰기
PR마다 같은 기준으로 리뷰하는 Claude Code Action
목차

PR마다 같은 기준으로 리뷰하는 Claude Code Action (2026-02)

원문 정보

각자의 로컬 환경에 흩어진 리뷰 기준

LINE NEXT 개발자들은 이미 Claude Code로 변경 코드를 검토하고 있었습니다. 로컬에서 빠르게 피드백을 받는 데는 유용했습니다. 하지만 같은 도구를 쓴다고 같은 리뷰를 받는 것은 아니었습니다. 개발자마다 요청 방식과 검토 관점이 달랐고, 그 결과도 PR의 리뷰 흐름으로 자연스럽게 이어지지 않았습니다.

해마다 새 서비스가 나오면서 리포지터리도 늘었습니다. 사람의 리뷰 역시 리뷰어의 경험과 성향에 따라 깊이가 달라지는 상황에서, 개인별 AI 활용만으로는 조직의 품질 프로세스를 하나로 묶기 어려웠습니다. 새로 합류한 구성원에게 동일한 수준의 리뷰 경험을 바로 제공하기도 힘들었습니다.

DevOps 팀은 Claude Code를 조직 공통의 코드 리뷰 구성 요소로 만들기로 했습니다. 목표는 수십 개 프로젝트에 일관된 기준의 AI 리뷰를 제공하는 것이었습니다. 도구를 실행하는 방법뿐 아니라 리뷰 기준을 어디서 관리하고, 바뀐 기준을 어떻게 전체에 적용할지까지 정해야 했습니다.

호출만 남긴 GitHub Actions 워크플로

기존 개발 흐름 안에서 조직 전체로 확산할 수 있는지가 도입 기준 중 하나였습니다. LINE NEXT는 GitHub를 사용했고, 대부분의 서비스 리포지터리에서 GitHub Actions로 CI/CD와 자동화를 운영하고 있었습니다. 공식 Claude Code Action은 PR을 분석한 뒤 GitHub 댓글이나 리뷰로 결과를 남깁니다. 개발자가 새 화면에 익숙해질 과정도 없었습니다.

실행 환경도 준비돼 있었습니다. 사내에는 Claude Code를 공식적으로 사용할 수 있는 환경이 있었고, DevOps 팀은 조직 공통 GitHub App Runner를 미리 구성해 두었습니다. 서비스 팀마다 인프라를 추가하지 않고도 기존 GitHub Actions 설정으로 AI 리뷰를 연결할 조건이 갖춰진 것입니다.

문제는 연결한 뒤의 관리였습니다. AI 설정과 프롬프트를 각 리포지터리에 따로 두면 처음에는 빨리 도입할 수 있습니다. 그러나 정책이 바뀔 때마다 모든 리포지터리를 고쳐야 하고, 수정하는 과정에서 리뷰 기준의 편차가 다시 생깁니다.

그래서 서비스 리포지터리에는 호출만 남겼습니다. 호출자인 caller는 PR 이벤트를 감지하고 중앙의 재사용 워크플로에 실행 컨텍스트를 전달합니다. DevOps 팀이 관리하는 중앙 리포지터리는 실행자인 executor가 되어 프롬프트, 리뷰 정책, 권한 위임, 실행 로직을 맡습니다.

새 프로젝트도 같은 워크플로에 연결하면 됩니다. 리뷰의 톤과 깊이, 지적할 항목의 우선순위, 보안·안정성 체크 포인트를 중앙의 설정과 프롬프트로 관리하므로, 기준을 한 번 수정하면 전체 리포지터리에 바로 반영됩니다. 서비스 팀이 내부 실행 로직까지 관리할 이유가 없어졌습니다.

사용자 요청보다 앞에 둔 응답 형식

실행을 중앙으로 모아도 리뷰 결과는 여전히 흔들렸습니다. @claude 보안 검토해줘, @claude review this, @claude 성능 체크처럼 사용자가 요청을 바꿀 때마다 출력 형식도 달라졌습니다. 기존 Claude Code Action이 사용자 코멘트인 trigger_comment를 최우선 지시로 삼고, 워크플로의 custom_instructions는 참고용 컨텍스트로 취급했기 때문입니다.

형식이 달라지면 후속 파싱과 지표화가 불가능해집니다. 조직이 합의한 최소 리뷰 기준도 강제할 수 없었습니다. 사용자에게 분석할 초점은 맡기되, 응답에 포함할 항목과 형식은 시스템이 정하도록 지시의 우선순위를 바꿨습니다.

src/create-prompt/index.ts에서는 트리거 코멘트의 지시만 따르라는 문구를 수정했습니다. 사용자 코멘트는 무엇에 집중할지를 정하고, <custom_instructions>는 반드시 지켜야 할 출력 형식을 정한다는 CRITICAL 지시를 넣었습니다. src/modes/tag/index.ts에서도 해당 섹션 전체를 필수 구조와 가이드라인을 정의하는 강제 조항으로 감쌌습니다.

이제 보안 검토를 요청하면 보안에 무게를 두면서도 정해진 섹션을 모두 채워 응답합니다. 요청의 초점은 바뀌어도 보고서 형식은 유지됩니다. 이 변경으로 응답 형식이 고정됐고, 리뷰 결과를 자동화와 데이터 처리에 활용하기도 쉬워졌습니다.

공통 기준이 서비스의 특성까지 지우지는 않습니다. 중앙 워크플로는 configs/common/<analysis_type>.yml의 공통 프롬프트와 configs/<service_name>/<analysis_type>.yml의 서비스별 프롬프트를 병합합니다. 공통 프롬프트에는 코드 스타일, 명명 규칙, 안티 패턴과 응답 형식을 두고, 서비스 프롬프트에는 언어나 도메인에 맞는 검토 관점을 담습니다.

예를 들어 Kotlin/Spring Boot용 프롬프트는 계층 간 책임, !! 사용과 Null Safety, 트랜잭션 경계, N+1 문제 등을 살핍니다. 실행할 때는 공통 기준과 서비스의 맥락을 합친 하나의 페르소나로 Claude에 전달합니다. 이렇게 중앙에서 관리하는 프롬프트에는 조직이 합의한 기술 기준과 시니어 엔지니어의 리뷰 노하우가 축적됩니다.

포크 PR을 가져오는 GitHub의 비밀 통로

리뷰를 시작하기도 전에 멈추는 경우도 있었습니다. 포크에서 만든 PR을 처리하면 couldn't find remote ref 오류가 났습니다. 기존 구현은 PR의 브랜치 이름으로 origin에서 fetch했는데, 포크의 브랜치는 베이스 저장소인 origin에 없었습니다. Claude Code Action 저장소의 이슈 #233에서도 확인된 제약입니다.

LINE NEXT에서는 외부 기여자나 협업 리포지터리에서 들어오는 PR이 자연스럽게 발생했습니다. 이런 PR을 같은 파이프라인으로 처리하려면 코드를 가져오는 경로부터 바꿔야 했습니다.

해결에 쓴 것은 GitHub이 PR마다 만들어 두는 ‘비밀 통로’였습니다. GitHub은 포크를 포함한 모든 PR에 refs/pull/<PR 번호>/head라는 전용 참조를 생성합니다. 예를 들어 PR #42의 코드는 refs/pull/42/head에서 가져올 수 있습니다. 상대방의 포크 저장소에 직접 접근하지 않아도 origin에 마련된 참조로 PR 코드를 읽을 수 있는 것입니다.

src/github/operations/branch.ts에 PR 출처를 판별하는 로직을 추가했습니다. isCrossRepository 또는 head 소유자와 베이스 소유자의 비교로 포크 여부를 확인하고, 포크 PR이면 git fetch origin pull/<번호>/head:<브랜치명>으로 가져온 뒤 해당 로컬 브랜치를 체크아웃합니다. 일반 PR은 기존처럼 브랜치 이름으로 가져옵니다. 이 변경으로 포크 PR과 내부 브랜치의 PR 모두 같은 리뷰 파이프라인에서 처리하게 됐습니다.

공통 Runner에서 PR로 돌아오는 리뷰

서비스 팀의 준비는 짧습니다. 표준 호출자 워크플로 템플릿을 복사하고 조직 공유 시크릿 권한을 확인하면 됩니다. 이후 PR을 생성하거나 @claude 코멘트를 남기면 워크플로가 시작됩니다. caller는 서비스 식별자인 service_name, 분석 목적을 담은 analysis_type, 실행 환경을 고르는 runner_type을 중앙에 넘깁니다. runner_type의 예로는 self-hosted와 github-hosted가 있습니다.

중앙 워크플로가 프롬프트를 조합하고 코드를 분석할 준비를 마치면 권한 위임과 모델 호출이 이어집니다. 다른 리포지터리의 코드를 읽고 PR에 댓글을 쓰는 권한은 GitHub App으로 관리합니다. 개인 토큰(PAT)은 유출 시 조직 전체에 영향을 줄 수 있어 사용하지 않았습니다.

Claude Code Action은 GitHub App에서 해당 PR에만 유효한 단기 액세스 토큰을 발급받아 PR 컨텍스트를 읽습니다. 필요한 최소 권한의 부여와 회수는 DevOps 팀이 중앙에서 통제합니다. 시크릿과 공통 Runner도 함께 관리하므로 누가 어떤 권한으로 어떤 코드에 접근했는지 추적할 수 있습니다. 모델 호출은 사내 프록시를 거쳐 AWS Bedrock의 Claude로 향합니다.

결과는 개발자가 보던 PR 화면으로 돌아옵니다. 일반 코드 리뷰는 Blocking Issues, Recommended Changes, Suggestions, Tech Debt로 분류하고, 각 이슈에 위치와 문제 설명, 문제 코드, 권장 수정, 이유를 붙입니다. @claude에 security 키워드를 더하면 보안 관점의 분석을 호출합니다. 보안 리뷰는 위험 관리에 초점을 두므로 Critical, High, Medium, Low의 심각도로 결과를 나눕니다.

원문이 샘플 코드로 재구성한 리뷰 예시에서도 분류 기준이 드러납니다. OrderService.kt:12의 !!로 인한 NPE 가능성은 Blocking Issues에, OrderService.kt:13의 Lazy Loading에 따른 N+1 가능성은 Recommended Changes에 들어갑니다. 발견한 문제를 같은 무게로 나열하지 않고 수정 우선순위와 함께 제시하는 형식입니다.

32개 리포지터리에서 반복된 호출

도입 뒤에는 실제 사용 흐름을 측정했습니다. DevOps 팀은 GitHub App의 웹훅 이벤트와 사내 프라이빗 클라우드 기능을 이용해 리포지터리별 호출 횟수, PR 기준 엔드투엔드 수행 시간, 실행 성공·실패를 수집했습니다.

2025년 12월 중순부터 2026년 1월 초순까지 약 한 달간, 별도의 복잡한 온보딩 과정 없이 32개 리포지터리로 확산됐습니다. AI 리뷰는 총 344회 수행됐습니다. 대부분의 호출은 PR 생성 직후에 집중됐고, 여러 리포지터리에서 지속적으로 반복하는 패턴이 관측됐습니다. 글쓴이는 이를 개발자들이 AI를 초기 코드 품질을 검토하는 동료로 받아들이고 있다는 징후로 해석했습니다.

수집한 지표는 사내 DORA 대시보드의 Build 섹션에 포함했습니다. AI 리뷰를 빌드 생산성의 요소로 보고 관측하기 시작한 것입니다. 글쓴이는 DORA 대시보드의 상세 구축 과정은 향후 별도 포스팅에서 다룰 예정이라고 밝혔습니다.

PR에서 피드백을 받는 시점도 앞당겨졌습니다. AI가 PR 생성 직후 명확한 버그 가능성, 보안·안정성 위험, 반복되는 코드 패턴 문제를 먼저 검토합니다. 개발자는 그 피드백을 확인하고, 사람 리뷰어는 논의가 필요한 영역에 집중합니다. 글쓴이는 이 흐름에서 리뷰 편차와 대기 시간이 줄고 PR 초기 품질이 일정 수준 이상으로 유지된다고 설명합니다. 원문은 이를 뒷받침하는 수치를 따로 싣지 않았습니다.

도입 지표와 실행 컨텍스트
항목값
측정 기간2025년 12월 중순 ~ 2026년 1월 초순(약 한 달)
적용 리포지터리32개
AI 리뷰 호출 횟수총 344회
수집 지표리포지터리별 호출 횟수, PR 기준 엔드투엔드 수행 시간, 실행 성공·실패
caller가 전달하는 값service_name, analysis_type, runner_type
프롬프트 위치configs/common/<analysis_type>.yml, configs/<service_name>/<analysis_type>.yml
마지막 수정 일자