이 글은 PyCon Korea 2025에서 진행된 <더 나은 내일을 위한 pre-commit> 세션을 정리한 내용입니다. 이번 글에서는 pre-commit이 무엇이며, 어떤 문제를 해결할 수 있는지, 발표자가 직접 경험한 활용 사례를 함께 소개합니다. 발표 자료는 PyCon Korea 2025 공식 홈페이지에서 확인할 수 있으며, 추후 파이콘 한국 유튜브 채널을 통해 영상으로도 만나보실 수 있습니다.

더 나은 내일을 위한 pre-commit
김수빈 당근마켓 백엔드 개발자

혹시 코드 리뷰에서 포맷팅이나 린터 오류를 반복해서 지적받은 경험이 있으신가요? 혹은 팀원마다 개발 환경(IDE) 설정이 달라, 코드 스타일이 제각각이라 고민해 보신 적이 있나요? 이번 글에서는 개발자들이 흔히 겪는 문제를 해결할 수 있는 ‘pre-commit 도구’에 대해 자세히 살펴보겠습니다.

‘pre-commit’이 뭔데요?

1) 우리가 겪는 일상적인 문제들

우선 pre-commit을 살펴보기 전에 우리가 어떤 문제에 놓여있는지 짚어보고 가겟습니다. 우리는 개발 과정에서 코드 품질을 유지하기 위해 많은 노력들을 합니다. IDE에서 린터(Linter)와 포매터(Formatter)를 설정하고, 타입 검사를 실행하고, 테스트하고, 코드 컨벤션을 지키기 위해 노력하죠. 하지만 이런 과정에서 여러 문제가 발생합니다.

개발을 하다 보면, 커밋하기 전에 매번 린터와 포매터를 수동으로 실행해야 하는 번거로움이 있는데요. 이때 터미널에서 ruff check --fix . 명령어를 실행하고, 이어서 ruff format .을 실행하고, 또 다른 검증 도구들을 하나씩 실행하는 과정은 단순하지만 반복적입니다. IDE가 어느 정도 도움을 주지만, IDE에만 의존하다 보면 수정하지 않은 다른 파일에서 발생한 오류를 놓치는 경우도 있습니다.

코드 리뷰 과정에서도 비슷한 문제가 발생합니다. 리뷰어는 코드 컨벤션이나, 스타일 문제를 지적하느라 시간을 소모하는데, 정작 중요한 비즈니스 로직이나 설계 문제에 대한 검토는 상대적으로 소홀해지기 쉽습니다. 팀원마다 사용하는 IDE가 다르고 설정도 제각각이라면, 이러한 문제는 더욱 심각해집니다. 매번 "여기 들여쓰기가 잘못되었네요.", "import 순서를 정리해 주세요." 같은 코멘트를 남기고 받는 것은 개발자와 리뷰어 모두에게 피로감을 주기 때문이죠.

2) pre-commit이란 무엇인가

그렇다면 pre-commit은 무엇일까요? 바로 이러한 문제들을 해결하기 위해 만들어진 깃 훅(Git Hook) 관리 도구입니다. 깃은 원래부터 훅이라는 기능을 제공하여 커밋, 푸시 등의 이벤트가 발생할 때 특정 스크립트를 실행할 수 있도록 지원하고 있습니다. 하지만 이를 직접 설정하고 관리하는 것은 꽤 복잡한 작업인데요. pre-commit은 이 과정을 단순화하여 하나의 YAML 파일로 관리할 수 있게 해줍니다.

Python 개발 환경에서 자주 사용되는 ruff, black, flake8, isort 같은 도구들을 커밋 시점에 자동으로 실행하도록 설정할 수 있습니다. 코드가 정해진 규칙을 위반하면 커밋이 차단되기 때문에, 개발자는 바로 문제를 확인하여 수정할 수 있습니다.

또 일부 도구들은 실행 중에 코드를 자동으로 수정할 수도 있는데요. 린터나 포매터가 코드를 수정하는 경우, pre-commit은 파일이 변경되었음을 감지하고 커밋을 중단합니다. 개발자는 변경된 내용을 확인한 후 다시 커밋하면 됩니다.

설정 방법도 매우 간단합니다. 프로젝트 루트에 .pre-commit-config.yaml 파일을 만들고, 사용하고 싶은 훅들을 나열하기만 하면 됩니다. 설정은 깃허브 저장소 주소(repo)와 버전(rev), 훅 아이디(hooks id)로 구성됩니다. pre-commit은 이 정보를 바탕으로 필요한 도구들을 자동으로 다운로드하여, 격리된 환경에서 실행해 주므로 개발자가 직접 각 도구를 설치하거나 관리할 필요가 없습니다.

3) 다른 깃 훅 도구들과의 비교

