기술 설계 먼저 (Tech-design-first)

아키텍처와 기술 설계에서 출발해, 그 설계 안에서 실현 가능한 요구사항을 역으로 도출하는 Spec 작성 방식입니다.

이 방식이 적합한 경우

다음과 같은 상황에서 Design-First 워크플로가 강점을 발휘합니다.

• 빠른 프로토타이핑 — 기술 스택은 이미 알고 있고, 그 안에서 무엇이 가능한지 빠르게 탐색하고 싶을 때
• 기술적 제약 — 시스템이 지연 시간, 처리량, 가동 시간, 컴플라이언스 등 엄격한 비기능 요구사항을 충족해야 할 때
• 기존 설계 — Kiro로 옮겨 올 아키텍처 다이어그램이나 설계 문서가 이미 있을 때
• 실현 가능성 탐색 — 주어진 설계에서 어떤 요구사항이 실현 가능한지 파악하고 싶을 때
• 뚜렷한 기술 선호 — 특정 아키텍처 선호나 제약이 분명할 때

워크플로 단계

1. Feature Spec 생성 — Kiro 패널 또는 command palette에서 새 Spec을 만들고 작성 방식으로 Design-First를 선택합니다.
2. 상세 수준 선택 — 아래 두 옵션 중 하나를 고릅니다.
   • High Level Design: 시스템 아키텍처, 주요 컴포넌트, 비기능 요구사항(NFR) 중심. 복잡한 시스템과 팀 협업, 정식 문서화에 적합합니다.
   • Low Level Design: 인터페이스, 자료 구조, 의사 코드 수준의 세부 설계. 빠른 프로토타이핑이나 1인 개발에서 타당성 검증을 빠르게 끝내고 싶을 때 유용합니다.
3. Design 단계 — Kiro가 입력한 프롬프트와 제약을 바탕으로 design.md를 생성합니다. 미리보기에서 Edit를 눌러 직접 수정하거나, 추가 지시로 보강할 수 있습니다.
4. Requirements 단계 — 확정된 아키텍처를 기반으로 EARS 형식의 요구사항을 자동으로 도출합니다. 설계 안에서 실제로 구현 가능한 동작만 요구사항으로 들어옵니다.
5. Tasks 단계 — Requirements-First와 동일하게 실행 가능한 작업 목록을 생성합니다.
6. 구현 — 각 task를 개별 실행하거나 한 번에 일괄 실행해 코드로 옮깁니다.

모범 사례

• 기술 제약을 먼저 명확히: 사용해야 하는 언어, 프레임워크, 외부 서비스, 성능 목표 등을 처음부터 명시합니다.
• 요구사항보다 아키텍처를 먼저 다듬기: design.md가 충분히 안정될 때까지 반복한 뒤 요구사항 단계로 넘어가는 편이 손실이 적습니다.
• 팀 프로젝트는 High Level Design: 컴포넌트 경계와 NFR을 함께 문서화해 리뷰와 인수 인계를 쉽게 만듭니다.
• 빠른 검증은 Low Level Design: 인터페이스와 의사 코드를 곧장 다뤄 “이 방식이 작동하는가”를 빠르게 확인합니다.
• 기존 설계 업로드: draw.io, Lucidchart 다이어그램이나 손으로 그린 스케치가 있으면 PNG로 내보내거나 사진으로 업로드해 초기 프롬프트에 포함합니다. Kiro가 시각 설계를 아키텍처 문서에 반영합니다.

자주 쓰이는 패턴

패턴 1: 외부 설계 이식

상황: 다른 도구에서 만든 설계 문서나 회의 노트가 있습니다.

1. 설계 내용을 복사하거나 다이어그램을 업로드합니다.
2. Design-First 워크플로를 선택합니다.
3. High Level Design을 고릅니다.
4. Kiro가 설계를 design.md로 정형화하도록 둡니다.
5. 정형화된 설계에서 요구사항을 도출합니다.

패턴 2: 기술 타당성 탐색

상황: 특정 제약 아래에서 어떤 기능이 가능한지 알고 싶습니다.

1. 기술적 제약과 대략적인 아키텍처를 설명합니다.
2. Design-First 워크플로를 선택합니다.
3. 빠른 반복을 위해 Low Level Design을 고릅니다.
4. 생성된 요구사항을 검토해 무엇이 실현 가능한지 확인합니다.
5. 요구사항이 기대와 다르면 아키텍처를 다시 다듬습니다.

패턴 3: 알려진 스택으로 프로토타이핑

상황: 고객이 사용할 서비스(Lambda, S3, DynamoDB)를 정확히 지정했고 빠르게 프로토타입을 만들어야 합니다.

1. 기술 스택과 상위 수준 흐름을 설명합니다.
2. Design-First 워크플로를 선택합니다.
3. 지정된 서비스로 아키텍처를 생성합니다.
4. 시스템이 할 수 있는 일을 보여주는 요구사항을 도출합니다.
5. task를 실행해 프로토타입을 만듭니다.

패턴 4: 엄격한 비기능 요구사항 충족

상황: 시스템이 특정 지연 시간, 처리량, 컴플라이언스 요구사항을 충족해야 합니다.

1. 초기 프롬프트에 비기능 요구사항을 정의합니다.
2. Design-First 워크플로를 선택합니다.
3. 컴플라이언스 접근 방식을 문서화하도록 High Level Design을 고릅니다.
4. 아키텍처가 모든 제약을 충족하는지 검증합니다.
5. 제약 안에서 실현 가능한 요구사항을 도출합니다.

예시 프롬프트

High Level Design 예시 — AWS 기반 실시간 알림 시스템.

“Design a real-time notification system using AWS services.” 동시 WebSocket 100k, 메시지 전달 지연 50ms 미만(<50ms message delivery latency), 오프라인 메시지 영속화, API Gateway WebSocket / Lambda / DynamoDB / SQS 활용.

Low Level Design 예시 — Express용 rate limiter 미들웨어.

“Build a rate limiter middleware for our Express API.” token bucket 알고리즘, 사용자·IP별 제한, Redis로 상태 보관, 엔드포인트별 한도 설정 가능.

자주 겪는 문제

• 요구사항이 설계와 어긋남 — 설계 단계에서 가정과 제약을 충분히 적어두지 않으면 발생합니다. design.md에 NFR과 외부 의존성을 명시하세요.
• 설계가 너무 추상적 — 프롬프트에 기술 세부와 정확한 프레임워크·라이브러리·서비스를 더 적고, 성능 수치와 제약을 포함하며, 더 깊은 문서화가 필요하면 High Level Design을 선택합니다.
• Requirements 이후 설계를 변경해야 할 때 — design.md를 수정한 뒤 Kiro에게 갱신된 아키텍처를 기준으로 요구사항을 검증하도록 요청하고, 필요하면 요구사항을 다시 생성합니다. 이런 반복은 워크플로의 자연스러운 일부입니다.

Design-First의 장점

• 실현 가능한 요구사항 산출 — 요구사항이 검증된 기술 설계에서 파생됩니다.
• 재조정 불필요 — 설계를 탐색하는 동안 요구사항을 다시 맞출 필요가 없습니다.
• 시간·크레딧 절약 — 요구사항과 설계를 오가는 반복이 줄어듭니다.
• 기술 옵션 탐색 — 확정하기 전에 여러 기술 접근 방식을 시도할 수 있습니다.
• 제약을 조기에 검증 — 비기능 요구사항이 실현 가능한지 미리 확인합니다.