Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
AI 코드 리뷰 시, 과거의 지적 사항을 단순 참조하는 것을 넘어 '교훈(review-lessons)'으로 체계화하여 다음 개발에 활용하는 시스템 구축 경험을 공유합니다. 이 시스템은 수집된 지적사항을 재활용 가능한 확인 관점으로 정리하고, 전문 담당자와 검증 담당자가 독립적으로 리뷰를 수행하도록 설계되었습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기AI에게 코드 리뷰를 맡겨도, 한 번 발견된 문제가 다른 변경 사항으로 인해 다시 나타날 수 있습니다. 그 자리에서 수정할 수는 있어도, 다음 설계나 리뷰에서 같은 관점을 사용할 수 있는 것은 아닙니다.
그래서 과거의 리뷰 지적을 교훈으로 남기고, 다음 리뷰에서 참조하는 'review-lessons'를 만들어 운영하고 있습니다. 이 글에서는 리뷰 체제를 바꾼 후 약 1개월간의 운영 경험을 되돌아봅니다. 시스템을 어떻게 변경했는지, 실제 리뷰에서 무엇이 일어났는지, 아직 측정하지 못한 부분까지 소개합니다.
리뷰 코멘트에는 단순히 수정한 라인에 대한 수정 방법뿐만 아니라, '이러한 조건에서는 이렇게 오작동한다'는 지식이 포함되어 있습니다. 이를 개별 PR(Pull Request)에 그대로 두면, 다음에 유사한 처리를 작성할 때 다시 찾아봐야 하는 번거로움이 생깁니다.
반면에 과거의 지적을 전부 프롬프트에 넣기만 하면 읽어야 할 양이 계속 늘어납니다. 전제가 다른 지적이나 오탐지까지 가져가면 오히려 리뷰를 방해하게 됩니다.
목표는 지적 사항을 모으는 것 외에도, 재활용 가능한 확인 관점으로 정리하고 이번 변경에 해당되는지 확인하는 흐름을 만드는 것이었습니다. 모델의 가중치(weights)를 업데이트하는 시스템은 사용하지 않았습니다. 업데이트한 것은 참조 자료와 리뷰 절차입니다.
대략적인 흐름은 다음과 같습니다.
현재 전문 담당은 인증/인가, 부작용(side effects), 데이터, UI/API 계약, 운영 5가지입니다. 예를 들어 데이터 담당자는 값의 일관성이나 업데이트 범위에 관한 교훈을 읽습니다. 모든 사람에게 모든 자료를 전달하는 대신, 담당자별로 읽는 범위를 나누고 있습니다.
각 담당자에게 동일한 차이점을 제공하고, 다른 담당자의 결론을 미리 보여주지 않습니다. 이는 같은 의견에 끌려가지 않고 각자의 관점에서 조사하도록 하기 위함입니다. 여러 담당자가 같은 원인을 발견하면 마지막에 하나의 지적으로 요약합니다.
검증 담당자는 '과거의 교훈과 비슷하다'는 이유만으로 지적을 채택하지 않습니다. 변경 전에도 존재했던 문제인지, 다른 처리로 방지되어 있는지, 그 코까지 실제로 도달하는지, 영향을 설명할 수 있는지 등을 확인합니다. 중간에 대상 차이점이 바뀌지 않았는지도 확인합니다.
여기서 중요한 것은 교훈을 정답으로 취급하지 않는 것입니다. 교훈으로부터 의심스러운 지점을 찾아내고, 이번 코드에서 근거를 확인합니다.
초기 버전에서는 과거의 지적을 정리하여 교훈을 만들고 AI가 참조할 수 있도록 했습니다. 이후에는 교훈을 사용하여 차이점을 확인하는 리뷰 담당자를 추가했습니다.
초기 버전은 공통된 교훈을 폭넓게 읽어보고, '이번 변경이 교훈에 위배되지 않는지'를 확인하는 방식이었습니다. 확신도가 낮은 지적도 후보에 포함했기 때문에, 교훈을 알고 있는 것과 이번 결함을 보여주는 것이 혼재되기 쉬운 설계였습니다.
그 후 5개의 전문 담당과 마지막 검증 담당으로 구성이 변경되었습니다. 역할별 자료, 독립적인 리뷰, 변경 전과의 비교를 조합하여, 이번 변경으로 새롭게 발생했거나 악화된 중대한 문제에 초점을 맞추고 있습니다.
이번에 되돌아본 약 1개월은 이 체제로 전환한 후의 운영 기간입니다. 교훈을 추가하면서 중간에 효과를 측정하기 위한 기록도 정리했습니다. 첫 번째 리뷰와 수정 후 재확인, 지적 없음과 미완료를 구분하고, 사용된 교훈이나 수정 사항과의 대응을 남기는 설계입니다.
구체적인 예시로 과거 데이터를 보완하는 변경이 있습니다.
도입 전 리뷰에서는 '아직 관측하지 않은 과거의 데이터를 현재 정보로 채우지 말라'는 지적이 있었습니다.
나중 변경안에서도 같은 종류의 문제가 나타났습니다. 처음 관측한 날짜의 정보부터 그보다 이전 날짜의 값까지 추정하여 채워 넣는 처리였습니다. 과거에 문제를 알고 있었더라도, 구현 시점에 같은 판단을 피할 수 있는 것은 아니었습니다.
이때 교훈을 참조한 데이터, 부작용, UI/API 계약 3개 담당자가 동일한 문제를 독립적으로 지적했습니다. 이후 보정 범위를 처음 관측한 날짜로 한정하고, 관측 전날로 거슬러 올라가 보정되지 않는지 회귀 테스트(regression test)를 통해 확인하는 방식으로 수정했습니다. 수정 후 리뷰도 진행했습니다.
3개 담당자가 지적했기 때문에 3건의 결함을 막았다고 계산하지 않습니다. 하나의 문제를 여러 관점에서 발견하고, 수정 및 테스트로 이어진 사례입니다.
이 예시를 통해 확인할 수 있었던 것은, 과거에 남긴 관점이 이후 리뷰에서 다시 사용되었다는 것입니다. 반면, 같은 문제가 포함된 안은 다시 만들어지고 있습니다. 설계나 구현 단계에서 막을 수 있도록 하려면, 교훈을 구현 전 확인 항목이나 테스트로 연결해야 합니다.
직전 변경에서도 테스트를 보조하는 처리의 중복이 리뷰에서 발견되어 공통화된 기록이 있습니다. 이 변경은 작성 시점에는 아직 병합되지 않았습니다. 이는 리뷰 후에 코드를 수정한 단계의 예시로 참고해 주십시오.
저희가 자체적으로 집계한 자료에서는, 리뷰 체계를 변경하기 전후 각각 3주를 비교했습니다. 변경 이전 기간에도 초기 운영이 포함되어 있기 때문에, 시스템 전체의 완전한 '미도입'과 '도입 후' 비교는 아닙니다.
직접 보관하고 있는 GitHub 코드 라인에 대한 지적 중 우선순위가 높은 문제로 P1 레이블이 붙은 지적을 기준으로 보면, 이전 기간에는 1,434건 중 722건(50.3%)이었고, 이후 기간에는 851건 중 193건(22.7%)이었습니다. 대부분 AI 리뷰 봇에 의한 지적이었습니다. 답변은 제외하고, 교훈으로 채택 여부를 판단하기 전의 기록을 집계했습니다.
이는 기록된 지적 건수 대비 P1 비율입니다. 이 수치만으로는 소프트웨어의 결함률이나 실제 장애가 같은 비율로 줄었다고 말할 수 없습니다.
비교에는 큰 편향도 있습니다. 이전 기간은 지적이 많은 상위 3개 PR(Pull Request)에만 약 절반이 집중되어 있었습니다. 또한, 지적이 1건 이상 기록된 PR당 평균 지적 건수는 감소했지만, 중앙값으로는 증가했습니다. 지적이 0건인 PR은 이 비교에서 제외되었습니다. 소수의 큰 PR의 영향을 받고 있어, 평균치만으로는 일상적인 리뷰 변화를 설명할 수 없습니다.
변경 규모나 난이도, 봇 설정, 리뷰한 횟수 등도 동일하지 않습니다. 각 PR에서 교훈을 실제로 사용했는지 여부도 보정할 수 없습니다. 이 집계는 경향을 파악하는 자료로만 사용해야 하며, 시스템의 효과를 증명하는 수치로는 다루지 말아 주십시오.
수치 비교는 각각 3주를 대상으로 한 것이며, 본 기사에서 되돌아보는 약 1개월 전체를 동일한 조건으로 집계한 결과가 아닙니다. 이전 절의 사례는 집계 기간 이후의 개발 기록에서 선택하여, 교훈이 사용된 장면으로 확인했습니다.
첫째는, 교훈이 늘어날수록 읽어야 할 양도 늘어난다는 점입니다. 조사 시점의 대장에는 301건의 교훈이 있습니다. 역할을 분담하더라도 해당 담당 자료를 일괄적으로 읽어야 하는 설계이기 때문에, 축적에 따른 부담은 남아 있습니다. 관련 교훈을 선택하여 전달하는 시스템과, 선택되지 않은 범위를 명확하게 보여주는 노력이 필요합니다.
둘째는, 교훈의 품질 문제입니다. 오지적이나 일회성 사유는 제외하고, 자료가 부족한 것은 보류하지만 완전히 제거할 수는 없습니다. 오래된 전제를 가져오지 않도록 원본 지적으로 돌아가 확인하고, 중복된 교훈을 정리하는 작업도 필요합니다.
셋째는, 지속적으로 운영하는 것입니다. 주기적으로 데이터를 수집하는 시스템을 준비하더라도 실행 환경이나 쓰기 권한이 갖춰져 있지 않으면 기록은 멈춥니다. 실제로 운영 도중에 쓰기 권한의 제약으로 인해 수집이 중단된 기록이 있어, 나중에 따라잡는 처리가 필요했습니다.
넷째는, 평가 방식입니다. 심각한 문제점을 찾는 것에만 초점을 맞추고 있기 때문에, 작은 개선 제안까지 포괄하는 용도로는 적합하지 않습니다. 향후 평가에서는 대상의 규모, 교훈 사용 여부, 최초 확인인지 재확인인지를 통일하여 채택된 지적, 오탐지, 재발한 문제를 추적해야 합니다.
개선 방향으로는, 교훈을 설계 시점의 확인 항목과 회귀 테스트에 연결하는 방법이 있습니다. 리뷰에서 떠올리는 것뿐만 아니라, 구현 전에 생각하고 동일한 실수를 테스트로 감지할 수 있는 단계까지 연결합니다.
review-lessons에서는 과거 지적을 교훈으로 정리하고, 역할별로 참조하며, 독립적인 리뷰와 최종 검증에 사용하는 흐름을 만들었습니다. 약 1개월간의 운영을 되돌아보니, 과거와 동일한 실패 메커니즘을 찾아내어 수정 및 회귀 테스트로 연결한 사례를 확인할 수 있었습니다.
지적 건수의 변화만으로는 품질이 얼마나 향상되었는지 아직 판단하기 어렵습니다. 교훈이 실제로 사용된 장면과 사용할 수 없었던 장면을 모두 남기면서, 다음 변경에서 유용한 확인 절차로 발전시켜 나가는 노력이 필요합니다.