CI에서의 Claude Code: 모든 Pull Request에 대한 에이전트 방식의 코드 리뷰, 테스트 생성 및 자동 수정 실행

이 기사는 인간의 감독과 검토 하에 AI의 도움을 받아 작성되었습니다.

왜 CI에서의 에이전트 방식(Agentic) 코드 리뷰가 모든 것을 바꾸는가

대부분의 CI 실패는 수동 개입에 수 시간을 낭비하게 만듭니다. 기존의 봇들은 문제를 지적할 뿐 결코 수정하지 않기 때문입니다. 개발자가 pull request (PR)를 열면, linter가 실패하고, 테스트가 깨지며, 누군가는 현재 작업에서 문맥 전환 (context-switch)을 하여 문제를 진단하고 패치해야 합니다. 이러한 문맥 전환은 팀 전체에 걸쳐 누적되어, CI 위생을 유지하는 비용이 CI가 제공하는 가치를 초과하게 됩니다.

자동 모드로 실행되는 Claude Code는 CI 파이프라인 내부에서 자율적인 에이전트 (autonomous agent)로 작동함으로써 이 문제를 해결합니다. pull request가 워크플로우를 트리거하면, Claude Code는 diff를 검토하고, 누락된 테스트를 생성하며, 실패를 수정하려고 시도하고, 리뷰 코멘트로 구조화된 피드백을 게시합니다. 이 모든 과정은 인간의 개입 없이 이루어집니다. 개발자는 에러 로그 대신 실행 가능한 수정 사항을 받게 됩니다.

이러한 차이점은 매우 중요합니다. 전통적인 CI 봇은 탐지하고 보고합니다. 에이전트 방식의 CI는 탐지하고, 수리하며, 문서화합니다. 투자 대비 효과 (ROI)는 두 가지 측면에서 나타납니다. 일상적인 문제에 대한 병합 시간 (time-to-merge) 단축과, 실제로 인간의 판단이 필요한 아키텍처 결정에 집중할 수 있도록 인지적 역량을 보존하는 것입니다.

핵심 요약 (Key Takeaways)

• Claude Code의 자동 모드(auto mode)는 CI 파이프라인에서 무인(unattended)으로 실행되며, 안전 분류기(safety classifier)가 위험한 명령을 실행하기 전에 차단합니다.
• 에이전트 방식의 CI(Agentic CI)는 코드 리뷰, 테스트 생성, 자동 수정(auto-fix)을 단일 워크플로우 내에서 수행하여, 수동적인 컨텍스트 스위칭(context-switch) 루프를 제거합니다.
• 프로덕션 배포 시에는 제어되지 않는 실행을 방지하기 위해 비용 제어(PR당 토큰 예산), 범위가 지정된 파일 권한(scoped file permissions), 종료 조건(exit conditions)이 필요합니다.
• GitHub Actions, GitLab CI, Azure DevOps 모두 환경 변수와 비밀 관리(secrets management)를 통해 Claude Code 통합을 지원합니다.
• 현재 유효한 패턴은 모든 작업을 시도하는 단일 에이전트가 아니라, 리뷰용, 테스트 생성용, 자동 수정용으로 각각 구분된 범위 지정형 단일 책임 에이전트(scoped, single-responsibility agents)를 사용하는 것입니다.

Claude Code 자동 모드: CI 파이프라인에서의 무인 실행

자동 모드(Auto mode)를 사용하면 Claude Code가 대화형 확인 없이 명령을 실행할 수 있습니다. 에이전트는 작업을 수신하고, 일련의 작업 시퀀스를 계획하며, 분류기 모델(classifier model)이 정의된 경계를 벗어난 권한 상승(scope escalation)이나 파일 시스템 접근을 검토하는 동안 작업을 완료할 때까지 실행합니다. 에이전트가 저장소 쓰기 권한과 환경 비밀(environment secrets)을 가지고 작동하기 때문에, CI에서는 이러한 안전 계층(safety layer)이 매우 중요합니다.

