Agent Hooks

목표

Agent Hooks의 개념과 활용법을 이해합니다. 특정 이벤트 발생 시 자동으로 AI 에이전트 작업을 실행하는 자동화 기능입니다.

Agent Hooks란?

Agent Hooks는 이벤트 기반 자동화입니다. 에이전트의 파일 저장·생성·삭제, 도구 호출, 세션 변화 등의 이벤트가 발생하면 미리 정의된 동작을 자동으로 수행합니다.

File Create·File Save·File Delete는 에이전트가 만든 파일 변경에만 반응합니다. 편집기에서 사람이 직접 저장·생성·삭제한 변경은 이 Hook들을 실행하지 않습니다.

핵심 동작 원리 (3단계)

1. 시스템이 특정 이벤트를 감지 (파일 저장 등)
2. 이벤트 발생 시 미리 정의된 프롬프트를 에이전트에 전달
3. 에이전트가 프롬프트를 처리하고 작업 수행

트리거 유형

화면 라벨	JSON `trigger`	설명	차단 가능
File Save	`PostFileSave`	에이전트가 파일을 저장·수정한 후 실행	아니요
File Create	`PostFileCreate`	에이전트가 새 파일을 생성한 후 실행	아니요
File Delete	`PostFileDelete`	에이전트가 파일을 삭제한 후 실행	아니요
Pre Tool Use	`PreToolUse`	도구 실행 전에 실행	예
Post Tool Use	`PostToolUse`	도구가 실행된 후 실행	아니요
Prompt Submit	`UserPromptSubmit`	사용자가 에이전트에 메시지를 보낼 때 실행	예
Session Start	`SessionStart`	새 세션이 시작될 때 실행	아니요
Agent Stop	`Stop`	에이전트가 응답을 마칠 때 실행	아니요
Pre Task Execution	`PreTaskExec`	Spec Task가 시작되기 전에 실행	예
Post Task Execution	`PostTaskExec`	Spec Task가 완료된 후 실행	아니요

차단 가능한 사전 트리거는 조건을 충족하지 못한 도구 실행, 사용자 프롬프트 제출 또는 Spec Task 시작을 중단하는 데 사용할 수 있습니다.

활용 사례

에이전트의 코드 저장 후 자동 품질 검사
문서 변경 시 자동 맞춤법 검사
보안 취약점 자동 스캔
에이전트의 파일 저장 후 테스트 자동 실행
TODO 주석 발견 시 이슈 자동 생성

사전 준비

Kiro IDE 로그인 및 프로젝트 폴더 열기 완료

해볼 것

1단계: Hook 생성

Kiro 패널 → Agent Hooks 섹션 → 생성 버튼 클릭 후 아래 입력:

JavaScript 파일을 저장할 때마다 다음을 자동으로 검사하고 개선 제안을 해주는 Hook을 만들어주세요:
1. 코드 스타일 검사 (들여쓰기, 세미콜론 등)
2. 변수명 개선 제안
3. 주석 추가 필요 부분 식별
4. 성능 최적화 가능 부분 찾기
5. 접근성 개선 사항 (HTML/CSS 관련)
트리거: 파일 저장
대상 파일: *.js, *.html, *.css

2단계: 테스트

채팅에서 Kiro에게 간단한 .js 파일을 만들거나 기존 파일에 주석을 추가해 달라고 요청합니다. 에이전트가 파일을 생성·저장한 뒤 Hook이 자동 실행되는지 확인합니다. 편집기에서 직접 저장한 변경은 File Hook을 실행하지 않습니다.

Hook 파일 구조 예시

json

{
  "version": "v1",
  "hooks": [
    {
      "name": "Code Quality Checker",
      "trigger": "PostFileSave",
      "matcher": "\\.(js|html|css)$",
      "action": {
        "type": "agent",
        "prompt": "저장된 파일의 코딩 스타일·보안 취약점·성능 최적화를 검사하고 개선을 제안해주세요."
      }
    }
  ]
}

생성된 Hook은 .kiro/hooks/<id>.json 파일로 저장됩니다. action.type은 셸 명령을 실행하는 command와 에이전트에 프롬프트를 전달하는 agent 중에서 선택합니다. command action은 프로젝트 루트에서 실행되며 세션 컨텍스트를 JSON 형식의 STDIN으로 받습니다. 선택 필드인 timeout은 명령 제한 시간(기본 60초, 0이면 제한 없음)을, enabled는 Hook 활성화 여부(기본 true)를 설정합니다.

기대 결과

.kiro/hooks/ 폴더에 Hook 파일 생성
에이전트가 파일을 저장하면 자동으로 검사 실행
개선 사항이 채팅 패널에 표시

✅ 핵심 요약

Agent Hooks = 이벤트 기반 AI 자동화
에이전트의 파일 저장·생성 후 정해진 작업 자동 수행
코드 품질·보안·문서 등 반복 작업에 최적
실습 Scene D에서 실전 실습 진행

통합 관점

Hooks와 같은 공식 Features 형제 항목 및 선택 기준은 Context Engineering에서 확인하세요.

🚨 문제 해결

Hook이 실행되지 않음: 편집기에서 직접 저장한 변경은 File Hook을 실행하지 않습니다. 채팅에서 Kiro에게 대상 파일 수정을 요청한 뒤, 파일 패턴과 Hook 활성화 상태를 확인하고 필요하면 Kiro를 재시작하세요.
실행이 너무 느림: 대상 파일 범위를 축소하거나, 지시사항을 단순화하세요.
결과가 기대와 다름: instructions를 더 구체적으로 작성하세요.

Agent Hooks ​

목표 ​

Agent Hooks란? ​

핵심 동작 원리 (3단계) ​

트리거 유형 ​

활용 사례 ​

사전 준비 ​

해볼 것 ​

1단계: Hook 생성 ​

2단계: 테스트 ​

Hook 파일 구조 예시 ​

기대 결과 ​