AI에게 코드 리뷰 맡기기(with Github Action)

 코드 리뷰를 자동화하는 건 개발자의 유구한 전통입니다. 안드로이드만 해도 AI 등장전부터 무수히 많은 자동화 툴들이 존재했고, 지금도 존 재하고 있죠. AI가 등장하고 난 후에는 조금 더 이 분야가 빨라질 것 같습니다. 분명 AI가 급격하게 발전해서 코딩을 스스로 할 수 있게된 순간부터 개발자들이 망하고, 실제로 코드를 작성할 일이 없고... 뭐 그런 많은 이야기들이 오갔는데 이제는 AI가 짠 코드를 또 다른 AI가 리뷰까지 자동으로 할 수 있게 개발하는 것 같습니다!...?

 파이토치나 텐서플로우로 딥러닝을 시킬 때 보면 각 레이어를 어떤식으로 구성하느냐, 얼마나 촘촘하게 쌓느냐에 따라 딥러닝 성능이 확연하게 차이나곤 했습니다. 페이스북도 논문을 작성할 때 이 부분에 대한 연구를 위해 수많은 노가다를 거쳤다고 하더라구요. 이처럼 현재 무수히 많은 사람들이 활용하는 LLM AI도 마찬가지 인 것 같습니다. 단순히 여러번 검증하는 것으로도 1번 검증하는 것 보다 더 효과를 볼 수도 있습니다만, 어떤식으로 검증절차를 지니는가에 따라 효율이 극단적으로 좋아지거나 오히려 나빠질 수도 있어 리뷰를 맡기는 방법론에 대해서도 많은 이야기가 오가는 것 같습니다.

 그래서 오늘은 저는 어떻게 AI에게 리뷰를 맡기는지에 대해서 가볍게 정리해보고자 합니다.

---

 일단 저는 개인 프로젝트에서는 딱히 리뷰를 진행할만큼 볼륨이 큰 프로젝트를 진행중이지 않기 때문에 회사에서 주로 AI 코드 리뷰를 사용하는데요. 회사다보니 무료의 간단한 AI는 아니고 토큰이 열심히 지급되는 유료 버전으로 진행하고 있습니다. AWS에서 야심차게 준비한 bedrock을 사용중인데요. 테스트용으로는 무료로 사용할 수 있는 방법이 많으니 검색 및 AI에게 질문을 통해 진행해볼 수 있을 것 같습니다(AWS Bedrock은 모델별로 정해진 벤더를 이용해야 해서...)

 

리뷰 요청 구성 방식

 일단 리뷰를 위한 yml 파일을 구성하기 위해 여러개의 guide 문서를 .github 하단의 review-guides 폴더에 작성해두었습니다. 구조는  아래와 같습니다.

 

