AI가 생성한 Pull Request를 승인하기 전 수행하는 5가지 빠른 체크리스트

고객 프로젝트 전반에서 AI가 생성한 Pull Request (PR)를 1년 동안 검토한 결과, 짧은 체크리스트가 만들어졌습니다. 다섯 가지 체크 항목이며, PR당 총 10분 정도 소요됩니다. 이 체크리스트는 그렇지 않았다면 운영 환경(Production)으로 유출되었을 버그의 상당 부분을 잡아냅니다.

이 포스트는 해당 체크리스트와 각 단계의 근거, 그리고 각 체크를 빠르게 만들어주는 도구들에 대해 다룹니다.

Photo by Tima Miroshnichenko on Pexels

이 체크리스트가 무엇이고 무엇이 아닌가

이것은 모든 AI 생성 PR에 실행되는 고효율 검토 단계입니다. 이것이 유일한 검토 단계는 아닙니다. 도메인 지식(Domain knowledge), 아키텍처 적합성(Architectural fit), 명명 규칙(Naming conventions), 보안 검토(Security review), 그리고 성능 특성(Performance characteristics)은 여전히 적용됩니다. 이 체크리스트는 검토 프로세스의 최전선에 위치하며, 전통적인 검토에서는 그럴듯해 보이기 때문에 때때로 놓칠 수 있는 AI 특유의 실패 모드(Failure modes)를 잡아냅니다.

아래의 다섯 가지 체크 항목은 무언가를 잡아냈을 때 절약되는 시간의 양에 따라 순서가 매겨져 있습니다. 목록의 앞쪽에 있을수록 버그가 더 자주 나타나며 검증 속도가 더 빠릅니다.

체크 1: 모든 임포트(Import)가 실제 존재하며 올바른 버전인지 확인

모든 임포트 문을 확인하십시오. 임포트된 각 모듈에 대해 다음을 수행합니다:

• 패키지가 존재하는지 확인합니다. Python의 경우 PyPI를, Node의 경우 npm registry를, Go의 경우 모듈 경로가 해결(Resolve)되는지 확인합니다.
• 프로젝트에 설치된 버전이 코드에서 호출하는 함수를 지원하는지 확인합니다. AI 어시스턴트는 종종 사용자가 설치한 버전과 다른 라이브러리의 메이저 버전(Major version)에 맞는 코드를 생성하곤 합니다.

이 과정은 환각 패키지(Hallucinated-package) 사례(패키지가 아예 존재하지 않는 경우)와 버전 불일치(Version-mismatch) 사례(패키지는 존재하지만 코드가 사용하는 API가 설치된 버전에는 없는 경우)를 잡아냅니다.

총 소요 시간: 일반적인 크기의 PR(Pull Request) 기준 2분 미만. 목록 중 가장 빠르게 얻을 수 있는 성과입니다.

체크 2: 모든 명명된 함수와 메서드가 실제로 존재하는지 확인

코드를 읽으면서 즉시 인식되지 않는 이름의 모든 함수 호출(function call) 또는 메서드 호출(method call)을 식별하십시오. 해당 라이브러리의 문서에서 이를 찾아보세요. 시그니처(Signature)가 코드에서 사용 중인 것과 일치하는지 확인하십시오.

이것이 임포트(Import) 확인과 별개의 체크 항목인 이유는, 임포트가 성공했다고 해서 임포트된 객체에서 호출하는 메서드가 반드시 존재한다는 의미는 아니기 때문입니다. 어시스턴트(Assistant)는 실제 클라이언트에는 client.refresh_token()만 있는데 client.refresh_token_safe()를 생성할 수 있습니다. 임포트는 작동하지만, 호출은 실패합니다.

Mozilla Developer Network는 JavaScript 및 웹 플랫폼 API(Web Platform APIs)를 위한 표준 참조 자료입니다. Python 표준 라이브러리 문서는 내장된 기능들을 다룹니다. 제3자 패키지(Third-party packages)의 경우, 해당 패키지 자체의 문서 사이트나 GitHub README가 신뢰할 수 있는 정보원(Source of truth)입니다.

총 소요 시간: 일반적인 PR 기준 3~5분.

체크 3: 프롬프트(Prompt)에서 언급되지 않은 예외 케이스(Edge cases)가 처리되었는지 확인

이것은 가장 오래 걸리는 체크 항목이지만, 구조적인 문제를 파악한 후에는 가장 가치 있는 작업입니다. 코드를 읽으며 다음과 같이 질문하십시오: 어떤 입력값이 이 코드를 망가뜨릴 것인가?

