헤드리스 AI 에이전트가 훅을 건너뛸 때, 게이트를 스크립트에 넣는 법

자동화를 짜다 보면 이런 순간이 와요. 대화형 세션에서는 잘 걸리던 검사가, 스케줄러나 배치로 돌리는 순간 조용히 사라지는 거죠. 혹시 겪어본 적 없나요?

대화형 훅은 헤드리스에서 안 돌아요

claude -p나 codex exec 같은 헤드리스(비대화형) 실행은 .claude/hooks에 걸어둔 대화형 훅을 자동으로 건너뜁니다. 테스트를 강제하거나 커밋을 막아주던 장치가, 무인 경로에서는 발동하지 않아요.

직접 돌려보니 차이가 확실했어요. 같은 프로젝트인데 터미널에서는 훅이 붙고, -p 플래그로 넘기면 훅이 하나도(0개) 실행되지 않더라고요.

진짜 무서운 건 false-green

문제는 실패가 아니라 성공처럼 보인다는 점이에요. 훅이 안 돌아도 실행 상태는 그대로 status=success로 찍힙니다. 가드가 작동한 적 없는데 초록불이 켜지는 거죠. 이걸 false-green이라고 불러요.

테스트해 보면 금방 드러나요. 일부러 타입 오류를 심고 헤드리스로 돌려도 통과로 처리됩니다. 검사기가 애초에 실행되지 않았으니까요.

대화형 실행과 헤드리스 실행에서 훅이 발동하는지 비교

AGENTS.md는 지침일 뿐, 강제가 아니에요

여기서 흔한 오해 하나. AGENTS.md에 "커밋 전 테스트 돌려라"라고 적어두면 될 것 같지만, 그건 문서상 약속이지 실행 강제가 아니에요. 확인해보니 헤드리스 워커는 그 문장을 참고만 할 뿐, 안 지켜도 아무도 막지 않았어요.

게이트를 실행 스크립트 안에 넣기

해법은 단순해요. 검사를 훅에 맡기지 말고, 페이즈 스크립트나 실행기 자체에 박아 넣는 거예요.

typecheck→lint→test→통과해야 다음 단계로

typecheck·lint·test 3단계를 스크립트 상단에 두고, 하나라도 실패하면 즉시 멈추게 하면 됩니다. 셸이라면 set -e 한 줄, 또는 pnpm typecheck && pnpm lint && pnpm test처럼 앞 단계 통과를 다음 단계 조건으로 걸면 돼요.

적용해 봤더니 헤드리스든 대화형이든 같은 게이트를 지나게 됐어요. 이제 어디서 실행하든 검사가 빠지지 않아요.

정리하면

• 헤드리스 실행은 대화형 훅을 건너뛴다
• 그래서 status=success가 실제 통과를 뜻하지 않는다
• 게이트는 문서(AGENTS.md)가 아니라 실행 경로에 배선해야 강제된다

라이프케어로그에서 플랜씨(plan-c)나 플랜엘(plan-l) 같은 도구를 혼자 운영하다 보면, 무인 자동화가 늘수록 이런 false-green이 시간을 잡아먹어요. 재현하는 데 5분이면 충분하니, 자동화 파이프라인을 쓰신다면 한 번쯤 헤드리스로 돌려서 훅이 정말 도는지 확인해보시길 권해요.