Kiro IDE와 함께 일주일 안에 첫 RAG 시스템 구축 🎃

발행: 3일 전 (2025년 12월 3일 오전 03:26 GMT+9)

10 min read

Source: Dev.to

🎃 도전 과제

주니어 앱 개발자로서 나는 RAG(검색 증강 생성) 시스템을 만든 적이 없었다. 벡터 임베딩, 의미 검색, 청크 전략 등은 모두 낯선 영역이었다. 하지만 Kiroween 해커톤의 “Skeleton Crew” 카테고리가 아이디어를 불러일으켰다: 하나의 재사용 가능한 스켈레톤을 만들면 어떤 AI 성격으로도 변신할 수 있다면?

일주일 후, 나는 Project Corpus를 완성했다: 프로덕션 수준의 RAG 챗봇으로, 설정 파일만 바꾸면 전문 법률 보조, 신비한 영혼 등 어떤 역할도 수행할 수 있다.

🔗 Live Demo | GitHub Repo

🔮 Project Corpus란?

Project Corpus는 문서‑채팅 애플리케이션에 변형을 가한 것이다: 동일한 핵심 로직이 전혀 다른 AI 성격을 구동한다.

두 가지 성격, 하나의 스켈레톤

⚖️ Legal Eagle

전문적인 법률 문서 분석
정확한 인용을 포함한 격식 있는 응답
타자기 소리와 함께하는 파란색 기업 스타일링
계약 분석 및 법률 조사에 최적

👻 Ouija Board

“베일 너머”에서 온 신비로운 문서 탐색
괴기 이모지를 곁들인 암호 같은 분위기 응답
피가 흐르는 애니메이션이 있는 어두운 고딕 테마
정적 글리치 효과가 있는 앰비언트 드론 오디오

두 앱은 동일한 skeleton_core 모듈을 공유하며, 설정 파일만 다를 뿐이다.

🛠️ 기술 스택

백엔드

Python 3.13 + Flask 3.1.0
ChromaDB 0.5.20 (벡터 데이터베이스)
Google Gemini API 0.8.3 (임베딩 + 생성)
pypdf 5.1.0 (PDF 처리)

프론트엔드

Vanilla JavaScript (프레임워크 없음)
테마 변수를 활용한 커스텀 CSS
실시간 진행 상황을 위한 Server‑Sent Events

테스트

pytest 7.4.3
hypothesis 6.92.1 (속성 기반 테스트)

개발

Kiro IDE (비밀 무기 🚀)

🤖 Kiro가 내 개발을 바꾼 방법

1. 🎨 Vibe Coding: 배우면서 만들기

주니어 개발자로서 나는 코드만 짜는 것이 아니라 RAG를 이해해야 했다. Kiro의 대화형 접근 방식 덕분에 학습과 구현을 동시에 할 수 있었다.

예시 대화

Me: "How do I chunk PDFs by page and preserve page numbers?"
Kiro: *Explains chunking strategies, then generates code that:*
- Extracts PDF pages individually
- Chunks each page with 500 char / 50 overlap
- Stores metadata with source, page, chunk_index
- Retrieves page numbers in search results

가장 인상 깊은 생성물

Kiro는 한 번의 대화로 전체 Server‑Sent Events 업로드 파이프라인을 만들어냈다. 포함 내용:

Response(stream_with_context()) 를 이용한 Flask SSE 스트리밍
4단계 진행률 계산(읽기, 파싱, 벡터화, 마무리)
진행 바와 함께 동작하는 클라이언트‑사이드 EventSource 리스너
Graceful error handling

SSE를 한 번도 사용해 본 적이 없었지만, Kiro는 코드를 작성할 뿐 아니라 왜 이 경우에 SSE가 폴링보다 좋은지 설명까지 해줬다.

2. 📋 Specs: 체계적인 UI 다듬기

핵심 기능을 vibe coding으로 만든 뒤, 나는 .kiro/spec.md에 원하는 사용자 경험을 기술했다.

## 4. Implemented Features
1. **Document Upload (`/upload`):**
   - Real‑time progress tracking via SSE
   - Page‑aware chunking with metadata
   - File validation (type, size, content)

2. **Chat Interface (`/chat`):**
   - Semantic search with relevance filtering
   - Source citations with page numbers
   - Typewriter effect for responses

스펙이 준비되면 “implement section 4.1” 라고 말하기만 하면 Kiro가 모든 기능을 체계적으로 추가해준다—왕복 대화가 필요 없다.

