Python과 Git Hooks로 구축한 Pre-Push 코드 리뷰 에이전트

제가 아는 모든 개발자는 똑같은 저녁 의식을 가지고 있습니다. 자기 전에 코드를 푸시하고, 일어나면 CI 실패를 마주하며, 자정에 작성했던 코드를 디버깅하며 오전 시간을 보내는 것이죠.

만약 푸시하기 전에 에이전트가 이를 잡아낼 수 있다면 어떨까요? 단순한 린팅 (Linting)이 아니라, 실제 코드 리뷰를 말입니다. 로직을 읽고, 명백한 버그를 찾아내며, 테스트를 확인하고, 사람의 주의가 필요한 부분을 표시하는 것입니다.

이것이 제가 만든 것입니다. 어떻게 작동하는지 소개합니다.

에이전트가 실제로 하는 일

설정은 모든 푸시 시 실행되는 세 가지 단계로 구성됩니다:

1단계: 정적 분석 (Static analysis) -- 린터 (Linters), 타입 체커 (Type checkers), 복잡도 지표 (Complexity metrics)를 실행합니다. 팀의 표준을 위반하는 모든 사항을 표시합니다.

2단계: 로직 리뷰 (Logic review) -- 변경된 파일을 읽고 일반적인 실수 패턴을 찾습니다: 처리되지 않은 엣지 케이스 (Edge cases), 누락된 에러 핸들링 (Error handling), 잠재적인 널 역참조 (Null dereferences), 작동은 하지만 명백히 잘못된 로직 등입니다.

3단계: 테스트 커버리지 확인 (Test coverage check) -- 변경된 코드에 상응하는 테스트가 있는지 확인합니다. 함수를 수정했는데 테스트를 수정하지 않았다면 이를 표시합니다.

에이전트는 승인하거나 차단하지 않습니다. 단지 의견(Comment)을 남길 뿐입니다. 무엇을 조치할지는 여러분이 결정합니다.

아키텍처

[git push]
    -> [pre-push hook]
    -> [에이전트가 변경된 파일 리뷰]
...

Pre-push hook은 코드가 원격 저장소로 넘어가기 전에 로컬에서 에이전트를 실행합니다. 출력값은 구조화된 보고서 형태로 제공되며, hook을 통해 GitHub에 게시하거나, 파일로 저장하거나, Slack으로 보낼 수 있습니다.

1단계: 정적 분석 (Static Analysis)

이 단계는 매우 빠릅니다. 대부분의 코드베이스에서 10초 미만이 소요됩니다. 만약 여기서 실패하면 hook이 실패하며 아무것도 원격으로 전송되지 않습니다.

#!/usr/bin/env python3
# stage1_static.py - 린터를 실행하고 이슈를 수집합니다
import subprocess
...

2단계: 로직 리뷰 (Logic Review)

여기서부터 흥미로워집니다. 정적 분석은 스타일 문제를 잡아냅니다. 로직 리뷰는 린터를 통과하지만 여전히 잘못된 실수들을 잡아냅니다.

#!/usr/bin/env python3
# stage2_logic.py - 변경된 코드를 읽고 로직 이슈를 표시합니다
import subprocess
...

버그 패턴은 시작점일 뿐입니다. 진정한 가치는 이를 여러분의 코드베이스에 맞게 조정하는 데서 옵니다. 즉, 여러분만의 특정 안티 패턴 (anti-patterns), 팀의 컨벤션 (conventions), 그리고 반복적으로 저지르는 실수들에 대한 체크를 추가하는 것입니다.

Stage 3: 테스트 커버리지 체크 (Test Coverage Check)

#!/usr/bin/env python3
# stage3_tests.py - 변경된 코드에 테스트 커버리지가 있는지 확인합니다
import subprocess
...

pre-push 훅 (The pre-push hook)

#!/bin/bash
# .git/hooks/pre-push

...

실행 권한을 부여합니다:

chmod +x .git/hooks/pre-push

실제로 얻게 되는 것

푸시(push)를 하면 터미널에 구조화된 보고서가 나타나고, /tmp/ 디렉토리에 보고서가 저장됩니다. 팀 단위로 사용한다면, 이 보고서를 PR (Pull Request) 코멘트로 게시하거나 Slack 메시지로 보내도록 확장할 수 있습니다.

핵심 통찰: 에이전트는 코드에 대해 똑똑해지려고 노력하는 것이 아니라, 팀이 결정한 일관된 규칙을 적용합니다. 바로 그것이 심야에 발생하는 버그를 잡아냅니다. 지능이 아니라, 바로 규율 (discipline)입니다.

확장하기

이 패턴 — 3단계 구성, 구조화된 출력, 결정을 위한 인간의 개입 (human in the loop) — 은 거의 모든 코드 품질 체크에 적용 가능합니다:

• 보안 스캐닝 단계 추가 (Bandit, Semgrep 규칙)
• 의존성 체크 추가 (새로운 간접 의존성 (transitive deps)을 가져오고 있지는 않은가?)
• 성능 단계 추가 (이 루프가 규모가 커졌을 때 문제가 되지 않을까?)

아키텍처는 동일하게 유지됩니다. 여러분은 그저 더 많은 단계를 추가하기만 하면 됩니다.

이 설정은 저의 개인 코드베이스에서 실행됩니다. 더 많은 에이전트 패턴은 https://thesolai.github.io에서 확인하세요.