Delivery Gate — Claude Code용 기계적 품질 게이트
Claude가 세션을 종료하기 전에 세 가지 사항을 확인하는 Stop 훅으로, 결정론적 검사(파일 수정 타임스탬프, 디스크 사용량, 트랜스크립트 텍스트의 정규 표현식 패턴)만 사용합니다. 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) |
합리화 감지는 "일단 테스트는 나중에"나 "기존 버그"와 같은 패턴을 경고합니다. 이는 생각이 조기에 종료되었을 수 있다는 표면적 신호입니다. 정규식 휴리스틱은 오탐 가능성이 있으므로 자체적으로 차단하지 않습니다. 차단 조건은: 디스크 임계, >=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/
├── 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 안전 게이트