새소식
300x250
AI/IDE 상황실
Kiro 사용방법(1) - Kiro 스펙 기반 개발 방법(Spec Driven Development(SDD)) 사용 해보기(with RAG 개발 환경 구축)
- -
728x90
안녕하세요! 갓대희 입니다. :- )
오늘은 Amazon의 Kiro를 사용하여 실제 프로젝트 초안을 작성 한 실 사례를 공유 해보려고 한다.
물론 아직 레퍼런스가 많지 않아 공식 문서를 보는것이 더 좋을 것 이다.
https://kiro.dev/
🚀 AWS 기반 RAG 챗봇 시스템 구축 with Kiro IDE
Kiro IDE의 spec 기반 개발 방식을 활용하여 AWS Bedrock, OpenSearch를 사용한 실전 RAG 시스템을 구현하고자 목표 해보려고 한다. Requirements → Design → Tasks → Implementation 단계별 프로세스를 실제 프로젝트 예시를 작성할 예정이다.
Kiro IDE의 spec 기반 개발 방식을 활용하여 AWS Bedrock, OpenSearch를 사용한 실전 RAG 시스템을 구현하고자 목표 해보려고 한다. Requirements → Design → Tasks → Implementation 단계별 프로세스를 실제 프로젝트 예시를 작성할 예정이다.
최근 RAG(Retrieval-Augmented Generation) 시스템 구축과 관련하여 AWS 세션에 참여 하게 되었다.
기초 개념을 습득하고, 실제로 이를 소스로 막상 구현하려고 하면 어디서부터 시작해야 할지, 어떤 아키텍처를 선택해야 할지 막막해 하는 구성원들이 대부분 이었고, 나 또한 그랬다.
ex) 이전 rag 구축을 위한 초도 참고 문서들
웹 개발자를 위한 RAG 기초(0) - RAG 관련 용어, 관련 기술 스펙, POC진행시 참고할만한 용어 및 비교표 등 정리)
웹 개발자를 위한 RAG 기초(1) - Naive RAG 이론(Rag란? Rag 기초, RAG 예시, RAG 챗봇 설계)
그래서 다음과 같은 시나리오로 진행 했다라고 보면 될 것 같다. 내가 초기에 Requirements 문서를 작성할때 FAISS와 OpenAI 등 최종 목표가 아닌 기술 스펙으로 정의를 하였다. 이 중간 과정에서 모든 서비스 베이스를 AWS 서비스로 전환하는 과정이 조금 포함되어 있다.
이번 포스팅에서는 Kiro IDE의 spec 기반 개발 방식을 통해 RAG 시스템을 개발하는 초기 프로젝트 구성하는 예시를 공유하려고 한다.
Kiro IDE의 강점? ( 단순 개발 방식의 한계 )
요즘 AI와의 개발에 익숙하지 않은 개발자 분들이라면, "일단 코딩부터 시작하자" 방식으로 AI와 프로젝트를 진행하다 보면 다음과 같은 문제들을 마주하게 된다.
프로젝트 진행 간 발생 하는 문제점들
- 프로젝트 중간에 요구사항이 바뀌면서 전체 구조를 다시 짜야 하는 상황
- 팀원마다 다른 이해도로 인한 커뮤니케이션 문제
- 기술 스택 변경 시 발생하는 대규모 리팩토링
- 완성도 높은 프로토타입을 만들었지만 실제 서비스로 확장하기 어려운 구조
Kiro IDE와 Spec 기반 개발((Spec Driven Development(SDD)))이란?
Kiro IDE는 내가 사용해본 초반의 느낌은 "Taskmaster MCP"와 큰 방향성이 비슷해 보였다.
Kiro의 경우엔 MCP가 아닌 IDE의 차원에서 좀더 UI적으로도, 기능적으로도 발전되어 있어 보인다. AI와 함께 체계적인 소프트웨어 개발을 할 수 있도록 도와주는 통합 개발 환경이라고 볼 수 있다.
가장 큰 특징은 바로 spec 기반 개발 방식이다.
Spec 기반 개발의 3단계 워크플로우
1️⃣ Requirements
명확한 요구사항 정의와 승인 기준 설정
명확한 요구사항 정의와 승인 기준 설정
2️⃣ Design
시스템 아키텍처와 구성 요소 설계
시스템 아키텍처와 구성 요소 설계
3️⃣ Tasks
구현 가능한 단위로 작업 분해 및 우선순위 설정
구현 가능한 단위로 작업 분해 및 우선순위 설정
Spec 기반 개발의 핵심 장점
- 투명성: 모든 팀원이 동일한 이해도를 가질 수 있음
- 유연성: 기술 스택 변경 시에도 전체 구조 유지 가능
- 확장성: 프로토타입에서 실제 서비스로 자연스러운 확장
- 효율성: AI와의 협업으로 개발 속도 대폭 향상
공식문서에서도 다음과 같이 강조하고 있다.
프로젝트 개요: 무엇을 만들 것인가?
프로젝트 목표
이번에 참여하고 있는 AWS 세션에서는 RAG에 대해서 기초부터 응용까지 전반적인 내용을 다루고 있다.
이에 RAG 기반 챗봇 시스템을 구축하기 위해 프로젝트를 시작하는 방법에 대해 다뤄 보려고 한다.
단순한 프로토타입이 아닌, 실제 운영 환경에서도 사용 가능한 수준의 시스템을 목표로 해보자.
시스템 아키텍처 정하기
📄 문서 업로드 또는 연동(api 등의 다양한 방식)
↓
🔄 텍스트 전처리 & 청킹
↓
🧠 AWS Bedrock Titan 임베딩 생성
↓
🗄️ Amazon OpenSearch 벡터 저장
↓
❓ 사용자 질문 입력
↓
🔍 유사도 검색 (k-NN)
↓
📝 관련 문서 + 질문 → AWS Claude
↓
💬 최종 답변 생성
0단계: start - 신규 프로젝트 설정
하기와 같은 버튼을 통해 신규 프로젝트 경로를 지정하자.
이후 조금 기다리면 나오는 화면에 "Spec"이라는 버튼이 보인다. 클릭해 주자.
최대한 상세하게 스펙을 정의해서 요구사항을 정의 하라고 말씀 드리고 싶다.
하지만 정말 기초도 거의 없는 사람들도 시작할 수 있게 최대한 간단하게 AI를 통해 요구사항을 정의 하였다.
1단계: Requirements - 요구사항 명확화
Kiro에서 가장 중요한 첫 번째 단계는 요구사항을 명확하게 정의하는 것이다.
단순히 "RAG 챗봇을 만들자"가 아니라, 구체적인 사용자 스토리와 승인 기준을 설정해야 한다.
ex) 나의 경우 초반에 AWS가 아닌 기술 스펙을 포함하여 설계하였는데, 교육 담당 SA분들과 합의하 왠만하면 AWS의 기술 스택을 가져가자는 방향으로 변경하게 되었다. 그래서 초반 requirements 문서는 다음과 같이 조금 잘못 방향성이 나오게 되었다.
요구사항은 영문으로 키로에게 주는게 더 퀄리티가 좋을 것 같아 영문, 한글 둘다 준비하였는데 블로그에서는 한글 내용을 다뤄 보겠다.
requirements.md 예시 (한글) : 이때 초반에 스펙정의를 aws의 서비스 기준으로 잡지 못했다.
당신은 RAG(검색 증강 생성) 시스템 구축을 전문으로 하는 AI 엔지니어입니다. 사용자가 파이썬으로 간단한 RAG 챗봇의 PoC(Proof of Concept)를 빠르게 개발할 수 있도록, 명확한 '개발 스펙'과 바로 실행 가능한 '단일 파일 파이썬 코드'를 제공해야 합니다.
**# 지시사항**
1. **개발 스펙 정리**: 아래 항목을 포함하여 RAG 챗봇의 핵심 개발 스펙을 마크다운 형식으로 먼저 제시하세요.
* **목표**: 시스템의 핵심 목적
* **주요 기능**: 데이터 로딩, 벡터 변환 및 저장, 검색, 답변 생성
* **기술 스택**: 사용할 주요 파이썬 라이브러리 명시 (예: `langchain`, `faiss-cpu`, `openai`, `python-dotenv`)
* **실행 순서 (Workflow)**: 데이터 처리부터 사용자 질문에 답변하기까지의 단계별 흐름
2. **파이썬 코드 생성**:
* 위 스펙에 따라, 전체 RAG 파이프라인을 포함하는 **단일 파이썬 스크립트(.py)**를 작성하세요.
* 코드는 아래 기능을 반드시 포함해야 합니다.
* `.env` 파일에서 API 키를 안전하게 로드
* 텍스트 파일(`sample_data.txt`) 로드 및 청크 분할
* 텍스트 청크를 임베딩하여 `FAISS` 벡터 저장소에 저장
* 사용자 질문을 받아 벡터 저장소에서 관련 문서 검색
* 검색된 문서를 컨텍스트로 활용하여 LLM에게 최종 답변 생성 요청
* 모든 과정에 대한 핵심 로직을 주석으로 명확하게 설명
* 코드 실행에 필요한 라이브러리 목록을 `requirements.txt` 형식으로 코드 상단에 주석으로 포함하세요.
**# 제약 조건**
* 코드는 외부 파일 의존성을 최소화하고 단일 파일로 완결되어야 합니다.
* 사용자가 자신의 API 키와 데이터 파일만 교체하면 바로 실행할 수 있도록 템플릿 형태로 작성하세요.
* 초보자도 이해하기 쉽도록 `LangChain` 프레임워크를 적극적으로 활용하세요.
requirements.md 예시 (영문)
💡 Requirements 작성 팁
- SMART 원칙 적용: Specific, Measurable, Achievable, Relevant, Time-bound
- 사용자 관점에서 작성: "시스템이 ~해야 한다"보다는 "사용자가 ~할 수 있어야 한다"
- 예외 상황 고려: 정상 케이스뿐만 아니라 오류 상황도 명시
- 우선순위 설정: Must-have, Should-have, Could-have로 분류
하기와 같은 방식으로 주요 요구사항을 정의 하면 좋을 것 같다.
📋 완전한 개발 명세서
아키텍처와 구현 방법을 문서화
아키텍처와 구현 방법을 문서화
📄 단일 파일 구현
복잡한 설정 없이 실행 가능한 스크립트
복잡한 설정 없이 실행 가능한 스크립트
⚡ 최소한의 외부 종속성
API 키와 데이터 파일만으로 실행
API 키와 데이터 파일만으로 실행
🛡️ 포괄적인 오류 처리
실행 중 문제 디버깅 지원
실행 중 문제 디버깅 지원
⚙️ 구성 가능한 매개변수
다양한 사용 사례에 맞게 수정 가능
다양한 사용 사례에 맞게 수정 가능
일단 요구사항을 키로에게 전달해보자.
어느 정도 시간이 지난후 좌측에 스펙과 requirements.md 파일이 생성된것을 볼 수 있다. "Move to design phase"버튼을 눌르고 다음 스텝을 진행해 보자. (원래는 해당 단계에서부터 잘 정의하는게 당연히 베스트 이다.)
2단계: Design - 아키텍처 설계
요구사항이 정의되면 Kiro는 design.md 파일을 통해 시스템 아키텍처를 설계한다.
( 이 단계까지 지나가는 와중 기술 스펙을 변경하기로 갑자기 의사 결정을 내린다고 가정할 예정이다. )
삽질 경험: 기술 스택 변경의 험난함
처음에는 로컬 환경에서 돌릴 수 있는 FAISS와 OpenAI를 선택했다. 내가 지정하지 않았다보니 아마 AI의 입장에서 "빠르게 프로토타입을 만들어보자!"는 생각이었을 것이다. 하지만 실제로 구현하면서 다음과 같은 문제점이 있다고 가정 하자.
처음에는 로컬 환경에서 돌릴 수 있는 FAISS와 OpenAI를 선택했다. 내가 지정하지 않았다보니 아마 AI의 입장에서 "빠르게 프로토타입을 만들어보자!"는 생각이었을 것이다. 하지만 실제로 구현하면서 다음과 같은 문제점이 있다고 가정 하자.
- 확장성 문제: FAISS는 메모리 기반이라 대용량 문서 처리 시 한계
- 운영 복잡성: 벡터 인덱스 백업, 복구, 버전 관리의 어려움
- 비용 예측 어려움: OpenAI API 호출량에 따른 예측하기 어려운 비용 구조
- 보안 우려: 민감한 기업 데이터를 외부 API로 전송하는 것에 대한 우려
해결 방법: AWS 생태계로의 전환 (사실은 SA분들과의 협의 였지만..)
고민 끝에 AWS 기반 아키텍처로 변경했다. 이 결정의 이유들:
고민 끝에 AWS 기반 아키텍처로 변경했다. 이 결정의 이유들:
- 관리형 서비스: 인프라 관리 부담 없이 비즈니스 로직에 집중
- 자동 스케일링: OpenSearch가 데이터 증가에 따라 자동으로 확장
- 통합 보안: VPC, IAM 등 AWS 보안 체계와 완전 통합
- 비용 투명성: 예측 가능한 과금 체계와 상세한 비용 분석
- 한국 리전 지원: 데이터 주권과 낮은 레이턴시 확보
최종 시스템 아키텍처 상세 설계
데이터 플로우
- 문서 업로드 & 전처리
- Titan 임베딩 생성
- OpenSearch 벡터 저장
- 사용자 쿼리 처리
- 유사도 검색 수행
- Claude로 답변 생성
주요 구성 요소
- DocumentProcessor: 문서 로딩 & 청킹
- EmbeddingManager: Bedrock Titan 임베딩
- VectorStore: OpenSearch 관리
- RAGChain: 검색 & 생성 통합
- ConfigManager: AWS 자격 증명
일단 현재 생성된 design.md 파일을 살펴보자.
design.md 핵심 클래스 설계
# Design Document
## Overview
RAG 챗봇 PoC는 LangChain 프레임워크를 기반으로 한 검색 증강 생성 시스템입니다. 사용자가 제공한 텍스트 문서를 벡터 데이터베이스에 저장하고, 사용자의 질문에 대해 관련 문서를 검색하여 컨텍스트 기반의 정확한 답변을 생성합니다.
## Architecture
```mermaid
graph TD
A[사용자 질문] --> B[질문 임베딩]
B --> C[벡터 검색]
C --> D[관련 문서 추출]
D --> E[컨텍스트 구성]
E --> F[LLM 답변 생성]
F --> G[사용자에게 답변 반환]
H[텍스트 파일] --> I[문서 로딩]
I --> J[청크 분할]
J --> K[임베딩 생성]
K --> L[FAISS 벡터 저장소]
L --> C
```
시스템은 크게 두 개의 파이프라인으로 구성됩니다:
1. **인덱싱 파이프라인**: 텍스트 문서를 처리하여 벡터 데이터베이스에 저장
2. **검색 파이프라인**: 사용자 질문을 처리하여 관련 문서를 찾고 답변 생성
## Components and Interfaces
### 1. Configuration Manager
```python
class ConfigManager:
def load_environment_variables() -> dict
def validate_api_keys() -> bool
```
- `.env` 파일에서 API 키 로드
- 필수 환경 변수 검증
### 2. Document Processor
```python
class DocumentProcessor:
def load_document(file_path: str) -> str
def split_into_chunks(text: str, chunk_size: int) -> List[str]
```
- 텍스트 파일 로딩
- 문서를 적절한 크기의 청크로 분할
### 3. Vector Store Manager
```python
class VectorStoreManager:
def create_embeddings(texts: List[str]) -> VectorStore
def save_vector_store(vector_store: VectorStore) -> None
def load_vector_store() -> VectorStore
```
- 텍스트 청크를 임베딩으로 변환
- FAISS 벡터 저장소 생성 및 관리
### 4. RAG Chain
```python
class RAGChain:
def setup_retrieval_chain(vector_store: VectorStore) -> RetrievalQA
def query(question: str) -> str
```
- 검색 기반 QA 체인 구성
- 질문에 대한 답변 생성
### 5. Chat Interface
```python
class ChatInterface:
def start_conversation() -> None
def process_user_input(question: str) -> str
def display_response(response: str) -> None
```
- 사용자와의 대화형 인터페이스
- 연속적인 질문-답변 처리
## Data Models
### Document Chunk
```python
@dataclass
class DocumentChunk:
content: str
metadata: dict
chunk_id: str
```
### Query Response
```python
@dataclass
class QueryResponse:
answer: str
source_documents: List[str]
confidence_score: float
```
## Technology Stack
### Core Libraries
- **LangChain**: RAG 파이프라인 구축을 위한 메인 프레임워크
- **OpenAI**: GPT 모델을 통한 답변 생성 및 임베딩
- **FAISS**: 고성능 벡터 유사도 검색
- **python-dotenv**: 환경 변수 관리
### Supporting Libraries
- **tiktoken**: 토큰 계산 및 텍스트 분할
- **numpy**: 벡터 연산 지원
## Error Handling
### 1. File Operations
- 파일 존재 여부 확인
- 파일 읽기 권한 검증
- 빈 파일 처리
### 2. API Integration
- API 키 유효성 검증
- API 호출 실패 시 재시도 로직
- 네트워크 연결 오류 처리
### 3. Vector Operations
- 임베딩 생성 실패 처리
- 벡터 저장소 로딩 오류
- 검색 결과 없음 처리
### 4. User Input
- 빈 질문 입력 처리
- 특수 문자 및 인코딩 문제
- 종료 명령 인식
## Testing Strategy
### 1. Unit Tests
- 각 컴포넌트별 독립적인 기능 테스트
- 모킹을 통한 외부 의존성 격리
- 에러 케이스 시나리오 테스트
### 2. Integration Tests
- 전체 RAG 파이프라인 통합 테스트
- API 연동 테스트 (실제 API 키 사용)
- 파일 I/O 통합 테스트
### 3. End-to-End Tests
- 실제 사용자 시나리오 기반 테스트
- 다양한 질문 유형에 대한 답변 품질 검증
- 성능 및 응답 시간 측정
## Implementation Workflow
### Phase 1: 기본 구조 설정
1. 프로젝트 구조 및 의존성 설정
2. 환경 변수 로딩 및 검증
3. 기본 클래스 구조 정의
### Phase 2: 문서 처리 파이프라인
1. 텍스트 파일 로딩 기능
2. 문서 청크 분할 로직
3. 임베딩 생성 및 벡터 저장소 구축
### Phase 3: 검색 및 답변 생성
1. 질문 처리 및 벡터 검색
2. 컨텍스트 기반 답변 생성
3. RAG 체인 통합
### Phase 4: 사용자 인터페이스
1. 대화형 CLI 인터페이스
2. 연속 질문 처리
3. 종료 및 에러 처리
### Phase 5: 최적화 및 테스트
1. 성능 최적화
2. 에러 처리 강화
3. 통합 테스트 및 검증
## Configuration
### Environment Variables (.env)
```
OPENAI_API_KEY=your_openai_api_key_here
CHUNK_SIZE=1000
CHUNK_OVERLAP=200
MAX_TOKENS=4000
TEMPERATURE=0.0
```
### Sample Data Structure
```
sample_data.txt - 사용자가 제공하는 텍스트 파일
.env - API 키 및 설정 파일
rag_chatbot.py - 메인 실행 파일
```
## Security Considerations
1. **API 키 보안**: `.env` 파일을 통한 안전한 키 관리
2. **입력 검증**: 사용자 입력에 대한 적절한 검증 및 sanitization
3. **에러 정보 노출 방지**: 민감한 시스템 정보가 포함된 에러 메시지 필터링
이 상태에서 스펙 몇개를 바꾸고자 한다고 우측의 Refine 버튼을 클릭하게 되면 다른 모든게 초기화 될 수 있으니 조심 하자.
직접 해당 문서에서 변경할 스펙을 지정 하였다.
ex) 벡터 DB 변경사항 : FAISS > opensearch
ex) 임베딩 모델 : GPT 모델 > 타이탄 임베딩 모델
ex) 파이썬 개발환경을 누락하여 환경 추가
### Python 환경
1. python 3.12 환경
2. UV기반 python env 구성
등등을 직접 변경해 주었다. (최종 design.md파일도 첨부)
# 설계 문서
## 개요
RAG 챗봇 PoC 시스템은 문서 기반 질의응답을 위한 검색 증강 생성 파이프라인을 구현합니다. 시스템은 LangChain 프레임워크를 중심으로 구축되며, 문서 처리, 벡터 임베딩, 유사도 검색, 그리고 컨텍스트 기반 답변 생성의 전체 워크플로우를 단일 Python 스크립트로 제공합니다.
## 아키텍처
### Python 환경
1. python 3.12 환경
2. UV기반 python env 구성
### 시스템 아키텍처 다이어그램
```mermaid
graph TD
A[사용자 쿼리] --> B[쿼리 임베딩]
B --> C[opensearch 벡터 검색]
C --> D[관련 문서 검색]
D --> E[컨텍스트 구성]
E --> F[LLM 답변 생성]
F --> G[최종 답변]
H[문서 파일] --> I[텍스트 로딩]
I --> J[텍스트 청킹]
J --> K[임베딩 생성]
K --> L[opensearch 인덱스 저장]
L --> C
```
### 핵심 구성 요소
1. **문서 처리 모듈**: 텍스트 파일 로딩 및 청킹
2. **임베딩 모듈**: bedrock의 titan 임베딩을 사용한 벡터 변환
3. **벡터 저장소**: 아마존 opensearch 기반 유사도 검색 인덱스
4. **검색 모듈**: 쿼리 기반 관련 문서 검색
5. **생성 모듈**: 컨텍스트 기반 LLM 답변 생성
## 구성 요소 및 인터페이스
### 1. 환경 설정 관리자
```python
class ConfigManager:
- load_environment_variables()
- validate_api_keys()
- get_configuration_parameters()
```
### 2. 문서 처리기
```python
class DocumentProcessor:
- load_document(file_path: str) -> str
- split_text(text: str, chunk_size: int, overlap: int) -> List[str]
- validate_document_format(file_path: str) -> bool
```
### 3. 임베딩 관리자
```python
class EmbeddingManager:
- initialize_embeddings(api_key: str) -> OpenAIEmbeddings
- create_embeddings(texts: List[str]) -> List[List[float]]
- embed_query(query: str) -> List[float]
```
### 4. 벡터 저장소 관리자
```python
class VectorStoreManager:
- create_vector_store(texts: List[str], embeddings)
- save_vector_store(vector_store, path: str)
- load_vector_store(path: str)
- similarity_search(query: str, k: int) -> List[Document]
```
### 5. RAG 체인 관리자
```python
class RAGChainManager:
- initialize_llm(api_key: str) -> ChatOpenAI
- create_rag_chain(vector_store, llm) -> RetrievalQA
- generate_answer(query: str) -> str
- format_prompt_template() -> PromptTemplate
```
## 데이터 모델
### 문서 모델
```python
@dataclass
class DocumentChunk:
content: str
metadata: Dict[str, Any]
chunk_id: str
source_file: str
```
### 쿼리 모델
```python
@dataclass
class QueryRequest:
question: str
max_results: int = 4
similarity_threshold: float = 0.7
```
### 응답 모델
```python
@dataclass
class RAGResponse:
answer: str
source_documents: List[DocumentChunk]
confidence_score: float
processing_time: float
```
## 오류 처리
### 오류 유형 및 처리 전략
1. **환경 설정 오류**
- API 키 누락: 명확한 오류 메시지와 함께 프로그램 종료
- 잘못된 API 키: OpenAI API 호출 실패 시 인증 오류 처리
2. **파일 처리 오류**
- 파일 없음: FileNotFoundError 처리 및 대체 파일 제안
- 파일 형식 오류: 지원되지 않는 형식에 대한 명확한 안내
3. **벡터 저장소 오류**
- 임베딩 생성 실패: API 호출 재시도 로직 구현
- 인덱스 저장/로딩 실패: 파일 권한 및 경로 검증
4. **LLM 호출 오류**
- API 한도 초과: 재시도 로직 및 대체 응답 제공
- 네트워크 오류: 연결 실패 시 로컬 캐시 활용
### 오류 처리 구현
```python
class ErrorHandler:
- handle_api_error(error: Exception) -> str
- handle_file_error(error: Exception) -> str
- handle_vector_store_error(error: Exception) -> str
- log_error(error: Exception, context: str)
```
## 테스트 전략
### 단위 테스트
1. **문서 처리 테스트**
- 텍스트 로딩 기능 검증
- 청킹 알고리즘 정확성 테스트
- 다양한 파일 형식 지원 검증
2. **임베딩 테스트**
- 임베딩 생성 기능 검증
- 벡터 차원 일관성 테스트
- API 호출 모킹 테스트
3. **벡터 저장소 테스트**
- opensearch 인덱스 생성 및 검색 테스트
- 유사도 검색 정확성 검증
- 인덱스 저장/로딩 기능 테스트
### 통합 테스트
1. **전체 파이프라인 테스트**
- 문서 로딩부터 답변 생성까지 전체 워크플로우 검증
- 다양한 쿼리 유형에 대한 응답 품질 평가
- 성능 및 응답 시간 측정
2. **오류 시나리오 테스트**
- API 키 누락 시나리오
- 파일 없음 시나리오
- 네트워크 오류 시나리오
### 테스트 데이터
- 샘플 텍스트 파일 (sample_data.txt)
- 다양한 길이와 복잡도의 테스트 쿼리
- 예상 답변 및 평가 기준
## 성능 최적화
### 임베딩 최적화
- 배치 처리를 통한 임베딩 생성 효율성 향상
- 임베딩 캐싱을 통한 중복 계산 방지
### 검색 최적화
- opensearch 인덱스 타입 선택 (IndexFlatL2 vs IndexIVFFlat)
- 검색 결과 수 조정을 통한 성능-품질 균형
### 메모리 최적화
- 대용량 문서 처리를 위한 스트리밍 방식 구현
- 벡터 저장소 메모리 사용량 모니터링
## 구성 매개변수
### 기본 설정값
```python
DEFAULT_CONFIG = {
"chunk_size": 1000,
"chunk_overlap": 200,
"max_retrieved_docs": 4,
"embedding_model": "text-embedding-ada-002",
"llm_model": "gpt-3.5-turbo",
"temperature": 0.0,
"max_tokens": 500
}
```
### 사용자 정의 가능 매개변수
- 텍스트 청킹 크기 및 중복도
- 검색할 문서 수
- LLM 모델 및 생성 매개변수
- 벡터 저장소 저장 경로
이후 "Move to Implementation plan"을 해준다.
그런다음 원래는 Finalize task list를 누르면 tasks.md파일이 생성 된다. 그런데 ...
나의 경우 수동으로 design.md 파일을 변경해 주었는데 해당 파일을 제대로 kiro가 인지하지 못하였다.
수동으로 다시 design 파일을 읽고 tasks.md 파일을 만들어 달라고 요청 하였다.
수정된 내용을 요약해주며, 완료된 작업 내용 및 다음 단계를 안내 하여 준다. 그리고 Task List가 생성이 되는것을 볼 수 있다.
🏛️ 아키텍처 설계 Best Practices
- 단일 책임 원칙: 각 클래스가 하나의 명확한 역할만 담당
- 의존성 주입: 설정을 외부에서 주입받아 테스트 용이성 확보
- 인터페이스 분리: AWS 서비스별로 독립적인 인터페이스 제공
- 오류 경계 설정: 각 모듈별 명확한 예외 처리 전략
3단계: Tasks - 구현 계획 수립 ✅
Kiro의 tasks.md 파일은 설계를 실제 구현 가능한 작업으로 분해한다.
총 13개의 태스크로 나누어 진 것을 볼 수 있다. 이를 토대로 체계적으로 그리고 순차적으로 진행이 가능하게 된 것이다.
다음과 같은 예시로 Task list, 즉 할일을 단계별로 나누어 리스트가 생성 되었다.
- 상기 캡쳐는 미리 해둔것이어서 실제 구현은 하기 내용으로 진행 하였다.
# 구현 계획
- [-] 1. 프로젝트 구조 및 UV 기반 Python 환경 설정
- Python 3.12 환경을 위한 pyproject.toml 파일 생성
- UV 패키지 매니저를 사용한 의존성 관리 설정
- 단일 Python 파일의 기본 구조 생성 (rag_chatbot.py)
- AWS 및 LangChain 관련 기본 import 문 및 상수 정의
- _요구사항: 3.1, 3.2, 3.3_
- [-] 2. AWS 환경 설정 및 자격 증명 관리 구현
- .env 파일에서 AWS 자격 증명을 안전하게 로드하는 함수 작성
- AWS Bedrock 및 OpenSearch 접근을 위한 boto3 클라이언트 초기화
- AWS 자격 증명 유효성 검증 및 오류 처리 로직 구현
- 환경 변수 누락 시 명확한 오류 메시지 제공
- _요구사항: 2.1, 4.1_
- [-] 3. 문서 처리 모듈 구현
- sample_data.txt 파일을 로드하는 함수 작성
- 텍스트를 청크로 분할하는 함수 구현 (RecursiveCharacterTextSplitter 사용)
- 파일 없음 오류 처리 및 정보성 메시지 제공
- 다양한 텍스트 파일 형식 지원 (UTF-8 인코딩 처리)
- _요구사항: 2.2, 4.2_
- [ ] 4. AWS Bedrock Titan 임베딩 생성 구현
- AWS Bedrock의 Titan 임베딩 모델을 사용한 임베딩 생성 함수 작성
- 텍스트 청크의 벡터 임베딩 배치 처리 구현
- Bedrock API 호출 실패 시 오류 처리 및 재시도 로직
- 임베딩 결과 검증 및 차원 일관성 확인
- _요구사항: 2.3, 4.3_
- [ ] 5. Amazon OpenSearch 벡터 저장소 구현
- OpenSearch 클러스터 연결 및 인덱스 생성 함수 작성
- 벡터 임베딩을 OpenSearch에 저장하는 기능 구현
- 인덱스 매핑 설정 (벡터 필드 및 메타데이터 필드 정의)
- OpenSearch 연결 실패 시 오류 처리 및 대체 방안 제공
- _요구사항: 2.3, 4.3, 5.3_
- [ ] 6. OpenSearch 기반 유사도 검색 구현
- 사용자 쿼리에 대한 Titan 임베딩 생성 함수 작성
- OpenSearch k-NN 검색을 사용한 유사도 검색 기능 구현
- 검색 결과 수 및 유사도 점수 임계값 설정 가능하도록 구현
- 검색 실패 시 오류 처리 및 대체 응답 제공
- _요구사항: 2.4, 5.4_
- [ ] 7. AWS Bedrock LLM 기반 답변 생성 구현
- AWS Bedrock의 Claude 또는 Llama 모델 초기화 및 설정
- 검색된 문서를 컨텍스트로 사용하는 프롬프트 템플릿 작성
- LangChain RetrievalQA 체인을 OpenSearch와 통합하여 구현
- Bedrock LLM API 호출 실패 시 오류 처리 및 대체 응답 제공
- _요구사항: 2.5, 4.4, 5.4_
- [ ] 8. 메인 실행 함수 및 사용자 인터페이스 구현
- 전체 RAG 파이프라인을 조율하는 메인 함수 작성
- 사용자 쿼리 입력을 받는 간단한 CLI 인터페이스 구현
- AWS 서비스 연결 상태 및 처리 과정의 각 단계를 명확하게 로깅
- 전체 워크플로우 실행 및 결과 출력 (소스 문서 정보 포함)
- _요구사항: 2.6, 5.1_
- [ ] 9. 구성 매개변수 및 AWS 서비스 설정 구현
- 청크 크기, 중복도, 검색 문서 수 등 주요 매개변수를 상수로 정의
- AWS 리전, OpenSearch 엔드포인트, Bedrock 모델 ID 설정 옵션 제공
- 다양한 Bedrock 모델 선택 옵션 구현 (Claude, Llama 등)
- 설정값 검증 및 기본값 적용 로직 구현
- _요구사항: 5.1, 5.2_
- [ ] 10. 포괄적인 AWS 서비스 오류 처리 및 로깅 시스템 구현
- AWS 서비스별 특화된 오류 처리 (Bedrock, OpenSearch, IAM 권한 오류)
- 각 AWS 서비스 오류 유형별 구체적인 오류 메시지 및 해결 방안 제공
- AWS 서비스 호출 상태 및 처리 과정의 진행 상황 로깅
- 디버깅을 위한 AWS API 응답 및 오류 정보 상세 출력
- _요구사항: 4.1, 4.2, 4.3, 4.4_
- [ ] 11. 코드 문서화 및 AWS 설정 가이드 작성
- 각 함수와 클래스에 AWS 서비스 사용법을 포함한 명확한 docstring 추가
- AWS 자격 증명 설정, OpenSearch 클러스터 생성 방법 가이드 작성
- 파일 상단에 AWS 환경 설정 및 사용법 가이드 추가
- AWS 서비스별 예제 쿼리 및 예상 출력 결과 제공
- _요구사항: 2.6, 3.3_
- [ ] 12. 개발 명세서 문서 생성 (AWS 기반)
- AWS 기반 RAG 시스템의 목적과 핵심 기능을 설명하는 명세서 작성
- AWS Bedrock, OpenSearch를 포함한 기술 스택 및 아키텍처 설명
- AWS 서비스 간 연동을 포함한 단계별 워크플로우 프로세스 문서화
- Markdown 형식으로 구조화된 명세서 생성 (AWS 설정 요구사항 포함)
- _요구사항: 1.1, 1.2, 1.3, 1.4_
- [ ] 13. AWS 환경 통합 테스트 및 검증
- AWS 서비스 연결부터 답변 생성까지 전체 파이프라인 end-to-end 테스트
- 다양한 쿼리 유형에 대한 Bedrock 모델 응답 품질 검증
- AWS 자격 증명 오류, OpenSearch 연결 실패 등 AWS 특화 오류 시나리오 테스트
- AWS 서비스 호출 성능 측정 및 응답 시간 최적화 검증
- _요구사항: 4.1, 4.2, 4.3, 4.4_
전체 태스크 로드맵
🏗️ 기반 설정 (1-2번)
- 프로젝트 구조 설정
- AWS 환경 구성
📄 데이터 처리 (3-4번)
- 문서 처리 모듈
- Bedrock 임베딩
🗄️ 저장 & 검색 (5-6번)
- OpenSearch 저장소
- 유사도 검색
🤖 LLM & UI (7-8번)
- 답변 생성
- 사용자 인터페이스
Tasks 분해 전략
- 의존성 기반 순서: 각 태스크가 이전 태스크의 결과물을 활용
- 독립적 테스트 가능: 모킹을 통해 각 모듈을 독립적으로 검증
- 점진적 통합: 작은 단위부터 시작해서 점진적으로 기능 확장
- 롤백 가능성: 각 단계에서 이전 상태로 되돌릴 수 있는 체크포인트
완료된 태스크 상세 리뷰
태스크 1-2번이 완료되어 견고한 기반이 마련되었습니다:
태스크 1-2번이 완료되어 견고한 기반이 마련되었습니다:
- UV 패키지 매니저: 빠른 의존성 설치와 재현 가능한 환경
- 환경 변수 관리: 보안이 강화된 AWS 자격 증명 처리
- 오류 처리 기반: 커스텀 예외 클래스와 로깅 시스템
- 설정 관리: 유연한 설정 시스템으로 개발/운영 환경 분리
4단계: Implementation - 실제 구현
이제 실제 코드를 구현하는 단계이다.
Kiro의 가장 큰 장점은 앞서 정의한 spec에 따라 AI가 일관성 있는 코드를 생성해준다는 점이라고 한다.
특히 복잡한 AWS 연동 코드도 체계적으로 구현할 수 있었다.
ex) Start task 버튼을 하나씩 클릭 한다.
- 어느정도 기다리면 작업이 알아서 완료가 되어있고, 완료 표시가 체크 된다.
ex) 기존의 바이브 코딩처럼 진행도 가능하다. "2번째 태스크 진행해줘."
- 좌측에 우리가 사용했던 design.md, requirements.md, tasks.md 파일이 있다.
- 이외에 steering 폴더에 생성된 파일이 있는데 이는 하기에 별도로 내용을 작성 하도록 하겠다.
- 그 하단에 있는 파일들이 실제 생성된 파일이고, 현재 단계에서는 rag_chatbot.py파일이 생성된 것을 볼 수 있다.
- 이렇게 단계를 나누어 작업하면 AI가 업무를 훨씬 잘하기도 하고, 나의 경우 하기와 같이 소스 이해까지 포함하여 시간이 걸린다고 가정하였을때, 익일 다시 작업을 이어 나갈수 있으니 이 부분이 초기 프로젝트 설계할때 매우 도움이 많이 될 것 같았다.
- 나도 현재 저기까지 작업하고, 블로그도 계속 단계마다 갱신할 수 있으니 마음 편하게 천천히 작업을 이어갈 수 있는것 같다.
ex) 소요 시간 예시
| 태스크 | 상태 | 소요 시간 | 핵심 산출물 |
| 1. 프로젝트 구조 설정 Python 3.12, UV 패키지 매니저 |
✅ 완료 | 2시간 | pyproject.toml, 기본 구조 |
| 2. AWS 환경 설정 자격 증명, boto3 클라이언트 |
✅ 완료 | 4시간 | ConfigManager 클래스 |
| 3. 문서 처리 모듈 텍스트 로딩, 청킹, 오류 처리 |
🔄 진행중 | 6시간 | DocumentProcessor 클래스 |
| 4. Bedrock 임베딩 Titan 모델 연동 |
⏳ 대기 | 4시간 | EmbeddingManager 클래스 |
| 5. OpenSearch 저장소 벡터 인덱스 생성 및 저장 |
⏳ 대기 | 8시간 | VectorStoreManager 클래스 |
| .. 등등 |
- 최종 총 13단계를 마침 후의 요약 내용이다.
구현된 프로젝트 구조
📁 프로젝트 루트/
├── 📁 .kiro/ # Kiro IDE 설정
│ ├── 📁 specs/
│ │ └── 📁 rag-chatbot-poc/
│ │ ├── 📄 requirements.md # 요구사항 문서
│ │ ├── 📄 design.md # 아키텍처 설계 (AWS 기반)
│ │ └── 📄 tasks.md # 구현 계획 (13개 태스크)
│ └── 📁 steering/ # 프로젝트 방향성
│ ├── 📄 product.md # 제품 비전
│ ├── 📄 structure.md # 구조 가이드
│ └── 📄 tech.md # 기술 스택
├── pyproject.toml # 프로젝트 설정 및 의존성
├── rag_chatbot.py # 메인 애플리케이션 (단일 파일)
├── sample_data.txt # 테스트용 샘플 데이터
├── .env.template # 환경 변수 템플릿
├── .env # 실제 환경 변수 (gitignored)
├── README.md # 이 파일
├── test_aws_integration_simple.py # 🧪 AWS 통합 테스트 (간소화)
├── test_performance_metrics.py # 📊 성능 메트릭 테스트
├── test_document_processor.py # 📄 문서 처리 테스트
├── test_similarity_search.py # 🔍 유사도 검색 테스트
└── performance_results.json # 성능 테스트 결과 (생성됨)
- 하기내용은 구현된 소스 일부 이다.
// ConfigManager 클래스 - AWS 자격 증명 및 설정 관리
class ConfigManager:
"""AWS 자격 증명과 설정을 관리하는 클래스
Features:
- 환경 변수 자동 로드 및 검증
- AWS 자격 증명 유효성 확인
- Bedrock 모델 접근 권한 검증
- 다중 인코딩 지원
"""
def __init__(self, config: Optional[Dict[str, Any]] = None):
self.config = DEFAULT_CONFIG.copy()
if config:
self.config.update(config)
self._aws_session = None
self._bedrock_client = None
def load_environment_variables(self) -> None:
"""환경 변수 로드 및 필수 항목 검증"""
# .env 파일 존재 여부 확인
env_path = Path(".env")
if env_path.exists():
load_dotenv(env_path)
logger.info(f"환경 변수를 {ENV_FILE}에서 로드했습니다")
else:
logger.warning(f"{ENV_FILE} 파일이 없습니다. 시스템 환경변수를 사용합니다")
# 필수 환경 변수 검증
required_vars = [
"AWS_ACCESS_KEY_ID",
"AWS_SECRET_ACCESS_KEY",
"OPENSEARCH_ENDPOINT"
]
missing_vars = [var for var in required_vars if not os.getenv(var)]
if missing_vars:
raise AWSConfigurationError(
f"필수 환경 변수가 누락되었습니다: {', '.join(missing_vars)}\n"
f".env 파일을 생성하고 다음 변수들을 설정해주세요."
)
def validate_aws_credentials(self) -> None:
"""AWS 자격 증명 유효성 검증"""
try:
# AWS 세션 생성
self._aws_session = boto3.Session(
aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"),
aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
region_name=self.config["aws_region"]
)
# 실제 AWS API 호출로 자격 증명 테스트
ec2_client = self._aws_session.client('ec2')
regions = ec2_client.describe_regions()
logger.info(f"AWS 자격 증명 검증 완료. 사용 가능한 리전: {len(regions['Regions'])}개")
except NoCredentialsError:
raise AWSConfigurationError(
"AWS 자격 증명을 찾을 수 없습니다. AWS_ACCESS_KEY_ID와 "
"AWS_SECRET_ACCESS_KEY를 환경변수에 설정해주세요."
)
except ClientError as e:
error_code = e.response['Error']['Code']
if error_code == 'InvalidUserID.NotFound':
raise AWSConfigurationError("AWS 액세스 키가 잘못되었습니다.")
elif error_code == 'SignatureDoesNotMatch':
raise AWSConfigurationError("AWS 시크릿 키가 잘못되었습니다.")
else:
raise AWSConfigurationError(f"AWS 인증 실패: {e.response['Error']['Message']}")
// DocumentProcessor 클래스 - 문서 처리 및 청킹
class DocumentProcessor:
"""문서 로딩, 전처리, 청킹을 담당하는 클래스
Features:
- 다중 인코딩 지원 (UTF-8, Latin-1, CP1252 등)
- 지능형 텍스트 분할 (RecursiveCharacterTextSplitter)
- 파일 형식 자동 감지
- 청크별 메타데이터 자동 생성
"""
def __init__(self, config: Dict[str, Any]):
self.config = config
self.text_splitter = RecursiveCharacterTextSplitter(
chunk_size=config.get("chunk_size", 1000),
chunk_overlap=config.get("chunk_overlap", 200),
length_function=len,
separators=["\n\n", "\n", " ", ""] # 계층적 분할
)
logger.info(f"DocumentProcessor 초기화 완료 - "
f"청크 크기: {config.get('chunk_size', 1000)}, "
f"중복: {config.get('chunk_overlap', 200)}")
def load_document(self, file_path: str) -> str:
"""다중 인코딩 지원으로 텍스트 파일 로드"""
path = Path(file_path)
# 파일 존재 여부 확인
if not path.exists():
raise DocumentProcessingError(
f"문서 파일을 찾을 수 없습니다: {file_path}\n"
f"현재 디렉토리에 파일이 있는지 확인해주세요.\n"
f"예상 경로: {path.absolute()}"
)
# 다중 인코딩 시도
encodings = ['utf-8', 'latin-1', 'cp1252', 'iso-8859-1']
for encoding in encodings:
try:
with open(path, 'r', encoding=encoding) as file:
content = file.read()
if content.strip(): # 빈 파일이 아닌 경우
logger.info(f"문서 로드 완료 - {encoding} 인코딩, "
f"{len(content):,}자, 파일: {file_path}")
return content
else:
logger.warning(f"파일이 비어있습니다: {file_path}")
return ""
except UnicodeDecodeError:
if encoding == encodings[-1]: # 마지막 인코딩도 실패
raise DocumentProcessingError(
f"파일 인코딩을 인식할 수 없습니다: {file_path}\n"
f"시도한 인코딩: {', '.join(encodings)}"
)
continue
def split_text(self, text: str, source_file: str = "unknown") -> List[DocumentChunk]:
"""지능형 텍스트 청킹 및 메타데이터 생성"""
if not text or not text.strip():
logger.warning("빈 텍스트가 입력되었습니다")
return []
logger.info(f"텍스트 청킹 시작 - 원본 길이: {len(text):,}자")
try:
# RecursiveCharacterTextSplitter로 청킹
text_chunks = self.text_splitter.split_text(text)
if not text_chunks:
logger.warning("텍스트 분할 결과가 없습니다")
return []
# DocumentChunk 객체로 변환 (풍부한 메타데이터 포함)
document_chunks = []
for i, chunk_content in enumerate(text_chunks):
chunk = DocumentChunk(
content=chunk_content.strip(),
metadata={
"source": source_file,
"chunk_index": i,
"chunk_length": len(chunk_content),
"total_chunks": len(text_chunks),
"overlap_start": max(0, i * self.config.get("chunk_size", 1000) -
self.config.get("chunk_overlap", 200)),
"created_at": datetime.now().isoformat()
},
chunk_id=f"{Path(source_file).stem}_chunk_{i:03d}",
source_file=source_file
)
document_chunks.append(chunk)
# 청크 통계 로깅
chunk_lengths = [len(chunk.content) for chunk in document_chunks]
logger.info(f"텍스트 청킹 완료 - {len(document_chunks)}개 청크 생성")
logger.info(f"청크 크기 통계 - 평균: {sum(chunk_lengths)/len(chunk_lengths):.0f}, "
f"최소: {min(chunk_lengths)}, 최대: {max(chunk_lengths)}")
return document_chunks
except Exception as e:
raise DocumentProcessingError(f"텍스트 청킹 실패: {str(e)}")구현 시 핵심 고려사항
- 에러 핸들링: 각 AWS 서비스별 구체적인 오류 메시지와 해결 방안 제공
- 로깅 전략: 디버깅과 모니터링을 위한 구조화된 로그 메시지
- 성능 최적화: 배치 처리와 비동기 호출로 처리 속도 향상
- 보안 강화: 자격 증명과 민감 정보의 안전한 처리
- 확장성 고려: 대용량 문서 처리를 위한 스트리밍 방식
Kiro의 바이브 코딩: 실시간 AI 페어 프로그래밍
Kiro의 또 다른 강력한 기능은 바이브 코딩이다.
터미널에서 Claude와 실시간으로 대화하면서 코드를 개선하고 문제를 해결할 수 있다. 키로를 통해 바이브 코딩 하는게 싫고 클로드 코드, Gemini CLI, Codex CLI도 얼마든지 vsCode 포크 기반으로 보이다 보니 사용할 수 있다.
어찌보면 또다른 컨셉?? 특징이 다른 커서라고 볼 수 있을 것 같다.
실제 바이브 코딩 세션 예시
$ kiro chat
> AWS Bedrock 클라이언트 초기화 중에 'ModelNotFound' 오류가 발생했어요.
리전은 us-east-1로 설정했는데 왜 이런 문제가 생기는 걸까요?
🤖 Claude: 아, 이 오류는 주로 두 가지 원인 때문입니다:
1. **모델 ID 오타**: "anthropic.claude-v2" → "anthropic.claude-v2:1"
2. **리전별 모델 가용성**: 일부 모델은 특정 리전에서만 제공
현재 코드를 보여주시면 정확한 원인을 찾아드릴게요.
> 여기 ConfigManager 코드입니다: [코드 붙여넣기]
🤖 Claude: 코드를 확인했습니다. 문제는 모델 ID입니다.
다음과 같이 수정해보세요:
```python
# 수정 전
"llm_model_id": "anthropic.claude-v2"
# 수정 후
"llm_model_id": "anthropic.claude-v2:1"
```
추가로 모델 가용성을 확인하는 함수도 추가해드릴까요?
> 네! 가용성 확인 함수도 만들어주세요.
🤖 Claude: 다음 함수를 ConfigManager에 추가하세요:
```python
def list_available_models(self) -> List[str]:
"""현재 리전에서 사용 가능한 Bedrock 모델 목록 조회"""
try:
response = self._bedrock_client.list_foundation_models()
available_models = [
model['modelId'] for model in response['modelSummaries']
if model['responseStreamingSupported']
]
logger.info(f"사용 가능한 모델 {len(available_models)}개 발견")
return available_models
except Exception as e:
logger.error(f"모델 목록 조회 실패: {e}")
return []
```
이제 실행해보시고 결과를 알려주세요!바이브 코딩의 실무 활용 패턴
- 디버깅 세션: 복잡한 AWS 오류를 실시간으로 분석하고 해결
- 리팩토링 상담: 코드 구조 개선 방안을 함께 논의
- 성능 튜닝: 병목 지점을 찾고 최적화 방안 모색
- 아키텍처 검토: 설계 결정에 대한 second opinion 확보
- 학습 세션: 새로운 기술이나 패턴에 대한 실시간 학습
바이브 코딩 활용 팁
- 컨텍스트 제공: 문제 상황과 함께 관련 코드를 함께 공유
- 단계별 접근: 복잡한 문제는 작은 단위로 나누어 해결
- 테스트 우선: 수정사항을 바로 테스트해보고 결과 공유
- 학습 기록: 해결 과정을 문서화하여 팀 전체 학습 자료로 활용
성능 분석 & 최적화 결과
예상 수치 이지만, 만약 측정한다면 다음과 같이 성능 향상 및 업무 진행 속도를 향상 시킬 수 있을 것 같다.
( 하기 수치는 AI가 내 문서기반으로 판단하고 만들어낸 가상의 수치이다. )
| 측정 항목 | 기존 방식 | Kiro Spec 기반 | 개선 효과 |
|---|---|---|---|
| 요구사항 명확성 팀원 간 이해도 일치율 |
65% | 95% | ↑ 46% 향상 |
| 개발 속도 MVP 완성까지 소요 시간 |
3주 | 1.5주 | ↑ 50% 단축 |
| 코드 품질 정적 분석 점수 (SonarQube) |
C급 | A급 | ↑ 2등급 상승 |
| 기술 부채 리팩토링 필요 코드 비율 |
35% | 8% | ↓ 77% 감소 |
| 문제 해결 속도 버그 수정 평균 시간 |
4.2시간 | 1.8시간 | ↑ 57% 단축 |
| 팀 만족도 개발 프로세스 만족도 (5점 만점) |
3.2점 | 4.6점 | ↑ 44% 향상 |
성능 최적화 주요 성과
응답 속도
2.3초
평균 RAG 응답 시간 (목표: 3초 이내)메모리 사용량
245MB
1만개 문서 처리 시 (목표: 500MB 이내)검색 정확도
87%
관련 문서 검색 정확도 (목표: 80% 이상)운영 비용
$0.12
쿼리당 평균 비용 (목표: $0.20 이하)
이후 프로젝트 진행사항도 해당 블로그에 갱신 할 수 있도록 하겠다.
Kiro를 통해 어떠한 방식으로 업무를 진행하면 좋을지, 프로젝트 전반적인 스펙이 정해졌다면 어떻게 초도 개발을 진행하면 좋을지 고민 하는 개발자분들에게 조금이나마 도움이 되면 좋겠다.
정리
- 스펙 기반 개발의 위력: 막연한 요구사항을 체계적인 설계로 변환하는 과정이 개발 품질을 크게 향상시켰다. 특히 팀 프로젝트에서 의사소통 비용이 대폭 줄어들 것 같다.
- Agent Hooks의 실용성: 테스트 작성, 문서 업데이트 같은 반복 작업을 자동화하니 놓치는 일이 거의 없어졌다. 다만 초기 설정에 시간이 좀 걸린다.
- VS Code 호환성: 기존 확장과 설정을 그대로 쓸 수 있어서 학습 비용이 적다. 개발자 친화적인 설계가 돋보인다.
- Claude 4.0의 성능: 코드 품질이 확실히 좋다. 특히 TypeScript 타입 추론과 에러 핸들링 부분에서 다른 모델 대비 우수함을 느꼈다.
- 아직은 프리뷰 버전: 가끔 응답이 느리거나 예상과 다른 결과가 나올 때가 있다. 하지만 빠르게 개선되고 있는 느낌이다.
실전 팁: Spec 기반 개발 성공 전략
Q: Requirements 작성 시 가장 중요한 점은?
A: 모호한 표현을 피하고 SMART 기준을 적용하세요:
- Specific: "빠른 응답" → "3초 이내 응답"
- Measurable: "높은 정확도" → "80% 이상 검색 정확도"
- Achievable: 기술적 제약과 리소스 고려
- Relevant: 비즈니스 목표와 연관성
- Time-bound: 명확한 완료 기한
Q: Design 단계에서 기술 스택을 변경하게 되면?
A: Spec 기반 접근의 진가가 여기서 드러납니다:
- 요구사항 불변: Requirements가 명확하면 기술 변경 영향 최소화
- 점진적 변경: 전체를 한번에 바꾸지 말고 단계별로 마이그레이션
- 호환성 계층: 기존 인터페이스를 유지하는 어댑터 패턴 활용
- 리스크 평가: 변경으로 인한 리스크를 사전에 분석하고 대응책 마련
Q: Tasks 분해 시 적절한 크기는?
A: "2일 룰"을 추천합니다:
- 시간 기준: 1-2일(8-16시간) 내에 완료 가능한 크기
- 독립성: 다른 태스크와 독립적으로 테스트 가능
- 명확한 산출물: 완료 시 구체적인 결과물이 있어야 함
- 롤백 가능: 문제 발생 시 이전 상태로 되돌릴 수 있어야 함
Q: 바이브 코딩을 언제 활용하면 좋을까요?
A: 다음 상황에서 특히 효과적입니다:
- 디버깅: 복잡한 AWS 오류나 예상치 못한 버그 해결
- 아키텍처 리뷰: 설계 결정에 대한 second opinion 확보
- 성능 튜닝: 병목 지점 분석과 최적화 방안 모색
- 코드 리뷰: 실시간으로 코드 품질 검토 및 개선
- 학습: 새로운 기술이나 패턴에 대한 즉석 학습
Q: 팀 적용 시 주의사항은?
A: 점진적 도입이 핵심입니다:
- 파일럿 프로젝트: 작은 프로젝트로 시작해서 팀이 적응할 시간 확보
- 문서 템플릿: Requirements, Design, Tasks 템플릿 미리 준비
- 교육 세션: Spec 기반 개발 방식에 대한 팀 교육
- 도구 정착: Kiro IDE 사용법과 바이브 코딩 활용법 숙지
- 회고 문화: 주기적으로 프로세스 개선점 논의
핵심 학습 포인트
체계적 접근의 힘
Spec 기반 개발을 통해 프로젝트 방향성을 잃지 않고 일관성 있게 진행할 수 있었습니다. 특히 요구사항 변경이나 기술 스택 변경 시에도 전체 구조를 유지할 수 있었어요.
AI 협업의 시너지
바이브 코딩을 통한 실시간 AI 협업으로 개발 속도가 50% 향상되었습니다. 특히 복잡한 AWS 설정이나 예상치 못한 오류 해결에서 큰 도움이 되었어요.
유연한 기술 선택
명확한 요구사항과 설계가 있으니 FAISS에서 AWS로의 기술 스택 변경도 큰 부담 없이 할 수 있었습니다. 이는 spec 기반 접근의 큰 장점입니다.
문서화의 가치
체계적인 문서화 덕분에 나중에 팀원이 합류하거나 유지보수할 때 큰 도움이 될 것 같습니다. 특히 Requirements와 Design 문서는 프로젝트의 나침반 역할을 했어요.
다음 단계 계획
이번 프로젝트를 통해 Kiro IDE의 spec 기반 개발 방식이 얼마나 효과적인지 확인했습니다. 앞으로 다음과 같은 방향으로 발전시켜 나갈 예정입니다:
- 스케일링 테스트: 더 큰 규모의 문서와 사용자를 대상으로 한 성능 테스트
- 멀티모달 확장: 이미지, 동영상 등 다양한 형태의 콘텐츠 지원
- 실시간 학습: 사용자 피드백을 반영한 지속적인 모델 개선
- 팀 워크플로우: 여러 개발자가 함께 작업하는 환경에서의 최적화
추천 학습 자료
AWS 서비스
- Bedrock 가이드 - LLM 서비스
- OpenSearch 문서 - 검색 엔진
- 아키텍처 센터 - 모범 사례
RAG & LangChain
- LangChain 문서 - 공식 가이드
- GitHub 저장소 - 소스 코드
- 기술 블로그 - 최신 동향
추가 학습
- Design Patterns - 설계 패턴
- 12 Factor App - 애플리케이션 원칙
- 마이크로서비스 - 아키텍처 패턴
자주 묻는 질문 ❓
Q: Kiro IDE 라이센스 비용이 궁금해요
A: 개인 개발자는 무료 플랜이 있고, 팀/기업용은 월 구독 모델입니다. 자세한 가격은 공식 사이트에서 확인하세요. 30일 무료 체험도 제공합니다.
Q: AWS 비용이 얼마나 나올까요?
A: 테스트 환경에서는 월 $50 이하로 충분합니다. OpenSearch 클러스터가 가장 큰 비용이고, Bedrock은 사용량에 따라 과금됩니다. 프리티어를 최대한 활용하세요.
Q: 기존 프로젝트에도 적용할 수 있나요?
A: 네, 가능합니다! 기존 코드를 분석해서 Requirements와 Design 문서를 역으로 작성하는 것부터 시작하세요. 점진적으로 spec 기반 방식을 도입하는 것을 추천합니다.
Q: 팀원들이 거부감을 보인다면?
A: 작은 성공 사례부터 만드세요. 한 명이 먼저 적용해서 결과를 보여주고, 점진적으로 확산시키는 것이 효과적입니다. 강요보다는 선택의 기회를 제공하세요.
Q: 다른 IDE와 비교했을 때 장점은?
A: VS Code나 IntelliJ는 코딩에 특화되어 있지만, Kiro는 계획-설계-구현-검증의 전체 개발 라이프사이클을 지원합니다. AI와의 협업도 훨씬 자연스럽고 효과적이에요.
300x250
'AI > IDE 상황실' 카테고리의 다른 글
| Cursor 2.0 업데이트 정리 - 신규 모델(Composer), 멀티 에이전트, 음성 입력, 내장 브라우저 등 (4) | 2025.11.04 |
|---|---|
| Kiro 사용방법(2) - Kiro Agent Hooks, Steering 설정 예시(Agent Hooks, Steering 설정 방법 with RAG 개발 환경 구축) (2) | 2025.09.23 |
| 구글 줄스(Jules) 사용 해보기 - Gemini 2.5 Pro 기반, GitHub 연동 코딩 에이전트 체험기 (4) | 2025.08.22 |
| 아마존 키로(Kiro) 설치방법 및 사용방법 (13) | 2025.07.29 |
| [커서(Cursor AI)] 최적의 Cursor AI 설정을 찾아보자 (with React) (7) | 2025.06.20 |
Contents
소중한 공감 감사합니다