AWS Kiro 2편—Specs Wave 실행·Steering 아키텍처·Autonomous Agent, 팀 프로덕션에서 살아남는 법

기초편에서 설치하고 첫 스펙 써봤다면, 이제부터가 진짜입니다. Kiro가 단순 코드 생성 도구와 달라지는 지점은 세 가지입니다. 스펙이 코드를 제어하는 방식, Steering이 팀 전체에 적용되는 방식, Autonomous Agent가 백그라운드에서 PR을 열어주는 방식. 이 세 가지를 프로덕션에 박아 넣는 법을 다룹니다.

---

📌 핵심 요약
→ Specs Wave 실행: tasks.md 의존성 그래프 → 병렬 실행 자동화, Wave N까지 순차 완료
→ Bugfix Spec: 버그 수정을 스펙 워크플로우로 — bugfix.md가 회귀 방지 가드레일
→ Steering 4가지 모드(always/auto/fileMatch/manual) 전략적 분리로 컨텍스트 낭비 제거
→ AGENTS.md 표준: Kiro·Claude Code·Cursor 모두 읽는 범용 규칙 파일
→ Skills 시스템: SKILL.md 기반 재사용 가능한 에이전트 역량 패키징
→ Autonomous Agent: 백그라운드에서 스펙 읽고 PR 오픈 — 인간 없이 작업 실행
→ AgentCore 연동: Kiro → Security Agent·DevOps Agent 멀티에이전트 오케스트레이션
→ Bedrock 비용 관리: 모델 라우팅 전략으로 Nova/Sonnet 선택적 사용

---

실전1 — Specs Wave 실행: 병렬 태스크 그래프 제대로 쓰기

기초편에서 tasks.md가 체크리스트로 끝났다면, 심화에서는 의존성 그래프로 씁니다. Kiro는 이걸 읽고 병렬 실행 가능한 Wave를 자동으로 구성합니다.

# tasks.md — 의존성 명시 버전

## Wave 구성 원칙
# Kiro가 이 파일을 읽고 의존성 없는 태스크를 동시 실행 (Wave 1)
# Wave 1 완료 후 의존하는 태스크 실행 (Wave 2) ...

## 구현 태스크

- [ ] 1. DB 스키마 생성 (users, tokens 테이블)
  - 의존성: 없음  ← Wave 1에서 실행

- [ ] 2. JWT 유틸리티 함수 구현 (sign/verify/decode)
  - 의존성: 없음  ← Wave 1에서 병렬 실행

- [ ] 3. 환경변수 설정 (.env 구조 정의)
  - 의존성: 없음  ← Wave 1에서 병렬 실행

- [ ] 4. UserRepository 구현 (findByEmail, findById)
  - 의존성: 태스크 1 (DB 스키마 필요)  ← Wave 2

- [ ] 5. AuthService.login() 구현
  - 의존성: 태스크 2, 4 (JWT + UserRepo 필요)  ← Wave 3

- [ ] 6. AuthService.refresh() 구현
  - 의존성: 태스크 2, 4  ← Wave 3 (5와 병렬 가능)

- [ ] 7. AuthController 라우트 정의
  - 의존성: 태스크 5, 6  ← Wave 4

- [ ] 8. 단위 테스트 작성
  - 의존성: 태스크 5, 6  ← Wave 4 (7과 병렬)

- [ ] 9. 통합 테스트
  - 의존성: 태스크 7, 8  ← Wave 5

[Wave 실행 구조]

Wave 1 ─── 태스크 1, 2, 3 (동시 실행)
              ↓ 완료 후
Wave 2 ─── 태스크 4 (DB 스키마 완료 후)
              ↓ 완료 후
Wave 3 ─── 태스크 5, 6 (동시 실행)
              ↓ 완료 후
Wave 4 ─── 태스크 7, 8 (동시 실행)
              ↓ 완료 후
Wave 5 ─── 태스크 9

→ 의존성 없는 태스크끼리는 동시에 에이전트가 작업
→ 직렬로 쓰면 3일짜리가 Wave 활용하면 1.5일로 줄어듦
→ Quick Plan: 스펙 승인 게이트 없이 3개 파일 자동 생성 후 바로 Wave 실행

---

실전2 — Bugfix Spec: 버그도 스펙으로 잡는다

Bugfix Spec 워크플로우는 버그를 묘사하면 Kiro가 근본 원인 분석, 수정 설계, 회귀 방지까지 단계적으로 안내합니다. 결과물로 나오는 bugfix.md는 현재 동작, 기대 동작, 변경되면 안 되는 것을 명시해 에이전트에게 명확한 가드레일을 줍니다.

