Ch5. Hooks 시스템

핵심 요약

Hooks는 fileEdited·fileCreated·promptSubmit·agentStop·userTriggered 같은 이벤트가 발생하면 자동으로 실행되는 액션입니다.
액션 타입은 두 가지로, askAgent는 새 에이전트 세션을 시작하고 runCommand는 쉘 명령을 실행(promptSubmit·agentStop에서만)합니다.
filePatterns는 glob을 지원하고, 설정은 프로젝트 .kiro/hooks/ 또는 글로벌 ~/.kiro/hooks/에 둡니다.
v0.10의 Task Hooks(pre/postTaskExecution)와 v0.9의 Tool Invocation Hooks(pre/postToolUse, read/write/shell/web 카테고리)까지 범위가 넓어졌습니다.
Hooks는 현재 사용자 권한으로 돌아가니 외부 훅 설정은 반드시 검토하고, 너무 많이 걸어두면 성능이 떨어질 수 있습니다.

Hooks는 Kiro의 특정 이벤트 시점에 자동으로 실행되는 액션입니다. 파일 변경, 프롬프트 제출, 에이전트 실행 완료 같은 이벤트에 맞춰 워크플로우를 자동화합니다.

이벤트 종류

주요 이벤트:

fileEdited: 파일 저장 시
fileCreated: 새 파일 생성 시
fileDeleted: 파일 삭제 시
promptSubmit: 프롬프트 제출 시
agentStop: 에이전트 실행 완료 시
userTriggered: 사용자 수동 트리거

Hook 액션 타입

askAgent 타입

새로운 에이전트 세션을 시작합니다.

{
  "id": "lint-on-save",
  "name": "저장 시 린트 실행",
  "description": "TypeScript 파일 저장 시 자동으로 린트 검사",
  "eventType": "fileEdited",
  "hookAction": "askAgent",
  "filePatterns": "**/*.{ts,tsx}",
  "outputPrompt": "방금 수정된 파일에 대해 eslint를 실행하고 발견된 문제들을 수정해주세요."
}

runCommand 타입

쉘 명령을 직접 실행합니다. (promptSubmit, agentStop 이벤트에서만 사용 가능)

{
  "id": "auto-format",
  "name": "자동 포매팅",
  "description": "에이전트 실행 완료 후 자동으로 Prettier 실행",
  "eventType": "agentStop", 
  "hookAction": "runCommand",
  "command": "npm run format"
}

Hook 설정 위치

프로젝트 레벨

.kiro/hooks/
├── lint-on-save.json
├── auto-test.json
└── deploy-check.json

글로벌 레벨

~/.kiro/hooks/
├── global-format.json
└── backup.json

파일 패턴 매칭

filePatterns는 glob 패턴을 지원합니다:

패턴	매칭 대상
`*/.ts`	모든 TypeScript 파일
`src/*/.{js,jsx}`	src 디렉토리의 JavaScript 파일
`*.md`	루트의 마크다운 파일
`!node_modules/**`	node_modules 제외

실전 레시피

1. TypeScript 파일 저장 시 자동 린트

{
  "id": "typescript-lint",
  "name": "TypeScript 린트 검사",
  "description": "TS/TSX 파일 저장 시 자동으로 ESLint 실행 및 수정",
  "eventType": "fileEdited",
  "hookAction": "askAgent", 
  "filePatterns": "**/*.{ts,tsx}",
  "outputPrompt": "방금 수정된 TypeScript 파일에 대해 `npm run lint:fix`를 실행하고, 자동으로 수정되지 않는 문제가 있다면 코드를 직접 수정해주세요."
}

2. 테스트 파일 생성 시 자동 실행

{
  "id": "run-new-tests",
  "name": "새 테스트 실행",
  "description": "테스트 파일 생성 시 자동으로 해당 테스트 실행",
  "eventType": "fileCreated",
  "hookAction": "askAgent",
  "filePatterns": "**/*.test.{ts,tsx,js,jsx}",
  "outputPrompt": "새로 생성된 테스트 파일을 실행해서 정상 동작하는지 확인해주세요. 실패하는 테스트가 있다면 수정해주세요."
}

3. 프롬프트 제출 후 자동 포매팅

{
  "id": "format-after-prompt",
  "name": "프롬프트 후 포매팅",
  "description": "프롬프트 제출 후 자동으로 Prettier 실행",
  "eventType": "promptSubmit",
  "hookAction": "runCommand",
  "command": "npx prettier --write . --ignore-path .gitignore"
}

