Chicago Code Review: 7명의 전문가 페르소나가 동시에 코드를 읽는다

들어가며

코드 리뷰는 언제나 누가 읽느냐에 종속된 작업이었습니다. 아키텍트가 읽으면 레이어 경계를 먼저 보고, 보안 엔지니어가 읽으면 입력값부터 의심하고, 운영 담당이 읽으면 장애 대응부터 떠올립니다. 동일한 diff라도 리뷰어의 배경과 관심사에 따라 완전히 다른 지적이 나옵니다.

그래서 잘 굴러가는 조직일수록 리뷰를 여러 사람에게 돌립니다. 아키텍처 리뷰, 보안 리뷰, QA 리뷰, 운영 리뷰를 각각 요청하고, 그 피드백을 하나로 모아 PR 작성자가 판단합니다. 정확하지만 느리고, 사람이 많이 듭니다.

Chicago Code Review는 이 구조를 AI 에이전트 위에 그대로 옮긴 플러그인입니다. 하나의 PR을 받으면 7명 이상의 전문가 페르소나 에이전트가 동시에, 각자 자기 관점으로만 분석하고, 오케스트레이터가 이들의 결과를 최종 검증·필터링해 하나의 구조화된 리포트로 통합합니다. "여러 전문가의 회의실 리뷰"를 몇 분 안에 돌리는 것에 가깝습니다.

Chicago Code Review란

Chicago Code Review는 Claude Code 플러그인으로 제공되는 멀티 에이전트 코드 리뷰 스킬입니다. 핵심 설계 원칙은 세 가지입니다.

1. 역할 분리(Role Separation): 각 에이전트는 자신의 전문 영역 하나만 본다. 보안 에이전트는 성능을 말하지 않고, 퍼포먼스 에이전트는 네이밍을 말하지 않는다. 리뷰가 서로 간섭하지 않도록 시스템 프롬프트 수준에서 스코프를 강제한다.
2. 병렬 실행: 기본 7개 역할을 하나의 메시지에서 동시에 스폰한다. 순차가 아니라 병렬이기 때문에 "리뷰 7개를 받는 데 걸리는 시간"이 "리뷰 1개를 받는 데 걸리는 시간"에 수렴한다.
3. 오케스트레이터 최종 검증: 에이전트 결과를 그대로 이어 붙이지 않는다. 오케스트레이터가 오탐을 걸러내고, 심각도를 재조정하고, 충돌을 트레이드오프로 정리한 뒤에야 사용자에게 노출된다.

팀 구성: 7개 기본 역할 + 4개 조건부 역할

Chicago의 기본 팀은 7명입니다. 모두 기본 활성화되며, 코드 성격에 따라 조건부 역할이 추가됩니다.

각 페르소나는 단순히 체크리스트 항목이 아니라, 구체적인 인물상과 핵심 질문으로 정의되어 있습니다. 예를 들어 Performance Engineer는 이렇게 정의됩니다.

"DB 튜닝과 JVM 프로파일링에 집착하는 성능 덕후. '지금은 괜찮아 보이는데' 라는 말을 들으면 '지금은 사용자가 10명이니까'라고 대답한다."

핵심 질문:

• '이 루프가 1만 건 데이터에서 실행되면 어떻게 되는가?'
• '동시 요청 100건일 때 이 로직의 병목은 어디인가?'
• '이 쿼리에 EXPLAIN을 실행하면 어떤 결과가 나오는가?'

이런 인물상 부여는 단순한 장식이 아닙니다. LLM은 "성능을 분석하라"는 지시보다 "이 질문에 답하라"는 질문 세트에 훨씬 구체적으로 반응합니다. 각 역할의 질문 세트가 곧 그 역할의 분석 프레임이 됩니다.

조건부 역할: 도메인에 따라 자동 활성화

기본 7명 외에, 코드의 성격에 따라 추가 전문가가 합류합니다.