# .kiro/specs/auth-refresh-bug/bugfix.md
# Kiro가 자동 생성 — 개발자가 검토 후 수정

## 버그 설명
Refresh Token으로 새 Access Token 요청 시
간헐적으로 401이 반환됨 (재현율 약 30%)

## 현재 동작 (Current Behavior)
- POST /auth/refresh 요청 시
- Redis에서 Refresh Token 조회 성공
- 그럼에도 불구하고 401 Unauthorized 반환
- 서버 로그: "Token validation failed: invalid signature"

## 기대 동작 (Expected Behavior)
- 유효한 Refresh Token 제출 시 200 + 새 Access Token 반환

## 근본 원인 분석 (Root Cause)
- JWT_SECRET 환경변수가 멀티 인스턴스 환경에서
  인스턴스마다 다른 값으로 로드되는 현상
- Lambda cold start 시 시크릿 재로딩 타이밍 이슈

## 수정 방향
- JWT_SECRET을 AWS Secrets Manager에서 캐싱 방식으로 로드
- 초기화 시점에 한 번만 로드, 이후 캐시 사용

## 변경되면 안 되는 것 (Must Not Change)
- 기존 발급된 토큰의 유효성 (마이그레이션 기간 동안)
- /auth/login 엔드포인트 응답 구조
- Refresh Token 만료 기간 (7일)

## 회귀 테스트 요구사항
- [ ] 멀티 인스턴스 환경에서 동일 토큰으로 100회 검증 테스트
- [ ] Secrets Manager 연결 실패 시 graceful degradation 확인

→ 핵심 가치: "변경되면 안 되는 것"을 명시 → 에이전트가 수정 범위 넘어서는 것 방지
→ 기존 방식: "버그 고쳐줘" → 에이전트가 관련 없는 코드까지 건드림
→ Bugfix Spec: 근본 원인 → 수정 범위 → 회귀 방지까지 구조화
→ bugfix.md도 Git에 커밋 → 나중에 "왜 이렇게 고쳤는지" 추적 가능

---

실전3 — Steering 4가지 모드 전략: 컨텍스트 낭비 없애기

기초편에서는 Steering을 단순히 "영구 컨텍스트"로 썼지만, 심화에서는 4가지 모드를 전략적으로 분리합니다.

# .kiro/steering/typescript-rules.md
---
inclusion: always          ← 항상 로드 (전역 규칙)
---

## TypeScript 규칙 (전체 프로젝트 적용)
- strict mode 필수
- any 타입 사용 금지
- 모든 함수 반환 타입 명시

# .kiro/steering/react-components.md
---
inclusion: fileMatch       ← 파일 패턴 매칭 시만 로드
patterns:
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
---

## React 컴포넌트 규칙
# .tsx 파일 편집할 때만 로드됨 → 백엔드 작업 시 컨텍스트 오염 없음

- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- props 타입은 interface로 선언
- 스타일: TailwindCSS만 (inline style 금지)
- 상태관리: Zustand (Redux 금지)

# .kiro/steering/aws-lambda.md
---
inclusion: auto            ← Kiro가 컨텍스트 보고 자동 판단
description: "Lambda 함수, CDK, Serverless 관련 작업 시 로드"
---

## AWS Lambda 규칙
# CDK 코드나 handler 파일 편집 시 Kiro가 자동으로 이 파일 로드

- 핸들러는 항상 무상태(stateless) 설계
- cold start 최적화: 핸들러 외부에서 초기화
- 타임아웃: 기본 30초, 배치 작업 300초
- 환경변수: Secrets Manager 우선, 직접 주입 금지
- 레이어 사용: 공통 의존성은 Lambda Layer로 분리

# .kiro/steering/security-audit.md
---
inclusion: manual          ← 수동 트리거 시만 로드
---

## 보안 감사 규칙
# /security-audit 명령으로 명시적 호출 시만 적용
# 평상시 로드되면 모든 응답이 보안 중심으로 치우쳐 개발 속도 저하

- OWASP Top 10 전체 항목 체크
- 의존성 CVE 스캔
- 시크릿 하드코딩 감지
- SQL 인젝션·XSS·CSRF 취약점 분석

[Steering 모드 선택 가이드]

always    → 코딩 컨벤션, 언어 규칙, 팀 표준 (항상 필요한 것)
fileMatch → 프레임워크별 규칙 (React/Lambda/DB 파일에만 적용)
auto      → Kiro 판단에 맡길 도메인 규칙 (맥락 의존적인 것)
manual    → 보안감사·성능프로파일링 등 특수 작업 시 호출