파이썬 생태계에는 pre-commit 외에도 몇 가지 깃 훅 관리 도구들이 있습니다. autohooks는 현재 파이썬 가상 환경(venv)을 활용하는 것이 특징인 도구입니다. 파이썬으로 구현된 플러그인을 사용할 수 있죠. 예를 들어, ruff를 사용하려면 autohooks-plugin-ruff 패키지를, black을 사용하려면 해당 플러그인 패키지를 함께 설치해야 합니다. 직관적으로 현재 프로젝트의 의존성들을 함께 활용할 수 있지만, 사용 가능한 플러그인 개수가 다소 제한적인 편입니다.

lefthook은 고(Go) 언어로 작성되어 더 나은 성능을 제공하고, 더 자유롭게 구성할 수 있습니다. 하지만 사용하려는 의존성들이 모두 환경에 미리 설치되어 있어야 한다는 제약이 있습니다. 각 도구마다 장단점이 있지만, pre-commit이 파이썬 생태계에서 자주 사용되는 이유는 간편한 설정과 풍부한 훅 생태계 때문입니다.

pre-commit을 쓰며 느낀 점들

1) 개발 문화의 변화

pre-commit을 도입하고 가장 먼저 느낀 변화는 코드 컨벤션을 일일이 신경 쓸 필요가 없다는 점이었습니다. 코드를 작성한 뒤 커밋하려 할 때, pre-commit이 미리 설정된 규칙에 따라, 린터와 포매터를 자동으로 실행해 검사하고 수정해 줍니다. 덕분에 잘못된 스타일의 코드가 커밋되거나, 푸시되는 일이 없어졌습니다.

코드 리뷰 문화도 크게 달라졌습니다. 스타일이나 포맷팅 문제를 발견하고 피드백할 필요가 없어지면서, 리뷰어는 로직의 정확성이나 성능, 설계 구조, 오류 같은 더 중요한 부분에 집중할 수 있게 되었죠. 또한 pre-commit에 테스트 실행이나 커버리지 검증까지 포함하면, 테스트 케이스가 깨지지 않도록 더욱 체계적으로 관리할 수 있습니다.

2) 시프트 레프트, 문제를 더 빠르게 발견하기

시프트 레프트(Shift Left)는 소프트웨어 개발에서 문제를 가능한 한 초기 단계에서 발견하고 해결하자는 철학인데요. 전통적으로 품질 검증은 개발 프로세스 후반부에 집중되어 있었는데, 이를 앞당기면 훨씬 효율적이라는 개념입니다.

실제로 배포 후에 오류를 발견해 수정하는 것보다, 풀 리퀘스트(PR) 단계에서 코드 리뷰로 확인하는 편이 낫습니다. 하지만 그보다 더 좋은 방법은 지속적 통합(CI) 과정에서 몇 분 안에 문제를 발견하는 것이죠. 그리고 가장 이상적인 시점은, 커밋하기 전 로컬 환경에서 몇 초 만에 오류를 바로 확인하는 겁니다. pre-commit은 바로 이 지점, 가장 빠르게 문제를 발견하고 예방할 수 있게 해주는 도구입니다.

이처럼 빠른 피드백 루프는 개발 생산성을 크게 높여줍니다. 문제를 발견하는 시점이 빨라질수록 수정 비용은 기하급수적으로 줄어들고, 개발자는 컨텍스트를 잃기 전에 즉시 문제를 해결할 수 있기 때문이죠.

3) AI 시대의 pre-commit

최근에는 AI를 활용한 개발이 빠르게 늘고 있는데요. AI 에이전트에 프롬프트로 각 단위 작업을 처리하고 커밋하도록 지시할 때, 종종 린터나 포매터 실행이 누락되는 경우가 있습니다. 이처럼 코드 컨벤션이나 스타일 가이드를 따르지 않는 코드가 늘어나면, 전체 코드의 가독성과 유지보수성이 급격히 떨어집니다. 또한 AI 에이전트는 이미 작성된 코드를 참고해 새로운 코드를 생성하거나 수정하기 때문에, 컨벤션에서 벗어난 코드가 많아질수록 그 비율이 더욱 빠르게 증가합니다.

이때 pre-commit이 설정되어 있다면, AI가 생성한 코드도 커밋 과정에서 자동으로 검증됩니다. 규칙에 맞지 않는 코드는 커밋이 실패하고, 재시도를 거치며 자연스럽게 팀의 코드 컨벤션을 따르게 되는 구조죠. AI를 활용한 개발에서도 일관된 코드 품질을 유지하는 건 여전히 중요한데요. 이런 측면에서도 pre-commit은 AI 시대의 개발 프로세스에 꼭 필요한 도구라고 할 수 있습니다.

4) CI와의 통합

그러나 아무리 pre-commit을 잘 설정해도, 모든 개발자가 로컬에서 이를 실행한다고 보장할 수는 없습니다. 예를 들어, 오픈소스 프로젝트에 기여하는 외부 개발자나, 신규 입사자가 아직 pre-commit 설정을 완료하지 않은 상태에서 코드를 제출할 수도 있죠. 또는 급한 수정이 필요할 때, --no-verify 옵션을 사용해 훅 실행을 우회하는 경우도 있습니다.

