훅 설계: 실패 신호 옆에 붙이기

2026년 5월 5일 | 바이브코딩 Tips

---

코딩 에이전트 훅을 붙일 때 내가 자주 실수한 부분은, 자동화할 일을 먼저 고르고 나서 이벤트를 찾았다는 점이다. “수정 뒤에는 포매터”, “위험 명령은 차단”, “끝나면 요약”처럼 규칙을 늘어놓으면 뭔가 단단해 보인다. 그런데 실제 세션에서는 규칙이 많다고 안정적이진 않았다. 훅이 가장 잘 먹히는 자리는 좋은 습관의 목록이 아니라, 반복해서 무너지는 실패 신호 바로 옆이었다.

바이브코딩에서 훅과 가드레일을 이야기하면 보통 “무엇을 자동화할까”로 시작하기 쉽다. 나도 처음에는 그랬다. 하지만 몇 번 길게 돌려 보니 질문을 조금 바꾸는 편이 나았다. “어느 순간에 사람이 다시 들어와야 했나”, “어떤 로그가 없어서 판단이 늦어졌나”, “어떤 변경은 실행되기 전에 멈췄어야 했나”를 먼저 적으면 훅의 위치가 더 자연스럽게 보인다.

훅은 모든 규칙을 한곳에 몰아넣는 장치가 아니라, 실패가 관찰되는 지점에 작게 붙이는 검문소에 가깝다.

실패 신호를 먼저 이름 붙이기

내가 요즘 쓰는 방식은 단순하다. 훅을 만들기 전에 실패 신호를 먼저 세 줄로 쓴다. 예를 들면 “보호 경로가 수정되려 한다”, “테스트를 한 번도 돌리지 않고 완료 답변으로 간다”, “diff가 커졌는데 설명이 파일명 나열에 멈춘다” 같은 식이다. 이 문장들이 있어야 훅이 추상적인 안전장치가 아니라, 특정 증상을 잡는 작은 장치가 된다.

여기서 중요한 건 신호를 너무 넓게 잡지 않는 것이다. “위험하면 멈춤”은 훅으로 만들기 어렵다. 반대로 “마이그레이션 파일을 수정하려 할 때”, “삭제 명령이 보호 디렉터리를 포함할 때”, “UI 변경인데 스크린샷이나 preview 확인이 없을 때”처럼 쓰면 에이전트도, 사람도 같은 기준을 볼 수 있다. 좋은 훅은 똑똑한 판단자라기보다 좁은 감지기에 가깝다.

세 종류로 나누면 덜 과해진다

실패 신호를 적고 나면 나는 보통 훅의 반응을 세 종류로 나눈다. 첫째는 자동 중단이다. 삭제, 배포, 시크릿 파일 접근, 보호 경로 수정처럼 되돌림 비용이 큰 행동은 프롬프트로 설득하기보다 실행 전에 끊는 편이 낫다. 이 부류는 에이전트가 “조심하겠다”고 말하는 것보다, 아예 다음 단계로 못 넘어가게 하는 쪽이 안전하다.

둘째는 증거 수집이다. 매번 막을 필요는 없지만, 나중에 사람이 판단하려면 꼭 필요한 정보를 자동으로 붙이는 칸이다. 변경 파일 목록, 마지막 테스트 결과, 실패 로그 일부, diff 크기, 화면 캡처 같은 것들이 여기에 들어간다. 이 칸은 에이전트를 멈추게 하려는 게 아니라, 마지막 handoff를 덜 흐리게 만들기 위한 장치다.

셋째는 사람 확인이다. 자동 중단보다는 부드럽지만, 그냥 통과시키기에는 위험한 경우다. 요구사항이 애매하거나, 수정 범위가 처음 계약보다 커졌거나, 같은 실패가 두 번째 반복됐을 때가 여기에 가깝다. 이때 훅은 답을 내는 장치가 아니라 “여기서 한 번 확인하자”는 표식을 붙이는 장치가 된다.

반응	붙일 신호	내가 기대하는 효과
자동 중단	삭제, 배포, 보호 경로, 시크릿 접근	되돌리기 비싼 행동을 실행 전에 끊기
증거 수집	테스트 결과 없음, diff 확대, 화면 확인 공백	완료 답변을 판단 가능한 자료로 바꾸기
사람 확인	범위 확대, 모호한 요구, 반복 실패	추측성 수정을 멈추고 계약을 다시 맞추기

프롬프트 계약과 훅을 같은 문장으로 잇기