Junior Developer 역할이 특히 흥미롭습니다. 팀에 새로 합류한 주니어 관점에서 "이해가 안 되는 부분에 솔직하게 질문" 하도록 설계되어 있습니다. 다른 역할이 모두 "전문가의 지적"을 내놓는다면, Junior는 "암묵적 지식에 의존하는 코드"를 질문 형태로 드러내서 문서화가 필요한 구간을 식별합니다. 시니어 리뷰어만으로는 놓치기 쉬운 사각지대를 메우는 자리입니다.

사용자가 "Security와 Performance 관점으로만 리뷰해줘"처럼 특정 역할을 지정하면, 해당 역할만 활성화됩니다.

워크플로우: 8단계 리뷰 파이프라인

Chicago의 실행은 Phase 0부터 Phase 7까지 엄격하게 정의되어 있습니다.

Phase 0 — 코드 입력 수집

리뷰 대상이 PR인지 파일/스니펫인지에 따라 분기합니다.

PR 기반 리뷰인 경우 gh pr view와 gh pr diff로 메타데이터와 전체 diff를 가져옵니다. 이 단계의 핵심은 대용량 diff 처리 전략입니다.

• pnpm-lock.yaml, package-lock.json, *.generated.*, *.min.js 등 자동 생성 파일과 록 파일 제외
• src/, lib/, app/, 설정 파일, 마이그레이션 우선 처리
• 필터링 후에도 3000줄 초과 시 영향도 높은 파일 우선 선택
• 최종 diff를 /tmp/chicago-review-diff-focused.txt에 저장

이 "포커싱된 diff" 파일은 이후 모든 서브에이전트가 동일한 스코프 위에서 분석하도록 만드는 공유 컨텍스트입니다. 한 에이전트는 라인 42를, 다른 에이전트는 라인 87을 본 채로 리포트가 뒤섞이는 사고를 방지합니다.

파일/코드 직접 리뷰인 경우에는 파일 경로를 Read 도구로 수집하거나 스니펫을 그대로 사용해 /tmp/chicago-review-code-input.txt에 저장합니다.

Phase 1 — 오케스트레이터의 컨텍스트 분석 및 역할 선택

서브에이전트를 띄우기 전에, 오케스트레이터(메인 에이전트)는 코드를 읽고 다음을 파악합니다.

• 언어/프레임워크: Spring Boot/Kotlin, Next.js/TypeScript, Django/Python 등
• 도메인: ERP, 커머스, API 서버, 인프라 설정 등
• 변경 범위: 신규 기능, 버그픽스, 리팩토링, 스키마 변경 등

이 정보를 바탕으로 활성화할 역할을 결정하고, 모든 에이전트에 동일하게 전달될 공통 컨텍스트(PR 제목/설명, 도메인 정보, 프로젝트 컨벤션 등)를 패키징합니다.

Phase 2 — 병렬 에이전트 실행

이 단계가 Chicago의 성능 특성을 결정합니다. 선택된 모든 역할이 하나의 메시지 안에서 동시에 Agent 도구로 스폰됩니다. 순차 실행이었다면 7번의 왕복이 필요했을 작업이, 병렬 실행으로 한 번에 끝납니다.

모든 서브에이전트는 다음 공통 규칙을 따릅니다.

• Research-only: 어떤 파일도 수정하지 않는다.
• Scope 엄격화: 리뷰는 diff에 추가(+) 또는 수정된 라인에만 집중한다. 주변 파일을 컨텍스트로 읽을 수는 있지만, PR에서 변경되지 않은 코드의 이슈는 보고하지 않는다.
• 심각도 레이블 필수: 🔴🟠🟡🟢 중 하나로 모든 이슈를 태깅한다.
• 긍정 피드백: 잘된 점 1–2개를 반드시 함께 기록한다.
• 결과 저장: 각자 /tmp/chicago-review-[역할]-findings.txt에 결과를 남긴다.

