커밋 전에 검사해야 하는 이유

린트 오류, 포맷 불일치, 타입 오류를 코드 리뷰나 CI 단계에서 처음 발견하면 수정 비용이 커집니다. 개발자는 브랜치를 전환한 뒤 다시 수정하고, CI 대기 시간을 반복하며, 리뷰어는 기능과 무관한 변경까지 확인해야 합니다. Git pre-commit 훅은 커밋 직전에 정해진 검사를 실행해 이런 기본 오류가 저장소에 들어가기 전에 막는 장치입니다.

다만 모든 검사를 훅에 넣으면 커밋이 느려져 개발자가 우회 옵션을 사용하게 됩니다. 핵심은 빠르고 결정적인 검사만 pre-commit에 배치하고, 전체 테스트·빌드·통합 테스트는 CI로 분리하는 것입니다. JavaScript와 TypeScript 프로젝트에서는 Husky가 Git 훅 설치를 담당하고, lint-staged가 이번 커밋에 포함된 파일만 골라 검사하도록 해 실용적인 실행 시간을 유지합니다.

적용 범위 먼저 정하기

pre-commit에는 보통 ESLint 검사, Prettier 포맷 적용, TypeScript의 가벼운 확인처럼 수 초 안에 끝나는 작업을 둡니다. 반면 외부 서비스가 필요한 테스트, 데이터베이스 마이그레이션, 전체 의존성 설치, 프로덕션 번들은 CI에서 실행합니다. 훅이 네트워크나 개발자 PC의 특정 상태에 의존하면 같은 커밋이 사람마다 다르게 실패할 수 있으므로 피해야 합니다.

  • 자동 수정 가능: Prettier, ESLint의 안전한 fix 규칙
  • 즉시 차단: 파싱 오류, 명백한 린트 오류, 비밀값 파일 추가
  • CI로 이동: 전체 단위 테스트, E2E 테스트, 전체 빌드와 보안 스캔

Husky와 lint-staged 설치

npm 기반 프로젝트라면 개발 의존성을 설치하고 prepare 스크립트로 훅 디렉터리를 초기화합니다. 팀원이 저장소를 새로 내려받아 npm install을 실행해도 훅이 설치되도록 package.json에 준비 작업을 남기는 방식입니다.

npm install -D husky lint-staged eslint prettier
npm pkg set scripts.prepare="husky"
npx husky init

생성된 .husky/pre-commit 파일에는 lint-staged 명령만 둡니다. Git 훅은 셸 환경에서 실행되므로 복잡한 로직, 환경별 분기, 긴 명령을 파일에 직접 쌓지 않는 편이 유지보수에 유리합니다. 검사 정책은 package.json 또는 별도 설정 파일에서 관리합니다.

#!/usr/bin/env sh
npx lint-staged

변경된 파일만 검사하는 설정

다음 예시는 JavaScript·TypeScript 파일에는 ESLint 자동 수정 후 포맷 검사를 실행하고, JSON·CSS·Markdown 파일에는 포맷만 적용합니다. lint-staged는 스테이지에 올라간 파일 목록을 각 명령에 전달하고, 수정된 결과도 다시 스테이지에 반영합니다. 따라서 이미 커밋 대상으로 선택한 파일만 다루며 작업 디렉터리 전체를 불필요하게 바꾸지 않습니다.

{ "lint-staged": { "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"], "*.{json,css,md,yml,yaml}": "prettier --write" } }

설정 후에는 의도적으로 포맷이 어긋난 파일을 git add 한 뒤 git commit으로 동작을 확인합니다. 훅이 수정한 파일이 커밋에 포함되는지, ESLint 오류가 있을 때 커밋이 중단되는지, 다른 파일은 건드리지 않는지를 확인해야 합니다. CI에서도 같은 ESLint와 Prettier 검사 명령을 실행해 로컬 훅을 건너뛴 커밋이나 웹 편집 커밋을 방어합니다.

실패를 줄이는 운영 기준

자동 수정 규칙은 코드 의미를 바꾸지 않는 범위로 시작하는 것이 안전합니다. 예를 들어 import 정렬이나 위험한 리팩터링을 자동 수정으로 도입하기 전에는 기존 코드 전체에 한 번 적용해 대규모 diff를 별도 커밋으로 분리합니다. 훅 오류 메시지에는 실행할 수 있는 복구 명령을 남기고, Node 버전은 .nvmrc나 package.json의 engines로 통일합니다. Windows, macOS, Linux 개발 환경에서 줄바꿈과 셸 호환성도 함께 검증해야 합니다.

긴급 상황의 --no-verify 사용은 가능하지만 표준 절차가 되어서는 안 됩니다. 사용 이유를 PR에 남기고 CI가 동일한 품질 기준을 반드시 검사하도록 구성하면 우회가 곧바로 배포 위험으로 이어지지 않습니다. 커밋 훅은 보안의 유일한 경계가 아니라 빠른 피드백 계층이라는 점도 중요합니다.

도입 체크리스트

  • pre-commit 작업은 일반적인 변경에서 수 초 내에 끝나는가
  • 검사 대상은 스테이지된 파일로 제한되어 있는가
  • 자동 수정 후 변경 파일이 다시 스테이지되는가
  • CI가 훅과 같은 핵심 검사 규칙을 실행하는가
  • Node 버전과 오류 복구 방법을 저장소 문서에 명시했는가

빠른 로컬 검사와 신뢰할 수 있는 CI 검사를 분리하면, 커밋 품질을 높이면서도 개발 흐름을 방해하지 않는 자동화 기준을 만들 수 있습니다.