16. AI 협업 코드리뷰 가이드

0. 먼저 알고 가기 (30초 요약)

• AI 제안은 작업 속도를 올리지만 최종 판단은 사람의 맥락 이해입니다.
• 제안은 테스트/근거/리스크를 분리해서 검토하면 오탐을 줄입니다.
• 사람의 리뷰가 지표와 정책을 통과하면 바로 반영, 아니면 재요청하세요.

왜 중요한가: AI 리뷰는 노이즈를 줄이고 사람의 주의력을 위험 구간에 모으는 도구입니다. 사람의 승인 책임을 대체하면 사고가 났을 때 책임 소재가 사라집니다.

일상 비유: 공장의 자동 검사 라인과 같습니다. 카메라(AI)가 1차로 결함을 걸러주지만, 출고 전 최종 인장 도장은 검사관(사람)이 찍습니다.

초심자용 한눈에 보기

AI는 속도 보조 도구이지 최종 결정권이 아닙니다. 사람이 최종 판단합니다.

flowchart LR
  D[작성자] -->|작은 PR| AI[AI 1차 리뷰]
  AI -->|시그널 정리| H[사람 reviewer]
  H -->|blocking 해결 확인| O[Code Owner 승인]
  O --> M[Merge + 모니터링]

핵심 용어 빠르게 정리

---

코드리뷰 표준은 특정 AI 리뷰 서비스가 아니라 변경 의도, 위험도, 검증 증적, 사람의 책임 있는 승인을 일관되게 남기는 협업 방식입니다.

---

추천 항목 (실무 우선순위)

• 시작 추천: AI 제안 요청 템플릿을 만들고 근거 링크/테스트 산출물을 함께 요구하세요.
• 안정 추천: PR template에 사람 최종 승인 라인과 리스크 사전 검토를 넣어 오탐을 줄입니다.
• 운영 추천: 반복 오류는 같은 루프에서 반복하지 않도록 체크리스트 자동화로 학습합니다.

추천 항목 고도화 체크

• 첫 적용 — AI finding triage와 사람 승인 책임 중 하나를 실제 PR이나 운영 이슈에 붙이고, 변경 전 기준을 먼저 적는다.
• 증거 정리 — finding disposition, 최신 head SHA review, 사람 reviewer 승인를 같은 작업 기록에 남긴다.
• 재점검 — false positive, 미해결 thread, 재리뷰 횟수가 나아졌는지 30일 안에 확인하고 기준을 유지, 수정, 폐기 중 하나로 판정한다.

추천 항목 실행 기록 템플릿

• 작업 : AI finding triage와 사람 승인 책임 적용 범위를 어느 화면, 패키지, 문서에 둘지 적는다.
• 증거 : finding disposition, 최신 head SHA review, 사람 reviewer 승인 중 실제로 남긴 항목만 링크한다.
• 판정 : 유지/수정/폐기 중 하나와 이유를 한 문장으로 남긴다.
• 다음 점검 : false positive, 미해결 thread, 재리뷰 횟수를 다시 볼 날짜와 담당자를 지정한다.

문서 책임 범위

---

0. 모든 프론트엔드 그룹 공통 Baseline

0.0 리뷰 플로우(사람+AI)

flowchart TD
  A[PR 생성] --> B[자동 체크 lint/type/test/security]
  B --> C{필수 게이트 통과}
  C -->|실패| D[작성자 수정]
  D --> B
  C -->|통과| E[AI 보조 리뷰]
  E --> F{블록킹 여부}
  F -->|있음| G[수정 후 재요청]
  G --> E
  F -->|없음| H[Review/Owner 승인]
  H --> I[Merge]
  I --> J[배포 후 모니터링]
  J --> K[피드백 반영]

0.0.1 사람과 AI의 역할 분담

flowchart TB
  subgraph AI역할["AI가 잘하는 영역"]
    A1[diff 요약]
    A2[테스트 누락 후보]
    A3[보안/접근성 체크리스트]
    A4[유사 패턴 검색]
    A5[PR 분할 제안]
  end
  subgraph Human역할["사람이 책임지는 영역"]
    H1[비즈니스 의도 확인]
    H2[보안/규제/계약 판단]
    H3[Merge approval]
    H4[운영 rollback 책임]
    H5[ADR/RFC 결정 기록]
  end
  AI역할 -.근거 제공.-> Human역할
  Human역할 -.피드백/규칙 보정.-> AI역할

비유: 의료 영상 판독 보조 AI와 같습니다. AI가 의심 영역을 강조해주지만, 진단서 서명은 의사가 합니다.