→ 실전 권장 구조: 전역 3개(always) + 도메인별 5~8개(fileMatch) + 특수 2~3개(manual)
→ always 파일이 너무 많으면 매 요청마다 컨텍스트 윈도우 낭비
→ 팀 전체 공유: ~/.kiro/steering/ 에 글로벌 파일 → MDM/그룹 정책으로 배포 가능

---

실전4 — AGENTS.md: Kiro·Claude Code·Cursor 한 번에 제어

Kiro는 AGENTS.md 표준을 지원합니다. 글로벌 steering 위치(~/.kiro/steering/)나 워크스페이스 루트에 AGENTS.md를 추가하면 Kiro가 자동으로 읽습니다. Claude Code도, Cursor도 같은 파일을 읽기 때문에 하나만 잘 써도 됩니다.

# AGENTS.md (프로젝트 루트 — 모든 AI 도구가 읽음)

## 프로젝트 개요
- 서비스: 가계부 공유 앱 (React Native + Supabase + Gemini API)
- 팀 규모: 3명
- 배포: AWS Lambda (서버리스) + CloudFront

## 절대 규칙 (모든 AI 도구 공통)
- 환경변수 하드코딩 금지 — .env 또는 Secrets Manager
- console.log 사용 금지 — logger 유틸리티 사용 (src/utils/logger.ts)
- any 타입 사용 금지
- 직접 DB 쿼리 금지 — 반드시 Repository 레이어 통해서

## 아키텍처 패턴
- Controller → Service → Repository 레이어 구조 준수
- 에러: Result<T, E> 패턴 (src/types/result.ts 참조)
- API 응답: { data: T | null, error: string | null, meta?: object }

## 테스트 기준
- 새 기능: 단위 테스트 커버리지 80% 이상 필수
- 수정: 기존 테스트 전부 통과 확인 후 PR

## 금지 라이브러리
- moment.js → date-fns 사용
- lodash → 네이티브 ES2024 메서드 우선
- axios → fetch API (Next.js 환경) 또는 ky

## 코드 리뷰 체크포인트
AI가 코드 생성 후 반드시 자가 점검:
1. 새 의존성 추가했다면 package.json에 명시됐는가?
2. 환경변수 새로 필요하다면 .env.example에 추가됐는가?
3. 새 엔드포인트라면 docs/api.md에 추가됐는가?

→ AGENTS.md 가 Steering 파일과 다른 점: 항상(always) 로드, inclusion 모드 없음
→ 장점: 도구 바꿔도 동일한 규칙 적용 → Kiro·Claude Code 동시에 쓰는 팀에 필수
→ 팀 규칙 변경 시 AGENTS.md 하나만 수정하면 전체 AI 도구 동기화
→ Git으로 관리 → PR 리뷰로 규칙 변경 이력 추적 가능

---

실전5 — Skills 시스템: 재사용 가능한 에이전트 역량 패키징

Skills는 재사용 가능한 에이전트 역량을 패키징하는 시스템입니다. 글로벌 스킬은 ~/.kiro/skills/에 위치하며 모든 워크스페이스에서 사용할 수 있고, 워크스페이스 스킬이 동일 이름이면 우선 적용됩니다.

# 스킬 디렉토리 구조
~/.kiro/skills/
├── code-review/
│   ├── SKILL.md        ← 필수: 스킬 설명 + 사용 방법
│   ├── checklist.md    ← 참조 문서
│   └── examples/       ← 예시 파일
├── api-design/
│   ├── SKILL.md
│   └── openapi-template.yaml
└── security-scan/
    ├── SKILL.md
    └── owasp-checklist.md

# ~/.kiro/skills/code-review/SKILL.md

## Code Review Skill

### 언제 사용하나요?
PR 리뷰 요청이 들어왔거나, 코드 품질 점검이 필요할 때

### 리뷰 체크리스트
1. **보안**: 인젝션, 인증 누락, 시크릿 노출
2. **성능**: N+1 쿼리, 불필요한 루프, 메모리 누수
3. **가독성**: 함수 길이 50줄 이하, 명확한 네이밍
4. **테스트**: 엣지케이스 커버, Mock 적절성
5. **에러 처리**: 모든 예외 처리, 사용자 친화 메시지

### 출력 형식
각 항목을 ✅ PASS / ⚠️ WARN / ❌ FAIL로 표시
WARN·FAIL은 구체적 수정 방법 포함