먼저 기술 스택 파악을 위해 libs.version.toml를 참조 시켰습니다. 버전 카탈로그로 변경하면서 불필요한 내용을 읽게 하지 않아도 되서 조금 좋아진 것 같습니다. 이후 프로젝트의 현재 형상에 대해서 설명하는 구간이 있습니다. 현재 프로젝트가 레거시 패키지와 신규 아키텍처 룰 적용 패키지를 구분해둬서 패키지가 레거시 부분인지 신규 아키텍처가 적용되어야 하는 패키지인지에 따라 가이드를 달리 구성해두었습니다.

 가장 먼저 공통 가이드인 .github/review-guides/commin-conventions.md 파일과 review-guide-conventions.md 파일을 참조하도록 합니다. commin의 경우 레거시와 신규 아키텍처 적용 트랙으로 분리하라는 가이드가 존재하며 각기 다른 가이드 문서를 참조하도록 명시하고 있습니다. 또한 공통적으로 코드 품질을 검토하는 부분에 대해서는 코틀린 언어로서 불필요한 !!, null 체크 등의 경고성 메시지 부터 val과 var의 사용성 여부, race condition에 대한 경고등을 언어 사용, 잠재적 버그, 성능, 메모리 누수, 코루틴, 보안 단계를 나눠 검토하도록 명시합니다.

 신규 아키텍처 적용 트랙에는 저희가 클린 아키텍처 + MVVM 모델(그리고 회사 내부적인 여러 컨벤션등)을 따르고 있기 때문에 가장 기본적으로 각 레이어 별 가이드(data, domain, presentation)를 구성하고 있습니다. 또 그 내부적으로는 viewmodel-conventions.md, usecase-conventions.md, repository-conventions, datasource-conventions등 가장 기본이 되면서 회사 내에서 네이밍 규칙이나 사용법등을 명시해놓은 부분들을 또 각기 다른 가이드를 사용해 구현 여부를 확인하도록 분리해두었습니다.

 이때 common의 아키텍처 적용 트랙에서 각 레이어 별로 가이드를 참고하라고 명시해둔 후, 각 레이어 가이드 내에서 또 각 컨벤션을 참조하라고 하게 되면 참조가 길어져 AI가(특히 claude-code) 컨텍스트를 위해 참조를 멈추는 문제가 발생하기도 하는데, 이를 해결하기 위해서 가이드는 디테일하게 걸어주어야 합니다.

 제가 레거시 패키지와 아키텍처 적용을 위한 개선 패키지의 root를 따로 둔 이유도 기존에 가독성을 위해 분리하려는 부분도 존재했지만, 패키지의 경로에 따라 각기 다른 가이드를 읽도록 AI에게 가이드를 주면 꽤나 정확하게(아직까지 리뷰의 퀄리티가 떨어지거나 ???를 발생시키는 코멘트를 내는 것을 보지는 못했습니다) 작동하는 것 같고, 또 개선 패키지 트랙으로 갔을 때 각 레이어별로 가이드를 확인하게 하기 위해 패키지의 구성이 '~root/data'면 data 레이어 가이드를, '~root/domain'이면 domain 레이어 가이드를 참조하도록 명시해두어 가이드를 확실하게 찾도록 했습니다. 또한 메인 프롬프트에 '~ViewModel' 패턴에는 viewmodel-conventions.md 파일을 참조하도록 작성해 리뷰시에 누락이 없게끔 이중 처리를 진행했습니다.

 그리고 리뷰의 형식에 대한 가이드를 개발자들이 수정하기 좋게 review-guide 문서를 추가했습니다. 여기서는 AI가 각 코멘트를 심각 - 주의 - 제안 단계를 가지도록 정리했으며 불필요한 토큰 낭비를 막기 위한 기본 처리(칭찬 금지, 문장 단순화, 긍정 평가 금지 등)와 리뷰 톤(현상 - 근거 - 시나리오와 같은 리뷰 양식)에 대한 설정을 처리합니다. 여기가 참조로 걸리면 AI가 이를 살짝 무시하는 경향이 생기기 때문에 이를 막아주기 위한 강한 문구들이 필요하다는 문제를 제외하면 개발자들이 이해하기 쉽고 수정도 간편해진다는 장점이 있어 리뷰도 따로 작성했습니다.

 

구성의 단점 분석 및 해결방안

 1차적으로는 위와 같이 리뷰의 형태를 정의하게 되었습니다. 처음에는 이 프롬프트의 내용을 간략하게 하나의 yml 파일에 작성했는데, 이렇게 가이드를 분리해두는 것 보다 훨씬 많은 토큰을 사용하고 리뷰의 퀄리티도 많이 부족한 모습을 보였습니다. 이렇게 가이드를 분리하고 나니 리뷰의 퀄리티가 팀에서 원하는 수준까지는 아니더라도 충분히 리뷰를 꼼꼼히 읽어볼 가치가 생겼습니다.

 하지만 아쉬운 게 있다면 가이드를 너무 세세하게 분리하는 경우(지금 보다 훨씬 더 세세한 조건일 경우) 아무리 명시적이고 강한 어조를 사용하더라도 클로드 코드의 경우 opus-4.7 버전은 컨텍스트의 절약을 위해 내부적으로 생략하는 로직이 존재하는 건지(추측입니다) 가이드를 무시하는 경우가 발생했습니다. codex의 경우에는 가이드를 좀 더 세분화해도 무시하거나 하는 문제는 발생하지 않아 괜찮았지만, 회사에서 공식적으로 사용하는 리뷰 AI는 클로드 였으므로 현재 상황에 맞게 리뷰의 퀄리티를 올려야 할 필요가 있었고, 추가적으로 진행해야 할 부분들이 생겼습니다.

 

