"사용자·프로젝트 단위 자동 검사 파이프라인은 있는데 에이전트 단위는 없다"는 통념은 절반만 맞다. Claude Code 플랫폼은 이미 세 가지로 지원하고 있었고, 없는 것은 하네스가 그걸 쓰지 않은 것뿐이다 — 89개 에이전트 중 채택 0개. 이 페이지는 그 원인분석과 실측, 그리고 만들어 본 파이프라인을 정리한다.
먼저 용어 하나. 훅(hook)은 "특정 순간이 오면 자동으로 실행되는 작은 검사 스크립트"다. 예를 들어 파일을 저장할 때마다 문법을 검사하거나, 서버에 코드를 올리기 직전 테스트가 통과했는지 막아서는 관문이 훅이다. Claude Code에서 이 훅은 지금까지 "사용자 전체" 또는 "프로젝트 하나" 단위로만 거는 줄 알려져 있었다. 그런데 "에이전트 하나하나마다 다른 훅을 건다"는 건 못 한다는 통념이 있었다. 실측해 보니 플랫폼은 이미 세 가지 방법으로 이걸 지원하고 있었다. 진짜 문제는 우리 하네스가 89개 에이전트 중 단 하나도 그 기능을 쓰지 않았다는 것이었다.
원인은 두 겹이다. 하나는 기능이 늦게 생긴 플랫폼의 역사, 다른 하나는 그 기능을 지나친 우리 하네스의 사각지대다. 진짜 원인은 오른쪽이다.
"원래 훅은 설정 파일만 소유했다"
"기능이 생긴 걸 관측할 표면이 없었다"
방안의 심장은 분배기(dispatcher)다. 설정 파일에 훅 하나만 걸어두고, 그 훅이 입력의 agent_type을 읽어 "지금 어느 에이전트냐"에 따라 알맞은 검사로 넘긴다. 89개 에이전트 파일을 하나도 안 건드리고 중앙에서 에이전트별 정책을 관리할 수 있다. 아래는 실제로 돌려 본 결과다 — 똑같은 date 명령이 메인 대화에선 통과하고, 특정 에이전트 안에서는 막힌다.
권장 순서는 C → B → A다. 관측을 먼저 깔아야 다음 두 층의 효과가 수치로 측정되고, 분배기가 중앙 규약을 세운 뒤 개별 훅은 꼭 필요한 고위험 에이전트에만 붙이는 것이 유지비가 가장 낮다.
텔레메트리(관측 로그)에 agent_type·agent_id 두 필드를 추가한다. 이게 없으면 아래 두 층을 깔아도 "훅이 에이전트 안에서 돈다"는 사실이 측정에 안 잡힌다. 몇 줄짜리 변경.
설정 훅 하나가 agent_type을 읽어 에이전트별 검사로 넘긴다. 89개 에이전트 파일을 안 건드리고 중앙에서 정책을 관리한다. "특정 에이전트 안에서만 위험 명령 차단" 같은 강제 게이트를 실증 완료.
에이전트 정의 파일에 훅을 직접 붙인다. 사용자 스코프 에이전트는 신뢰 승인 배관 없이 바로 동작한다(실측). 인프라를 되돌릴 수 없게 만지는 devops, 검증 담당 user-proxy 같은 고위험 에이전트에만 선별 적용.
| 지원 방식 | 플랫폼 상태 | 하네스 채택 | 실측 증거 |
|---|---|---|---|
| frontmatter 훅 | 지원됨 — 에이전트 수명 동안 유효 | 0 / 89 | debug 로그 Registered 1 frontmatter hook(s) |
| agent_type 입력 | 지원됨 — 서브에이전트 훅에만 존재 | 미사용 | 에이전트 3건 vs 메인 0건 (덤프) |
| SubagentStart 필터 | 지원됨 — 에이전트 이름으로 매칭 | 미사용 | matcher 4/4 발화, 오발화 0 |
| 신뢰 승인 관문 | 프로젝트 에이전트만 필요 · 사용자 스코프는 불필요 | 즉시 채택 가능 | "not trusted" 에러 재현 |
방안을 실제 코드로 만든 뒤, 다른 모델(Codex)에게 "이건 헛소리다"라고 가정하고 결함을 찾게 했다. 라운드마다 진짜 결함이 나왔다. 아래 타임라인에서 위쪽 붉은 마커는 심각(CRITICAL) 결함, 아래 회색은 높음(HIGH) 결함이다. 핵심 로직의 심각 결함은 6라운드에서 사라졌고, 이후는 곁가지(로그 유틸리티)의 하드닝이 이어지다 13라운드에서 전부 통과(CLEAN)로 수렴했다.
"헛소리라고 가정하라"는 적대 검증이 실제로 결함을 잡았다. 그중 하나는 내가 놓칠 뻔한 진짜 버그였다 — 로그 유틸을 파이썬으로 바꾸며 입력 통로가 막혀 데이터가 하나도 안 써졌는데, "실제로 기록됐는지" 검증하는 습관 덕에 잡았다. 결론은 단순하다: 에이전트 스코프 훅은 이미 있었고, 없던 건 채택뿐이다. 관측(C) → 분배기(B) → 개별 훅(A) 순으로 3층을 세우면 89개 에이전트를 안 건드리고도 에이전트별 강제 게이트를 얻는다.