Specs 개요

막연한 아이디어를 요구사항·설계·작업 목록이라는 세 단계의 산출물로 정형화해, 기능 개발과 버그 수정을 체계적으로 끌고 가는 Kiro의 핵심 워크플로우입니다.

Spec이란 무엇인가

Spec은 단순한 메모가 아니라, 한 가지 변경(새 기능 또는 버그 수정)을 끝까지 추적하기 위한 구조화된 문서 묶음입니다. 머릿속에 있는 “이런 걸 만들고 싶다”는 생각을 다음과 같이 단계별로 구체화해 줍니다.

• 요구사항을 사용자 스토리와 수용 기준(acceptance criteria)으로 분해
• 아키텍처와 시퀀스 다이어그램을 포함한 설계 문서 작성
• 실행 가능한 단위 작업(task)으로 쪼개어 진행 상황을 실시간으로 추적
• 제품팀과 엔지니어링팀이 같은 문서를 보면서 협업

세 가지 기본 파일

모든 Spec은 다음 세 개의 마크다운 파일로 구성됩니다. 파일명을 그대로 유지해야 Kiro가 각 단계를 인식하고 UI에서 적절한 액션을 제공합니다.

• requirements.md — 새 기능 Spec에서 사용자 스토리와 수용 기준을 정리하는 파일. 버그 수정의 경우에는 bugfix.md가 그 자리를 대신하며, 현재 동작/기대 동작/변경하지 않을 동작을 함께 기록합니다.
• design.md — 기술 아키텍처, 시퀀스 다이어그램, 에러 처리, 테스트 전략 등 구현 전 결정해야 할 내용을 담습니다.
• tasks.md — 설계를 실제로 옮길 수 있는 단위 작업 목록. 체크박스 형태로 진행 상태가 갱신됩니다.

3단계 워크플로우

1. 요구사항 또는 버그 분석 — 새 기능이라면 requirements.md에 사용자 스토리를 모으고, 버그라면 bugfix.md에 재현 조건과 기대 동작을 정리합니다.
2. 설계 — design.md에 모듈 구조, 데이터 흐름, 시퀀스 다이어그램, 예외 처리 시나리오, 테스트 계획을 담아 구현 전 합의를 마칩니다.
3. 작업 분해 및 실행 — tasks.md가 자동 생성되며, 각 항목은 단독으로 또는 일괄로 실행할 수 있고 상태가 실시간으로 갱신됩니다.

작업(task) 실행 방식

tasks.md는 단순한 텍스트 목록이 아니라 실행 가능한 인터페이스입니다. 각 항목은 진행 중·완료 상태로 자동 전환되며, 완료된 항목은 즉시 체크 표시됩니다.

병렬 실행과 wave 개념

Run all Tasks 버튼을 누르면 Kiro가 작업 간 의존성 그래프를 분석한 뒤 다음과 같이 묶어 실행합니다.

1. Wave 1 — 어떤 선행 작업도 필요 없는 항목을 동시에 실행
2. Wave 2 — Wave 1이 끝나야 비로소 가능한 작업들을 다시 동시 실행
3. Wave N — 모든 작업이 끝날 때까지 같은 패턴을 반복

웨이브 사이는 순차적으로 진행되지만 한 웨이브 안의 작업은 모두 병렬로 처리되므로, 단순히 위에서 아래로 실행하는 것보다 훨씬 빠르게 끝납니다.

Spec의 두 가지 유형

• Feature Specs — 새 기능을 위한 Spec. 요구사항부터 합의하는 Requirements-First, 설계를 먼저 펼쳐 보는 Design-First, 그리고 승인 게이트를 건너뛰고 바로 계획으로 넘어가는 Quick Plan 모드를 제공합니다.
• Bugfix Specs — 버그의 원인을 분석하고, 회귀(regression)를 막기 위한 안전장치까지 함께 설계하는 데 특화된 Spec입니다.

시작하는 방법

1. Kiro 좌측 패널의 Specs 섹션에서 + 버튼을 누르거나, 채팅 패널에서 Spec을 선택합니다.
2. 유형(Feature 또는 Bug)을 고릅니다. 기능이라면 Requirements-First와 Design-First 중 작업 스타일에 맞는 쪽을 선택합니다.
3. 요구사항 → 설계 → 작업 순서로 진행하며 각 단계가 끝날 때마다 검토하고 다음 단계로 넘어갑니다.

Spec과 Vibe, 언제 무엇을 쓸까

• Spec을 쓰는 게 좋은 경우: 여러 모듈을 건드리는 복잡한 기능, 회귀 위험이 큰 버그 수정, 팀 차원의 문서화가 필요한 작업, 요구사항·설계를 반복적으로 다듬어야 하는 상황.
• Vibe가 적합한 경우: 목표가 아직 흐릿한 탐색적 코딩, 빠른 프로토타입, 산출물 추적이 필요 없는 1회성 실험.