Pre-commit 훅

개요

pre-commit hook은 단순한 품질 도구가 아니다. AI 작업자 관점에서는 로컬에서 반복 가능한 작은 하네스에 가깝다.

commit 직전의 짧은 gate는 AI가 가장 자주 통과하려는 경계 중 하나이기 때문이다.

이 문서는 harness/ai 적용 레이어에서 로컬 gate를 어디에 둘지와 그 gate가 어떤 loop를 만드는지를 다룬다.

왜 pre-commit hook이 잘 맞는가

좋은 pre-commit gate는 다음 특징을 가진다.

• 로컬에서 바로 돌 수 있다
• 반복 비용이 낮다
• 결과가 비교적 안정적이다
• 바뀐 범위와 가깝다
• commit이라는 명확한 경계를 가진다

이런 조건은 AI가 같은 작업 루프 안에서 여러 번 활용하기에 적합하다.

어떤 훅이 좋은가

AI 작업자 하네스에 잘 맞는 훅은 보통 다음과 같다.

• 금지된 import / direct access 차단
• raw context / singleton / bypass helper 차단
• 포맷과 lint의 changed-files 검사
• 작은 analyzer 또는 static rule
• 빠른 단위 테스트 subset
• generated artifact drift 검사

공통점은 모두 빠르고 좁고 결정적이라는 점이다.

어떤 훅은 오히려 나쁜가

다음은 pre-commit에 올리기 쉽지만 종종 나쁘다.

• 너무 느린 통합 테스트
• flaky한 네트워크 의존 검사
• failure 원인이 모호한 대규모 빌드
• 인간 설명 없이는 해석하기 어려운 policy text

이런 훅은 AI에게 교정 루프를 제공하기보다, 그냥 commit 시도를 막는 큰 벽으로 느껴지기 쉽다.

pre-commit은 어디에 위치하는가

pre-commit은 전체 enforcement를 대체하지 않는다. 보통 다음 중간 층에 놓이는 것이 자연스럽다.

save-time signal
-> local command check
-> pre-commit hook
-> CI / branch gate

즉 pre-commit은 가장 첫 gate는 아니지만, AI가 반복적으로 통과하는 현실적인 boundary로서 가치가 크다.

hook 설계 시 중요한 점

출력이 machine-readable해야 한다

AI가 훅 실패를 보고 바로 수정하려면 rule id, 위치, 대안이 드러나야 한다.

훅은 canonical path를 강화해야 한다

단순히 금지 목록만 늘리면 안 된다. 대신 무엇을 써야 하는지 같이 보여줘야 한다.

changed scope에 가깝게 유지해야 한다

AI는 가까운 범위에서 빨리 수렴할 때 가장 안정적이다. 훅이 매번 전체 저장소를 흔들면 loop 품질이 떨어진다.

AI 코딩에서 더 도드라지는 이유

사람은 훅을 귀찮아하면서도 문맥으로 보완할 수 있다. AI는 훅 결과가 곧 가장 가까운 규칙 신호가 된다.

그래서 좋은 pre-commit hook은 AI에게 규칙을 설명하는 문서보다 더 직접적인 하네스가 된다.

실무 질문

• 이 훅은 로컬에서 반복 실행하기 충분히 싼가
• failure output만 보고 수정 방향이 보이는가
• changed scope와 너무 멀리 떨어진 검사를 하지 않는가
• 금지만 말하지 않고 canonical path를 같이 보여주는가
• CI에서만 잡히는 규칙 중 더 앞당길 수 있는 것은 없는가

요약

좋은 pre-commit hook은 다음을 만족한다.

• 빠르고
• 좁고
• 결정적이며
• machine-readable하고
• canonical path를 강화한다

하네스의 AI 적용 관점에서 pre-commit hook은 사소한 자동화가 아니라, 가장 자주 통과하는 로컬 경계에 붙는 작은 enforcement다.