### 예시 사용법
"이 PR 코드 리뷰해줘" → Kiro가 자동으로 이 스킬 활성화

# ~/.kiro/skills/api-design/SKILL.md

## REST API Design Skill

### 적용 조건
routes/, controllers/, endpoints/ 파일 작업 시 자동 활성화

### API 설계 원칙
- 리소스 중심 URL (동사 금지): /users/{id} ✅  /getUser ❌
- HTTP 메서드 의미 준수
- 페이지네이션: cursor 기반 (offset 금지 — 대용량 비효율)
- 에러 코드: RFC 7807 Problem Details 형식
- 버전: URL 경로 방식 (/v1/, /v2/)

### 자동 생성 산출물
1. OpenAPI 3.1 스펙 (docs/api/[feature].yaml)
2. Postman 컬렉션 (docs/postman/[feature].json)
3. 통합 테스트 케이스 (tests/api/[feature].test.ts)

→ Skills vs Steering 차이:
   Steering: 항상 적용되는 규칙 (언어, 아키텍처)
   Skills:   특정 작업 시 활성화되는 역량 (리뷰, 설계, 스캔)
→ GitHub에서 스킬 임포트 가능: 공개 repo URL만 붙여넣으면 설치
→ 팀 스킬 저장소 만들어서 공유하면 팀 전체 에이전트 역량 표준화 가능

---

실전6 — Autonomous Agent: 백그라운드에서 PR 열어주는 에이전트

Kiro Autonomous Agent는 제품 스펙, ADR, 저장소를 읽고 아키텍처를 이해한 다음 코드를 작성·리팩토링하고 테스트를 작성하며 PR을 엽니다. 목표를 주면 스스로 계획하고 분해하고 실행합니다.

# Autonomous Agent 실전 사용 시나리오

# 시나리오 1: 백로그 태스크 자동 처리
# CodeCatalyst 이슈 #142 내용:
# "사용자 프로필 이미지 업로드 기능 추가 — S3 + CloudFront"

kiro agent run \
  --issue "codecatalyst://my-project/issues/142" \
  --steering ".kiro/steering/" \
  --output "pr"   # 완료 시 자동 PR 오픈

# → 에이전트가:
# 1. 이슈 읽고 스펙 생성 (requirements.md, design.md, tasks.md)
# 2. Steering 파일 로드 (TypeScript 규칙, AWS Lambda 규칙)
# 3. Wave 단위로 구현 (S3 유틸 → 업로드 서비스 → 컨트롤러 → 테스트)
# 4. 완료 후 PR 오픈 (변경 파일 목록 + 스펙 링크 포함)

# 시나리오 2: Security Agent와 협업 (멀티에이전트)
kiro agent run \
  --spec ".kiro/specs/user-auth/tasks.md" \
  --after-impl "invoke:security-agent"
  # 구현 완료 후 Security Agent 자동 호출 → 취약점 리포트 생성

[Autonomous Agent 운영 원칙]

✅ 사용 적합한 작업:
→ 스펙이 명확하게 작성된 백로그 태스크
→ 반복적인 CRUD 엔드포인트 추가
→ 마이그레이션 스크립트 작성
→ 테스트 커버리지 보완

❌ 사용 부적합한 작업:
→ 요구사항이 불명확한 탐색적 기능
→ 기존 아키텍처 대규모 리팩토링
→ 프로덕션 DB에 직접 영향 미치는 작업
→ 외부 API 연동 (자격증명 처리 복잡)

→ 핵심 원칙: Autonomous Agent가 열어준 PR은 반드시 인간이 리뷰
→ "Kiro가 AWS를 날렸다" 사건 이후 위험 행동 전 AgentCore 정책 검사 강화됨

---

실전7 — Bedrock 비용 관리: 모델 라우팅 전략

Kiro는 추론 집약적 스펙 작업에는 Claude Sonnet을, 고처리량 코드 생성에는 Amazon Nova를 라우팅합니다. Bedrock이 통합 모델 플레인입니다. 이 라우팅을 이해하면 비용을 전략적으로 제어할 수 있습니다.

[Kiro 모델 라우팅 원칙]

Claude Sonnet (추론 집약)        Amazon Nova (처리량 집약)
────────────────────────         ──────────────────────────
스펙 생성·분석                    반복 코드 생성
requirements.md 작성             보일러플레이트 구현
아키텍처 설계 판단                단위 테스트 작성
버그 근본 원인 분석               파일 포맷 변환
Steering 규칙 적용 판단           단순 리팩토링