이런 상황을 대비해, CI 파이프라인에서도 pre-commit을 함께 실행하는 것이 좋습니다. 다만 pre-commit 설정과 CI 환경에서 ruff, black, 테스트 케이스 등의 검증을 각각 따로 설정하게 되면, 두 벌의 의존성과 스크립트를 관리해야 하는 번거로움이 있습니다. 검증 결과가 불일치하는 문제가 발생할 수도 있고요.

이때 깃허브 액션(GitHub Actions)을 사용하면, pre-commit 공식 액션을 추가하는 것만으로 간단히 해결할 수 있습니다. 로컬과 동일한 검증이 CI에서도 수행되므로, 설정 누락이나 우회로 인한 문제를 방지할 수 있죠.

더 간편한 방법을 원한다면 pre-commit.ci 서비스를 사용할 수도 있습니다. 깃허브 앱만 설치하면 자동으로 저장소의 pre-commit 설정 파일을 읽어 실행하고, 훅 버전을 주기적으로 확인하여 최신 버전으로 업데이트하는 PR도 자동으로 생성해 줍니다. 다만 공개 저장소에만 무료로 제공되어, 공개 저장소 아닌 경우 유료 구독이 필요합니다.

pre-commit의 풍부한 생태계

1) 다양한 훅

pre-commit의 또 다른 강점은 풍부한 생태계입니다. 공식 훅 저장소인 pre-commit/pre-commit-hooks 저장소에는 문자 끝 공백 문자를 제거하거나 파일 끝 개행 문자를 추가하는 것과 같이 사소하지만 유용한, 다양한 훅들이 제공됩니다. black, ruff, flake8 같은 파이썬 린터와 포매터는 물론, 다양한 JSON, YAML 파일들의 스키마 검증 도구들도 있습니다.

아래는 제가 즐겨 사용하는 훅 저장소들입니다.

pre-commit/pre-commit-hooks
psf/black
astral-sh/ruff-pre-commit
PyCQA/flake8
python-jsonschema/check-jsonschema

2) 다양한 생태계

러스트(Rust)로 작성된 빠른 파이썬 패키지 매니저인 uv와의 통합도 지원됩니다. pre-commit-uv를 사용하면 훅과 의존성들을 설치하는 속도가 더 빨라지고, action-pre-commit-uv를 사용하면 pre-commit이 CI로 실행될 때 GitHub Actions에서 설치하는 속도도 크게 개선할 수 있습니다.

<출처: https://github.com/tox-dev/pre-commit-uv>

닉스(Nix) 사용자를 위한 통합도 제공됩니다. git-hooks.nix를 사용하면 닉스의 패키지 레지스트리를 통해 의존성을 관리하고, 더욱 선언적이고 결정론적인 방식으로 pre-commit 설정 및 훅 버전들을 간편히 구성할 수 있습니다. 재현 가능한 개발 환경을 구축할 때 유용합니다.

3) 직접 만든 훅

필요하다면 직접 pre-commit 훅을 만들어서 사용할 수도 있습니다. 꼭 코드 컨벤션을 위해서만 사용할 수 있는 것은 아닙니다. 저는 이미지 파일을 커밋할 때 자동으로 이미지를 압축하거나 형식을 최적화하고, 이를 통해 사용자들이 더 빠르게 이미지를 조회하고, 저장소를 체크아웃(checkout)하여 기여할 수 있도록 pre-commit-image를 만들었습니다.

<출처: https://github.com/sudosubin/pre-commit-image>

pre-commit-image 훅은 현재 github.com/sudosubin/awesome-communities 프로젝트에서 사용되고 있습니다. 해당 저장소에서는 다양한 이미지 파일들을 포함하고 있는데요. 이미지 파일들을 커밋하기 전, 자동으로 최적의 이미지 크기와 형식(avif)으로 압축 및 변환하고 있습니다.

마치며

지금까지 pre-commit에 대해 살펴봤습니다. 처음 pre-commit을 도입할 때는 점진적인 접근이 중요합니다. 처음부터 모든 규칙을 엄격하게 적용하면 부담이 될 수도 있어서, 간단한 규칙과 훅부터 하나씩 도입하며 시작하는 것이 좋습니다. 팀이 익숙해지면 린터와 포매터를 추가하고, 타입 체커나 테스트 실행과 같은 무거운 검증들을 하나씩 추가해 보세요. 이렇게 규칙을 강화해 나가는 방식으로 단계적으로 확장한다면, pre-commit을 처음 사용하는 사용자분들도 부담 없이 사용할 수 있습니다. 각 규칙과 훅을 도입하게 된 이유를 정리하여 소개하는 것도 좋은 방법이고요.

pre-commit은 단순한 도구지만, 그 영향력은 결코 작지 않습니다. 오늘 잠깐의 시간을 투자해 프로젝트에 pre-commit을 설정한다면, 내일부터는 더 행복하게 개발할 수 있을 겁니다. 여러분의 프로젝트에도 작은 변화를 시작해 보면 어떨까요?