리뷰가 따라가지 못할 때, 시스템으로 해결하기: 관점을 CI·AI·인간에게 분배한 과정 기록

서론

AI로 코드를 작성하는 양이 늘어나면서 PR(Pull Request)의 수와 크기 모두 증가했고, 리뷰를 담당하는 인간이 병목 현상이 되고 있습니다. 회고(KPT)에서도 '리뷰에서 무엇을 봐야 하는지 명문화되어 있지 않아 리뷰어마다 확인 내용이 다르다'는 의견이 나왔습니다.

이에 팀 차원에서 리뷰의 관점을 정리하고, 기계(CI)·AI·인간의 역할 분담을 결정하여 점진적으로 시스템에 녹여내는 작업을 시작했습니다.

본 글은 완성된 성공 사례가 아니라, 과정 기록 및 그 과정에서 내린 판단들을 담고 있습니다. 잘되지 않았던 부분이나 포기하기로 결정한 내용도 포함합니다.

목표 설정

처음에 정한 것은 '무엇을 완료로 볼 것인가'였습니다.

• 리뷰는 완료 후에도 일정 부분 인간이 개입하므로, 명확한 목표를 세우기 어려웠습니다.
• 속도보다는 리뷰 관점이 사람에게 의존하지 않는 것을 목표로 삼았습니다. 수치(리뷰 시작부터 종료까지의 시간 등)는 측정해도 파악하기 어렵다고 판단하여 너무 집착하지 않기로 했습니다.
• 우선 '정해진 것을 실행할 수 있다면 초기 도입 완료'로 보고, 이후에는 지속적인 개선 단계로 넘어가기로 했습니다.

그 위에 작업을 다음 페이즈로 나누어 하나의 트래킹 이슈(Tracking Issue)로 관리했습니다.

기본 방침: 3단계로 생각하기

방침은 간단히 세 가지입니다.

기계가 판별할 수 있는 것은 CI에 맡기고, 인간은 원칙적으로 재확인하지 않는다.

• **AI 리뷰는 일차 필터(一次フィルタ)**로 사용하며, 명백한 문제를 인간 앞에 줄인다.
• 인간은 사양이나 트레이드오프를 이해해야 판단할 수 있는 것에 집중한다.

PR이 나와서 인간에게 도달하기까지의 흐름은 다음 이미지를 참고하세요.

이 방침에 따라 리뷰 관점을 파악하여 3단계로 분배했습니다.

리뷰 관점 분배

관점별 논의 내용 (발췌)

크기: StackedPR은 '큰 PR에서 효과적'

PR이 커지는 문제에는 StackedPR(gh-stack)을 시도했습니다. 실제로 몇 번 사용해 본 결과, 덩치가 큰 PR에서 효과가 크다는 실감을 했습니다. 반면 과제도 발견했습니다.

• 스택 단위로 CI가 자주 실패한다.
• 스택 단위 테스트로는 일관된 케이스나 의존성이 있는 케이스가 누락될 가능성이 있다.
• 리뷰 수정 시, 해당 수정이 어느 스택 브랜치에 속하는지 확인하는 수고가 필요하다.

PR 크기 문제는 StackedPR로 일단 해소한다고 보고, 효과 측정을 통해 문제가 남아있으면 재검토하기로 했습니다. 과제 해결에는 hook이나 skill을 이용한 시스템화가 가능할 것 같아, 이는 조사 주제로 남겨두었습니다.

업무 로직: AI에게 '요건 이해'를 설명하게 하기

업무 로직은 AI가 더 잘하는 부분도 있지만, 근본적으로 요건이 올바르게 전달되었는지가 본질입니다. 그래서 다음과 같은 사용법을 고려하고 있습니다.

• AI에게 요건을 설명하게 하고, 인간이 인식에 차이가 없는지 확인한다.
• AI에게 요건 기반의 문제를 만들게 하고, 인간이 해결한다(해결할 수 없거나 틀리면 이해가 부족한 것).
• 문제와 답만 만들어 보게 해도, 차이에 눈치챌 수 있을 것 같다.

배경에는 '인간이 애초에 코드를 완전히 이해하지 못하게 되고 있다'는 과제가 있습니다.

하위 호환성: AI는 '불필요한 호환성'을 남기려는 경향이 있다

AI는 친절함 때문에 필요 없는 하위 호환성을 남기려고 할 때가 있습니다. 이를 제거하고 싶으면서도, 사용자에게 영향을 주는 부분은 꼼꼼히 보고 싶다는 양면성이 존재합니다.

• 사용자에게 영향이 가는 부분은 인간과 AI 모두에서 확인한다.
• 개발 환경에서 망가져도 확인할 수 있는 범위는 어느 정도 포기한다.
• 프론트와 백의 동기는 확실하게 확인한다.

테스트: 커버리지 임계값은 정말 효과적인가

당초에는 '양은 커버리지 임계값, 질은 커스텀 지시'라는 두 가지 방식을 생각했습니다. 하지만 논의 과정에서,

• 커버리지 밖에 있는 것이 중요한 경우가 많다.
• 프론트엔드는 스토리 단위의 커버리지가 확보되지 않았다.

이러한 지적이 나오면서, 임계값 설정(閾値設定)만으로는 문제의 본질적인 해결책이 아닐 수 있다고 정리했습니다. 테스트 품질을 AI 리뷰 쪽에 맡기는 다른 접근 방식을 조사하고 있습니다.

진행하지 않기로 한 판단

진행 과정에서 하지 않기로 결정한 것들도 많았습니다. 이것 또한 성과라고 생각합니다.

• linter 추가 규칙 도입: 시도해 본 결과 효과가 미미하다고 판단하여 폐기 -
• 프론트/백 API 정의 동기화 체크 CI: 비용 대비 효율이 낮아 보류 -
• PR 크기 라벨 개별 도입: 이후 설명할 자동 리뷰 조사에 통합 -
• 호스트형 Codex 리뷰 도입: 도입 과정의 수고가 크고, 각자 로컬에서 Codex로 리뷰하는 형태로 충분하다고 판단 -
• Copilot 커스텀 지시 개선: 방침 전환 (다음 절)

먼저 작동시켜 본 PR들을 관점 문서(観点ドキュメント)를 만든 후에 정리하면서, '만들었지만 적용하지 못할 것'을 판단할 수 있었습니다.

방침 전환: 커스텀 지시에서 범용적인 리뷰 시스템으로

처음에는 기존 Copilot 리뷰에 커스텀 지시(カスタム指示)를 추가하여 정확도를 확인하는 것이 목표였습니다. 하지만 팀원들과 논의하면서 다음 이유들로 인해 방침을 변경했습니다.

• Copilot의 커스텀 지시는 모델이 고정되어 있어 로컬 리뷰에는 사용할 수 없음
• 애초에 지시 파일(指示ファイル)이 어디까지 읽히는지 알기 어려워, CLI로 실행하는 것이 더 확실할 수 있음
• 지적 내용을 우리가 직접 커스터마이징하고 싶음 (AI와 인간의 역할 분담을 제어하고 싶음)

그래서 리뷰 관점을 하나의 정식 문서(正ドキュメント)로 두고, 거기서 AI 리뷰를 호출하는 형태로 변경했습니다. 이 관점 문서를 리포지토리 루트에 배치하고 팀 합의 후 병합합니다.

나아가, 리뷰는 다음 두 가지를 염두에 두고 있습니다.

• 작성한 모델과는 다른 모델, 다른 컨텍스트에서 리뷰시키기 (같은 모델이라도 컨텍스트 분리) **