하네스란?
개발자(사람이든 AI든)가 실수를 하면 코드가 차단됩니다. “규칙을 읽고 따라라”가 아니라 물리적으로 진행이 안 되는 구조입니다.
- HARD Gate (exit 2): 조건 미충족 시 Edit/Write/Push 자체를 차단
- SOFT Guard (additionalContext): 경고를 주입하되 진행은 허용
Hook 이벤트 흐름
sequenceDiagram
participant S as SessionStart
participant U as UserPromptSubmit
participant P as PreToolUse
participant W as Edit / Write / Push
participant Q as PostToolUse
participant E as Stop
S->>U: 권한 설정, 이전 세션 복원
U->>P: self-improve 체크, 루프 규칙 재강조
P->>W: .env, --no-verify, QA gate 검사
W->>Q: 코드 수정 결과 전달
Q->>E: 품질 체크, 증거 요구, 파일 크기 제한
E-->>S: HANDOFF 저장 후 다음 세션으로 연결
주요 HARD Gate (차단)
Git 보호
| Hook | 차단 대상 |
|---|
no-env-commit.sh | .env 파일 git add |
ai-commit-msg-ban.sh | 커밋 메시지에 AI 관련 내용 |
no-verify-ban.sh | —no-verify 플래그 사용 |
branch-flow-guard.sh | 보호 브랜치 직접 커밋 |
qa-gate-before-push.sh | QA 미통과 상태에서 push |
코드 품질
| Hook | 차단 대상 |
|---|
as-any-ban.sh | TypeScript as any 사용 |
console-log-ban.sh | console.log 잔존 |
default-export-ban.sh | default export 사용 |
css-import-verify.sh | CSS import 누락 |
행동 규칙
| Hook | 차단 대상 |
|---|
claim-done-gate.sh | 증거 없이 “완료” 선언 |
assumption-answer-gate.sh | 추측으로 답변 |
defer-to-user-ban.sh | ”사용자가 확인해주세요” 떠넘기기 |
api-contract-required.sh | API 변경 시 계약 명세 누락 |
SOFT Guard (경고/주입)
| Hook | 동작 |
|---|
handoff-recap.sh | 이전 세션 HANDOFF를 컨텍스트에 자동 주입 |
self-improve-check.sh | /self-improve 실행 필요 시 지시 주입 |
mid-loop-question-reminder.sh | 루프 중 “계속할까요?” 금지 규칙 재강조 |
premature-completion-reminder.sh | 조기 완료 선언 방지 |
prompt-enhancer.sh | 2,642개 프롬프트 기반 RAG로 입력 강화 |
SOFT → HARD 자동 승격
같은 패턴이 2회 이상 SOFT 위반되면 자동으로 HARD hook으로 승격됩니다:
flowchart LR
A["1회 위반<br/>SOFT 경고"]
B["2회 위반<br/>패턴 감지"]
C["self-improve<br/>hook 코드 생성"]
D["3회 이후<br/>HARD 차단"]
A --> B --> C --> D
이 메커니즘이 시스템을 자가 강화하게 만듭니다. 시간이 지날수록 더 많은 실수가 자동 차단됩니다.