훅이 있다고 해서 시작 프롬프트가 필요 없어지는 건 아니다. 오히려 둘의 역할을 분리해야 덜 헷갈린다. 프롬프트 계약은 “이번 작업에서 무엇을 하려는지”와 “어디까지 허용되는지”를 말한다. 훅은 그 계약이 깨질 가능성이 높은 지점에서 실행된다. 그래서 나는 도구 계약서를 쓸 때 훅으로 걸 신호도 같이 한 줄 남긴다.

작업 계약
- 목표: 결제 실패 화면에서 재시도 버튼이 사라지는 문제를 고친다.
- 허용 범위: checkout UI와 관련 테스트만 수정한다.
- 실패 신호: 결제 API, 마이그레이션, 배포 설정을 건드리려 하면 멈춘다.
- 증거 신호: 수정 뒤 실패 케이스 테스트와 모바일 폭 preview를 남긴다.
- 확인 신호: 원인이 checkout 밖으로 넘어가면 사람에게 범위 재확인을 요청한다.

이 정도만 적어도 훅은 더 구체적인 이름을 갖는다. “안전하게 해줘”가 아니라 “결제 API를 건드리면 멈춰”, “모바일 preview가 없으면 완료로 보지 마”가 된다. 에이전트가 더 잘 알아듣는 것도 있지만, 사람 입장에서도 나중에 훅이 왜 울렸는지 훨씬 빨리 이해된다. 규칙의 이름이 작업 계약 안에 있으니, 자동화가 갑자기 끼어드는 느낌이 줄어든다.

훅이 너무 많아지는 신호

훅을 붙이다 보면 반대쪽 함정도 생긴다. 모든 것을 막고, 모든 것을 기록하고, 모든 작업에 같은 검사를 걸면 세션이 느려지고 노이즈가 늘어난다. 특히 작은 문서 수정에도 무거운 테스트가 자동으로 붙거나, 단순 리팩터링에도 사람 확인이 계속 뜨면 에이전트와 사람이 둘 다 훅을 우회하고 싶어진다. 가드레일이 많아서 안전한 게 아니라, 필요한 곳에 있어서 안전해야 한다.

그래서 나는 훅을 추가할 때마다 삭제 기준도 같이 둔다. 한 달 동안 한 번도 울리지 않았거나, 울릴 때마다 사람이 무시했다면 신호가 너무 넓거나 쓸모없는 것이다. 반대로 훅이 자주 울리는데 항상 실제 위험을 잡았다면 그 신호는 더 앞단으로 올릴 수 있다. 훅도 프롬프트처럼 쌓아 두면 빚이 된다. 신호, 반응, 삭제 기준이 같이 있어야 오래 간다.

내가 남기는 최소 루프

새 프로젝트나 새 도구에서 바로 복잡한 hook 시스템을 만들 필요는 없다. 나는 보통 세 개만 먼저 잡는다. 하나는 “실행 전에 절대 막을 것”, 하나는 “완료 전에 자동으로 모을 증거”, 하나는 “사람에게 다시 물어볼 조건”이다. 이 세 개가 있으면 프롬프트, 훅, 종료 체크가 서로 따로 놀지 않는다.

작게 붙일 때는 로그 위치도 같이 정해 둔다. 훅이 울렸다는 사실만 남으면 다음 세션에서 원인을 다시 찾아야 한다. 그래서 나는 가능하면 신호 이름, 실행 직전 의도, 차단 또는 통과 이유, 사람이 다시 볼 파일을 한 줄로 남기게 한다. 이 기록이 있으면 훅은 단순한 방해물이 아니라 다음 작업의 관찰 자료가 된다. 특히 여러 에이전트나 여러 도구를 번갈아 쓰는 날에는 이 얇은 기록이 생각보다 큰 차이를 만든다.

바이브코딩은 점점 더 긴 세션과 더 많은 도구를 다루는 방향으로 가고 있다. 이 흐름에서 모든 규칙을 프롬프트에만 넣는 방식은 금방 버거워진다. 그렇다고 모든 판단을 자동화로 밀어 넣는 것도 불안하다. 내가 지금 가장 편하게 느끼는 중간 지점은 실패 신호를 작게 이름 붙이고, 그 신호 옆에만 훅을 붙이는 방식이다. 반복해서 무너지는 순간을 먼저 찾고, 그 옆에 작은 검문소를 세우기. 이 정도가 실제 작업 속도와 안전 사이에서 제일 덜 무리한 출발점이었다.