Delivery Gate — Claude Code를 위한 기계적 품질 게이트
Stop 후크로서, Claude가 세션을 종료하기 전에 결정론적 검사(파일 수정 타임스탬프, 디스크 사용량, 대화 텍스트의 정규식 패턴)만 사용하여 세 가지 사항을 확인합니다. AI 추론은 사용하지 않습니다.
이는 추론 게이트(예: self-audit)와 구별됩니다. delivery-gate는 기계가 확인 가능한 사실을 검사하고, self-audit은 네 가지 추론 차원에서 출력 품질을 검사합니다. 함께 사용하면 심층 방어를 구성합니다:
- delivery-gate: "오늘 학습 라이브러리를 수정했는가? 디스크 공간은 안전한가?"
- self-audit: "파일 내용이 정확하고, 완전하며, 정직한가?"
이는 CI 파이프라인 게이트와 동일한 패턴입니다. 자체 보고된 상태를 신뢰하는 대신 기계가 읽을 수 있는 사실을 자동으로 결정론적으로 검증합니다.
검사 항목
| 검사 | 메커니즘 | 적중 시 동작 |
|---|---|---|
| 합리화 패턴 | 대화 꼬리의 정규식 | 경고만 (차단하지 않음) |
| 오래된 학습 라이브러리 | 5개 설정 가능 경로의 mtime | 일부 오래됨: 경고; 3개 이상 오래됨 또는 복잡한 작업 + growth-log 오래됨: 차단 |
| 디스크 공간 < 50GB | shutil.disk_usage | 경고 |
| 디스크 공간 < 15GB | shutil.disk_usage | 차단 (exit 2) |
합리화 탐지는 "일단 테스트는 건너뛰자", "기존 버그" 같은 패턴을 감지하여 사고가 조기 종료되었을 가능성을 경고합니다. 정규식 휴리스틱은 오탐지(false positive) 가능성이 있으므로 자체적으로는 절대 차단하지 않습니다. 차단 조건은: 디스크 임계, >=3개의 학습 라이브러리 오래됨, 또는 growth-log가 특히 오래된 경우입니다(모두 복잡한 작업 >=3회 편집 필요).
이유
Claude Code의 내장 검사는 코드 품질(빌드 → 타입 → 린트 → 테스트)을 다룹니다. 하지만 다른 실패 유형이 있습니다: 에이전트가 동작하는 코드를 생성하면서도 세션 위생이 소홀해진 경우 — 학습이 캡처되지 않았고, 합리화된 단축키가 사용되었으며, 디스크가 조용히 가득 차는 경우입니다.
수많은 "배송 후 망각" 세션을 거치면서 인간은 성장하지 않습니다. 이 후크는 습관을 강제합니다: 복잡한 작업 → 반드시 학습 라이브러리를 수정해야 함.
설치
cp quality-gate.py ~/.claude/scripts/
~/.claude/settings.json에 추가:
{
"hooks": {
"Stop": [{
"hooks": [{
"type": "command",
"command": "python3 ~/.claude/scripts/quality-gate.py",
"timeout": 5000
}]
}]
}
}
학습 라이브러리
프로젝트의 memory 디렉토리에 다음 파일들을 생성하세요. 후크는 오늘 최소 하나가 업데이트되었는지 확인합니다:
memory/
├── growth-log/ # 일일 학습 항목 (디렉토리)
├── decisions/log.md # 결정 로그
├── output-index.md # 세션 출력 인덱스
├── ratings-tracker.md # 시간에 따른 스킬 평가
└── tooling_capabilities.md # 알려진 도구 목록
자신의 파일 구조에 맞게 LIBS 딕셔너리를 사용자 정의하세요.
설정
quality-gate.py를 편집하세요:
| 변수 | 기본값 | 용도 |
|---|---|---|
RATIONALIZE | 4개 패턴 | 합리화 탐지를 위한 정규식 패턴 |
LIBS | 5개 라이브러리 | 오늘 업데이트를 확인할 파일/디렉토리 |
COMPLEX_THRESHOLD | 3 | 복잡한 작업으로 분류할 Edit/Write 호출 횟수 |
DISK_WARN_GB | 50 | 이 미만이면 경고 |
DISK_CRIT_GB | 15 | 이 미만이면 차단 |
예시
단순 세션 — 허용:
edit_count=1 (< 3, 복잡하지 않음) → exit 0
복잡한 작업, 학습 캡처됨 — 허용:
edit_count=5 (복잡함) → LIBS 확인 → growth-log 오늘 업데이트됨 → exit 0
복잡한 작업, 학습 없음 — 차단됨:
edit_count=4 (복잡함) → LIBS 확인 → 5개 모두 오래됨 → exit 2
stderr: "차단됨: 복잡한 작업이 완료되었지만 오늘 학습이 캡처되지 않았습니다."
디스크 공간 부족 — 차단됨:
disk_free=12GB < 15GB 임계 → exit 2
stderr: "차단됨: 디스크 공간이 12GB입니다 (임계값: 15GB)."
제한 사항
이 후크는 학습 라이브러리를 수정하는 습관을 강제할 뿐, 기록된 내용의 품질은 강제하지 않습니다. output-index.md가 업데이트되었지만 growth-log가 건너뛰어지면 후크는 통과합니다(5개 중 1개 라이브러리 수정). 이는 의도된 설계입니다: 기계적 게이트는 기계가 확인 가능한 사실을 검사합니다. 내용 품질 검증을 위해서는 self-audit과 함께 사용하세요.
호환성
- Python 3.8+ (
from __future__ import annotations사용) - 크로스 플랫폼: Windows, macOS, Linux
- 표준 라이브러리 외 추가 의존성 없음
품질
이 코드는 4라운드의 자동화된 코드 리뷰(CodeRabbit + Greptile)를 거쳤으며, 9개의 실제 버그가 발견되어 수정되었습니다.
함께 보기
self-audit— 추론 품질 게이트 (완전성/일관성/근거성/정직성)verification-loop— 코드 품질 검사 (빌드/타입/린트/테스트)gateguard— PreToolUse 안전 게이트