0.1 교차 검증 매트릭스

0.1.1 AI finding 처리 판정표

flowchart TD
  START["AI finding 도착"] --> REPRO{"재현 가능한가?"}
  REPRO -->|"아니오"| LABEL_FALSE["false positive로 표시<br/>규칙 보정 후보 등록"]
  REPRO -->|"예"| RISK{"보안/데이터/접근성/성능<br/>위험인가?"}
  RISK -->|"예"| BLOCK["blocking finding<br/>수정 또는 명시적 거절 사유 필요"]
  RISK -->|"아니오"| TEST{"테스트나 로그로<br/>확인 가능한가?"}
  TEST -->|"예"| FOLLOW["follow-up 또는 현재 PR 반영"]
  TEST -->|"아니오"| HUMAN["사람 reviewer 판단으로<br/>non-blocking 처리"]
  BLOCK --> VERIFY["수정 commit + 최신 head 재리뷰"]
  FOLLOW --> VERIFY
  VERIFY --> OWNER{"owner 승인 완료?"}
  OWNER -->|"예"| MERGE["merge 가능"]
  OWNER -->|"아니오"| WAIT["승인 대기"]

0.2 운영 게이트

---

1. PR 작성 기준

좋은 PR 설명은 reviewer가 코드를 열기 전에 위험도를 판단할 수 있게 합니다.

---

2. 리뷰 관점

리뷰어는 취향보다 기준을 근거로 코멘트합니다. 기준이 없다면 새 표준/RFC 후보로 올립니다.

---

3. AI 리뷰 사용 기준

왜 중요한가: AI 리뷰를 무차별 적용하면 false positive로 리뷰 피로가 누적되고, 결국 정작 중요한 경고도 무시되는 "양치기 소년" 상태가 됩니다.

AI는 다음 작업에 유용합니다.

• diff 요약과 위험 후보 정리
• 누락된 테스트 케이스 제안
• 보안/성능/접근성 체크리스트 적용
• 큰 PR 분할 제안
• RFC/ADR과 구현의 일치 여부 점검

AI 사용 제한:

• AI 코멘트는 merge approval이 아닙니다.
• AI가 만든 수정안은 로컬 테스트와 사람이 읽는 리뷰를 거칩니다.
• private code, secret, 고객 데이터, 내부 로그는 정책에 맞게 마스킹합니다.
• AI가 찾은 문제는 재현 코드, 테스트, 링크 중 하나로 검증합니다.

3.1 AI finding triage 흐름

flowchart TD
  F[AI finding] --> Q1{재현 가능한가}
  Q1 -->|아니오| REJECT[reject<br/>오탐 마킹 + 규칙 보정 후보]
  Q1 -->|예| Q2{현재 PR<br/>범위 내인가}
  Q2 -->|아니오| FU[follow-up<br/>issue + owner + due date]
  Q2 -->|예| Q3{기존 정책/ADR과<br/>충돌하는가}
  Q3 -->|예| REJECT_DOC[reject<br/>근거 문서 링크 첨부]
  Q3 -->|아니오| Q4{blocking 위험인가}
  Q4 -->|예| ACCEPT_B[accept blocking<br/>수정 + 테스트 추가]
  Q4 -->|아니오| ACCEPT_S[accept suggestion<br/>작성자 판단]
  ACCEPT_B --> COMMIT[수정 commit + 검증 명령]
  ACCEPT_S --> COMMIT
  REJECT --> RULE[규칙 보정 backlog]
  REJECT_DOC --> RULE

비유: 우편물 분류와 같습니다. 광고지(reject), 다음 주 처리할 청구서(follow-up), 즉시 처리할 등기우편(accept blocking)으로 나누어야 책상이 정돈됩니다.

---

4. Conventional Comments

리뷰 코멘트는 의도를 분명히 합니다.

blocking: 이 API 응답은 외부 입력이므로 runtime validation이 필요합니다.
테스트에는 잘못된 enum 값이 들어왔을 때 fallback되는 케이스도 추가해 주세요.

---

5. PR 크기와 분할

왜 중요한가: PR 크기는 리뷰 누락률과 거의 선형으로 관련됩니다. 큰 PR은 reviewer가 끝까지 보지 않고 LGTM을 누를 위험이 큽니다.

큰 변경은 preparatory refactor -> behavior change -> cleanup 순서로 나누면 리뷰가 쉬워집니다.

5.1 PR 크기와 리뷰 시간/결함의 상관

