PR이 말을 걸기 시작했다
"AI 코드 리뷰"라고 하면 많은 팀이 ChatGPT 탭을 열어 코드를 붙여 넣는 장면을 떠올립니다. 근데 솔직히 그건 AI를 보조 도구로 쓰는 거지, AI-First 워크플로우가 아니에요. 진짜 AI-First는 AI가 레포지토리 안에서 살아 숨쉬는 겁니다. Cristian Sifuentes가 dev.to에 연재 중인 Conversational Development With Claude Code 시리즈 16·17화를 보면서 "이제 이게 팀 표준이 돼야 한다"는 확신이 생겼습니다.
핵심 이슈: Claude Code가 GitHub Actions의 1등 시민이 되다
Claude Code를 GitHub에 통합하는 방식은 크게 두 경로입니다. Quick Setup은 터미널에서 /install-github-app 명령 하나로 Claude Code가 직접 PR을 열어 워크플로우 YAML을 추가합니다. Manual Setup은 GitHub App 설치 → 시크릿 등록 → YAML 복사 순서로 직접 세팅합니다. 조직 정책상 모든 YAML 라인을 명시적으로 리뷰해야 한다면 후자를 택하세요. 두 경로 모두 .github/workflows/에 두 개의 워크플로우를 심는 것으로 끝납니다.
첫 번째는 Interactive 모드입니다. PR 코멘트에 @claude fix the TypeError in the dashboard component처럼 멘션하면 Claude가 워크플로우 잡을 실행해 응답합니다. 프롬프트가 아티팩트로 남고, 응답이 코멘트로 달리고, 제안된 변경이 커밋이 됩니다. 두 번째는 Automation 모드입니다. PR이 열리는 순간 자동으로 코드 리뷰, 보안 패스, 릴리즈 노트 생성 등 고정 프롬프트가 실행됩니다. Claude가 "챗 창"이 아니라 "신뢰할 수 있는 유틸리티"가 되는 순간이에요.
맥락 해석: 리뷰가 '의식(ritual)'에서 '대화'로 바뀐다
PR은 단순한 diff가 아닙니다. 브랜치가 의도를 선언하고, 커밋이 reasoning을 기록하고, PR이 변경을 심사에 노출하는 계약적 제안입니다. 여기에 Claude Code가 들어오면 심사가 자동화되면서 동시에 대화형이 됩니다. 사람 리뷰어가 비일관성을 발견하길 기다릴 필요 없이, PR이 열리는 즉시 구조화된 리뷰가 실행됩니다.
특히 인상적인 건 CLAUDE.md 파일입니다. 팀의 코딩 컨벤션, 아키텍처 경계, 금지 패턴을 이 파일에 정의해두면 Claude가 리뷰할 때 이를 기준으로 삼습니다. "기억에 의존하지 마라, 레포지토리 아티팩트에 의존하라"는 원칙이죠. 이거 Claude한테 물어보니까 실제로 팀 표준을 CLAUDE.md에 잘 정의해두면 리뷰 일관성이 눈에 띄게 올라간다고 하더라고요. 팀원들에게 AI-First 마인드를 심어줄 때 가장 먼저 작성하게 해야 할 파일입니다.
LLM 에이전트 테스트: 파이프라인의 빠진 조각
CI/CD에 AI를 심었다면, AI가 생성한 코드의 품질을 어떻게 검증할지도 설계해야 합니다. dev.to의 또 다른 글 Building a Practical Test Suite for Your LLM Agent는 이 문제를 정면으로 다룹니다.
핵심 통찰은 간단합니다. LLM 출력에 assertEquals를 쓰는 건 낡은 방식입니다. 온도 0으로 설정해도 GPT-4o는 100번 호출 중 12%에서 출력이 달라집니다. 모델 업데이트, 인프라 라우팅, GPU 클러스터의 부동소수점 차이가 분산을 만들어냅니다. 대신 세 가지 패턴을 써야 합니다.
① 행동 어설션(Behavioral Assertions): 에이전트가 무엇을 말했는지가 아니라 무엇을 했는지를 검증합니다. 요약 결과가 원문보다 짧은지, 핵심 개념을 포함하는지, "As an AI"로 시작하는 메타 코멘터리가 없는지 등을 체크합니다. 의미 있는 에이전트 실패의 약 80%는 잘 설계된 행동 어설션으로 잡을 수 있습니다.
② Eval 하네스: gpt-4o-mini 같은 저렴한 LLM을 판정관(judge)으로 써서 에이전트 출력을 1~5점으로 채점합니다. 50줄 미만의 코드로 구현 가능하고, 1년 365일 야간 실행해도 $5 미만입니다. AI가 AI를 리뷰하는 구조, 이게 바로 AI-First 파이프라인의 묘미죠.
③ 결정론적 셸 테스트: 대부분의 에이전트는 [라우터] → [프롬프트 빌더] → [LLM 호출] → [파서] → [검증기] 구조입니다. LLM 호출을 제외한 모든 단계는 결정론적입니다. 이 부분을 일반 단위 테스트로 커버하면 LLM 호출 비용 없이 높은 테스트 커버리지를 확보할 수 있습니다.
시사점: 벤치마크 함정과 실코드 평가의 중요성
dev.to의 How to Test LLM Performance on Real Code Instead of Synthetic Benchmarks는 AI-First 파이프라인을 설계할 때 반드시 알아야 할 불편한 진실을 짚습니다. HumanEval에서 87% 정확도를 기록한 LLM이 실제 코드베이스에서는 30%대로 떨어집니다. 분포 이동(distribution shift) 때문입니다. 팀의 독자적인 프레임워크, 레거시 패턴, 조직 고유의 컨벤션은 공개 벤치마크가 전혀 캡처하지 못하는 영역입니다.
AI 기반 코드 리뷰를 자동화 파이프라인에 심을 때 이 함정을 피하려면, 팀의 머지된 PR 이력을 기반으로 직접 평가 데이터셋을 만들어야 합니다. 사람이 승인한 before/after 코드 페어가 곧 ground truth입니다. AI가 생성해준 걸 기반으로 우리가 다듬는 협업 모델에서, 그 '다듬기'의 기준을 팀 자체 데이터로 정의하는 거예요. 코드 리뷰 메트릭도 중요합니다. AI 리뷰어의 정밀도(Precision)—유용한 제안 비율—와 재현율(Recall)—실제 이슈 탐지 비율—을 측정하면 파이프라인의 신뢰도를 정량화할 수 있습니다.
실전 적용: 우리 팀 AI-First 파이프라인 로드맵
이 모든 걸 팀에 적용한다면 단계별로 이렇게 접근합니다.
1단계 (즉시): CLAUDE.md 작성. 팀 코딩 컨벤션, 보안 경계, 리뷰 기준을 문서화합니다. Claude가 일관된 기준으로 리뷰하게 만드는 첫 번째 투자입니다.
2단계 (이번 스프린트): Claude Code GitHub App 설치 + Automation 모드 활성화. PR이 열릴 때마다 자동 리뷰가 달리게 합니다. 사람 리뷰어가 AI 리뷰 코멘트를 보고 판단하는 구조, 이거 자동화하면 팀원들이 더 중요한 아키텍처 결정에 집중할 수 있습니다.
3단계 (다음 스프린트): LLM 에이전트 테스트 스위트 구축. 행동 어설션 + Eval 하네스 + 결정론적 셸 테스트 세 레이어를 CI에 심습니다.
4단계 (지속): 팀 PR 이력 기반 평가 데이터셋 구축. AI 리뷰어의 정밀도/재현율을 분기별로 측정해 파이프라인 품질을 개선합니다.
전망: 레포지토리가 대화의 공간이 된다
Claude Code + GitHub Actions 조합이 가리키는 방향은 명확합니다. 코드에 대한 대화가 Slack이나 Notion이 아니라, 코드가 있는 곳—PR과 이슈—에서 일어나는 세상입니다. @claude implement this feature based on the issue description이 자연스러운 엔지니어링 언어가 되는 시대요.
하지만 주의할 점도 있습니다. Claude에게 Contents, Issues, Pull Requests 읽기/쓰기 권한을 주는 건 강력한 만큼 책임이 따릅니다. API 키 관리, 워크플로우 트리거 범위, 조직 보안 정책과의 정합성을 꼼꼼히 챙겨야 합니다. "권한의 대가는 책임"이라는 원칙을 기억하면서요. AI-First 파이프라인을 구축한다는 건 AI를 도구로 쓰는 게 아니라, AI를 팀의 일원으로 온보딩하는 겁니다. 그 온보딩이 제대로 됐을 때, 팀은 코드를 쓰는 게 아니라 문제를 설계하는 데 집중할 수 있게 됩니다.