4. 에이전트 완료 후 Git 커밋 준비

{
  "id": "prepare-commit",
  "name": "커밋 준비",
  "description": "에이전트 실행 완료 후 변경사항 스테이징",
  "eventType": "agentStop",
  "hookAction": "runCommand", 
  "command": "git add . && git status"
}

5. 컴포넌트 파일 생성 시 스토리북 파일 생성

{
  "id": "create-storybook",
  "name": "스토리북 파일 생성",
  "description": "React 컴포넌트 생성 시 자동으로 스토리북 파일 생성",
  "eventType": "fileCreated",
  "hookAction": "askAgent",
  "filePatterns": "src/components/**/*.tsx",
  "outputPrompt": "새로 생성된 React 컴포넌트에 대응하는 Storybook 스토리 파일(.stories.tsx)을 생성해주세요. 컴포넌트의 주요 props와 상태를 보여주는 기본적인 스토리들을 포함해주세요."
}

6. 수동 트리거 - 전체 프로젝트 검토

{
  "id": "project-review",
  "name": "프로젝트 전체 검토",
  "description": "수동으로 트리거하여 프로젝트 전체 코드 품질 검토",
  "eventType": "userTriggered",
  "hookAction": "askAgent",
  "outputPrompt": "프로젝트 전체를 검토하여 다음 사항들을 확인해주세요: 1) 코드 품질 및 일관성 2) 보안 취약점 3) 성능 최적화 기회 4) 문서화 누락 부분. 발견된 문제점들과 개선 제안을 정리해주세요."
}

Hook 관리 명령어

VS Code 명령 팔레트에서

Ctrl/Cmd + Shift + P
> Kiro: Manage Hooks
> Kiro: Create New Hook  
> Kiro: Trigger Hook

Hook UI 패널

Ctrl/Cmd + Shift + P
> Kiro: Open Hook UI

Task Hooks (v0.10+)

v0.10부터 태스크 실행 전후에 트리거되는 Hook이 생겼습니다.

Pre Task Execution

태스크를 시작하기 전에 셋업 스크립트를 돌리거나 전제조건을 검증합니다.

{
  "id": "pre-task-setup",
  "name": "태스크 전 환경 확인",
  "description": "태스크 시작 전 의존성 및 환경 검증",
  "eventType": "preTaskExecution",
  "hookAction": "runCommand",
  "command": "npm run typecheck && npm run lint"
}

Post Task Execution

태스크 완료 후 테스트, 린팅, 외부 시스템 알림 등을 실행합니다.

{
  "id": "post-task-notify",
  "name": "태스크 완료 알림",
  "description": "태스크 완료 후 Slack 알림 전송",
  "eventType": "postTaskExecution",
  "hookAction": "runCommand",
  "command": "curl -X POST $SLACK_WEBHOOK -d '{\"text\": \"Task completed\"}'"
}

Tool Invocation Hooks (v0.9+)

v0.9부터 특정 도구 사용 전후에 트리거되는 Hook이 생겼습니다. 도구 카테고리(read/write/shell/web)나 와일드카드 이름 필터로 거를 수 있습니다.

Pre Tool Use

특정 도구를 차단하거나 실행 전 추가 컨텍스트를 제공합니다.

{
  "id": "pre-write-check",
  "name": "파일 쓰기 전 검증",
  "eventType": "preToolUse",
  "hookAction": "runCommand",
  "toolCategory": "write",
  "command": "echo 'Validating write operation...'"
}

Post Tool Use

도구 사용 후 로깅, 코드 포맷팅, 후속 지시를 실행합니다.

{
  "id": "post-shell-log",
  "name": "쉘 명령 로깅",
  "eventType": "postToolUse",
  "hookAction": "runCommand",
  "toolCategory": "shell",
  "command": "echo \"$(date): Shell command executed\" >> .kiro/audit.log"
}

주의사항

보안 주의

Hooks는 현재 사용자 권한으로 실행됩니다. 외부에서 가져온 훅 설정은 반드시 검토하세요.

성능 고려

너무 많은 Hook이 설정되면 성능에 영향을 줄 수 있습니다. 필요한 Hook만 활성화하세요.

참고 문서

Kiro 공식 사이트: https://kiro.dev
Hooks 문서: https://kiro.dev/docs/hooks/
Kiro 문서: https://kiro.dev/docs