AI가 가이드를 무시할 가능성의 존재를 무시할 수 없다면 가장 중요한 것은 가이드 문서의 크기와 숫자를 줄이는 것입니다. 이를 줄이기 가장 좋은 부분은 레이어 별 가이드입니다. 레이어 별 리뷰는 대체로 클린 아키텍처의 위반 여부를 판단하는 부분으로 구성되어 있는데, 이는 detekt와 같은 분석 기반 코드 리뷰 툴을 이용하면 AI 없이도 해결이 가능한 부분입니다(AI가 없던 시절 자동화를 위해 노력하신 분들께 감사를...). 이러한 분석 기반 툴을 이용해 레이어별 가이드 문서를 제거하고, yml의 프롬프트를 실행하기 전 detekt의 결과물을 먼저 생성하고, 이 결과물을 AI에게 분석시켜 전달하도록 프롬프트의 전반을 수정합니다.

 분석 기반 툴을 이용해서 위반 사항을 잡고, 이를 필요한 부분만 AI에게 읽도록 시키면 각 레이어별 세세한 가이드 문서를 작성했을 때 보다 읽어야 할 문서가 줄고(특히 위반사항이 없는 경우에 좋습니다.) 그 가이드를 검사하기 위해 코드를 읽는 부분이 사라지게 되므로 토큰 소모량이 줄어들게 됩니다(회사는 종량제를 사용하고 저에게 돈을 요구하지 않기 때문에 알빠!를 시전할 수 있지만).

 그렇게 효율화된 부분으로 회사 내부 컨벤션을 리뷰하도록 하면 정확도가 더욱 좋아지게 되지만 단점으로는 분석 툴이 빌드되는 시간이 AI의 코드 리뷰 시간보다 더 많은 시간이 걸린다는 점이 있습니다. 아무래도 lint나 detekt는 개발자의 품이 AI에게 명령하는 것 보다 많이 들고(그것조차 AI가 작성하겠지만) PR된 파일만 보도록 설정하게 되면 전체적인 구조를 제대로 분석하지 못해 AI보다 수준이 떨어지는 경우도 생기기 때문에 프로젝트 전체를 검사하도록 하는 편이 예외처리에 좋으니 결과적으로 더 많은 시간을 잡아먹게 될 수 있습니다. 이는 사용할 때 환경에 따라 적절하게 선택할 필요가 있을 것 같습니다.

 

 

---

 아직까지는 코드 리뷰를 위해 이정도까지만 작업을 했습니다. 최종 목표는 RAG를 이용한 방식을 통해 프로젝트를 파편화하여 DB로 저장해둔 후, 이를 리뷰 시에 참조하여 연관된 부분들을 AI에게 확인해서 전체적인 맥락을 파악해달라고 요청하는 것이지만, 회사에서 그 정도까지 투자할 가치가 있는지와 실제로 현재와 비교해 얼마나 더 리뷰의 효율이 좋아지는지에 대한 검증이 필요해 진행하지는 못하고 있습니다.

 역시 그냥 취미삼아 하는 개발과 회사에서 작업하는 것에는 이 검증 라인의 차이 덕분에 많은 차이를 보이는데, 덕분에 의도치 않게 자꾸 'why'를 고민하게 되어 좋은 것 같습니다. 가끔은 그냥 개발자로서 재밌어보이거나 좋아보이면 무턱대고 시도한 후에 누가 왜 했냐고 물었을 때 쉽게 대답하지 못하는 경우가 많았는데, 회사에서는 항상 왜 리소스를 투자해야하는지에 대해 물어봐주니 진지하게 고민할 수 있습니다.

 일단 적용해보니 AI 코드 리뷰는 확실히 쓸모가 많은 것 같습니다. 다들 많이 사용했으면 좋겠습니다.