표준 목록:

• 빈 입력값 (빈 리스트, 빈 문자열, null/None)
• 단일 요소 컬렉션 (Single-element collections)
• 매우 큰 입력값
• 코드가 내부적으로 사용하는 구분자(Delimiter)를 포함하는 입력값
• 코드가 ASCII라고 가정하는 입력값 내의 유니코드(Unicode)
• 시간대(Time zone) 예외 케이스
• 코드가 순차적이라고 가정하는 동시적(Concurrent) 입력값

각 케이스를 머릿속으로 코드에 대입해 보십시오. 만약 특정 케이스가 처리되지 않았고 실제 데이터에 해당 케이스가 포함되어 있다면, 이를 재현하는 테스트를 작성하십시오. 테스트를 작성하면 버그가 구체화되며, 수정(Fix)을 위한 깔끔한 재현(Repro) 환경을 제공합니다.

이 단계는 또한 조용히 잘못된(silently-wrong) 케이스들을 잡아내는 지점이기도 합니다. 일광 절약 시간제(Daylight saving) 경계에서 깨지는 날짜 산술(Date arithmetic), 정확한 등호 비교에서 실패하는 부동 소수점 비교(Floating-point comparisons), 페이지네이션(Pagination)에서의 오프 바이 원(Off-by-one) 오류 등이 이에 해당합니다. AI가 생성한 코드는 해피 패스(Happy path)에서는 거의 항상 정확하지만, 엣지 케이스(Edge cases)에서는 사람이 작성한 코드보다 더 자주 조용히 망가집니다.

총 소요 시간: 일반적인 PR의 경우 5~10분. 리뷰 시간의 대부분을 차지합니다.

체크 4: 테스트가 가정이 아닌 실제 동작을 테스트하는가

만약 PR에 테스트가 포함되어 있다면(포함되어 있어야 합니다), 이를 주의 깊게 읽으십시오. 각 테스트에 대해 다음과 같이 질문하십시오: 만약 구현(Implementation)이 조용히 잘못되었다면, 이 테스트가 그것을 잡아낼 수 있는가?

주의해야 할 실패 모드(Failure mode): 코드를 실행하기는 하지만 결과에 대해 의미 있는 어설션(Assert)을 수행하지 않는 테스트입니다. 함수를 호출하고 예외(Exception)가 발생하지 않았는지 확인하는 테스트는 정확성(Correctness)에 대한 테스트가 아니라, "이것이 충돌(Crash)하지 않는다"는 것에 대한 테스트일 뿐입니다. 유용할 수는 있지만 제한적입니다.

또 다른 실패 모드: 구현의 현재(잘못된) 동작이 올바르다고 어설션하는 테스트입니다. 어시스턴트(Assistant)가 동일한 결함이 있는 가정(Flawed assumption)을 바탕으로 구현과 테스트를 모두 생성했기 때문에

AI가 생성한 PR(Pull Request)은 때때로 원래의 의도에서 벗어나기도 합니다. 어시스턴트(Assistant)가 50줄 정도면 충분했을 요청에 대해 200줄짜리 변경 사항을 만들어내기도 합니다. 혹은 변경 사항의 규모는 적절하지만, 설명(Description)에서 제안한 것과는 다른 파일들을 수정하기도 합니다.

차이점(Diff)에 포함된 각 파일에 대해 다음과 같이 질문하십시오. 이 파일이 설명에 언급되어 있는가? 그리고 해당 파일의 변경 사항이 설명에서 말하는 내용과 일치하는가? 만약 파일이 변경되었는데 설명에 언급되지 않았다면, 그 이유를 물으십시오. 때로는 "관련된 정리(Cleanup) 작업이었습니다"라는 답이 나올 수 있으며, 이는 괜찮습니다. 하지만 때로는 "어시스턴트가 요청하지 않은 무언가를 리팩터링(Refactor)하기로 결정했습니다"라는 답이 나올 수 있는데, 이는 주의 신호(Flag)입니다.

총 소요 시간: 대부분의 PR에 대해 1분 미만입니다.

요약

다섯 가지 체크리스트. 평균적인 규모의 AI 생성 PR에 대해 약 15분 정도 소요됩니다. 처음 두 가지 체크는 로직(Logic)을 고민하기도 전에 대부분의 구조적 문제를 잡아냅니다. 중간 단계는 대부분의 로직 버그(Logic bugs)를 잡아냅니다. 마지막 두 가지는 어시스턴트가 요청보다 더 많은 것을 생성하거나, 자신의 가정을 확인하는 테스트를 생성할 때 나타나는 판단 오류를 잡아냅니다.

