Hooks 개요

IDE에서 발생하는 이벤트에 맞춰 미리 정의한 Agent 동작이나 셸 명령을 자동으로 실행해 반복 작업을 줄여주는 자동화 도구입니다.

Agent hook이란?

Agent hook은 특정 IDE 이벤트가 발생했을 때 미리 작성해 둔 Agent 프롬프트나 셸 명령을 자동으로 실행하는 트리거입니다. 일상적으로 반복하던 작업을 매번 직접 요청하지 않아도 되고, 코드베이스 전반에 걸쳐 동일한 규칙을 일관되게 적용할 수 있습니다.

대표적인 트리거 이벤트는 다음과 같습니다.

• 파일 저장, 생성, 삭제
• 사용자 프롬프트 제출, Agent 턴 종료
• 도구 호출 직전 또는 직후 (Pre/Post Tool Use)
• Spec 작업 실행 직전 또는 직후

Agent hook을 적극적으로 활용하면 다음과 같은 이점을 얻을 수 있습니다.

• 일관된 코드 품질 유지
• 보안 취약점 사전 차단
• 수작업으로 처리하던 운영 부담 감소
• 팀의 개발 프로세스 표준화
• 전체 개발 사이클 단축

동작 방식

hook 시스템은 두 단계의 흐름으로 동작합니다.

1. 이벤트 감지 — IDE에서 미리 지정한 이벤트가 발생하는지 모니터링합니다.
2. 자동 실행 — 이벤트가 감지되면 등록해 둔 Agent 프롬프트 혹은 셸 명령이 즉시 실행됩니다.

이러한 구조 덕분에 포매팅, 테스트 실행, 문서 갱신과 같은 반복적인 작업이 자동으로 처리되고, 작은 사이드 프로젝트부터 대규모 모노레포까지 동일한 방식으로 일관성을 유지할 수 있습니다.

hook 설정하기

hook을 만드는 방법은 세 가지입니다. 자연어로 원하는 워크플로를 설명하는 방식, 폼을 직접 채워 세부 항목을 지정하는 방식, 그리고 JSON 파일을 직접 작성하는 방식입니다.

JSON 파일 형식

hook은 워크스페이스의 .kiro/hooks/에 저장되는 JSON 파일입니다.

{
  "version": "v1",
  "hooks": [
    {
      "name": "lint-on-save",
      "trigger": "PostFileSave",
      "matcher": "\\.ts$",
      "action": { "type": "command", "command": "npm run lint" },
      "timeout": 30,
      "enabled": true
    }
  ]
}

UI에서 hook 만들기

1. Kiro 패널에서 Agent Hooks 섹션으로 이동합니다.
2. + 버튼을 눌러 새 hook 만들기를 시작합니다.
3. 다음 두 가지 생성 방식 중 하나를 선택합니다.
   • Manually create a hook — 폼에서 항목을 직접 채워 구성
   • Ask Kiro to create a hook — 자연어 설명으로 Kiro가 자동 생성

Ask Kiro to create a hook

1. Ask Kiro to create a hook을 선택합니다.
2. 실행하고 싶은 작업의 흐름을 자연어로 설명합니다. 예: "TypeScript 파일을 저장하면 ESLint를 실행하라."
3. Enter를 누르거나 Submit 버튼을 클릭합니다.
4. Kiro가 만들어 준 설정을 확인하고 필요한 부분을 수정한 뒤 Save Hook을 클릭해 저장합니다.

Manually create a hook

1. Manually create a hook을 선택해 hook 작성 폼을 엽니다.
2. 각 항목을 다음과 같이 채웁니다.
   • Title — hook을 식별할 짧은 이름
   • Description — 어떤 일을 하는지에 대한 간단한 설명
   • Event — 트리거 종류. 예: File Save, Post Tool Use, Pre Task Execution
   • Tool name — Pre/Post Tool Use 이벤트를 사용할 때 어떤 도구를 대상으로 할지 지정
   • File pattern — 파일 관련 이벤트에서 매칭할 파일 패턴
   • Action — Ask Kiro(Agent 프롬프트)와 Run Command(셸 명령) 중 선택
   • Instructions 또는 Command — 실제로 실행할 프롬프트나 셸 명령 입력
3. 입력이 끝나면 Create Hook을 눌러 저장하거나, 처음부터 다시 시작하려면 Clear를 눌러 폼을 초기화합니다.

트리거 레퍼런스

종료 코드 동작

command 액션의 경우 종료 코드에 따라 다음과 같이 동작합니다.

다음으로 읽을 만한 문서

• Hook Types — 트리거 종류별 활용 사례
• Hook Actions — 각 액션 유형과 사용 예시
• Management — hook 정리·수정·유지 관리 방법
• Best Practices — 효과적인 hook 설계 패턴
• Examples — 바로 활용 가능한 템플릿 모음