[TIL][Claude Code] "이게 최선이야?" 를 자동으로 묻게 만들기

Claude Code 로 코드를 짜면 빠르다

근데 빠른 만큼 대충 끝내는 경우도 있다

"완료했습니다" 하고 보여주는데 보면 에러 처리가 빠져있거나, 실행도 안 해봤거나,.

그래서 "이게 최선이야?" 를 매번 물어봐야 했다

이걸 자동화했다

구조: 3중 게이트

코드 편집 (Edit/Write)
    ↓
[자동] post-edit-quality-check.sh → 파일별 셀프 리뷰 체크리스트
    ↓
"/quality_gate" 커맨드 실행
    ↓
[수동] quality_gate.md → 5단계 체계적 검증
    ↓
"완료했습니다" 보고 시도
    ↓
[자동] notification-quality-gate.sh → 최종 게이트

1차는 편집할 때마다 자동으로, 2차는 내가 직접 부를 때, 3차는 완료 보고할 때 자동으로 발동한다

1차: 편집 직후 — 파일별 맞춤 체크리스트

PostToolUse Hook 이 .py 파일 편집 후 자동으로 출력한다

Step 파일 수정했으면:

□ page.locator() 직접 사용하지 않았는가?
□ feature 텍스트와 정확히 일치하는가?
□ assert 에 의미 있는 메시지가 있는가?
□ 다른 시나리오에 영향을 주지 않는가?

Page Object 수정했으면:

□ browser_snapshot 으로 실제 UI 를 확인했는가?    ← 이게 1순위
□ locators 파일의 상수를 사용했는가?
□ XPath 를 쓰지 않았는가?
□ Strict Mode Violation 가능성은 없는가?
□ 엣지 케이스를 점검했는가?

파일 종류를 보고 다른 질문을 던진다

Step 파일에 "browser_snapshot 확인했는가?" 를 물어봤자 의미 없으니까

2차: /quality_gate 커맨드 — 5단계 검증

작업 중간에 "이 정도면 된 것 같은데?" 싶을 때 직접 실행한다

/quality_gate

Step 1: 변경 파일 확인

git diff --name-only
git diff --staged --name-only

뭘 바꿨는지 전체 목록을 본다

Step 2: 코드 품질 체크

변경된 파일마다 3가지 관점으로 확인한다

관점	체크 항목
구조적 품질	POM 패턴, 로케이터 중앙관리, XPath 미사용
코드 완성도	명시적 return, 구체적 예외 타입, 엣지 케이스
실행 가능성	즉시 실행 가능한가, 관련 검증이 있는가

Step 3: 검증 실행

pytest tests/step_definitions/ -v --tb=short -x

실패하면 원인 분석하고 수정까지 한다

Step 4: 개선점 도출

"사용자가 '이게 최선이야?' 라고 물어볼 부분이 있는가?"
"더 깔끔하게 작성할 수 있는 부분이 있는가?"
"생략한 것이 있는가?"

있으면 즉시 수정, 없으면 통과

Step 5: 결과 보고

✅ 품질 게이트 통과
- 변경 파일: 3개
- 검증 결과: PASS
- 개선 사항: 없음
- 종합 판단: 완료

3차: 완료 보고 직전 — Notification Hook

Claude 가 "완료했습니다" 라고 알림을 보내려는 그 순간 자동으로 발동한다

🚦 품질 게이트 — 보고 전 최종 확인:

🔴 필수:
  □ 코드가 즉시 실행 가능한가?
  □ pytest 를 실행했는가?
  □ 에러/경고가 없는가?

🟡 품질:
  □ 더 나은 방법이 있는데 귀찮아서 안 한 건 아닌가?
  □ 코드를 다시 읽고 개선점을 반영했는가?
  □ "이게 최선이야?" 라고 셀프 질문했는가?

settings.json 에서 Notification 이벤트에 걸었다

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/notification-quality-gate.sh" }
        ]
      }
    ]
  }
}

matcher 가 빈 문자열이면 모든 알림에 동작한다

왜 3중인가

게이트	시점	빠뜨리기 쉬운 것
1차 (편집 후)	코드 쓰는 중	로케이터 하드코딩, XPath
2차 (커맨드)	작업 중간 점검	전체적 구조, 검증 실행
3차 (완료 보고)	끝났다고 생각할 때	"진짜 실행해봤는가?"

1차만 있으면 전체 그림을 안 본다

3차만 있으면 이미 다 끝난 뒤라 고치기 귀찮다

중간중간 걸러야 마지막에 할 게 없다

🐣 만든 계기

3개월 동안 Claude Code 로 E2E 검증 코드를 만들었고,

커밋 348개, 그 중 Fix 가 102개다

Feat: 103개
Fix:  102개   ← 기능 추가만큼 버그 수정
Refactor: 77개

Fix 의 상당수가 처음에 꼼꼼히 했으면 안 났을 버그였다

• except Exception: pass 로 에러를 삼켜서 원인을 못 찾은 것
• 실행 안 해보고 "됐습니다" 한 것
• .first 빼먹어서 Strict Mode Violation 난 것

그래서 "완료" 라고 말하기 전에 자동으로 한 번 더 확인하게 만들었다

Quality Gate 도입 후 Fix 커밋 비율이 눈에 띄게 줄었다

사용법

# 수동 실행
# Claude Code 에서 "/quality_gate" 입력

# 자동 실행
# 코드 편집하면 1차 자동 발동
# "완료" 보고하면 3차 자동 발동

주의점

• Notification Hook 의 matcher 를 빈 문자열로 설정해야 모든 알림에 동작한다
• Quality Gate 가 너무 엄격하면 Claude 가 같은 코드를 계속 고치는 루프에 빠진다 — 차단(exit 2) 이 아닌 체크리스트(exit 0) 로 설계해야 한다
• /quality_gate 커맨드는 .claude/commands/quality_gate.md 파일이다