post-merge-regression-guard

name

post-merge-regression-guard

description

git merge나 rebase가 끝나는 순간 스모크 테스트를 자동으로 돌려, 브랜치를 합치면서 생긴 통합 회귀(integration regression)를 새 작업으로 넘어가기 전에 즉시 잡아내는 훅(hook) 기반 루프입니다. 사용자가 "머지하고 나면 스모크 테스트 자동으로 돌려줘", "rebase 직후 회귀 검사", "브랜치 합친 다음 깨진 데 없는지 바로 확인", "머지 후 통합 회귀 가드", "post-merge regression guard", "run smoke tests after every merge", "catch integration regressions after rebase"처럼 머지·rebase 직후 회귀 가드를 걸고 싶을 때 사용하세요. 이벤트 기반이라 Claude Code에서는 hooks 설정이 필요합니다. (구분: 파일 편집 직후 연관 테스트는 looping:post-edit-test-guard, 커밋 직전 차단은 looping:pre-commit-guard, 머지 중 충돌을 파일별로 푸는 건 looping:merge-conflict-resolver, 배포된 스테이징에 스모크를 돌리는 건 looping:staging-smoke-test)

머지 후 회귀 가드 (Post-Merge Regression Guard)

git merge·rebase 직후 스모크 테스트를 돌려 통합 회귀를 즉시 잡아내는 훅 기반 루프.

항목	값
카테고리	테스트(Testing)
트리거	이벤트(event) — git_merge(git merge 또는 rebase 완료) 발생 시
종료 조건(Exit)	머지·rebase 직후 스모크 스위트가 종료 코드 0
매 반복 체크 명령	npm run test:smoke
설치 파일	있음 — 훅 설정 필요
가드레일	강화됨(Hardened)
지원 에이전트	Claude Code · Cursor

이 루프는 언제 쓰나

여러 브랜치를 자주 합치는 상황에서 씁니다. 각자 따로 보면 다 통과하던 코드가 막상 합쳐 놓으면 서로 맞물려 깨지는 일이 잦은데(통합 회귀), 이걸 한참 뒤에야 발견하면 원인을 추적하기 어렵습니다. 이 루프는 git merge나 rebase가 끝나는 순간 빠른 스모크 스위트만 자동으로 돌려, "방금 합친 것 때문에 뭔가 깨졌나?"를 그 자리에서 답합니다. 실패가 나오면 새 기능 작업을 시작하기 전에 먼저 고치도록 유도합니다. 전체 스위트가 아니라 핵심 흐름만 빠르게 확인하므로 머지 직후의 부담이 작습니다.

루프 흐름

〔git merge/rebase 완료 시〕→ 머지 감지 → 스모크 스위트 실행 →〔피드백 게이트〕
   스모크 테스트 통과? → 아니오: 새 작업 전에 회귀 수정 / 예: 종료(계속 진행)

매 반복(pass)마다 하는 일

1. 머지 감지(Detect merge) — 머지나 rebase가 방금 완료됐는지 확인합니다. diff stat에서 영향받은 영역을 파악합니다.
2. 스모크 스위트 실행(Run smoke suite) — 빠른 스모크 테스트 스위트를 돌립니다. 새 기능 작업을 시작하기 전에 실패를 먼저 고칩니다.

   npm run test:smoke
   

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

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

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

Claude Code에서 실행하기

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

방법 1 — 프롬프트만으로(설정 없이) 가드 켜기 아래를 붙여넣으면, 이번 세션 동안 에이전트가 머지나 rebase를 한 직후 스스로 스모크 테스트를 돌립니다.

"머지 후 회귀 가드(Post-Merge Regression Guard)" 루프를 설치하고 시작합니다.

목표: 머지나 rebase 직후마다 스모크 테스트가 통과한다.
매 반복 사이 실행: npm run test:smoke
종료 조건: 스모크 스위트가 종료 코드 0일 때.

1단계: 머지 후 스모크 테스트를 돌린다. 다른 작업을 계속하기 전에 회귀를 고친다.

방법 2 — .claude/settings.json 훅으로 영구 자동화 (권장) 에이전트가 Bash로 git merge/git rebase를 실행한 직후, 그 명령을 감지해 자동으로 스모크 테스트가 돌도록 PostToolUse 훅을 등록합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.command' | grep -qE 'git (merge|rebase)' && npm run test:smoke 2>&1 | tail -40" }
        ]
      }
    ]
  }
}

저장 후 Claude Code 세션을 재시작하면 훅이 등록됩니다. jq로 방금 실행한 Bash 명령을 읽어 git merge/git rebase일 때만 스모크 스위트를 돌립니다. 훅 출력(테스트 실패)이 에이전트에게 전달되므로, 위 kickoff를 한 번 붙여넣어 "실패하면 새 작업 전에 고친다"는 규칙을 알려 두면 됩니다.

참고: 훅은 "언제 깨어날지"(머지/rebase 직후)를 자동화하고, kickoff는 "매 회차 무엇을 할지"(스모크 돌리고 회귀 수정)를 정의합니다. 둘은 보완 관계입니다.

팁 / 변형

• 스모크 명령 교체: npm run test:smoke는 예시입니다. 프로젝트 스모크 명령으로 바꾸세요 — pytest -m smoke, go test ./... -run Smoke, npm run e2e:smoke, pnpm test:smoke 등.
• 트리거 넓히기: git pull(내부적으로 머지 발생)까지 잡고 싶으면 grep 패턴을 git (merge|rebase|pull)로 확장하세요.
• 막힐 때: 같은 실패가 2회 반복되면 가드레일대로 멈추고, 원인 가설과 함께 사람에게 보고하게 하세요. 머지 충돌 자체를 풀어야 한다면 looping:merge-conflict-resolver로 넘기는 게 맞습니다.
• 연관 루프: 파일 편집 직후 연관 테스트는 looping:post-edit-test-guard, 커밋 직전 차단은 looping:pre-commit-guard, 머지 중 충돌 해소는 looping:merge-conflict-resolver.

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

Install and run the "Post-Merge Regression Guard" loop.

Goal: smoke tests pass immediately after every merge or rebase.
Between iterations run: npm run test:smoke
Exit when: smoke suite exits 0.

Step 1: After a merge, run smoke tests. Fix regressions before continuing other work.

출처: https://loops.elorm.xyz/loops/post-merge-regression-guard