반복 규칙을 프롬프트 안에만 두지 않기: hooks로 가드레일 빼두기

2026년 4월 9일 | 바이브코딩 Tips

---

코딩 에이전트에서 hooks는 프롬프트보다 더 단단한 가드레일에 가깝다. 훅은 에이전트 세션의 특정 시점에 셸 명령을 자동으로 끼워 넣는 연결점이다. 예를 들면 도구 실행 직전, 파일 수정 직후, 컨텍스트 압축 직전 같은 순간이다. 나는 예전엔 이런 규칙을 전부 프롬프트 안에 적어 넣는 쪽이었다. “수정 뒤에는 포매터 돌려”, “위험한 명령은 치지 마”, “길어지면 상태 파일 남겨” 같은 식이다. 그런데 바이브코딩이 길어질수록 이 규칙들은 생각보다 자주 빠진다. 프롬프트에 있는 문장은 결국 기억에 기대는 약속이고, 훅은 매번 실행되는 계약에 더 가깝다.

오늘 본 공식 문서들과 사례 글을 묶어 보면 방향이 꽤 선명하다. 이제는 에이전트를 더 세게 설득하는 프롬프트보다, 반복되는 규칙을 프롬프트 밖으로 빼두는 구조가 더 중요해지고 있다. 특히 포매팅, 위험 명령 차단, 세션 상태 백업처럼 한 번만 빠져도 손실이 큰 규칙은 더 그렇다. 이런 건 그때그때 말로 상기시키는 것보다, 아예 실행 지점에 묶어 두는 편이 낫다.

Figure 1: 에이전트 훅은 도구 실행 전후와 세션 수명주기 특정 지점에 규칙을 자동으로 걸 수 있게 해 준다.

내가 오늘 여기서 무릎 친 포인트는 단순했다. 반복해서 말하는 규칙은 프롬프트가 아니라 훅에 둘 것. 프롬프트는 의도를 설명하는 데 좋고, 훅은 규칙을 강제로 통과시키는 데 좋다. 바이브코딩이 잘 안 되는 날을 떠올려 보면 대개 모델이 멍청해서가 아니라, 사람도 에이전트도 항상 지켜야 하는 작은 절차를 놓쳐서 무너지는 경우가 많았다. 수정은 했는데 포맷이 안 맞고, 테스트는 돌렸는데 로그 저장이 안 되고, 길게 디버깅한 내용이 압축 한 번에 날아가 버리는 식이다.

1. 훅이 가장 먼저 먹히는 세 군데

나는 훅을 거창한 자동화보다 늘 반복되는 손실 지점 막기에 먼저 붙이는 편이 좋다고 본다.

• PreToolUse: 위험한 Bash 명령, 보호 파일 수정, 금지된 경로 접근을 막기 좋다.
• PostToolUse: 파일이 바뀐 직후 포매터나 린터를 자동으로 태우기 좋다.
• PreCompact / Session 종료 직전: 지금까지의 작업 상태를 파일이나 로컬 저장소에 남기기 좋다.

중요한 건 “무엇을 자동화할까”보다 “무엇을 절대 잊고 싶지 않은가”를 먼저 고르는 것이다. 프롬프트는 긴 세션에서 희미해지기 쉽지만, 훅은 이벤트가 오면 그냥 돈다. 그래서 실패 비용이 큰 반복 규칙일수록 훅으로 먼저 빼는 편이 결과가 안정적이다.

2. 내가 바로 따라 해볼 만하다고 느낀 최소 예시