여기서 발생하는 실패 모드는 미묘하지만 비용이 많이 듭니다. 자동 모드가 없으면 Claude Code는 모든 명령에 대해 대화형 승인을 기다리며 일시 중지됩니다. CI 환경에는 상호작용을 위한 터미널이 존재하지 않으므로, 워크플로우는 타임아웃(timeout)이 발생할 때까지 멈춰 있게 됩니다. 자동 모드를 활성화하면 에이전트는 작업을 완료하거나 안전 차단(safety block)에 걸리게 되며, 두 경우 모두 풀 리퀘스트(pull request)를 위한 유용한 결과를 생성합니다.

자동 모드(auto mode)를 설정하려면 CLAUDE_AUTO_MODE 환경 변수를 설정하고 워크플로 매니페스트(workflow manifest)에 권한 범위(permission scope)를 정의해야 합니다. 이 범위는 에이전트가 읽거나 수정할 수 있는 파일을 제한합니다. 코드 리뷰 에이전트는 전체 디프(diff)를 볼 수 있어야 하지만, 쓰기 작업은 임시 댓글 파일에만 수행해야 합니다. 테스트 생성 에이전트는 소스 파일에 대한 읽기 권한과 테스트 디렉토리에 대한 쓰기 권한이 필요합니다.

풀 리퀘스트 리뷰를 위한 Claude Code 설정

에이전트 방식의 CI(agentic CI)를 위한 진입점은 풀 리퀘스트(pull request) 이벤트 발생 시 트리거되는 GitHub Actions 워크플로입니다. 이 워크플로는 저장소를 체크아웃(check out)하고, Claude Code를 설치하며, 특정 PR 디프(diff)와 연결된 작업 설명(task description)과 함께 이를 호출합니다.

// .github/workflows/claude-review.yml
name: Claude Code Review

...

이 구성은 관심사(concerns)를 깔끔하게 분리합니다. CLAUDE_SCOPE 변수는 리뷰 중에 에이전트가 소스 파일을 수정하는 것을 방지합니다. 작업 설명은 에이전트의 초점을 특정 품질 차원(quality dimensions)에 고정합니다. GitHub Script 액션은 결과를 댓글로 게시하여, 향후 참조를 위해 PR 타임라인에 보존합니다.

리뷰 단계는 기존 CI 체크와 병렬로 실행됩니다. 빌드가 실패하더라도 Claude Code는 디프(diff)를 기반으로 리뷰를 수행합니다. 테스트가 실패하면 별도의 워크플로가 자동 수정(auto-fix)을 처리합니다. 이러한 병렬 실행은 순차적 단계(sequential stages)에 비해 전체 파이프라인 시간을 단축합니다.

CI에서의 테스트 자동 생성 및 실패 자동 수정

테스트 생성 및 자동 수정(auto-fix)은 저장소에 대한 쓰기 권한을 필요로 하며, 이는 에이전트가 잘못된 형식의 코드를 생성할 경우 위험을 초래할 수 있습니다. 완화 전략은 2단계 워크플로를 사용하는 것입니다. 에이전트가 기능 브랜치(feature branch)에 코드를 작성하면, 사람이 대상 브랜치(target branch)로 병합하기 전에 에이전트의 커밋(commit)을 검토합니다.

// .github/workflows/claude-auto-fix.yml
name: Claude Auto-Fix

...

CLAUDE_TOKEN_BUDGET 환경 변수는 이 작업에 대한 에이전트의 총 토큰 사용량(token usage)을 제한합니다. 이 제한이 없다면, 에이전트가 새로운 실패를 유발하는 코드를 생성하고 다시 그 실패를 수정하려고 시도하는 제어 불능의 루프(runaway loop)가 발생하여 할당량(quota)을 빠르게 소모할 수 있습니다. 일반적으로 50,000 토큰의 예산이면 대부분의 테스트 스위트(test suites)에 대한 진단, 코드 생성 및 검증을 수행하기에 충분합니다.

