Specs Best Practices

Feature Spec, Bugfix Spec, 그리고 일반 운영 측면에서 자주 묻는 질문을 모아 Spec을 효과적으로 활용하기 위한 권장 패턴을 정리합니다.

Feature Specs

어떤 워크플로를 선택해야 할까?

Feature Spec은 Requirements-First와 Design-First 두 가지 흐름을 제공합니다. 상황에 맞는 쪽을 고르세요.

Requirements-First를 선택해야 할 때

• 원하는 시스템 동작이 비교적 명확합니다.
• 아키텍처를 유연하게 조정할 여지가 있습니다.
• 고객 피드백 기반으로 기능을 만들고자 합니다.
• 특정 기술 제약 없이 시작합니다.

Design-First를 선택해야 할 때

• 기존 기술 설계나 아키텍처가 이미 존재합니다.
• 지연 시간, 처리량, 컴플라이언스 같은 비기능 요구사항이 엄격합니다.
• 특정 기술 스택으로 프로토타이핑을 진행합니다.
• 범위 확정 전에 기술적 실현 가능성을 검증해야 합니다.

Spec 시작 후 워크플로를 바꿀 수 있나?

아니요. 워크플로는 생성 시점에 선택하며, 이후 전환은 지원하지 않습니다. 변경이 필요하면 새 Feature Spec을 만들고 기존 내용을 옮겨 붙이세요.

같은 프로젝트에서 두 워크플로를 모두 쓸 수 있나?

네. 예를 들어 다음과 같이 단계적으로 사용할 수 있습니다.

1. Design-First로 기술적 실현 가능성을 먼저 검증합니다.
2. 그 다음 Requirements-First Spec을 만들어 본격적인 기능 개발로 넘어갑니다.

기존 디자인이나 아키텍처를 가져오려면?

1. Design-First 활용: Design-First로 새 Feature Spec을 만들고 다이어그램(PNG, JPG)을 업로드하거나 설계 내용을 붙여넣습니다. Kiro가 이를 정리해 design.md로 만들고 거기서 요구사항을 도출합니다.
2. 이미지 활용: draw.io, Lucidchart에서 export한 파일이나 화이트보드 사진을 초기 프롬프트에 함께 첨부합니다.
3. MCP 연동: 디자인 도구가 지원한다면 MCP server를 통해 연결합니다.

기존 요구사항을 가져오려면?

1. MCP 연동: JIRA, Confluence 등을 MCP server를 통해 연결합니다. 로컬과 원격 MCP 모두 사용할 수 있습니다.
2. 수동 가져오기: foo-prfaq.md 같은 요구사항 문서를 저장소에 복사한 뒤 Spec 세션에서 #foo-prfaq.md Generate a spec from it처럼 지시합니다.

Feature Spec을 어떻게 반복 개선하나?

Requirements-First Spec의 경우

1. 요구사항 갱신: requirements.md를 직접 수정하거나 Kiro에게 지시합니다.
2. 설계 갱신: design.md를 열고 Refine을 눌러 design과 tasks를 함께 갱신합니다.
3. 파일 동기화: tasks.md에서 Sync Files를 선택해 새 task를 새 요구사항에 매핑합니다.

Design-First Spec의 경우

1. 설계 갱신: design.md를 직접 또는 Kiro 세션에서 수정합니다.
2. 요구사항 갱신: 아키텍처 변경 후 Kiro에게 요구사항 검증과 재생성을 요청합니다.
3. 파일 동기화: tasks.md에서 Sync Files를 실행합니다.

Bugfix Specs

좋은 버그 설명은 어떻게 쓰나?

1. 재현 절차 — 정확히 어떤 조건에서 발생하는지
2. 현재 동작 — 실제 결함이 어떤 형태로 나타나는지
3. 기대 동작 — 어떤 결과가 정상인지
4. 제약 — 변경되어선 안 되는 코드나 동작

Bugfix Spec으로 어떻게 회귀를 막나?

Bugfix Spec은 수정 사항과 함께 "유지되어야 할 기존 동작"도 명시적으로 기록합니다. 다음 형태로 작성하세요.

• WHEN [조건] THEN the system SHALL CONTINUE TO [기존 동작]

Kiro는 이 정보를 바탕으로 수정과 기존 동작 보존을 동시에 검증하는 property-based test를 생성합니다.

Bugfix Spec과 즉석 수정, 어떻게 구분할까?

다음과 같다면 Bugfix Spec을 권장합니다.

• 핵심 코드 경로의 버그
• 이전 수정이 회귀를 유발한 적이 있는 영역
• 근본 원인이 불분명한 경우
• 컴플라이언스나 팀 지식 보존을 위해 문서화가 필요한 경우