특히 "다른 역할의 관점(예: 보안, 성능)은 다루지 않는다"는 지시가 각 에이전트 프롬프트에 명시되어 있습니다. 이 제약이 있어야 리포트가 겹치지 않고, 오케스트레이터가 나중에 중복 제거를 할 수 있습니다.

Phase 3 — 결과 수집

모든 서브에이전트가 완료되면 오케스트레이터는 각 에이전트가 저장한 findings 파일을 읽어들입니다. 포그라운드 실행이기 때문에 별도의 폴링이나 대기 로직은 필요하지 않습니다.

Phase 4 — 오케스트레이터의 최종 검증

이 단계가 Chicago를 단순 멀티 에이전트 호출과 구분하는 가장 중요한 지점입니다. 오케스트레이터는 서브에이전트의 결과를 그대로 전달하지 않습니다. 다음 기준으로 전체 결과를 재검토합니다.

4-1. 중복 제거 동일한 파일·라인에 대해 여러 에이전트가 유사한 이슈를 보고한 경우, 가장 상세한 것을 대표로 선택하고 다른 에이전트의 관점을 병기합니다.

4-2. 충돌 분석 에이전트 간 상반된 의견이 있으면 트레이드오프 섹션에 정리합니다. 예를 들어:

"Architect는 레이어 분리를 권고하지만, Performance는 직접 쿼리가 효율적이라 함. → 현재 트래픽 규모에서는 가독성 우선, 성능 이슈 발생 시 캐시 계층 추가 권장."

4-3. 적합성 검증 (오탐 필터링) 실제 코드 컨텍스트와 맞지 않는 이슈를 걸러냅니다. 예를 들어 프레임워크가 이미 처리하고 있는 문제(Spring의 자동 CSRF 방어 같은)를 에이전트가 지적한 경우, 오케스트레이터가 해당 지적을 최종 리포트에서 제외합니다.

4-4. 심각도 재조정 에이전트가 과대 또는 과소 평가한 심각도를 프로젝트 컨텍스트에 맞게 조정합니다. 이때 원래 심각도와 조정 사유를 함께 기록해 투명성을 유지합니다.

4-5. 일관성 검증 한 에이전트의 수정 제안이 다른 에이전트의 지적 사항과 모순되지 않는지 교차 검증합니다. 리팩토링 제안이 성능 지적을 악화시키는 경우가 대표적입니다.

4-6. 우선순위 정리 단순 심각도뿐 아니라 변경 범위, 영향 받는 사용자 수, 수정 비용을 고려해 최종 우선순위를 결정합니다. CRITICAL 1건보다 영향 범위가 큰 HIGH 3건이 먼저 나오는 경우도 있습니다.

이 과정을 거치면 7개의 개별 리포트가 하나의 통합된, 신뢰할 수 있는 리포트로 재구성됩니다. 사용자에게 노출되는 것은 이 최종본뿐입니다.

Phase 5 — 사용자 확인

PR 코멘트로 게시하기 전, 오케스트레이터는 전체 리뷰 내용을 사용자에게 보여주고 승인을 요청합니다. 사용자는 yes, edit, no 중 하나를 선택할 수 있습니다. 자동 게시를 막는 이 게이트는, AI 리뷰가 실수로 공개 코멘트에 남을 가능성을 원천 차단합니다. 파일/스니펫 직접 리뷰인 경우에는 이 단계와 다음 단계를 건너뛰고 리포트만 출력합니다.

Phase 6 — PR 코멘트 게시

사용자 승인 후에만 gh pr comment로 최종 리포트를 PR에 게시합니다.

Phase 7 — 임시 파일 정리

/tmp/chicago-review-*.txt 파일을 모두 삭제해 민감한 diff 조각이 디스크에 남지 않게 합니다.

공통 심각도 레이블

모든 에이전트가 동일한 스케일을 쓰기 때문에, 최종 리포트에서 심각도 비교가 가능합니다.