여기서 사용된 패턴은 방어적입니다. 에이전트는 PR(Pull Request) 브랜치에 직접 쓰지 않고 별도의 브랜치에 작성합니다. 이는 수동 승인 게이트(manual approval gate)를 생성합니다. 즉, 개발자가 자동 수정(auto-fix) PR을 검토하여 변경 사항이 올바른지 확인한 다음, 이를 원래의 PR에 병합(merge)합니다. 만약 자동 수정이 회귀(regressions)를 유발한다면, 개발자는 자동 수정 PR을 닫고 문제를 수동으로 해결합니다.

특히 테스트 생성의 경우, 작업 설명(task description)에 기존 테스트 스위트의 패턴을 참조하도록 해야 합니다. 프로젝트가 특정 단언 스타일(assertion style)을 사용하는 Vitest를 사용한다면, 프롬프트(prompt)에 반드시 예시를 포함해야 합니다. 이러한 고정 장치(anchoring)가 없으면, Claude Code는 프로젝트의 컨벤션(conventions)과 일치하지 않을 수 있는 일반적인 Jest 패턴을 기본값으로 사용합니다.

비교: Claude Code vs 전통적인 CI 봇 vs 수동 검토

전통적인 CI 봇은 위반 사항을 감지하지만 절대 이를 수정하지는 않습니다. 수동 검토는 문제를 잡아내지만 팀이 성장함에 따라 확장성(scales)이 떨어집니다. Claude Code는 그 중간 지점에 위치합니다. 즉, 기계적인 문제에 대한 수정은 자동화하는 동시에, 복잡한 문제는 인간의 검토를 위해 플래그(flagging)를 표시합니다.

여기서의 시사점은 에이전트 방식의 CI(agentic CI)가 아키텍처 결정, 보안 경계 또는 제품 요구 사항에 대한 인간의 검토를 대체하는 것이 아니라는 점입니다. 대신 린트(lint) 에러 수정, 누락된 null 체크 추가, 보일러플레이트(boilerplate) 테스트 생성과 같은 반복적인 업무를 대체합니다. 팀이 하루에 수십 개의 PR을 병합할 때 이러한 시간 절약 효과는 복리로 나타납니다.

전통적인 봇(Traditional bots)은 일관성 측면에서 뛰어납니다. 이들은 피로감 없이 스타일 규칙을 강제합니다. 에이전트 방식의 CI (Agentic CI)는 수정(remediation) 측면에서 뛰어납니다. 사람이 사용하는 것과 동일한 패턴을 따르는 수정 사항을 적용하되, 컨텍스트 스위칭 (context-switching) 비용은 발생시키지 않습니다. 수동 리뷰 (Manual review)는 판단력 측면에서 뛰어납니다. 사람은 정적 분석 도구 (static analysis tool)가 잡아내지 못하는, 겉보기에 무해해 보이는 변경 사항의 보안적 함의를 포착합니다.

효과적인 패턴은 이 세 가지를 모두 결합합니다. 전통적인 봇이 빠른 게이트 (fast gate)로서 가장 먼저 실행됩니다. 만약 봇이 실패하면, Claude Code가 자동 수정 (auto-fix)을 시도합니다. 자동 수정에 성공하면, PR은 기계적이지 않은 사항들에 대해 수동 리뷰 단계로 넘어갑니다. 자동 수정에 실패하면, 개발자는 봇의 보고서와 함께 왜 수정이 수렴(converge)하지 않았는지에 대한 Claude의 분석 내용을 모두 받게 됩니다.

프로덕션 패턴: 비용 제어, 범위 제한 권한, 그리고 안전 분류기

프로덕션 환경에 에이전트 방식의 CI를 배포하려면 세 가지 제어 장치가 필요합니다: 비용 폭주를 방지하기 위한 토큰 예산 (token budgets), 영향 범위 (blast radius)를 제한하기 위한 범위 제한 파일 권한 (scoped file permissions), 그리고 위험한 작업을 차단하기 위한 안전 분류기 (safety classifiers)입니다.

