사용 사례에서 프로덕션으로
Source: Dev.to
소개
대학에 다닐 때, 새로운 프로젝트 아이디어가 떠오르면 가장 먼저 VS Code를 열고 코드를 쓰기 시작했습니다. 익숙하신가요?
문제는 프로젝트가 방향 없이 성장하고, 계속해서 뭔가를 바꾸며, 언제 *“완료”*됐는지 전혀 알 수 없고, 두 주가 지나도 내가 이해하지 못하는 코드를 만들었으며 결국 다시는 손대지 않는 프로젝트가 된다는 것이었습니다. 제 관점에서는 기술적인 능력의 문제가 아니라, 일을 할 수는 있었지만 프로세스의 문제였다는 것을 나중에 깨달았습니다.
기술 분야에서 커리어를 시작하고 비슷한 상황이라면, 괜찮습니다. 모두 처음엔 그렇게 시작하니까요. 하지만 더 효과적인 방법이 있습니다.
이 글에서는 Kiro를 사용해 아이디어를 사용 사례에서 실제 동작 코드까지 옮겨보겠습니다. Kiro를 처음 사용하고 좀 더 입문적인 내용을 원한다면, Ana Cunha가 작성한 첫 단계 가이드를 시작점으로 활용할 수 있습니다.
프로젝트가 실패하는 이유
제 경험에 비추어 보면, 제 프로젝트 대부분은 나쁜 코드 때문에 실패한 것이 아니라, 해결하고자 하는 문제를 제대로 정의하지 못했기 때문에 실패했습니다.
인공지능을 사용해서 이력서를 구인 공고와 비교하고, 부족한 부분을 알려주는 애플리케이션을 만든다고 상상해 보세요.
어디서부터 시작하시겠습니까? 프론트엔드부터? 데이터베이스부터? 인공지능 통합부터?
제 경력 중 어느 시점에 프리랜서로 일했을 때, 그 경험을 통해 소프트웨어 공학 수업에 가치를 부여하게 되었습니다. 저는 코드는 시작점이 아니라 결과물이라는 사실을 깨달았습니다. 한 줄이라도 코드를 쓰기 전에, 무엇을 만들고 있는지, 그리고 누구를 위한 것인지를 이해해야 합니다.
사용 사례 정의
사용 사례는 단순히 사용자가 시스템과 어떻게 상호작용하는지를 설명하는 것입니다. 건축가의 설계도와 같이 생각하세요: 설계도 없이 집을 짓지 않듯이, 무엇을 만들고 있는지 이해하지 못하고 코딩을 시작해서는 안 됩니다.
필요한 것 (실용 버전)
- 사용자 스토리 – 사용자가 무엇을 하고 싶은지, 그리고 그 이유.
- 수락 기준 – 올바르게 작동하는지 어떻게 알 수 있는지.
- 엔티티 및 관계 – 시스템에 존재하는 “것들”과 그들이 어떻게 연결되는지.
예시: 이력서 비교기
사용자 스토리
구직자로서, 내 이력서를 PDF 또는 텍스트 형식으로 업로드하고 싶습니다, 시스템이 이를 분석하고 구인 공고와 비교할 수 있도록.
De repente ya sabes varias cosas:
- PDF와 텍스트를 지원해야 합니다.
- 두 번째 입력으로 직무 설명이 필요합니다.
- 결과는 비교입니다.
수용 기준
| # | 조건 | 기대 결과 |
|---|---|---|
| 1 | 사용자가 PDF를 업로드할 때 | 시스템은 내용을 올바르게 추출해야 합니다 |
| 2 | 사용자가 지원되지 않는 형식을 업로드하려고 할 때 | 시스템은 유효한 형식을 포함한 오류를 표시해야 합니다 |
이제 무엇을 구축해야 하는지와 언제 “완료”인지 알 수 있습니다.
요구사항에서 코드까지: Spec‑Driven Development (SDD)
Spec‑Driven Development는 먼저 사양을 설계하고 그 다음 구현하는 접근 방식입니다. 네 단계로 나뉩니다:
의도 포착
- 자연어로 만들고자 하는 것을 정의합니다 (사용자 스토리와 수용 기준).
- 목표는 기술자든 비기술자든 모든 사람이 무엇을 만들지 이해하도록 하는 것입니다.
의도를 시스템 청사진으로 변환
- 해당 요구사항을 기술 설계로 변환합니다: 컴포넌트, 통신, 기술 스택.
- 이것이 당신의 아키텍처 설계도입니다.
작업 단위 생성
- 설계를 구체적이고 점진적인 작업으로 나눕니다.
- 각 작업은 작고 명확하며 테스트 가능한 기능을 산출해야 합니다.
구현 및 검증
- 코드를 작성합니다.
- 각 작업은 1단계에서 정의한 수용 기준에 따라 검증됩니다.
💡 참고: 이 프로세스는 새로운 기능을 추가할 때마다 반복됩니다.
이 접근 방식은 특정 도구에 의존하지 않습니다; 텍스트 문서, 화이트보드, 심지어 냅킨을 사용할 수 있습니다. 중요한 것은 코딩하기 전에 생각하는 것입니다.
Kiro와 SDD 흐름
Kiro와 같은 도구는 이 방법론을 구현하고 구조화된 방식으로 단계들을 진행하도록 도와줍니다. Kiro는 세 단계 흐름(1️⃣ requirements, 2️⃣ design, 3️⃣ tasks)을 따르며, 이는 방금 본 내용과 직접 매핑됩니다.
| SDD 단계 | 내용 | Kiro에서 |
|---|---|---|
| 의도 포착 | 자연어로 아이디어를 설명합니다 | Kiro에게 무엇을 만들고 싶은지 말합니다 |
| 시스템 청사진 | 요구사항 + 설계 + 작업 | Kiro가 requirements.md, design.md와 tasks.md를 생성합니다 |
| 작업 단위 | 작업을 실행합니다 | IDE에서 각 task를 실행합니다 |
| 구현 및 검증 | 코드 + 검증 | Kiro가 구현하고, 당신은 수용 기준에 맞춰 검증합니다 |
💡 중요한 팁: AI 도구가 당신의 비판적 사고를 대체하는 것이 아니라 확대합니다. 문서를 만들기 위해 문서를 만드는 것이 아니라 코딩 전에 생각하는 것이 중요합니다. 문서는 그 사고의 결과물입니다.
실용 적용: 이력서 비교기 프로젝트
사용자 스토리 및 수용 기준
애매한 프롬프트인 Kiro를 *“이력서 앱을 만들어줘”*와 같이 여는 대신, 먼저 정의해 둔 사용자 스토리와 수용 기준이 포함된 파일을 작성했습니다:
- 프로젝트 배경
- 사용자는 누구인가
- 무엇을 해야 하는가
- 작동 여부를 어떻게 확인할 것인가
파일 예시:
# Ejemplo de archivo de historias de usuario
---
proyecto: "Generador de CV"
usuario: "Candidato a empleo"
historias:
- id: HU-01
descripción: "Como candidato, quiero crear mi CV a partir de un formulario sencillo para poder exportarlo en PDF."
criterios_de_aceptación:
- "El formulario debe incluir campos obligatorios: nombre, email, experiencia y educación."
- "Al guardar, el CV se genera en formato PDF con el diseño seleccionado."
- "El PDF debe descargarse automáticamente y también estar disponible en la cuenta del usuario."
- id: HU-02
descripción: "Como candidato, quiero previsualizar mi CV antes de descargarlo para asegurarme de que la información está correcta."
criterios_de_aceptación:
- "Debe mostrarse una vista previa en tiempo real mientras el usuario completa el formulario."
- "La vista previa debe reflejar exactamente el diseño final del PDF."참고: 이는 단지 예시일 뿐이며, 스토리와 기준을 프로젝트의 구체적인 요구에 맞게 조정하세요.
프로젝트 컨텍스트
주 사용자: 활발히 구직 중인 사람들
목표: 전문 프로필을 강화하기 위해 이력서의 품질을 향상시키기
스토리 1 – 이력서 업로드 및 분석
사용자로서 구직자
원한다 PDF 또는 텍스트 형식의 이력서를 업로드하고 싶다
목적 시스템이 이를 분석하고 구인 공고와 비교할 수 있도록
수용 기준
- 사용자가 PDF 형식의 이력서 파일을 업로드할 때, 시스템은 문서 내용을 올바르게 추출해야 합니다.
- (여기에 나머지 수용 기준을 추가하세요…)
2단계 – 시스템 청사진
사용 사례를 기반으로 Kiro는 프로젝트 전체 청사진을 구성하는 세 개의 문서를 생성했습니다:
| 문서 | 목적 |
|---|---|
requirements.md | 사용자 스토리를 정식 요구사항으로 확장하고, 용어집(예: Brecha_Crítica, Generador_Recomendaciones)을 포함하며, 수용 기준 및 기술 요구사항(예: PDF 텍스트 추출, 작업 설명 구조화 분석)을 상세히 기술합니다. |
design.md | 기술 아키텍처를 정의합니다: 다이어그램, 데이터 흐름(PDF → 브라우저 → AI), 컴포넌트 간 인터페이스(각 Lambda가 받는 입력과 반환값) 및 오류 처리 전략을 포함합니다. |
tasks.md | 설계를 점진적인 작업으로 분해하고, 각 작업이 구현하는 요구사항과 연결합니다. 명확한 하위 작업과 실행 순서(인프라 → Presigned URL Lambda → PDF 추출 → 등)를 포함합니다. |
참고: Kiro는 처음에 Lambda를 Python으로 제안했지만, 팀은 Rust를 선호했습니다. Kiro는 백엔드에서 Rust를 사용하도록 자동으로 아키텍처, 의존성 및 작업을 조정했습니다.
결과 아키텍처
- 프론트엔드: Astro(현대적인 웹 프레임워크).
- 백엔드: Rust 기반 서버리스 함수, AWS Lambda에 배포.
- AI: Amazon Bedrock(생성형 모델)으로 이력서 분석.
- 임시 저장소: Amazon S3.
첫 번째 코드를 작성하기 전에 모든 것이 정의되었습니다.
단계별 구현
- 모노레포 생성 – Kiro가 프로젝트 구조를 생성했습니다.
- 프론트엔드 초기화 – Astro가 설정되었습니다.
- Rust 워크스페이스 – 환경 및 의존성 설정.
- SAM 템플릿(
template.yaml) – 서버리스 인프라의 기본 틀.
작업 계획 (총 21개)
| Nº | 작업 | 간단한 설명 |
|---|---|---|
| 1 | AWS 인프라 | S3, Cognito, API Gateway, Lambda 구성. |
| 2 | Lambda → Presigned URLs | CV 업로드를 위한 일시적 URL 생성. |
| 3 | PDF 추출 | PDF 내용 파싱 및 정규화. |
| 4 | Bedrock 연동 | 텍스트를 AI에 전송하고 결과 수신. |
| 5 | 응답 파싱 | Bedrock 출력물을 유용한 데이터로 변환. |
| … | … | … |
| 20 | 프론트엔드 – 결과 페이지 | 호환도와 추천 사항 표시. |
| 21 | 최종 배포 | CI/CD 설정 및 배포. |
각 작업은 구현하는 요구사항과 연결되어 있어, 언제든지 무엇을 만들고 왜 만드는지 파악할 수 있습니다.
최종 결과
사용자가:
- 이력서를 업로드 (PDF 또는 텍스트).
- 채용 공고를 붙여넣기.
- 호환성 분석 및 개선 영역 목록을 받음.
모든 것이 텍스트 파일에 작성된 여섯 개의 사용자 스토리에서 구축되었습니다.
반성
최소 30 분을 투자해 무엇을 만들지 생각하고 어떻게 할지 결정하기 전에 고민하면, 이후에 수시간의 좌절을 절약할 수 있습니다.
이 접근 방식이 유용하다고 생각하고 프로젝트에 적용하는 것에 대해 이야기하고 싶다면, LinkedIn에서 저를 찾아주세요.
추가 자료
- Spec‑Driven Development – Kiro
- Kiro 시작 가이드 – Kiro 시작하기: 단계별 튜토리얼 (Ana Cunha)
- AWS Free Tier – 비용 없이 시작하세요.