오타, 간단한 로직 오류, 한 줄 수정은 채팅으로 빠르게 처리해도 무방합니다.

Bugfix Spec을 Feature Spec으로 전환할 수 있나?

직접 전환은 지원하지 않습니다. 수정에 의미 있는 새 기능이 포함된다면 별도의 Feature Spec을 만드세요.

일반

팀과 Spec을 어떻게 공유하나?

Spec은 버전 관리 대상이므로 코드와 같은 저장소에 두는 것이 가장 단순합니다.

여러 팀에 걸쳐 Spec을 공유할 수 있나?

네. 다음과 같은 패턴이 자주 쓰입니다.

1. 중앙 Spec 저장소 — 공유 Spec만 모은 전용 저장소
2. Git submodule, 패키지 참조, 심볼릭 링크로 각 프로젝트에 연결
3. 크로스 레포 워크플로로 리뷰와 갱신 절차 정착

피드백은 GitHub issue tracker(github.com/kirodotdev)에 남길 수 있습니다.

vibe 세션에서 Spec 세션으로 전환할 수 있나?

네. 대화 도중 Generate spec이라고 입력하면 Kiro가 Spec 세션 시작을 제안합니다.

Spec의 모든 task를 한 번에 실행할 수 있나?

가능합니다. tasks.md에서 Run all Tasks를 누르면 Kiro가 의존성 그래프를 만들어 서로 독립적인 task를 동시에 실행합니다. 미완료 상태의 필수 task만 실행 대상입니다.

Task가 병렬로 실행되나?

네. Run all Tasks를 실행하면 의존성이 없는 task들이 자동으로 wave 단위로 묶여 병렬 처리됩니다.

Quick Plan과 표준 Feature Spec, 언제 무엇을 쓰나?

Quick Plan이 어울리는 상황

• 기능 자체가 충분히 명확한 경우
• 속도가 우선인 빠른 프로토타이핑
• 요구사항/설계 문서를 자주 손보지 않는 경우
• 표준 흐름이 다소 무겁게 느껴졌던 경우

표준 Feature Spec이 어울리는 상황

• 익숙하지 않은 영역을 탐색할 때
• 요구사항과 설계를 반복해 다듬어야 할 때
• 컴플라이언스가 중요한 도메인
• 승인 체크포인트가 팀 협업에 도움이 되는 경우

두 방식 모두 결과물로 requirements.md, design.md, tasks.md를 생성합니다.

요구사항을 언제 분석해야 하나?

요구사항 생성이 끝나면 Analyze Requirements를 눌러 모순, 모호한 표현, 누락 등을 점검합니다. 다음 상황에서 특히 유용합니다.

• 여러 요구사항이 서로 얽힌 복잡한 기능
• 금융, 의료, 컴플라이언스처럼 도메인 민감도가 높은 프로젝트
• Quick Plan으로 자동 생성된 요구사항을 가진 세션

일부 task가 이미 구현되어 있다면?

방법 1. tasks.md의 Sync Files 활용

• tasks.md를 열고 Sync Files를 누르면 Kiro가 이미 완료된 task를 자동으로 표시합니다.

방법 2. Spec 채팅 세션 활용

• Kiro에게 "Check which tasks are already complete"처럼 요청하면 코드베이스를 훑어 완료 항목을 표기합니다.

채팅에서 Spec을 어떻게 참조하나?

#spec을 입력하고 Enter를 누르면 사용 가능한 Spec 목록이 나타납니다. 선택한 Spec의 requirements.md, design.md, tasks.md가 모두 컨텍스트에 포함됩니다.

채팅에서 #spec은 언제 쓰면 좋나?

• task 구현 — 설계와 수용 기준에 맞춰 코드 작성
• Spec 다듬기 — 요구사항/설계/task 변경
• 구현 검증 — 현재 코드가 Spec을 충족하는지 확인
• 아키텍처 질의 — 설계 의사결정에 대한 질문

예시:

#spec:user-authentication implement task 2.3
#spec:user-authentication update the design file to include password reset flow
#spec:user-authentication does my current implementation meet the acceptance criteria for task 7.1?
#spec:user-authentication why did we choose JWT over session-based authentication?

한 저장소에 Spec을 몇 개까지 둘 수 있나?

제한 없습니다. 거대한 단일 Spec보다는 기능 단위로 잘게 나누는 편을 권장합니다.

.kiro/specs/
├── user-authentication/       # 로그인, 가입, 비밀번호 재설정
├── product-catalog/           # 상품 목록, 검색, 필터링
├── shopping-cart/             # 장바구니, 수량 변경, 결제 진입
├── payment-processing/        # 결제 게이트웨이 연동, 주문 확정
└── admin-dashboard/           # 상품 관리, 사용자 분석