flowchart LR
  XS[XS<br/>~50줄] -->|리뷰 5~15분<br/>결함 검출 높음| Q[정상 머지]
  S[S<br/>~200줄] -->|리뷰 15~30분<br/>핵심 logic 추적 가능| Q
  M[M<br/>~400줄] -->|리뷰 30~60분<br/>피로 누적 시작| Q
  L[L<br/>~800줄] -->|리뷰 1~2시간<br/>스킵 위험| WARN[분할 권장]
  XL[XL<br/>800줄+] -->|LGTM 의례화<br/>escaped defect 급증| SPLIT[필수 분할]

비유: 식사량과 같습니다. 한 끼에 한 끼분만 먹어야 소화가 됩니다. 일주일치를 한 번에 먹으면 탈이 납니다.

5.2 큰 PR 분할 전략

flowchart TB
  BIG[큰 변경 1개<br/>800줄+] --> P1[1. preparatory refactor<br/>동작 변경 없음, 테스트 그대로 통과]
  P1 --> P2[2. behavior change<br/>실제 로직 변경, 테스트 새로 추가]
  P2 --> P3[3. cleanup<br/>죽은 코드/dead config 제거]
  P3 --> DONE[모든 단계 reviewable]

---

6. Merge 기준

승인은 "읽었다"가 아니라 "이 변경을 해당 위험도로 배포해도 된다고 판단했다"는 의미입니다.

---

7. 리뷰 메트릭

왜 중요한가: 메트릭이 없으면 "리뷰 잘하고 있다"는 감각만 남고, 어디가 막혔는지 데이터로 말할 수 없습니다.

메트릭은 사람 평가보다 프로세스 개선에 사용합니다.

7.1 PR 상태 다이어그램

stateDiagram-v2
  [*] --> Draft: 작성 시작
  Draft --> Open: ready for review
  Open --> CIRunning: 자동 게이트 진행
  CIRunning --> CIFail: 실패
  CIRunning --> AIReview: 통과
  CIFail --> Draft: 수정 필요
  AIReview --> ChangesRequested: AI/사람 blocking
  AIReview --> ApprovedReady: blocking 없음
  ChangesRequested --> Draft: 작성자 수정
  ApprovedReady --> Merged: owner approval
  Merged --> Monitored: 배포/모니터링
  Monitored --> [*]: 안정
  Monitored --> Reverted: 회귀 감지
  Reverted --> Draft: 재설계

---

8. 체크리스트

• [ ] PR 설명에 변경 의도, 영향 범위, 테스트 결과가 있는가
• [ ] 변경 크기가 리뷰 가능한 단위인가
• [ ] 보안/성능/접근성/장애 대응 관점이 검토되었는가
• [ ] AI 리뷰 결과를 사람이 검증했는가
• [ ] blocking 코멘트가 모두 해결되었는가
• [ ] 문서/RFC/ADR 업데이트가 필요한 변경인지 확인했는가
• [ ] 배포 후 모니터링 owner가 명확한가

---

9. 제외한 벤더 종속 항목

공통 개발 가이드에는 특정 코드리뷰 SaaS, 특정 SCM bot, 특정 AI 에이전트 제품, 특정 가격/벤치마크, 특정 PR 자동화 action을 팀 표준으로 강제하지 않습니다. 다만 도구를 도입한 저장소가 일관되게 운영할 수 있도록 CodeRabbit 같은 AI 리뷰 도구의 설정 예시는 선택 가이드로 제공합니다.

---

10. CodeRabbit 설정 운영 예시

CodeRabbit은 사람 리뷰를 대체하지 않고 PR 초안 검토, 반복 품질 규칙, 경로별 체크리스트를 자동으로 상기시키는 도구로 사용합니다.

10.1 .coderabbit.yaml 기본값

# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
language: ko-KR
tone_instructions: '간결하게, 파일/라인 근거와 재현 가능한 검증 명령을 우선한다.'
early_access: false

