# 16. AI 협업 코드리뷰 가이드 ## 0. 먼저 알고 가기 (30초 요약) - AI 제안은 작업 속도를 올리지만 최종 판단은 사람의 맥락 이해입니다. - 제안은 테스트/근거/리스크를 분리해서 검토하면 오탐을 줄입니다. - 사람의 리뷰가 지표와 정책을 통과하면 바로 반영, 아니면 재요청하세요. > **왜 중요한가**: AI 리뷰는 노이즈를 줄이고 사람의 주의력을 위험 구간에 모으는 도구입니다. 사람의 승인 책임을 대체하면 사고가 났을 때 책임 소재가 사라집니다. > > **일상 비유**: 공장의 자동 검사 라인과 같습니다. 카메라(AI)가 1차로 결함을 걸러주지만, 출고 전 최종 인장 도장은 검사관(사람)이 찍습니다. ## 초심자용 한눈에 보기 AI는 속도 보조 도구이지 최종 결정권이 아닙니다. 사람이 최종 판단합니다. ```mermaid flowchart LR D[작성자] -->|작은 PR| AI[AI 1차 리뷰] AI -->|시그널 정리| H[사람 reviewer] H -->|blocking 해결 확인| O[Code Owner 승인] O --> M[Merge + 모니터링] ``` ### 핵심 용어 빠르게 정리 | 용어 | 쉬운 뜻 | | ----------- | ------------------------------------------------- | | `AI 제안` | 생성된 수정안이나 리뷰 코멘트 | | `근거 링크` | 변경 이유를 뒷받침하는 문서/로그 | | `triage` | finding 분류(즉시 반영/보류/제거) | | `검증` | 로컬 테스트, 리뷰, 정책 검토로 실제 동작 확인 | | `인수인계` | AI 제안을 사람이 최종 승인/결정하고 반영하는 과정 | | 분류 | 협업 & 품질 | 상태 | Stable | | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :------------ | :-------- | | **연관 가이드** | [07. 테스팅](./07_테스팅_가이드.md), [15. 의사결정](./15_RFC_의사결정_프로세스.md), [18. AI 워크플로우](./18_AI_개발_워크플로우_종합.md) | **도구 원칙** | 벤더 중립 | | **핵심 테마** | 작은 PR, 리뷰 기준, AI 보조 검토, Conventional Comments, merge 책임 | **Update** | 최신 기준 | --- > 코드리뷰 표준은 특정 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, 재리뷰 횟수를 다시 볼 날짜와 담당자를 지정한다. ## 문서 책임 범위 | 이 문서가 결정하는 것 | 단일 출처로 따르는 문서 | | :---------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PR 크기, 리뷰 관점, merge 책임, Conventional Comments | [15. 의사결정](./15_RFC_의사결정_프로세스.md), [11. CI/CD](./11_CICD_파이프라인_표준.md) | | 테스트/보안/성능/접근성 증적을 리뷰에서 확인하는 기준 | [07. 테스팅](./07_테스팅_가이드.md), [06. 보안](./06_웹_보안_심화_가이드.md), [08. 성능](./08_성능_최적화_가이드.md), [19. 웹 접근성](./19_웹_접근성_가이드.md) | | AI 보조 리뷰의 non-blocking/blocking 판단 기준 | [18. AI 개발 워크플로우](./18_AI_개발_워크플로우_종합.md) | | 신규 구성원이 리뷰 기준을 학습하는 경로 | [17. 온보딩](./17_신규_입사자_온보딩_가이드.md) | --- ## 0. 모든 프론트엔드 그룹 공통 Baseline | 영역 | 공통 기준 | 실패 시 | | :------------ | :----------------------------------------------------------------- | :------------------ | | **PR 크기** | 리뷰 가능한 작은 단위로 분리 | 분할 요청 | | **변경 의도** | 문제, 해결 방식, 영향 범위, 검증 방법 기재 | 리뷰 보류 | | **자동 검증** | lint, type, test, build, security gate 통과 | merge 차단 | | **리뷰 관점** | correctness, security, performance, accessibility, maintainability | 누락 관점 추가 요청 | | **AI 역할** | 초안 검토, 위험 후보 제안, 테스트 누락 탐지 | 사람 승인 전 참고만 | | **책임** | 최종 merge 책임은 reviewer와 owner에게 있음 | AI 단독 승인 금지 | | **증적** | 중요한 논의와 결정은 PR/RFC/ADR에 남김 | 추적 불가 시 보완 | ### 0.0 리뷰 플로우(사람+AI) ```mermaid 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의 역할 분담 ```mermaid 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 교차 검증 매트릭스 | 권고 | 1차 출처 | 실행 증거 | 운영 증거 | 철회 조건 | | :----------- | :-------------------------------------------------------- | :------------------- | :----------------------------- | :---------------------------- | | 작은 PR | 코드리뷰 연구와 팀 cycle time | PR size report | escaped defect, review latency | 대형 변경은 stacked PR로 분할 | | AI 보조 리뷰 | [18. AI 워크플로우](./18_AI_개발_워크플로우_종합.md) 정책 | AI finding 재현 test | false positive/false negative | 검증 없는 AI blocking 금지 | | Merge 책임 | CODEOWNERS/ownership 기준 | approval record | rollback/incident owner 추적 | owner 불명확 PR merge 금지 | ### 0.1.1 AI finding 처리 판정표 ```mermaid flowchart TD START["AI finding 도착"] --> REPRO{"재현 가능한가?"} REPRO -->|"아니오"| LABEL_FALSE["false positive로 표시
규칙 보정 후보 등록"] REPRO -->|"예"| RISK{"보안/데이터/접근성/성능
위험인가?"} RISK -->|"예"| BLOCK["blocking finding
수정 또는 명시적 거절 사유 필요"] RISK -->|"아니오"| TEST{"테스트나 로그로
확인 가능한가?"} TEST -->|"예"| FOLLOW["follow-up 또는 현재 PR 반영"] TEST -->|"아니오"| HUMAN["사람 reviewer 판단으로
non-blocking 처리"] BLOCK --> VERIFY["수정 commit + 최신 head 재리뷰"] FOLLOW --> VERIFY VERIFY --> OWNER{"owner 승인 완료?"} OWNER -->|"예"| MERGE["merge 가능"] OWNER -->|"아니오"| WAIT["승인 대기"] ``` ### 0.2 운영 게이트 | Gate | Evidence | Owner | Rollback | | :------------- | :-------------------------------------------------- | :--------- | :----------------------------------- | | PR readiness | 변경 의도, 위험도, 검증 결과, 관련 링크 | Author | draft 전환 또는 PR 분할 | | AI review | 재현 가능한 finding, test/link, false-positive 표시 | Reviewer | AI 코멘트 non-blocking 처리 | | Merge approval | owner approval, 품질 gate, rollback owner | Code owner | merge 보류 또는 revert owner 지정 | | Review latency | review SLA, PR size, blocking reason | Team lead | reviewer 재배정 또는 stacked PR 전환 | --- ## 1. PR 작성 기준 | 항목 | 작성 기준 | | :--------------- | :------------------------------------------- | | Summary | 무엇을 바꿨는지 3줄 이내 | | Motivation | 왜 필요한 변경인지 | | Scope | 포함/미포함 범위 | | Risk | 사용자 영향, rollback 난이도, migration 여부 | | Test | 실행한 테스트와 결과 | | Screenshot/Trace | UI 변경, E2E, 성능 변경 증적 | | Links | 관련 issue, RFC, ADR, design, incident | 좋은 PR 설명은 reviewer가 코드를 열기 전에 위험도를 판단할 수 있게 합니다. --- ## 2. 리뷰 관점 | 관점 | 질문 | | :-------------- | :------------------------------------------------------ | | Correctness | 요구사항을 실제로 만족하는가, edge case가 처리되는가 | | Type safety | API boundary와 external input이 검증되는가 | | Security | 인증/인가/secret/PII/XSS/CSRF 위험이 없는가 | | Performance | 렌더링, bundle, network, cache 비용이 증가하지 않는가 | | Accessibility | keyboard, focus, name/role/value, contrast가 유지되는가 | | Reliability | 실패 상태, retry, fallback, rollback이 있는가 | | Maintainability | ownership, layering, naming, duplication이 적절한가 | | Testability | 변경 위험에 맞는 테스트가 있는가 | 리뷰어는 취향보다 기준을 근거로 코멘트합니다. 기준이 없다면 새 표준/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 흐름 ```mermaid flowchart TD F[AI finding] --> Q1{재현 가능한가} Q1 -->|아니오| REJECT[reject
오탐 마킹 + 규칙 보정 후보] Q1 -->|예| Q2{현재 PR
범위 내인가} Q2 -->|아니오| FU[follow-up
issue + owner + due date] Q2 -->|예| Q3{기존 정책/ADR과
충돌하는가} Q3 -->|예| REJECT_DOC[reject
근거 문서 링크 첨부] Q3 -->|아니오| Q4{blocking 위험인가} Q4 -->|예| ACCEPT_B[accept blocking
수정 + 테스트 추가] Q4 -->|아니오| ACCEPT_S[accept suggestion
작성자 판단] ACCEPT_B --> COMMIT[수정 commit + 검증 명령] ACCEPT_S --> COMMIT REJECT --> RULE[규칙 보정 backlog] REJECT_DOC --> RULE ``` 비유: 우편물 분류와 같습니다. 광고지(reject), 다음 주 처리할 청구서(follow-up), 즉시 처리할 등기우편(accept blocking)으로 나누어야 책상이 정돈됩니다. --- ## 4. Conventional Comments 리뷰 코멘트는 의도를 분명히 합니다. | Prefix | 의미 | | :------------ | :-------------------------- | | `blocking:` | merge 전 반드시 해결 | | `suggestion:` | 개선 제안, 작성자 판단 가능 | | `question:` | 의도 확인 | | `nit:` | 사소한 스타일/표현 | | `praise:` | 좋은 패턴 강조 | | `thought:` | 장기 개선 아이디어 | ```text blocking: 이 API 응답은 외부 입력이므로 runtime validation이 필요합니다. 테스트에는 잘못된 enum 값이 들어왔을 때 fallback되는 케이스도 추가해 주세요. ``` --- ## 5. PR 크기와 분할 > **왜 중요한가**: PR 크기는 리뷰 누락률과 거의 선형으로 관련됩니다. 큰 PR은 reviewer가 끝까지 보지 않고 LGTM을 누를 위험이 큽니다. | 크기 | 기준 | 정책 | | :--- | :--------- | :----------------------------- | | XS | 50줄 이하 | 빠른 승인 가능 | | S | 200줄 이하 | 권장 | | M | 400줄 이하 | 변경 의도와 테스트 명확해야 함 | | L | 800줄 이하 | 분할 검토 | | XL | 800줄 초과 | 원칙적으로 분할 | 큰 변경은 `preparatory refactor -> behavior change -> cleanup` 순서로 나누면 리뷰가 쉬워집니다. ### 5.1 PR 크기와 리뷰 시간/결함의 상관 ```mermaid flowchart LR XS[XS
~50줄] -->|리뷰 5~15분
결함 검출 높음| Q[정상 머지] S[S
~200줄] -->|리뷰 15~30분
핵심 logic 추적 가능| Q M[M
~400줄] -->|리뷰 30~60분
피로 누적 시작| Q L[L
~800줄] -->|리뷰 1~2시간
스킵 위험| WARN[분할 권장] XL[XL
800줄+] -->|LGTM 의례화
escaped defect 급증| SPLIT[필수 분할] ``` 비유: 식사량과 같습니다. 한 끼에 한 끼분만 먹어야 소화가 됩니다. 일주일치를 한 번에 먹으면 탈이 납니다. ### 5.2 큰 PR 분할 전략 ```mermaid flowchart TB BIG[큰 변경 1개
800줄+] --> P1[1. preparatory refactor
동작 변경 없음, 테스트 그대로 통과] P1 --> P2[2. behavior change
실제 로직 변경, 테스트 새로 추가] P2 --> P3[3. cleanup
죽은 코드/dead config 제거] P3 --> DONE[모든 단계 reviewable] ``` --- ## 6. Merge 기준 | 조건 | 기준 | | :------------ | :------------------------------------------ | | Gate | 필수 CI 통과 | | Approval | 코드 owner 또는 책임 reviewer 승인 | | Discussion | blocking thread 해결 | | Documentation | 표준/RFC/ADR 영향이 있으면 문서 업데이트 | | Release | feature flag, migration, rollback 계획 확인 | | Ownership | 배포 후 모니터링 owner 확인 | 승인은 "읽었다"가 아니라 "이 변경을 해당 위험도로 배포해도 된다고 판단했다"는 의미입니다. --- ## 7. 리뷰 메트릭 > **왜 중요한가**: 메트릭이 없으면 "리뷰 잘하고 있다"는 감각만 남고, 어디가 막혔는지 데이터로 말할 수 없습니다. | 지표 | 목적 | | :------------------- | :-------------------------- | | PR size | 리뷰 가능성 관리 | | Time to first review | 병목 확인 | | Rework count | 요구사항/설계 불명확성 탐지 | | Escaped defects | 리뷰 품질 확인 | | Flaky gate rate | 자동화 신뢰도 관리 | | Review coverage | owner 없는 영역 탐지 | 메트릭은 사람 평가보다 프로세스 개선에 사용합니다. ### 7.1 PR 상태 다이어그램 ```mermaid 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 # 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 처리 | 상태 | 의미 | PR에 남길 것 | | :-------- | :-------------------------------- | :------------------------------- | | accept | 실제 결함 또는 품질 개선으로 반영 | 수정 commit과 검증 명령 | | reject | 오탐 또는 의도된 예외 | 공식 문서, 테스트 결과, ADR 링크 | | follow-up | 현재 PR 범위를 넘는 개선 | issue 링크, owner, due date | ### 10.5 CodeRabbit 리뷰 게이트 CodeRabbit을 merge 조건으로 쓰는 저장소는 `.coderabbit.yaml`과 별도로 `CodeRabbit review gate` 체크를 둡니다. 이 체크는 PR의 최신 head SHA에 달린 CodeRabbit 리뷰만 인정합니다. 과거 commit에서 승인된 리뷰는 새 commit 이후의 변경을 검토하지 않았으므로 merge 근거가 될 수 없습니다. | 조건 | 처리 | | :------------------------------- | :------------------------------------------------------------------------ | | 최신 head SHA 리뷰 없음 | 게이트 실패, CodeRabbit 리뷰를 기다리거나 `@coderabbitai review`로 재요청 | | `APPROVED` | 게이트 통과, 사람 reviewer의 위험 항목 확인 후 merge 가능 | | `CHANGES_REQUESTED` | 수정 commit push, CodeRabbit 재리뷰 후 재검증 | | `COMMENTED` / `DISMISSED` / 기타 | 명시적 승인으로 보지 않고 재리뷰 또는 사람 reviewer 판단 필요 | 브랜치 보호 규칙에는 `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 기준을 조정한다.