PR이 반영(Land)된 후 운영 환경(Production)에서 버그가 발생했을 때 실행하는 전체 디버깅 워크플로우(Debugging workflow)에 대해서는, AI가 생성한 코드의 디버깅에 관한 137Foundry의 상세 가이드를 참조하십시오. 해당 가이드는 실패 모드(환각된 API(Hallucinated APIs), 엣지 케이스(Edge cases), 버전 불일치(Version mismatches), 조용히 잘못된 로직(Silently wrong logic))와 이를 확인해야 하는 순서를 다룹니다.

이러한 체크를 더 빠르게 만드는 도구들

리뷰 시간을 단축해 주는 몇 가지 특정 도구들:

• CI 단계에서의 패키지 존재 여부 확인 (A package-existence check as a CI step). 모든 PR(Pull Request)에서 pip install -r requirements.txt(또는 그에 상응하는 명령)를 실행하세요. 리뷰가 시작되기도 전에 환각(hallucination)된 패키지를 잡아낼 수 있습니다.
• 타입 체커 (A type checker). Python의 경우 Mypy, JavaScript의 경우 TypeScript, Go와 Rust의 강력한 타입 시스템(strong typing)을 활용하세요. 타입 오류(Type errors)는 잘못된 시그니처(wrong-signature) 문제를 자동으로 많이 잡아냅니다.
• 팀의 스타일에 맞춰 설정된 린터 (A linter configured with the team's style). 환각된 파라미터(parameter) 대부분은 린터 경고를 발생시킵니다. 깨끗한 린터 통과(linter pass)는 수동 리뷰의 부담을 줄여줍니다.
• 단언(assertion)이 없는 테스트에서 빌드를 실패시키는 테스트 러너 (A test runner that fails the build on tests with no assertions). "함수를 호출하기는 하지만 결과를 확인하지는 않는" 실패 모드(failure mode)를 포착합니다.

각 도구는 PR당 몇 분의 시간을 벌어다 줍니다. 어떤 도구도 인간의 리뷰를 대체할 수는 없지만, 인간의 리뷰가 실제로 판단이 필요한 부분에 집중할 수 있도록 만들어 줍니다.

팀 워크플로우(workflow)에 관한 참고 사항

AI 코딩 어시스턴트(AI coding assistant)를 도입하면 리뷰 부담의 형태가 변합니다. 이전에는 리뷰 시간의 대부분을 변경 사항을 이해하는 데 사용했습니다. 도입 후에는 변경 사항이 설명된 내용과 일치하는지, 그리고 구조적 요소들(import, 함수 호출, 파라미터)이 모두 실제 존재하는지 검증하는 데 리뷰 시간의 상당 부분을 사용하게 됩니다.

이는 다른 근육을 사용하는 것이며, 이를 발달시키는 데는 몇 주가 걸립니다. 137Foundry 팀은 고객 업무를 위해 약 1년 동안 이 체크리스트를 반복 개선해 왔으며, 그 형태는 위의 5가지 체크 항목을 중심으로 안정화되었습니다. 정확한 도구는 프로젝트마다 다르지만, 각 체크 항목을 신중하게 실행하는 규율은 변하지 않습니다.

AI 코딩 어시스턴트 도입을 위한 팀 관행에 대한 배경 지식으로는, GitHub의 코드 리뷰 내 AI에 관한 가이드라인과 OpenAI의 개발자 생산성에 관한 가이드라인에서 플랫폼들이 발표한 지침을 확인할 수 있습니다. 이 중 어떤 것도 신중한 체크리스트를 대체할 수는 없으며, 단지 보조 자료일 뿐입니다.

마치며

5가지 체크리스트, 15분, 코드가 반영되기 전에 AI가 생성한 버그의 대부분을 포착할 수 있습니다. 실행할 가치가 있습니다. 또한 여러분의 팀이 특정 스택에서 어떤 실패 모드 (failure modes)가 가장 자주 발생하는지 학습함에 따라, 이를 반복적으로 개선할 가치가 있습니다.

이 체크리스트가 효과적인 이유는 AI가 생성한 코드를 일반적인 코드와 동일하게 취급하는 대신, AI 특유의 실패 모드 (hallucination (환각), version drift (버전 드리프트), tautological tests (동의어 테스트))에 집중하기 때문입니다. 변화는 작지만, 결과는 상당합니다.