[Tool] Kiro Hooks - 에이전트가 스스로 학습하는 Self-Improvement 시스템

문제

AI 에이전트는 같은 실수를 반복함. 어제 “그 명령어 안 돼”라고 알려줬는데 오늘 또 같은 걸 시도함. 세션이 바뀌면 이전 교정 내용을 잊어버리기 때문.

이걸 해결하려면 에이전트가 실수를 기록하고, 다음 세션에서 참조할 수 있어야 함.

---

Kiro Hooks

Kiro의 Hook은 특정 이벤트 발생 시 자동으로 스크립트를 실행하는 기능임. 두 가지 훅을 활용:

• userPromptSubmit: 사용자가 프롬프트를 보낼 때 실행
• postToolUse: 도구 사용 후 실행 (특정 도구에 매칭 가능)

---

error-detector.sh: 명령어 실패 자동 감지

#!/bin/bash
# .kiro/hooks/error-detector.sh
EVENT=$(cat)
EXIT_CODE=$(echo "$EVENT" | jq -r '.tool_response.result.exit_status // empty' 2>/dev/null | grep -oP '\d+$')

if [ -n "$EXIT_CODE" ] && [ "$EXIT_CODE" != "0" ]; then
  echo "Command failed (exit $EXIT_CODE). Log this to .learnings/ERRORS.md with context and suggested fix."
fi
exit 0

postToolUse 훅에 shell 매처로 연결:

"hooks": {
  "postToolUse": [{
    "matcher": "shell",
    "command": ".kiro/hooks/error-detector.sh"
  }]
}

shell 명령어가 실패(exit code ≠ 0)하면 자동으로 에이전트에게 “이거 .learnings/ERRORS.md에 기록해”라고 지시함. 에이전트가 알아서 에러 컨텍스트와 해결 방법을 기록.

---

learning-reminder.sh: 세션 시작 시 학습 상태 알림

#!/bin/bash
# .kiro/hooks/learning-reminder.sh
if [ -d ".learnings" ]; then
  PENDING=$(grep -ch "Status\*\*: pending" .learnings/*.md 2>/dev/null | paste -sd+ | bc 2>/dev/null || echo 0)
  echo "Self-improvement active. ${PENDING} pending entries in .learnings/. Log errors and corrections as they occur."
else
  echo "Self-improvement active. No .learnings/ found — create on first error or correction."
fi

userPromptSubmit 훅에 연결:

"hooks": {
  "userPromptSubmit": [{
    "command": ".kiro/hooks/learning-reminder.sh"
  }]
}

사용자가 메시지를 보낼 때마다 “학습 시스템 활성 상태”를 에이전트에게 상기시킴. pending 항목이 있으면 개수도 알려줌.

---

Self-Improvement 프롬프트

에이전트 설정에 학습 트리거를 정의:

## Self-Improvement
- 명령어 실패 시 → .learnings/ERRORS.md에 기록
- 유저가 교정 시 → .learnings/LEARNINGS.md에 기록 (category: correction)
- 지식이 틀렸을 때 → .learnings/LEARNINGS.md에 기록 (category: knowledge_gap)
- 더 나은 방법 발견 시 → .learnings/LEARNINGS.md에 기록 (category: best_practice)
- 기록 전 기존 항목 검색(grep)하여 중복 방지
- 3회 이상 반복되면 프로젝트 문서로 승격

---

.learnings/ 디렉토리 구조

.learnings/
├── ERRORS.md       # 명령어 실패 기록
├── LEARNINGS.md    # 교정/지식 갭/베스트 프랙티스
└── FEATURE_REQUESTS.md  # 기능 요청 기록

각 항목 형식:

### 2026-03-15 — AWS profile not found

**Category**: correction
**Status**: resolved
**Context**: `sls deploy --stage prod` 실행 시 profile 'cft-deploy' 없다는 에러
**Root Cause**: 로컬 환경에 해당 profile이 설정되지 않음
**Fix**: `aws configure --profile cft-deploy` 로 설정 필요
**Prevention**: deploy 명령은 AI가 실행하지 않음 (workflow-rules 참조)

---

흐름 정리

사용자 메시지 → learning-reminder.sh 실행 → "학습 시스템 활성" 알림
    ↓
에이전트 작업 수행
    ↓
shell 명령어 실행 → error-detector.sh 실행
    ↓ (실패 시)
에이전트가 .learnings/ERRORS.md에 자동 기록
    ↓
다음 세션에서 .learnings/ 참조 → 같은 실수 반복 방지

---

효과

• 에이전트가 같은 에러를 두 번 내지 않음 (기록을 참조하니까)
• 내가 교정한 내용이 영구적으로 남음 (세션 독립적)
• 3회 이상 반복되는 패턴은 프로젝트 문서로 승격되어 규칙화됨
• Hook이 자동으로 트리거하니까 내가 “기록해”라고 말할 필요 없음

---

정리

Kiro Hooks는 단순한 자동화를 넘어서, 에이전트에게 학습 능력을 부여하는 도구임. error-detector로 실패를 감지하고, learning-reminder로 학습 상태를 유지하면, 세션이 바뀌어도 에이전트가 프로젝트의 히스토리를 기억함. 사람으로 치면 “업무 일지 쓰는 신입”을 만든 셈.