pre-commit-guard

name

pre-commit-guard

description

git commit 명령이 실행되려는 순간을 가로채, 커밋 전에 전체 테스트 스위트를 돌리고 실패하면(스위트가 빨가면) 커밋을 막아 깨진 코드가 히스토리에 들어가지 못하게 하는 훅(hook) 기반 루프입니다. 사용자가 "커밋 전에 테스트 돌려서 실패하면 막아줘", "깨진 채로 커밋 못 하게", "커밋 전 가드 걸어줘", "pre-commit 훅으로 테스트 강제", "pre-commit guard", "block commits when tests fail", "run tests before git commit"처럼 커밋 직전 차단 가드를 걸고 싶을 때 사용하세요. 이벤트 기반이라 Claude Code에서는 hooks 설정이 필요합니다. (구분: 편집할 때마다 연관 테스트는 looping:post-edit-test-guard, 머지·리베이스 직후 스모크는 looping:post-merge-regression-guard, 전체 스위트를 수동으로 green까지 돌리는 건 looping:test-until-green)

커밋 전 가드 (Pre-Commit Guard)

매 git commit 직전에 테스트를 돌려, 스위트가 빨가면(실패) 커밋을 막는 훅 기반 루프.

항목	값
카테고리	테스트(Testing)
트리거	이벤트(event) — git commit 명령 직전(커밋 의도 감지 시)
종료 조건(Exit)	매 커밋 직전 테스트가 종료 코드 0
매 반복 체크 명령	npm test
설치 파일	있음 — 훅 설정 필요
가드레일	강화됨(Hardened)
지원 에이전트	Claude Code · Cursor

이 루프는 언제 쓰나

테스트가 빨간 상태인데 무심코 git commit을 날려 깨진 코드가 히스토리에 들어가는 일을 막고 싶을 때 씁니다. 커밋이 일어나려는 바로 그 순간을 가로채 먼저 전체 스위트를 돌리고, 실패하면 커밋을 차단하고 고치게 만듭니다. CI가 빨개진 뒤에야 알아차리는 대신, 커밋 자체를 게이트로 삼아 문제를 한 단계 앞에서 잡습니다.

루프 흐름

〔git commit 직전〕→ 커밋 의도 감지 → 테스트 실행 →〔피드백 게이트〕
   테스트 통과? → 아니오: 실패 수정 후 재실행(커밋 차단) / 예: 커밋 허용

매 반복(pass)마다 하는 일

1. 커밋 의도 감지 — git commit 명령이 실행되려 하면 멈추고, 먼저 테스트 스위트를 돌립니다.
2. 테스트 실행 — 커밋을 진행시키기 전에 전체 테스트 스위트를 돌립니다.

   npm test
   

3. 차단 또는 허용 — 테스트가 실패하면 실패를 고치고 다시 돌립니다. 테스트가 통과할 때만 커밋을 허용합니다.

가드레일 (점수 조작 방지 규칙)

종료 조건을 "가짜로" 통과시키지 못하게 막는 규칙입니다. 반드시 지키세요.

• 체크 명령이나 종료 기준을 고쳐서 억지로 성공시키지 않는다.
• 체크를 건너뛰거나 비활성화·우회해서 종료 조건을 통과시키지 않는다.
• 여러 번 반복해도 막히면, 지표를 조작하지 말고 멈추고 블로커를 보고한다.
• 스위트를 통과시키려고 테스트를 약화·삭제·skip 하지 않는다.
• 진짜 단언(assertion)을 항상 통과하는 껍데기 테스트로 바꾸지 않는다.
• green으로 만들려고 테스트를 땜질하기보다 프로덕션 코드를 고치는 쪽을 택한다.

Claude Code에서 실행하기

이 루프는 이벤트(훅) 기반입니다. 원본 사이트는 .cursor/·.claude/ 훅 번들 zip을 제공하지만, Claude Code에서는 .claude/settings.json의 hooks로 직접 설정하는 것이 가장 깔끔합니다.

방법 1 — 프롬프트만으로(설정 없이) 가드 켜기 아래를 붙여넣으면, 이번 세션 동안 에이전트가 커밋하기 전에 스스로 테스트를 돌리고 실패하면 커밋을 멈춥니다.

"커밋 전 가드(Pre-Commit Guard)" 루프를 설치하고 시작합니다.

목표: 테스트가 실패하는 동안에는 git commit을 막는다.
매 반복 사이 실행: npm test
종료 조건: 매 커밋 직전 테스트가 종료 코드 0일 때.

1단계: 어떤 git commit이든 실행하기 전에 테스트를 돌린다. 실패가 있으면 커밋하기 전에 고친다.

방법 2 — .claude/settings.json 훅으로 영구 자동화 (권장) git commit을 실행하려는 Bash 호출을 PreToolUse로 가로채, 테스트가 빨가면 그 커밋을 막습니다(종료 코드 2로 차단하면 실패 출력이 에이전트에게 전달됩니다).

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "cmd=$(jq -r '.tool_input.command'); echo \"$cmd\" | grep -q 'git commit' || exit 0; npm test || { echo '테스트 실패 — 커밋을 막습니다. 먼저 고치세요.' >&2; exit 2; }"
          }
        ]
      }
    ]
  }
}

저장 후 Claude Code 세션을 재시작하면 훅이 등록됩니다. 커밋이 막혔다는 출력(테스트 실패)이 에이전트에게 전달되므로, 위 kickoff를 한 번 붙여넣어 "막히면 고친 뒤 다시 커밋한다"는 규칙을 알려 두면 됩니다.

참고: 훅은 "언제 깨어날지"(git commit 직전)를 자동화하고, kickoff는 "매 회차 무엇을 할지"를 정의합니다. 둘은 보완 관계입니다.

팁 / 변형

• 테스트 러너 교체: npm test는 예시입니다. pytest, go test ./..., cargo test, pnpm test 등 프로젝트에 맞게 바꾸세요.
• 네이티브 git 훅으로: 에이전트와 무관하게 모든 커밋을 막고 싶으면 .git/hooks/pre-commit(또는 husky의 pre-commit)에 npm test를 넣어 두는 방법도 있습니다. 단, --no-verify로 우회할 수 있으니 가드레일 정신에 맞게 우회하지 마세요.
• 막힐 때: 같은 실패가 반복되면 가드레일대로 멈추고, 원인 가설과 함께 사람에게 보고하게 하세요. 커밋을 통과시키려 테스트를 끄는 건 금지입니다.
• 연관 루프: 편집할 때마다 연관 테스트는 looping:post-edit-test-guard, 머지·리베이스 직후 스모크는 looping:post-merge-regression-guard, 전체 스위트를 수동으로 green까지는 looping:test-until-green.

원본 영어 kickoff (loops.elorm.xyz 원문)

Install and run the "Pre-Commit Guard" loop.

Goal: block git commits when tests are failing.
Between iterations run: npm test
Exit when: tests exit 0 before each commit.

Step 1: Before any git commit, run tests. Fix failures before committing.

출처: https://loops.elorm.xyz/loops/pre-commit-guard