AI가 검토한 PR, Farol로 사람이 확인할 코드 좁히기

코드 한 줄이 닿는 화면과 API를 따라간다

Winnin의 Farol은 AI 코드 검토 뒤에 사람이 승인 여부를 판단할 때 쓰는 CLI·GitHub Action이다. 보고서의 Start here에서 위험 신호가 큰 파일부터 읽고, 변경과 연결된 진입점을 볼 수 있다.

작동 원리 문서에 따르면 언어의 파서와 타입 검사 도구로 코드 연결을 읽는다. 변경 코드에서 화면·엔드포인트 같은 진입점까지 경로를 찾는 방식이다. 사용자가 서비스를 실제로 실행한 기록을 수집하는 기능과는 구별된다.

예를 들어 공통 함수를 고쳤다면 수정 파일의 줄 수만 보는 대신 그 함수를 사용하는 기능을 함께 읽을 수 있다. 승인자가 어디에 검토 시간을 써야 하는지 판단할 단서를 주는 것이다.

보고서가 없으면 미검증으로 남는다

Farol은 기존 테스트·린트·보안 검사 결과를 받아 변경 내용과 연결한다. 코드가 바뀐 줄을 테스트가 실행했는지 보는 diff coverage와, 클라이언트가 기대하는 요청·응답 형태가 달라졌는지 보는 계약 검사는 서로 다른 신호다.

표의 첫 행은 테스트가 그 줄을 실행했다는 뜻이다. 기대한 동작을 충분히 검사했는지는 테스트 내용을 읽어 판단해야 한다. API 계약 변화도 의도한 변경인지, 호출하는 쪽이 함께 수정됐는지가 후속 질문이다.

74점이라는 숫자를 장애 확률로 받아들이면 안 된다

Farol은 0~100점의 위험 점수를 보여주지만, 설계 문서는 가중치와 기준값을 휴리스틱, 즉 경험적 규칙이라고 명시한다. 이를 특정 서비스가 장애를 일으킬 확률로 그대로 대입할 근거는 없다.

파일을 검토했다고 표시하면 그 파일의 항목이 남은 점수에서 빠진다. 코드가 바뀌지 않아도 숫자가 내려갈 수 있다는 뜻이다. 따라서 잔여 점수는 검토 진행 상황과 함께 읽어야 한다. 파일을 읽었다는 표시만으로 결함이 수정되거나 수동 테스트가 끝나는 것은 아니다.

먼저 도구가 자기 서비스의 진입점을 읽는지 본다

명령 참조 문서의 routes는 인식한 화면·엔드포인트 등을, impact는 파일과 연결된 진입점을 보여준다. 도입 검토는 이 목록이 실제 서비스 구조와 맞는지 보는 데서 시작할 수 있다. Node.js 22 이상과 Git이 필요하며, Go·Python 프로젝트에는 해당 언어 도구도 필요하다.

실행 중 만드는 경로나 동적으로 찾는 호출은 정적 분석의 한계에 걸린다. 지원 언어라는 이유만으로 모든 프레임워크 구성을 읽는다고 기대할 수는 없다. 프로젝트는 읽지 못한 구성을 unknown으로 처리하는 방식을 설명한다.

보안 설계는 분석 대상 코드를 실행하지 않는 구조와, 테스트 작업·댓글 작성 작업의 분리를 명시한다. 명령별 역할도 다르다. analyze는 네트워크를 쓰지 않지만 comment는 GitHub API, 선택 기능인 usage는 Datadog API를 이용한다.

자주 묻는 질문

Farol의 활용 지점은 승인자가 먼저 읽을 코드와 확인할 기능을 좁히는 데 있다. 점수 옆의 근거와 분석하지 못한 부분까지 읽어야 검토 순서를 제대로 정할 수 있다.