기술 설계 먼저 (Tech-design-first)
아키텍처와 기술 설계에서 출발해, 그 설계 안에서 실현 가능한 요구사항을 역으로 도출하는 Spec 작성 방식입니다.
이 방식이 적합한 경우
다음과 같은 상황에서 Design-First 워크플로가 강점을 발휘합니다.
- 사용 가능한 기술 스택, 프레임워크, 라이브러리 등 기술적 제약이 이미 명확하게 정해져 있을 때
- 요구사항을 수집하기 전에 아키텍처 자체의 실현 가능성을 먼저 검증하고 싶을 때
- 기존에 작성해 둔 설계 문서나 다이어그램이 있어 이를 출발점으로 삼고 싶을 때
- 팀이 합의한 아키텍처 원칙이 있고 모든 기능이 그 원칙을 따라야 할 때
워크플로 단계
- Feature Spec 생성 — Kiro 패널 또는 command palette에서 새 Spec을 만들고 작성 방식으로
Design-First를 선택합니다. - 상세 수준 선택 — 아래 두 옵션 중 하나를 고릅니다.
- High Level Design: 시스템 아키텍처, 주요 컴포넌트, 비기능 요구사항(NFR) 중심. 복잡한 시스템과 팀 협업, 정식 문서화에 적합합니다.
- Low Level Design: 인터페이스, 자료 구조, 의사 코드 수준의 세부 설계. 빠른 프로토타이핑이나 1인 개발에서 타당성 검증을 빠르게 끝내고 싶을 때 유용합니다.
- Design 단계 — Kiro가 입력한 프롬프트와 제약을 바탕으로
design.md를 생성합니다. 미리보기에서Edit를 눌러 직접 수정하거나, 추가 지시로 보강할 수 있습니다. - Requirements 단계 — 확정된 아키텍처를 기반으로 EARS 형식의 요구사항을 자동으로 도출합니다. 설계 안에서 실제로 구현 가능한 동작만 요구사항으로 들어옵니다.
- Tasks 단계 — Requirements-First와 동일하게 실행 가능한 작업 목록을 생성합니다.
- 구현 — 각 task를 개별 실행하거나 한 번에 일괄 실행해 코드로 옮깁니다.
팁. 프롬프트에 기술 스택과 제약을 함께 적으면 결과가 훨씬 또렷해집니다. 예: “Create an MCP server for querying our Redshift data lake. Must use FastAPI and mcp-python.”
모범 사례
- 기술 제약을 먼저 명확히: 사용해야 하는 언어, 프레임워크, 외부 서비스, 성능 목표 등을 처음부터 명시합니다.
- 요구사항보다 아키텍처를 먼저 다듬기:
design.md가 충분히 안정될 때까지 반복한 뒤 요구사항 단계로 넘어가는 편이 손실이 적습니다. - 팀 프로젝트는 High Level Design: 컴포넌트 경계와 NFR을 함께 문서화해 리뷰와 인수 인계를 쉽게 만듭니다.
- 빠른 검증은 Low Level Design: 인터페이스와 의사 코드를 곧장 다뤄 “이 방식이 작동하는가”를 빠르게 확인합니다.
- 기존 설계 업로드: 이미 보유한 설계 문서가 있으면 입력으로 제공해 일관성을 유지합니다.
예시 프롬프트
High Level Design 예시 — AWS 기반 실시간 알림 시스템.
“Design a real-time notification system using AWS services.” 동시 WebSocket 100k, p50 50ms 미만, 오프라인 메시지 영속화, 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만으로 부족할 때는 핵심 모듈에 한해 Low Level Design을 덧붙이는 하이브리드 방식을 사용합니다.
- EARS 요구사항이 빈약 — 도메인 용어와 트리거 조건을 설계에 추가한 뒤 요구사항을 다시 생성합니다.
주의. 설계가 확정되기 전에 Tasks 단계로 넘어가면, 이후 아키텍처 변경 시 task와 코드가 함께 흔들립니다. 가능한 한
design.md 단계에서 충분히 반복하세요.
Design-First의 장점
- 요구사항이 검증된 아키텍처에서 파생되므로 기술적 실현 가능성이 보장됩니다.
- 설계 문서가 자연스럽게 산출물로 남아 온보딩과 리뷰에 그대로 활용됩니다.
- 제약이 분명한 환경에서 불필요한 요구사항·작업이 줄어 구현 단계의 재작업이 감소합니다.