Claude Code subagent hooks: 팀 자동화 시작과 종료를 안전하게 묶는 법 | DAKER 커뮤니티

Claude Code subagent hooks: 팀 자동화 시작과 종료를 안전하게 묶는 법

Claude Code subagent hooks란, subagent가 시작되거나 끝나는 시점에 준비·정리 작업을 자동 실행하는 설정을 의미합니다. 2026년 6월 23일 기준 공식 문서는 SubagentStart와 SubagentStop 이벤트를 제공하므로, 팀은 리뷰 agent나 테스트 agent의 환경 준비와 결과 수집을 한 흐름으로 묶을 수 있습니다.

_클로드 코드 subagent hooks로 시작, 준비, 검증, 정리를 묶는 카드 이미지._

Claude Code subagent hooks는 언제 필요한가요?

한 줄 요약: subagent가 맡은 역할은 지시문으로 정하고, 시작 전 준비와 종료 후 정리는 hooks로 고정합니다.

subagent를 쓰는 팀은 보통 "리뷰는 code-reviewer에게", "테스트 실패는 test-runner에게"처럼 역할을 분리합니다. 문제는 역할만 나누면 매번 같은 준비가 빠질 수 있다는 점입니다. 예를 들어 리뷰 agent가 시작될 때 fixture를 만들고, 끝날 때 lint 결과와 diff 요약을 남기는 일은 사람이 매번 기억하기 어렵습니다.

DAKER의 Claude Code auto mode git 안전장치는 자동 실행의 위험 경계를 다뤘고, Claude Code worktree skills 로딩은 격리 세션에서도 팀 절차를 유지하는 방법을 다뤘습니다. 오늘 글은 그 다음 단계로, subagent 시작과 종료 시점을 팀 자동화의 체크포인트로 쓰는 방법에 집중합니다.

SubagentStart와 SubagentStop은 무엇을 해주나요?

공식 문서 기준 SubagentStart는 subagent가 실행을 시작할 때, SubagentStop은 subagent가 완료될 때 발생합니다. 두 이벤트는 agent type name을 matcher로 받을 수 있어 특정 agent에만 hook을 연결할 수 있습니다.

이벤트	실행 시점	실무 용도
`SubagentStart`	subagent가 시작될 때	테스트 fixture 생성, 환경 변수 점검, 임시 DB 연결
`SubagentStop`	subagent가 끝날 때	cleanup, 로그 수집, evidence report 저장
subagent frontmatter hooks	해당 agent가 활성화된 동안	agent별 로컬 규칙과 검증 루틴
project `settings.json` hooks	프로젝트 세션 전체	팀 공통 setup, cleanup, 보안 점검

핵심은 hook을 "더 강한 지시문"으로 생각하지 않는 것입니다. hook은 자동화 시점과 실행 명령을 고정하는 도구입니다. 위험 명령 차단처럼 반드시 지켜야 하는 정책은 permission rule, 승인 경계, 별도 보안 검토와 함께 설계해야 합니다.

단계별 사용법: 팀 subagent hook은 어떻게 설계하나요?

subagent 이름을 역할 중심으로 정합니다. 예: code-reviewer, test-runner, db-agent.
subagent description에는 언제 자동 위임해도 되는지 한 문장으로 씁니다.
SubagentStart에는 준비 작업만 둡니다. 예: fixture load, sandbox 확인, 필요한 로그 파일 생성.
SubagentStop에는 정리와 증거 수집만 둡니다. 예: temp cleanup, test summary, review notes 저장.
실패해도 안전해야 하는 작업과 실패하면 멈춰야 하는 작업을 분리합니다.
hook 로그는 사람이 읽을 수 있는 짧은 파일로 남깁니다.

_SubagentStart와 SubagentStop으로 팀 자동화의 준비와 종료 기준을 나누는 워크플로 이미지._

짧은 예시: 리뷰 subagent 지시문은 어떻게 쓰나요?

code-reviewer subagent로 최근 변경을 리뷰해줘.

시작 전:
- 테스트 fixture가 필요한지 확인한다.
- 변경 파일 목록과 위험 파일을 먼저 요약한다.

종료 전:
- 발견한 문제를 severity 순으로 정리한다.
- 실행한 테스트와 실행하지 못한 테스트를 분리한다.
- cleanup 결과와 남은 리스크를 남긴다.

이 지시문은 hook 설정 자체가 아닙니다. 대신 팀이 어떤 준비와 종료 증거를 원해야 하는지 보여주는 운영 예시입니다. 실제 자동화는 project settings.json 또는 subagent frontmatter에 넣어 반복 실행되게 만드세요.

팀 적용 체크리스트는 무엇인가요?

subagent마다 "시작 전 준비"와 "종료 후 정리"를 한 줄로 정의했는가
SubagentStart에는 destructive action이 들어가지 않았는가
SubagentStop 실패 시 cleanup 누락을 사람이 볼 수 있는가
agent별 hook과 project-level hook의 책임이 겹치지 않는가
review, test, db 작업의 로그 위치가 일정한가
hook이 권한 정책을 대신한다고 착각하지 않았는가

공식 출처는 어디에서 확인했나요?

2026년 6월 23일 기준 Claude Code Hooks reference와 Create custom subagents 문서를 확인했습니다. 공개 본문에는 DAKER 운영 정책에 맞춰 DAKER 내부 링크만 연결했습니다.

FAQ

Claude Code subagent hooks는 custom command와 같은 건가요?

아닙니다. custom command는 사용자가 호출하는 작업 단위에 가깝고, hooks는 Claude Code lifecycle의 특정 시점에 자동 실행되는 설정입니다.

SubagentStart hook에 테스트 실행을 넣어도 되나요?

가능하지만 시작이 느려질 수 있습니다. 일반적으로 시작 hook에는 환경 점검과 fixture 준비를 두고, 실제 테스트 실행은 subagent 작업 또는 종료 전 검증으로 분리하는 편이 명확합니다.

모든 subagent에 같은 cleanup hook을 붙여도 되나요?

공통 cleanup은 project-level SubagentStop에 둘 수 있습니다. 다만 DB 연결, 임시 파일, 외부 서비스 토큰처럼 agent별 책임이 다른 항목은 matcher로 좁히는 편이 안전합니다.

subagent가 자동 위임되지 않으면 어떻게 하나요?

description 필드가 너무 모호할 수 있습니다. 어떤 작업에서 proactive하게 쓰면 좋은지 명확히 쓰고, 중요한 작업은 @-mention이나 --agent로 명시 호출하세요.

다음 팀 자동화에서는 subagent 이름을 정한 뒤, 그 agent의 "시작 전 준비"와 "종료 후 증거"를 먼저 한 문장으로 적어 보세요.