레이블은 단순 색상이 아니라 행동 지시입니다. CRITICAL은 배포 블로킹이고, LOW는 선택적입니다. PR 작성자가 리포트를 받았을 때 어떤 항목부터 손대야 하는지 명확해집니다.

최종 리포트 구조

Chicago의 최종 산출물은 다음과 같은 구조를 갖습니다.

# 🔍 Chicago Code Review

## 📋 리뷰 요약
- 리뷰 대상: PR #123
- 참여 에이전트: Architect, Security, Performance, QA, ...
- 전체 평가: (오케스트레이터 한 줄 총평)
- 머지 판단: ✅ 승인 / ⚠️ 조건부 승인 / ❌ 수정 필요
- 🔴 Critical: N건 / 🟠 High: N건 / 🟡 Medium: N건 / 🟢 Low: N건

## 🚨 즉시 수정 필요 (CRITICAL / HIGH)
(머지를 차단하는 이슈만 상단에 배치)

## 🔍 에이전트별 상세 리뷰
### 🏗️ Architect 관점
### 🔒 Security 관점
### ⚡ Performance 관점
...

## ⚖️ 트레이드오프 분석
(에이전트 간 충돌이 있을 때만)

## ✅ 잘된 점
(긍정 피드백 통합)

## 🎯 오케스트레이터 최종 검증 노트
- 필터링된 이슈: ...
- 심각도 조정: ...
- 주의 영역: ...

## 📌 권장 액션 플랜
1. [즉시] ...
2. [이번 PR] ...
3. [다음 스프린트] ...

구조의 핵심은 두 가지입니다. 첫째, CRITICAL/HIGH 이슈가 가장 위에 배치되어 급한 것을 바로 볼 수 있습니다. 둘째, 오케스트레이터 검증 노트가 명시적 섹션으로 존재해 "왜 이 이슈는 빠졌는가", "왜 심각도가 조정되었는가"가 투명하게 드러납니다. 블랙박스 리뷰가 아니라 추적 가능한 리뷰입니다.

설계 결정: 왜 "토론"이 아니라 "격리된 전문성"인가

같은 저자의 다른 플러그인인 Montreal Code Review는 4명의 리뷰어가 서로의 지적을 보고 재평가하는 토론 라운드를 핵심 특징으로 삼습니다. Chicago는 정반대의 선택을 했습니다. 에이전트들은 서로의 결과를 보지 않고, 자기 영역에만 집중합니다. 이 차이는 의도적입니다.

토론 기반의 장점은 합의의 깊이입니다. 한 리뷰어의 오탐을 다른 리뷰어가 지적해서 제거할 수 있고, 여러 관점이 겹쳐진 이슈는 신뢰도가 올라갑니다. 단점은 수렴 편향입니다. 토론이 길어질수록 "가장 강한 의견"으로 수렴하기 쉽고, 비주류 관점(Junior의 순진한 질문, Craftsman의 가독성 지적 등)이 씻겨 나갈 위험이 있습니다.

격리 기반의 장점은 다양성 보존입니다. 보안 엔지니어가 성능 엔지니어를 설득할 필요가 없기 때문에, 각자 자기 영역에서 가장 독립적이고 날카로운 지적을 내놓습니다. 오탐 필터링은 토론이 아니라 오케스트레이터의 컨텍스트 검증이 담당합니다. 단점은 에이전트 간 모순 의견이 리포트에 공존할 수 있다는 것인데, 이는 트레이드오프 섹션으로 흡수합니다.

Chicago의 설계는 "PR 한 건에 대한 넓이"를 더 중시하는 선택입니다. 합의보다 관점의 폭, 토론보다 전문 영역의 독립성을 우선한다는 명시적 결정입니다. Montreal이 적합한 상황과 Chicago가 적합한 상황이 다르고, 같은 플러그인 레포에 두 가지가 공존하는 것은 우연이 아닙니다.