비용: 높음                        비용: 낮음
속도: 느림                        속도: 빠름

# .kiro/config.yaml — 모델 라우팅 커스텀 설정

model_routing:
  spec_generation:   claude-sonnet    # 스펙은 품질 우선
  code_generation:   nova-pro         # 코드 생성은 비용 우선
  test_generation:   nova-lite        # 테스트는 최저 비용
  security_review:   claude-sonnet    # 보안 판단은 품질 필수

cost_controls:
  daily_limit_usd: 50               # 일일 한도 (초과 시 알림)
  nova_preference: true             # 판단 불확실 시 Nova 우선
  log_model_usage: true             # 모델별 토큰 사용량 로깅

[비용 최적화 실전 팁]

→ Hook은 저렴한 모델로: file_save마다 Sonnet 쓰면 하루 수십 달러
→ 스펙 리뷰 단계를 명확히: 승인 전 불필요한 코드 생성 방지
→ Quick Plan 남용 금지: 승인 게이트 없는 Quick Plan은 토큰 낭비 가능
→ Steering 파일 다이어트: always 모드 파일이 많으면 매 요청 토큰 낭비
→ AWS Cost Explorer: Bedrock 항목으로 Kiro 사용량 모니터링

---

실전8 — 팀 도입 체크리스트: Cursor에서 Kiro로 마이그레이션

[단계별 마이그레이션 플랜]

Week 1 — 환경 세팅
  □ AGENTS.md 작성 (팀 공통 규칙)
  □ Steering 파일 구조 설계 (always / fileMatch 분리)
  □ 핵심 Hooks 3개 설정 (테스트 자동생성·보안스캔·API문서)
  □ 글로벌 Skills 라이브러리 초기 세팅

Week 2 — 파일럿 기능 1개
  □ 신규 기능 1개를 Spec 워크플로우로 전체 진행
  □ requirements.md → design.md → tasks.md 팀 리뷰
  □ Wave 실행 결과 품질 확인
  □ Steering 규칙 보완

Week 3 — 팀 전체 적용
  □ 모든 신규 기능 → Spec 워크플로우 의무화
  □ Bugfix Spec 워크플로우 적용 (버그도 스펙으로)
  □ Autonomous Agent 파일럿 (백로그 태스크 1개)
  □ 비용 모니터링 대시보드 세팅

Week 4 — 최적화
  □ 모델 라우팅 설정 튜닝 (비용 vs 품질 균형)
  □ 팀 Skills 라이브러리 확장
  □ PR 리뷰에서 스펙 파일 리뷰 문화 정착
  □ 회고: Cursor 대비 개발 속도·품질 측정

→ 가장 큰 마이그레이션 장벽: 도구 적응이 아니라 "스펙 먼저 쓰는 문화"
→ 코드부터 짜고 싶은 욕구를 Spec 리뷰 단계가 막아줌 → 처음엔 답답, 나중엔 자산
→ Kiro가 Cursor보다 유리한 팀: AWS 스택·협업 중심·장기 유지보수가 많은 팀
→ Kiro가 Cursor보다 불리한 팀: 1인·빠른 프로토타입·비 AWS 스택

---

✅ 심화편 핵심 정리
✅ Wave 실행: tasks.md에 의존성 명시 → 병렬 실행으로 개발 속도 단축
✅ Bugfix Spec: 변경 범위 명시로 에이전트 오버리치 방지 + 회귀 가드레일
✅ Steering 4모드: always/auto/fileMatch/manual 분리로 컨텍스트 낭비 제거
✅ AGENTS.md: Kiro·Claude Code·Cursor 공통 규칙 파일로 도구 간 일관성 확보
✅ Skills: 재사용 가능한 에이전트 역량 패키징 → 팀 표준화
✅ Autonomous Agent: 스펙 기반 백그라운드 PR 자동화 → 인간은 리뷰만

❌ Autonomous Agent는 탐색적 작업·대규모 리팩토링에 부적합
❌ always 모드 Steering 남발 시 매 요청 토큰 낭비
❌ 스펙 없는 Quick Plan 남용 시 품질 보장 불가
❌ "Kiro가 AWS 날렸다" 사건 → 프로덕션 인프라 작업 시 반드시 인간 검토

---

관련글

• AWS Kiro 완전 가이드 — Amazon Q Developer가 죽고 Spec-Driven IDE가 왔다
• CLAUDE.md 잘 쓰는 법
• Spec-Driven Development — Vibe Coding 다음 단계