Claude Code hook matcher exact-match: 하이픈 도구 오탐을 막는 설정법 | DAKER 커뮤니티
Claude Code hook matcher exact-match: 하이픈 도구 오탐을 막는 설정법
Claude Code hook matcher exact-match란, hook이 실행될 대상을 문자열 그대로 비교해 잘못된 도구까지 잡지 않게 만드는 규칙입니다. v2.1.195에서는 code-reviewer, mcp__brave-search처럼 하이픈이 들어간 이름의 substring 오탐이 수정됐으므로 팀 hook 설정을 한 번 점검해야 합니다.
클로드 코드 디렉터리용 hook matcher 카드: 하이픈 이름을 exact-match와 regex로 나눠 점검하는 장면.
문제 상황은 어떤 자동화에서 터지나요?
문제 상황은 hook이 너무 넓게 실행될 때입니다. 예를 들어 code-reviewer agent 종료에만 돌려야 할 정리 스크립트가 비슷한 이름까지 건드리거나, mcp__brave-search 서버만 보려던 matcher가 의도보다 넓은 도구를 잡으면 자동화 신뢰도가 떨어집니다. 보안 hook, 비용 로깅, 결과 검증 hook일수록 오탐은 실제 작업 방해로 이어집니다.
한 줄 요약: hook matcher는 “비슷하면 실행”이 아니라 “정확히 맞을 때만 실행”되도록 팀 규칙을 적어야 합니다.
핵심 개념은 어떻게 바뀌었나요?
공식 hooks reference는 matcher 값을 세 가지로 나눕니다. *나 빈 값은 전체 매칭, 문자·숫자·언더스코어·공백·콤마·파이프만 있으면 exact string 또는 목록 매칭, 그 외 문자가 있으면 JavaScript 정규식으로 평가됩니다. v2.1.195 릴리스는 하이픈이 들어간 identifier의 substring matching 오탐을 고쳤고, 하이픈 MCP 서버 전체를 잡으려면 mcp__brave-search__.*처럼 정규식 형태를 쓰라고 안내합니다.
단계별 사용법은 어떻게 점검하나요?
.claude/settings.json, 사용자 설정, plugin hook, skill frontmatter에 있는 hook matcher를 모두 모읍니다.matcher가
code-reviewer,mcp__brave-search처럼 하이픈을 포함하는지 표시합니다.특정 도구 하나만 잡으려면 exact-match로 둡니다.
같은 MCP 서버의 모든 도구를 잡아야 하면
mcp__brave-search__.*처럼 서버 prefix 뒤를 정규식으로 명시합니다.PreToolUse,PostToolUse,PermissionDenied처럼 tool name을 보는 이벤트와SubagentStart,SubagentStop처럼 agent type을 보는 이벤트를 섞지 않습니다.
짧은 예시는 어떻게 적용하나요?
MCP 서버 이름이 brave-search이고 그 서버의 모든 도구 호출을 로깅해야 한다면 matcher를 서버 이름만으로 두지 말고 mcp__brave-search__.*로 적습니다. 반대로 custom agent 이름이 정확히 code-reviewer인 경우에는 그 이름만 매칭하도록 두고, 비슷한 agent 이름을 만들 때는 별도 matcher를 추가합니다.
비교하면 무엇이 안전한가요?
목적 | 권장 matcher | 이유 |
|---|---|---|
Bash만 감시 |
| 정확한 tool name 하나만 매칭 |
Edit 또는 Write 감시 |
| 목록 매칭으로 의도 명확 |
하이픈 MCP 서버 전체 감시 |
| 서버 prefix 뒤 도구명을 정규식으로 포함 |
모든 도구 감시 |
| 비용이 크므로 감사 hook에만 제한적으로 사용 |
팀 적용 체크리스트는 무엇인가요?
hook matcher마다 “정확히 하나”, “목록”, “정규식”, “전체” 중 하나로 의도를 적는다.
하이픈이 들어간 agent와 MCP 서버는 릴리스 이후 동작을 재검증한다.
정규식 matcher는 리뷰 없이 추가하지 않는다.
hook handler 안의
if조건과 matcher가 같은 필터를 중복하지 않는지 본다.PermissionDeniedhook은 auto mode denial retry와 연결될 수 있으므로 더 좁게 시작한다.
Claude Code hooks에서 exact-match, 목록, regex matcher를 분리해 하이픈 도구 오탐을 줄이는 워크플로 카드.
함께 보면 좋은 DAKER 글은 무엇인가요?
Claude Code subagent hooks 글, Claude Code MCP 재연결 글, Claude Code workflow schema 글을 함께 보면 hook 실행 시점, MCP 도구 경계, 결과 검증을 같이 설계할 수 있습니다.
공식 출처는 어디인가요?
Anthropic Claude Code hooks reference: 2026년 6월 29일 확인
Anthropic Claude Code settings 문서: 2026년 6월 29일 확인
anthropics/claude-code v2.1.195 릴리스: 2026년 6월 29일 확인
FAQ
모든 matcher를 정규식으로 바꾸면 되나요?
아닙니다. 정확한 tool name 하나면 exact-match가 더 읽기 쉽고 안전합니다. 정규식은 서버 prefix 전체처럼 패턴이 필요할 때만 씁니다.
하이픈이 없는 matcher도 다시 봐야 하나요?
우선순위는 하이픈이 들어간 agent와 MCP 서버입니다. 다만 목록 구분자와 wildcard가 섞인 오래된 설정은 같이 정리하는 편이 좋습니다.
hook matcher와 permission rule은 같은 문법인가요?
같지 않습니다. matcher는 이벤트별 필드를 필터링하고, handler의 if 조건은 tool name과 인자를 더 좁게 보는 용도입니다.
v2.1.195 이전 버전을 팀원이 쓰면 어떻게 하나요?
팀 hook은 릴리스 동작 차이를 받을 수 있으므로 최소 버전을 문서화하고, 자동화 세션 시작 전에 Claude Code 버전을 확인하는 절차를 넣는 편이 안전합니다.
오늘은 팀 저장소의 hook matcher를 열어 하이픈이 들어간 이름만 먼저 표시하고, exact-match와 regex 의도를 한 줄씩 붙여 보세요.