Vibe Coding vs. Specs

Vibe Coding: 탐색적이며 학습과 핵심 기능 구현에 적합.
Specs: 체계적이며 마무리와 완성도 향상에 최적.

3. 📚 Steering Docs: 내 아키텍처를 Kiro에게 교육하기

프로젝트 DNA를 Kiro에게 가르쳐 주는 네 개의 스티어링 문서를 만들었다.

structure.md – 게임 체인저

### Skeleton + Config Pattern

The `skeleton_core` module contains all shared RAG functionality.  
Individual app folders provide configuration objects that customize behavior.

Each `app_*/config.py` must define:
- `APP_NAME`: String for branding  
- `THEME_CSS`: CSS theme identifier  
- `SYSTEM_PROMPT`: AI personality instructions  
- `CHUNK_SIZE`, `CHUNK_OVERLAP`, `TOP_K_RESULTS`, `RELEVANCE_THRESHOLD`

스티어링 문서 전

Me: “Add a delete document feature”
Kiro: app_legal/main.py 를 직접 수정 ❌ (재사용성 파괴)

스티어링 문서 후

Me: “Add a delete document feature”
Kiro: skeleton_core/vector_store.py 에 delete_document() 추가, /documents/ DELETE 라우트 생성, 프론트엔드 업데이트 ✅ (스켈레톤 패턴 유지)

스티어링 문서는 “잘못된 제안”을 약 80% 감소시켰으며, Kiro가 단순 문법이 아니라 프로젝트 철학을 이해하는 파트너가 되게 했다.

4. 🪝 Agent Hooks: 자동화된 품질 보증

버그를 배포 전에 잡아내는 다섯 개의 훅을 만들었다.

test-runner-on-save.kiro.hook

{
  "when": { "type": "fileEdited", "patterns": ["**/*.py"] },
  "then": { "type": "runCommand", "command": "pytest --tb=short -q" }
}

파일을 저장할 때마다 테스트를 자동 실행해 깨지는 변경을 즉시 포착한다.

config-validator.kiro.hook – 설정 파일에 모든 필수 필드가 존재하는지 검증해 런타임 오류 방지.

env-check-on-session.kiro.hook – 세션 시작 시 GOOGLE_API_KEY 존재 여부를 확인, 디버깅 시간 절감.

Impact – 반응형 디버깅에서 사전 검증 중심 워크플로우로 전환돼, 주니어 개발자에게 안전망을 제공한다.

🧟 가장 큰 도전 과제

1. RAG 학습 곡선

벡터 임베딩, 의미 검색, 청크 방식을 이해하는 것이 압도적이었다. Kiro는 교사 역할을 하며 설명과 솔루션을 제공했고, 검색 결과가 부정확할 때도 도움을 줬다.

해결책: 최상위 매치와 거리 0.3 이내인 문서만 보여주는 relevance filtering을 구현해 정확한 인용을 보장했다.

2. 페이지‑인식 청크

PDF 추출 → 청크 → 임베딩 → 저장 → 검색 전 과정에서 페이지 번호를 유지하려면 메타데이터 관리가 필수였다.

해결책: 각 단계마다 메타데이터에 페이지 정보를 추가했다. 예:

metadata = {
    "source": filename,
    "page": page_num,
    "chunk_index": i
}

3. 테마 전환 아키텍처

하나의 코드베이스에서 극단적으로 다른 성격을 지원하려면 강력한 추상화가 필요했다.

해결책: 설정 기반 접근 방식을 채택해, 새로운 성격을 추가하는 데 약 10분이면 충분하다.

🏆 내가 자랑스러워하는 점

1. 일주일 만에 RAG 습득

RAG에 대한 사전 지식이 전혀 없던 내가 7일 만에 벡터 검색, 임베딩, 의미 검색을 갖춘 프로덕션‑레디 시스템을 만들었다. Kiro의 vibe coding 덕분에 가능했다.

2. 스켈레톤 패턴 실효성

아키텍처가 실제로 재사용 가능하다. 새로운 성격을 추가하는 과정은 다음과 같다:

mkdir app_detective
# Add config.py with Config class
# Add main.py entry point
# Done! 🎉

3. 프로덕션‑급 UI

부드러운 애니메이션(타자기 효과, 피 흐름)
SSE 기반 실시간 업로드 진행 표시
선택적 필터링이 가능한 문서 라이브러리
접근성(ARIA 라벨, 키보드 내비게이션)
테마별 오디오(타자기, 앰비언트 드론)