성능 특성

Chicago의 실행 시간은 대략 "가장 느린 단일 에이전트의 시간 + 오케스트레이터 검증 시간"으로 수렴합니다. 7개가 순차 실행이었다면 7배가 걸렸을 작업이, 병렬 실행으로 1배 수준에 머무릅니다.

실무적으로 주의할 점은 다음과 같습니다.

• Diff 크기: 3000줄이 넘으면 자동 필터링이 작동하지만, 정말 큰 PR은 여전히 컨텍스트 압박을 받습니다. 리뷰 대상 스코프를 미리 좁히는 것이 가장 효과적인 대응입니다.
• 에이전트 실패: 특정 에이전트가 실패해도 나머지 결과로 리포트가 생성됩니다. 최종 리포트에 실패한 에이전트가 명시되므로, 누락이 은폐되지 않습니다.
• 토큰 소비: 7명이 동시에 동일 diff를 읽기 때문에 토큰 비용은 사람이 리뷰할 때보다 싸지만 단일 에이전트 리뷰보다는 당연히 큽니다. 기본 6개 역할 모두가 기본 활성화되는 것은 "적당히 아끼지 말고 리뷰를 제대로 돌려라"는 명시적 철학입니다.

어떤 상황에 쓰면 좋은가

Chicago가 빛을 발하는 상황은 분명합니다.

• 릴리스 직전 PR: 아키텍처부터 운영까지 한 번에 점검해야 할 때. 사람이었다면 리뷰 요청을 4–5명에게 돌려야 했을 작업을 병렬로 해결합니다.
• 온보딩 직후 기여: Junior Developer 역할이 암묵적 지식 의존 구간을 짚어주기 때문에, 신규 팀원의 PR에 특히 유용합니다.
• 스키마 변경 PR: Data Steward가 자동 활성화되어 마이그레이션 안전성을 별도로 검토합니다.
• 복잡한 비즈니스 로직: Business Analyst가 요구사항과 구현의 괴리를 잡아냅니다.

반대로 단순 오탈자 수정, 사소한 설정 변경에는 과잉입니다. 그럴 때는 단일 리뷰어 스킬이 적합합니다. 스킬 정의도 "단순 코드 설명이나 단일 이슈 질문에는 사용하지 않는다"고 명시적으로 선을 긋고 있습니다.

마치며

Chicago Code Review는 "한 명의 똑똑한 리뷰어" 대신 "여러 명의 전문 리뷰어 + 한 명의 꼼꼼한 오케스트레이터"라는 구도를 택한 플러그인입니다. 역할마다 페르소나와 질문 세트를 명시적으로 부여하고, 서로 간섭하지 않도록 격리하고, 최종 단계에서 오케스트레이터가 오탐과 심각도를 재검증합니다.

핵심 통찰은 간단합니다. "전문성을 합치려고 하지 말고, 전문성을 분리해서 각자 가장 날카롭게 만든 뒤 마지막에 정리하자." 이 원칙은 사람 조직에서 이미 검증된 것이고, Chicago는 그것을 에이전트 레이어에서 재현했을 뿐입니다. 에이전트 오케스트레이션이 단순 "여러 번 호출하기"에서 "역할 분리와 최종 검증이 있는 파이프라인"으로 진화할 때 어떤 모습인지를 보여주는 좋은 레퍼런스입니다.

코드 리뷰를 AI에 맡기는 것이 불안한 이유는 대부분 "블랙박스로 결정을 내리기 때문"입니다. Chicago는 각 에이전트의 결과를 섹션별로 드러내고, 오케스트레이터의 검증 내역까지 리포트에 남깁니다. 결과에 동의하지 않아도 왜 그런 결론이 나왔는지를 읽을 수 있다는 것—이것이 프로덕션 엔지니어링에 AI 리뷰를 집어넣을 때 가장 중요한 요건이고, Chicago가 그 요건을 충족하는 방식입니다.