reviews:
  profile: assertive
  request_changes_workflow: false
  high_level_summary: true
  review_status: true
  review_details: true
  auto_review:
    enabled: true
    drafts: false
  path_filters:
    - '!dist/**'
    - '!node_modules/**'
    - '!coverage/**'
    - '!public/mockServiceWorker.js'
    - 'src/**'
    - 'public/개발가이드/**'
  path_instructions:
    - path: 'src/**/*.test.{ts,tsx}'
      instructions: 'MSW handler가 실제 API 계약과 같은 fixture를 쓰는지, 성공/실패/empty/error 경로가 모두 있는지 확인한다.'
    - path: 'src/**/api/**/*.{ts,tsx}'
      instructions: 'hidden side effect, 인증 wrapper 이름, Result/error 반환 계약, timeout/retry/idempotency 정책을 확인한다.'
    - path: 'public/개발가이드/**/*.md'
      instructions: 'Frontend Fundamentals의 가독성, 예측 가능성, 응집도, 낮은 결합도 기준과 PR 완료 기준이 실무적으로 연결되는지 확인한다.'
  tools:
    eslint:
      enabled: true
    markdownlint:
      enabled: true
    github-checks:
      enabled: true

chat:
  auto_reply: true

10.2 경로별 리뷰 지침

• path_filters는 generated code, build output, lockfile, coverage처럼 리뷰 가치가 낮은 파일을 제외합니다.
• path_instructions는 테스트, API, 문서, 보안 파일처럼 관점이 다른 경로에 별도 체크 기준을 둡니다.
• CodeRabbit의 third-party tool 연동은 저장소의 ESLint/markdownlint 같은 기존 설정을 기준으로 삼습니다. 도구 설정이 없으면 기본 profile이 쓰일 수 있으므로 중요한 rule은 repository config에 명시합니다.

10.3 주석 룰

• TODO, FIXME, XXX는 ESLint no-warning-comments로 감지하고, owner 또는 issue 링크가 없는 항목은 PR에서 제거합니다.
• inline comment는 ESLint no-inline-comments 또는 review rule로 제한합니다. 같은 줄 설명이 필요할 정도로 표현이 어려우면 변수명, predicate 함수, 타입명으로 먼저 옮깁니다.
• eslint-disable 주석은 한 줄 단위로 제한하고, 규칙명과 사유를 함께 적습니다.
• 주석으로 코드 동작을 설명하기보다 "왜 이 예외가 필요한지", "언제 제거할지", "어떤 외부 계약 때문인지"를 남깁니다.

10.4 AI finding 처리

10.5 CodeRabbit 리뷰 게이트

CodeRabbit을 merge 조건으로 쓰는 저장소는 .coderabbit.yaml과 별도로 CodeRabbit review gate 체크를 둡니다. 이 체크는 PR의 최신 head SHA에 달린 CodeRabbit 리뷰만 인정합니다. 과거 commit에서 승인된 리뷰는 새 commit 이후의 변경을 검토하지 않았으므로 merge 근거가 될 수 없습니다.

브랜치 보호 규칙에는 CodeRabbit review gate를 required status check로 등록하고 required conversation resolution을 켭니다. workflow 파일만 추가하면 빨간 체크나 미해결 리뷰 스레드가 보여도 설정에 따라 merge가 가능할 수 있으므로, 실제 강제력은 브랜치 보호 설정에서 완성됩니다.

CodeRabbit 적용 저장소에는 .github/workflows/branch-protection.yml을 두고, GH_ADMIN_TOKEN 시크릿으로 수동 실행합니다. 이 워크플로우는 저장소별 quality aggregator 체크와 CodeRabbit review gate를 required status checks로 묶고, 미해결 리뷰 스레드가 남아 있으면 auto-merge도 대기하게 만듭니다. 사람 승인까지 필수로 둘 저장소는 dispatch 입력값 required_approving_review_count를 1 이상으로 실행합니다.

자동 머지는 Dependabot safe bump 정책 또는 automerge/auto-merge 라벨처럼 병합 의도가 명확한 PR에만 활성화합니다. Dependabot이라도 production dependency major는 자동 머지하지 않습니다. CodeRabbit이 CHANGES_REQUESTED를 남긴 상태에서는 required check가 빨간 상태로 유지되어 auto-merge가 대기해야 하며, 수정 commit 후 최신 head SHA에 대한 재승인이 있어야 병합됩니다. 리뷰 스레드가 열린 상태라면 conversation resolution이 auto-merge를 계속 대기시킵니다.

운영자는 CodeRabbit review gate를 사람 승인 카운트와 혼동하지 않습니다. 기본 브랜치 보호는 사람 승인 수를 0으로 두고 CodeRabbit/CI required checks와 conversation resolution으로 자동화 게이트를 강제할 수 있습니다. 사람 리뷰도 반드시 요구하는 저장소는 같은 branch-protection.yml을 required_approving_review_count=1 이상으로 다시 실행해 정책을 올립니다.

AI 리뷰 도구를 새 저장소에 도입할 때는 다음 순서로 적용합니다.

