Claude Academy
로드 중

PR 리뷰 루프 속의 AI

강의 105분

Claude는 리뷰를 제공하기도 하고 받기도 합니다. 조직의 정책에 따라 들어오는 PR을 검토하고, 자신의 PR에 달린 리뷰 코멘트를 직접 처리합니다. 이를 통해 엔지니어는 PR 리뷰에서 의도와 위험을 판단하는 일, 즉 본질적인 부분에 집중할 수 있습니다.

무엇이 달라지는가

전통적 방식AI 네이티브 방식
리뷰 역량은 사람의 산출량을 기준으로 계획됩니다. PR은 리뷰어가 전체를 읽어줄 때까지 기다려야 하고, 리뷰 품질은 리뷰어의 업무 부담에 따라 달라지며, 작성자는 백로그가 쌓이는 동안 독촉을 계속합니다.모든 PR은 동일한 일련의 리뷰 패스를 거치며, 발견된 사항은 심각도에 따라 순위가 매겨집니다. 사람의 주의는 한 단계 위로 이동하여, 변경 사항이 계획한 의도대로 동작하는지, 그리고 위험이 수용 가능한 수준인지에 집중됩니다.

시작하기

  • 사전 준비 사항: 3단계: 빌드에서 업데이트된 CLAUDE.md 파일, 리뷰 패스가 문서화된 정책을 강제해야 하는 경우의 Skills, 그리고 정의된 서브에이전트.
  • 인프라: Claude 통합이 설치된 저장소로, Claude 조직의 소유자가 활성화한 관리형 Code Review 서비스를 사용하거나, 자체 CI에서 claude-code-action을 실행하며 필요에 따라 Amazon Bedrock, Google Cloud의 Vertex AI, 또는 Microsoft Foundry를 통해 모델을 호출합니다(배포 옵션은 CI/CD 플레이에서 다룹니다). 코드 소유자의 승인을 요구하는 브랜치 보호 정책도 마련해 두는 것이 좋습니다.

실행 방법

  1. 관리형 Code Review 서비스가 가장 빠르게 시작할 수 있는 방법입니다. Claude 조직의 소유자가 이를 활성화하고 저장소를 선택합니다. 파이프라인을 직접 제어하거나 API 호출을 자체 클라우드 계약을 통해 라우팅하고 싶다면 claude-code-action을 사용해 자체 CI에서 리뷰를 실행하세요(해당 배관 작업은 CI/CD 플레이에서 다룹니다).
  2. 테크 리드는 저장소 루트에 REVIEW.md로 리뷰 정책을 작성하며, 조직이 중요하게 여기는 패스들로 나눕니다: 버그 및 논리적 오류; 보안 및 취약점; 스펙(요구사항 플레이의 spec.md), 구현 계획(plan mode 플레이의 plan.md), 설계 원칙에 대한 준수 여부. REVIEW.md는 또한 무엇이 Nit이 아닌 Important로 간주되는지, 그리고 무엇을 건너뛸지도 정의합니다.
  3. 테크 리드는 사람이 개입하는 기준을 설정합니다. 발견 사항 자체만으로는 PR을 승인하거나 차단하지 않으며, 브랜치 보호는 여전히 코드 소유자의 승인을 요구합니다. 발견 사항을 기준으로 머지를 제한하고 싶은 플랫폼 엔지니어는 체크 실행이 게시하는 심각도 집계를 기계가 읽을 수 있는 형태로 확인할 수 있습니다.
  4. 리뷰어나 작성자가 리뷰 코멘트에서 @claude를 태그하면, Claude는 해당 코멘트를 처리하고 수정 사항을 푸시합니다. PR 스레드에는 요청과 변경 사항이 모두 기록됩니다. 이 수정 루프는 claude-code-action을 통해 실행됩니다. 관리형 서비스에서는 @claude review라고 코멘트하면 새로운 리뷰를 요청하게 됩니다. Claude가 연 PR의 경우, 한 걸음 더 나아가 Claude가 PR을 머지까지 직접 돌보도록 할 수 있습니다. 팀들은 이 루프를 커스텀 슬래시 명령으로 감싸서, PR의 미해결 리뷰 코멘트와 실패한 체크를 훑어보고 처리한 뒤 수정 사항을 푸시하는 작업을, PR이 그린 상태가 되어 코드 소유자 승인만 남을 때까지 반복합니다.
  5. 리뷰 결과는 다시 CLAUDE.md에 반영됩니다. 리뷰가 같은 실수를 두 번째로 지적하면, 그 수정 사항은 해당 리뷰의 일부로 CLAUDE.md에 추가되며, 리뷰가 CLAUDE.md를 읽기 때문에 다음 PR부터는 그 실수가 걸러집니다. 리뷰는 또한 변경 사항으로 인해 CLAUDE.md가 오래된 상태가 되었을 때도 이를 표시합니다.
  6. 한 달에 한 번, 테크 리드는 발견 사항을 평가하여 리뷰어가 개선되도록 하고, REVIEW.md에서 Nit의 양을 제한함으로써 설정을 조정합니다. 생성된 경로와 CI가 이미 강제하고 있는 항목은 제외됩니다.

