Cursor나 Claude Code로 기능을 만들다 보면 이런 상황이 반복돼요.
"분명 요구사항대로 만들었는데 리뷰에서 '이게 아닌데요' 나온다." "3개월 지나서 이 코드 왜 이렇게 짰는지 아무도 모른다." "파일 저장할 때마다 테스트 돌리는 거 깜빡했다."
Kiro의 Specs는 첫 번째와 두 번째 문제를, Hooks는 세 번째 문제를 해결해요.
🔑 핵심 요약
Specs + Hooks 핵심 → Specs: 프롬프트 1줄 → 요구사항(EARS) → 기술 설계 → 태스크 목록 → 구현 자동화 → 스펙 파일은 .kiro/specs/에 Git 버전 관리 — 코드와 함께 이력 추적 → Hooks: 파일 저장·생성·커밋 시 에이전트 자동 실행 → Hook 타입: File Save / File Create / Agent Stop / Prompt Submit / Manual → Hook 액션: Ask Kiro (에이전트 프롬프트) / Run Command (셸 커맨드) → MCP 서버 + Hook 결합 → Figma 디자인 검증, Jira 티켓 업데이트 등 가능
실전 1 — Specs 전체 워크플로우
e-커머스 앱에 리뷰 시스템을 추가하는 예제로 흐름을 설명할게요.
Step 1: 프롬프트 → 요구사항
# Kiro 채팅에 입력
"상품에 리뷰 시스템 추가해줘"
# Kiro가 자동 생성하는 요구사항 (EARS 표기법)
.kiro/specs/product-review-system/requirements.md
## 요구사항
### REQ-001: 리뷰 작성
WHEN 로그인한 사용자가 구매한 상품 상세 페이지를 열 때
THE SYSTEM SHALL 리뷰 작성 폼을 표시해야 한다
- 별점 1~5점 (필수)
- 텍스트 내용 최소 10자 (필수)
- 이미지 첨부 최대 3장 (선택)
### REQ-002: 리뷰 목록 조회
WHEN 사용자가 상품 페이지에 접근할 때
THE SYSTEM SHALL 최신순으로 정렬된 리뷰 목록을 표시해야 한다
- 페이지당 10개
- 별점 필터 (1~5점)
- 평균 별점 표시
### REQ-003: 비로그인 접근 엣지케이스
WHEN 비로그인 사용자가 리뷰 작성 버튼을 클릭할 때
THE SYSTEM SHALL 로그인 페이지로 리다이렉트해야 한다
EARS(Easy Approach to Requirements Syntax): "WHEN [이벤트], THE SYSTEM SHALL [동작]" 형식으로 요구사항을 명시화해요. 모델이 만든 가정이 명시적으로 드러나서 "이게 왜 이렇게 만들어졌지?"가 없어져요. 개발자가 수정하거나 엣지케이스를 추가한 뒤 승인해요.
Step 2: 요구사항 → 기술 설계
요구사항 승인 후 Kiro가 자동 생성:
.kiro/specs/product-review-system/design.md
## 기술 설계
### 데이터 모델
interface Review {
id: string;
productId: string;
userId: string;
rating: number; // 1-5
content: string; // 최소 10자
images: string[]; // S3 URL 배열, 최대 3개
createdAt: Date;
updatedAt: Date;
}
### API 엔드포인트
POST /api/products/:productId/reviews → 리뷰 작성
GET /api/products/:productId/reviews → 리뷰 목록 조회
?page=1&limit=10&rating=5 → 필터/페이지네이션
### 데이터 플로우
[사용자] → [ReviewForm] → [POST /api/reviews]
↓
[ReviewService.create()]
↓
[PostgreSQL reviews 테이블]
↓
[S3 이미지 업로드 (있을 때)]
Step 3: 설계 → 태스크 목록
## 태스크 목록 (.kiro/specs/product-review-system/tasks.md)
- [ ] 1. PostgreSQL reviews 테이블 마이그레이션 생성
- [ ] 2. ReviewService 클래스 구현
- [ ] 2-1. create() 메서드 + 단위 테스트
- [ ] 2-2. getByProductId() 메서드 + 단위 테스트
- [ ] 3. API 엔드포인트 구현
- [ ] 3-1. POST /api/products/:id/reviews
- [ ] 3-2. GET /api/products/:id/reviews (필터 + 페이지네이션)
- [ ] 4. ReviewForm 컴포넌트 구현
- [ ] 4-1. 별점 입력 컴포넌트
- [ ] 4-2. 이미지 업로드 (S3 presigned URL)
- [ ] 4-3. 로그인 상태 체크 + 리다이렉트
- [ ] 5. ReviewList 컴포넌트 구현
- [ ] 6. 통합 테스트 (상품-리뷰 인터랙션)
- [ ] 7. 모바일 반응형 + 접근성 (WCAG 2.1)
태스크 순서가 자동 정렬: 의존성을 분석해서 DB 마이그레이션이 Service보다 먼저, Service가 API보다 먼저 실행돼요. 태스크를 하나씩 클릭해서 실행하고, 코드 diff와 에이전트 실행 이력을 확인할 수 있어요.
스펙의 장점 — 6개월 뒤에도 맥락이 살아있음
기존 AI 코딩 툴:
채팅 로그 → 세션 종료 시 사라짐
코드만 남음 → "왜 이렇게 짰지?" 아무도 모름
Kiro Specs:
.kiro/specs/ → Git에 커밋됨
요구사항 + 설계 + 태스크 + 구현 이력 전부 추적
→ 6개월 뒤 신입 개발자도 맥락 이해 가능
→ 요구사항 변경 시 스펙 수정 → 태스크 자동 갱신
실전 2 — Hooks 실전 패턴 5가지
Hooks는 .kiro/hooks/ 폴더에 정의 파일로 저장돼요. Git에 커밋하면 팀 전체에 동일하게 적용돼요.
Hook 타입 전체 목록:
File Save → 파일 저장 시
File Create → 새 파일 생성 시
Agent Stop → 에이전트 작업 완료 시
Prompt Submit → 프롬프트 제출 시
Manual → 수동 트리거
패턴 1: 테스트 커버리지 자동 유지 (File Save)
# .kiro/hooks/test-coverage.yaml
name: "Test Coverage Maintainer"
trigger:
type: file_save
filePattern: "src/**/*.{js,ts,jsx,tsx}"
action:
type: agent
prompt: |
소스 파일이 수정되면:
1. 새로 추가되거나 수정된 함수/메서드 식별
2. 해당 함수에 대한 테스트 존재 여부 확인
3. 테스트 없으면 → 테스트 케이스 자동 생성
4. 테스트 실행해서 통과 확인
5. 커버리지 리포트 업데이트
패턴 2: 보안 스캔 (Agent Stop)
# .kiro/hooks/security-scan.yaml
name: "Security Scanner"
trigger:
type: agent_stop # 에이전트 작업 완료 후 자동 실행
action:
type: agent
prompt: |
변경된 파일에서 보안 이슈 검토:
1. API 키, 토큰, 크레덴셜 하드코딩 확인
2. 프라이빗 키, 민감 정보 노출 확인
3. 데이터베이스 연결 정보 확인
4. 내부 URL, IP 주소 노출 확인
이슈 발견 시:
→ 구체적인 리스크 설명
→ 안전한 대체 방법 제안
→ 보안 모범 사례 권고
패턴 3: i18n 번역 동기화 (File Save)
# .kiro/hooks/i18n-sync.yaml
name: "i18n Translation Sync"
trigger:
type: file_save
filePattern: "src/locales/en/*.json" # 영어 원본 파일만 감지
action:
type: agent
prompt: |
영어 로케일 파일이 업데이트되면:
1. 추가/수정된 문자열 키 식별
2. 다른 언어 파일에서 해당 키 확인
3. 누락된 키 → "NEEDS_TRANSLATION" 마커 추가
4. 수정된 키 → "NEEDS_REVIEW" 마커 추가
5. 변경 필요 사항 요약 리포트
패턴 4: 문서 자동 생성 (Manual)
# .kiro/hooks/doc-generator.yaml
name: "Documentation Generator"
trigger:
type: manual # 수동 트리거 — 원할 때만 실행
action:
type: agent
prompt: |
현재 파일 문서 생성:
1. 함수/클래스 시그니처 추출
2. 파라미터/반환값 문서화
3. 기존 코드 기반 사용 예시 작성
4. README.md 새 export 항목 업데이트
5. 프로젝트 표준에 맞는 문서 형식 적용
패턴 5: Figma 디자인 검증 (File Save + MCP)
# .kiro/hooks/figma-validation.yaml
name: "Figma Design Validator"
trigger:
type: file_save
filePattern: "src/**/*.{html,css,tsx}"
action:
type: agent
prompt: |
HTML/CSS 컴포넌트가 수정될 때
Figma MCP를 사용해서:
1. 해당 컴포넌트의 Figma 디자인 스펙 조회
2. 수정된 코드와 디자인 스펙 비교
3. 색상, 간격, 폰트 사이즈 불일치 리포트
4. 디자인 토큰 사용 여부 확인
mcp:
- figma # Figma MCP 서버 활성화
팀 전체 동일 품질 적용: Hooks는 .kiro/hooks/에 저장되고 Git에 커밋돼요. 팀 리드가 한 번 설정하면 모든 팀원의 저장 이벤트에 동일하게 적용돼요. 주니어 개발자 출력도 자동으로 같은 품질 기준을 통과해요.
실전 3 — Specs와 Hooks 결합 패턴
두 기능을 같이 쓸 때 진가가 나와요.
전체 개발 루프:
① 스펙 작성 (Specs)
"장바구니에 쿠폰 적용 기능 추가해줘"
→ 요구사항 생성 → 검토 → 승인
② 태스크 실행 (Specs)
태스크 1: DB 스키마 수정
→ 파일 저장 ──────────────────→ Hook 발동!
└→ 테스트 자동 생성
└→ 보안 스캔
태스크 2: API 구현
→ 파일 저장 ──────────────────→ Hook 발동!
└→ README 업데이트
└→ i18n 키 동기화
태스크 3: 프론트엔드 컴포넌트
→ 파일 저장 ──────────────────→ Hook 발동!
└→ Figma 디자인 검증
└→ 접근성 체크
③ 에이전트 완료 (Agent Stop Hook)
→ 보안 스캔 최종 실행
→ 스펙 vs 구현 완료 여부 대조
✅ 결론
✅ Specs의 핵심 가치는 "코드가 아니라 스펙이 소스 오브 트루스"예요. 채팅 로그는 사라지지만 .kiro/specs/는 Git에 살아요. 6개월 뒤에도 왜 이렇게 만들었는지 추적 가능해요.
✅ Hooks가 팀 레벨에서 진짜 강점을 발휘해요. 개인 설정이 아니라 .kiro/hooks/로 Git 커밋되니까, 팀 전체가 동일한 자동화를 적용받아요. 코드 리뷰에서 "테스트 빠뜨렸네요" 같은 피드백이 사라져요.
❌ Specs는 "스펙 세금(Spec Tax)"이 있어요. 단순한 버그 픽스나 작은 변경엔 요구사항 → 설계 → 태스크 과정이 오버헤드예요. 빠른 이터레이션이 필요한 프로토타이핑엔 에이전트 채팅 모드가 더 적합해요.
❌ Hooks는 잘못 설정하면 저장할 때마다 느려져요. 무거운 에이전트 태스크를 File Save에 걸면 개발 속도가 떨어져요. Manual 트리거나 Agent Stop으로 분리하는 게 맞아요.
'Kiro' 카테고리의 다른 글
| AWS Kiro 완전 가이드 1편 — Amazon Q Developer가 사라진 이유와 Kiro가 뭔지 (0) | 2026.06.02 |
|---|