1. .coderabbit.yaml을 먼저 추가하고 PR에서 실제 CodeRabbit 리뷰가 생성되는지 확인한다.
2. .github/workflows/coderabbit-gate.yml을 추가해 최신 head SHA 승인만 통과하게 한다.
3. .github/workflows/branch-protection.yml의 required check 목록에 저장소의 quality aggregator와 CodeRabbit review gate를 넣는다.
4. GitHub 원격 main 브랜치 보호에 required checks와 required conversation resolution을 적용한다.
5. automerge/auto-merge 라벨 workflow는 브랜치 보호가 검증된 뒤 활성화한다.

---

실무 적용 가이드

언제 이 문서를 펼칠까

• AI 리뷰를 도입했지만 지적사항이 피상적이거나 노이즈가 많을 때
• AI가 만든 코드가 테스트 없이 merge될 위험이 있을 때
• PR이 커져 사람이 변경 의도를 따라가기 어려울 때

적용 순서

1. PR을 기능, 리팩터, 테스트, 문서 변경으로 작게 나눈다.
2. AI 리뷰에는 변경 의도, 위험 영역, 확인할 파일을 명확히 준다.
3. AI finding을 accept, reject, follow-up으로 triage한다.
4. 보안, 접근성, 성능 항목은 사람 reviewer가 최종 승인한다.
5. 리뷰 결과와 검증 명령을 PR description에 남긴다.

함께 두는 파일

• 리뷰 체크리스트는 PR template과 가이드 문서에 둔다.
• AI가 생성한 fixture/test는 기능 코드 가까이에 둔다.
• review metric은 repository 단위로 보되 finding taxonomy는 도메인별로 기록한다.

흔한 실수

• AI approve를 사람 리뷰 대체로 사용한다.
• 큰 PR 하나에 기능, 구조 변경, 스타일 수정이 섞인다.
• AI가 제안한 dependency나 API를 공식 문서로 확인하지 않는다.
• false positive가 많아도 규칙을 조정하지 않는다.

PR 완료 기준

• [ ] PR 크기와 의도가 명확하다.
• [ ] AI finding disposition이 남아 있다.
• [ ] CodeRabbit review gate가 최신 head SHA 기준으로 통과했다.
• [ ] 사람 reviewer가 위험 항목을 확인했다.
• [ ] 테스트/보안/접근성 증거가 연결되어 있다.

추천 항목 실행 우선순위 매핑

• P1(7일 내) — AI finding triage와 사람 승인 책임 중 하나를 작은 변경 1건에 적용하고 증거(finding disposition)를 남긴다.
• P2(30일 내) — AI 리뷰 기준을 팀 템플릿, 체크리스트, CI 중 한 곳에 고정한다.
• P3(90일 내) — false positive, 미해결 thread, 재리뷰 횟수 추이를 보고 기준을 유지할지 조정할지 결정한다.
• 완료 기준 — 리뷰 오너가 증거와 철회 조건을 확인했다는 기록을 남긴다.

추천 항목 실행 체크리스트

• [ ] 1단계(7일) : AI finding triage와 사람 승인 책임 적용 대상을 1개로 좁힌다.
• [ ] 2단계(30일) : 증거(finding disposition, 최신 head SHA review, 사람 reviewer 승인)를 PR, ADR, 회고 중 한 곳에 연결한다.
• [ ] 3단계(60일) : false positive, 미해결 thread, 재리뷰 횟수가 기준 안에 들어왔는지 확인한다.
• [ ] 문제 대응 : 미달성 사유와 다음 조치, 중단 여부를 같은 기록에 남긴다.

추천 항목 실행 운영 규칙

• 실행 게이트 : AI approve가 사람의 위험 판단을 대체하지 않는지 확인한다.
• 승인 체계 : 리뷰 오너가 영향 범위와 rollback 담당자를 적용 전에 확인한다.
• 재개 조건 : 최신 head SHA 리뷰와 사람 승인 근거가 맞으면 merge를 진행한다.
• 정지 조건 : AI 제안이 테스트 없이 바로 반영되거나 thread가 미해결이면 멈춘다.
• 리스크 점수 : PR 크기, 자동 수정량, 민감 파일 변경으로 산정한다.
• 리더 승인자 : 코드리뷰 리드가 최종 승인 책임을 맡는다.
• 승인 역할 : AI 리뷰 작성자, 검토자, 운영 확인자를 분리해 기록한다.
• 재평가 주기 : 2주마다 false positive와 blocking 기준을 조정한다.