실제 모습

REVIEW.md:

markdown
# Review instructions
## Passes
Run three passes and tag each finding with its pass:
- Bugs: logic errors, broken edge cases, subtle regressions
- Security: injection risks, authentication gaps, PII in logs
- Compliance: the change matches spec.md, plan.md and our design principles
## What Important means here
Reserve Important for findings that would break behavior, leak data
or breach a policy. Style and naming are nits.
## Cap the nits
Report at most five nits per review; summarize the rest as a count.
## Do not report
Generated files under src/gen/ and anything CI already enforces.

다음 예시는 보험사 고객 포털에 청구 상태 패널을 추가하는 풀 리퀘스트에 대해 체크 실행이 나열하는 내용입니다. 여기서 claims-core는 포털 백엔드 뒤에 있는 더 오래된 내부 시스템입니다:

심각도파일:줄문제
Importantportal/src/claims/StatusPanel.tsx:22준수: 패널이 렌더링할 때마다 데이터를 가져옵니다. plan.md에는 claims-core가 초당 50건의 요청만 허용하므로 반드시 캐시해야 한다고 명시되어 있습니다
Importantclaims-api/routes/status.py:31보안: 오류 경로가 policy_holder_name을 포함한 claims-core 응답 전체를 로그에 남깁니다
Nitclaims-api/tests/test_status.py:8버그: 예상 날짜가 없는 paid 청구를 다루는 테스트가 없습니다

첫 번째 발견 사항은 준수 패스가 커밋된 plan.md를 읽기 때문에만 존재하며, diff만 보는 리뷰어라면 이 파일을 열어보지 않았을 것입니다.

거버넌스 고려 사항

코드를 작성한 에이전트가 이를 승인할 방법이 없으므로 직무 분리가 유지됩니다. REVIEW.md의 리뷰 정책은 모든 PR에 적용되며, 발견 사항, 수정, 평가, 승인은 모두 PR 이력에 기록되므로 PR 자체가 감사 기록이 됩니다. 승인은 발견 사항을 참고한 사람이 브랜치 보호를 통해 내립니다.

측정 방법

  • 선행 지표: 첫 리뷰까지 걸리는 시간으로, 이는 몇 분 단위로 줄어들어야 하며, 사람이 브랜치를 건드리지 않고 해결된 리뷰 코멘트의 비율도 포함됩니다. 데이터는 Git에 직접 저장됩니다.
  • 후행 지표: 머지 전에 발견된 결함 및 취약점을 프로덕션으로 유출된 것과 비교한 수치로, PR 이력과 인시던트 트래커에서 확인합니다.