공식 문서에서 가장 실용적으로 보였던 건 수정 직후 자동 포매팅이었다. VS Code 계열 에이전트 쪽 문서는 저장소 안의 .github/hooks/*.json에서 바로 훅을 읽는 예시를 보여준다. 제일 작은 시작은 이 정도면 충분하다. 아래 예시에서는 공개 글 렌더링 충돌을 피하려고 환경변수 자리를 TOOL_INPUT_FILE_PATH, CLAUDE_PROJECT_DIR처럼 단순 표기로 적었다.

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

이 한 덩어리의 장점은 단순하다. 내가 매번 “수정 끝나면 prettier 돌려”라고 다시 말하지 않아도 된다. 에이전트가 파일을 건드렸다면 그 뒤에 포매터가 붙는다. 바이브코딩에서 이런 자동 연결은 생각보다 크다. 수정은 했는데 정리가 덜 된 상태가 다음 턴의 노이즈가 되기 쉽기 때문이다.

위험 명령 차단도 같은 결이다. Claude Code 문서 예시처럼 PreToolUse에 가벼운 셸 스크립트를 붙여 두면, 프롬프트를 아무리 길게 써도 놓칠 수 있는 실수를 바깥에서 한 번 더 걸러낼 수 있다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

이 스크립트 안에서 rm -rf나 특정 보호 경로를 검사해 거부 응답을 내보내게 만들면, 그 규칙은 더 이상 “오늘은 잊지 말아야지”가 아니다. 나는 이런 류의 규칙일수록 프롬프트에 남겨 두지 않는 편이 훨씬 낫다고 본다. 프롬프트는 협상처럼 흘러가지만, 훅은 체크리스트처럼 작동한다.

3. 긴 세션에서 더 체감되는 포인트: compaction 앞단

오늘 같이 본 사례 글은 이 감각을 더 세게 밀어 줬다. 긴 Claude Code 세션에서 자동 compaction이 걸리면, 대화가 요약본으로 압축되면서 방금까지 잡고 있던 파일 경로, 에러 문장, 버린 접근 방식이 한꺼번에 흐려질 수 있다는 내용이었다. 글에서는 이를 막으려고 PreCompact / PostCompact 훅으로 전체 대화를 로컬 DB에 저장하고, 압축 뒤 필요한 문맥을 다시 주입하는 구조를 설명한다.

나는 모든 사람이 그렇게까지 크게 깔 필요는 없다고 본다. 대신 가볍게라도 SESSION_STATE.md 같은 파일을 남기는 훅은 바로 써볼 만하다. 최소한 아래 다섯 줄만 남아도 압축 뒤 복구 속도가 확 달라진다.

• 지금 하고 있는 작업과 진행률
• 방금 내린 결정과 이유
• 건드린 파일 목록
• 막혔던 에러나 실패한 시도
• 다음에 바로 칠 명령 한 줄

이건 메모 습관 이야기 같지만, 사실은 훅으로 남겨야 하는 작업 계약에 더 가깝다. 프롬프트에 “길어지면 상태를 잘 정리해 둬”라고 쓰는 것보다, 특정 이벤트에서 상태 파일을 갱신하게 두는 쪽이 훨씬 덜 까먹는다.

4. 오늘 바로 붙여 볼 10분짜리 순서

내가 이걸 처음 붙인다면 욕심내지 않고 세 단계만 갈 것 같다. 첫째, PostToolUse에 포매터 하나만 건다. 둘째, PreToolUse에 정말 위험한 명령이나 보호 경로 하나만 막는다. 셋째, 세션이 길어지는 편이라면 PreCompact나 종료 직전 훅에서 상태 파일을 남긴다. 처음부터 검색, DB, 알림, 리포트까지 다 넣으면 오히려 관리 포인트가 많아져서 오래 못 간다.

• 1단계: 수정 뒤 자동 포매팅처럼 결과가 바로 보이는 훅부터 붙이기
• 2단계: rm -rf, 배포 스크립트, 민감 파일처럼 비용이 큰 실수만 먼저 막기
• 3단계: SESSION_STATE.md, logs/tool-results.jsonl처럼 복구용 흔적 남기기

이 순서가 좋은 이유는 에이전트를 더 똑똑하게 만들려는 접근이 아니라, 사람이 다시 들어왔을 때 바로 파악할 수 있는 흔적을 남기기 때문이다. 바이브코딩은 종종 모델 품질 문제처럼 보이지만, 실제로는 어디서 무엇이 실행됐는지 안 남아 있는 상태 때문에 더 크게 꼬인다. 훅은 그 흔적을 자동으로 고정해 준다.

5. 오늘 내 결론

바이브코딩에서 프롬프트는 여전히 중요하다. 다만 프롬프트는 무엇을 하려는지를 설명하는 곳이고, 훅은 무엇을 절대 빼먹지 않을지를 고정하는 곳이라는 구분이 점점 더 중요해지는 것 같다. 내가 요즘 에이전트와 일하면서 진짜 자주 놓치는 건 거대한 설계보다도, 반복되는 작은 절차였다. 그래서 오늘 이후로는 같은 규칙을 두세 번 이상 말하고 있다면 한 번 더 생각해 보려고 한다. 이건 프롬프트에 적을 문장인지, 아니면 훅으로 밖에 빼둘 계약인지.

결국 실전에서는 더 영리한 한 문장보다, 늘 같은 자리에서 도는 자동 가드레일이 작업 품질을 더 오래 지켜 준다. 반복되는 규칙은 설명하지 말고, 가능한 한 실행 지점에 걸어 두기.