토큰 예산은 과금 제약 조건에 따라 리포지토리 레벨 또는 PR 레벨로 설정됩니다. 리포지토리당 월간 예산을 설정하면, 단 하나의 악의적이거나 잘못 설정된 PR이 조직의 할당량 (quota)을 모두 소진하는 것을 방지할 수 있습니다. PR당 예산을 설정하면 여러 PR이 동시에 도착할 때 공정한 리소스 분배를 보장할 수 있습니다. 트레이드오프 (tradeoff)는 복잡성입니다. PR당 예산을 관리하려면 워크플로 실행 전반에 걸친 상태 추적 (state tracking)이 필요하며, 이는 일반적으로 리포지토리 시크릿 (repository secrets)이나 데이터베이스에 저장됩니다.

범위 지정 권한 (Scoped permissions)은 glob 패턴을 사용하여 읽기 및 쓰기 경계를 정의합니다. 리뷰 에이전트 (review agent)는 read:**/* 권한이 필요하지만, write:.claude/review.md 권한만 필요합니다. 테스트 생성 에이전트 (test generation agent)는 read:src/**/*,read:tests/**/* 및 write:tests/**/*.test.ts 권한이 필요합니다. 리팩토링 에이전트 (refactoring agent)는 더 넓은 쓰기 권한이 필요하므로, 예산 (budget)을 더 낮게 설정해야 하며 그 출력물은 항상 리뷰 브랜치 (review branch)에 반영되어야 합니다.

안전 분류기 (Safety classifiers)는 명령 실행 전에 작동합니다. 분류기 모델 (classifier model)은 명령이 권한 상승을 시도하는지, 네트워크 리소스에 접근하는지, 또는 선언된 범위를 벗어난 파일을 수정하는지 평가합니다. 분류기가 명령을 플래그 (flag)하면, 에이전트는 에러를 받고 대안적인 접근 방식을 선택해야 합니다. 이는 프롬프트 (prompts)에 에이전트를 속여 curl이나 rm -rf를 실행하게 만드는 미묘한 인젝션 공격 (injection attacks)이 포함될 수 있기 때문에 중요합니다.

개발자들이 가장 자주 접하는 실패 모드 (failure mode)는 범위 설정 오류 (scope misconfiguration)입니다. 범위가 너무 좁으면 에이전트가 작업을 완료할 수 없어 워크플로 (workflow)가 조용히 실패합니다. 범위가 너무 넓으면 에이전트가 국소적인 문제를 해결하려 시도하는 동안 관련 없는 파일을 수정할 수도 있습니다. 해결책은 Claude Code가 실제 실행 없이 의도한 작업을 로그로 남기는 드라이 런 모드 (dry-run mode)를 사용하는 것이며, 이를 통해 개발자는 자동 모드 (auto mode)를 활성화하기 전에 범위의 정확성을 검증할 수 있습니다.

여러 리포지토리를 관리하는 팀의 경우, 공유된 워크플로 구성 템플릿 (workflow configuration template)을 사용하면 드리프트 (drift)를 줄일 수 있습니다. 템플릿은 표준 범위, 예산, 작업 설명을 정의합니다. 개별 리포지토리는 리포지토리 변수 (repository variables)를 통해 특정 값을 재정의 (override)합니다. 이러한 중앙 집중화는 한 팀이 중요한 보안 개선 사항을 발견하더라도 다른 팀들이 취약한 구성을 계속 사용하는 상황을 방지합니다.

실제 CI 통합: GitHub Actions, GitLab CI, 및 Azure DevOps

GitHub Actions는 시크릿 (secrets), 매트릭스 빌드 (matrix builds), 그리고 재사용 가능한 워크플로 (reusable workflows)를 기본적으로 지원하기 때문에 가장 직관적인 통합을 제공합니다. 앞서 보여준 워크플로 매니페스트 (workflow manifest)는 GitHub에서 호스팅하는 러너 (hosted runners)에서 실행되지만, 컴플라이언스 (compliance) 요구 사항이 있는 팀은 Claude Code 바이너리가 사전 설치된 셀프 호스팅 러너 (self-hosted runners)를 사용할 수 있습니다.