AI Protégé 구축: Kiro와 함께하는 한 달간의 스펙 기반 개발

Source: Dev.to

저는 현재 자료구조와 알고리즘을 공부하고 있습니다. 교과서는 지루합니다. 챕터를 읽고, 튜토리얼을 보고, 모든 것을 이해한 듯 느끼지만 일주일 뒤면 모두 잊어버립니다.

하지만 누군가에게 무언가를 설명하면 그때는 확실히 기억에 남습니다. 이것이 바로 Feynman Technique—쉽게 설명할 수 없으면 제대로 이해하지 못한 것입니다. 또 rubber‑duck debugging이라는 방법도 있는데, 코드를 고무오리에게 설명하면서 버그를 찾는 방식입니다.

이 두 아이디어를 결합하고 싶었습니다. AI가 나를 가르치는 대신, 내가 AI에게 가르치는 것이죠. 일종의 프랑켄슈타인처럼, 아무것도 모르는 존재에게 지식을 불어넣는 느낌이었습니다.

What I Built

AI Protégé는 AI 학생에게 가르치는 학습 앱입니다. (반대로가 아니라.)

• 배우고 싶은 내용의 URL이나 PDF를 제공합니다.
• 5개의 핵심 개념을 추출합니다.
• 각 개념을 가르칩니다—캔버스에 다이어그램을 그리고, 설명을 작성합니다.
• 다 끝나면 AI가 질문을 던지고, 설명이 명확한지 확인한 뒤, RAG를 이용해 원본 자료와 대조합니다.
• 마지막에 AI가 배운 내용을 요약합니다. 요약이 틀리면, 그것은 여러분의 설명이 부족했기 때문입니다.

AI는 세 가지 입력을 결합합니다: 캔버스 그림(시각), 텍스트 설명, 그리고 원본 자료에서 추출한 관련 청크(RAG). 이 삼중 입력 방식 덕분에 AI가 명확성과 정확성을 동시에 검증할 수 있습니다.

Tech stack: Next.js 15, Convex, Excalidraw, OpenAI, Clerk, Vercel.

The Development Journey

Version 1: The Prototype

첫 번째 버전도 스펙을 사용했습니다. ai-protege-learning-app이라는 레포를 만들어 초기 프로토타입을 정의했는데, 이는 캔버스에 그림을 그리고 AI 피드백을 받을 수 있는 간단한 교육 인터페이스였습니다.

프로토타입은 동작했지만 UX가 거칠었습니다:

• 캔버스가 너무 작았습니다.
• 입력 박스가 두 개로 나뉘어 있었습니다.
• 채팅 패널이 화면을 대부분 차지했습니다.
• 힌트가 일반 메시지와 구분되지 않아 구별하기 어려웠습니다.

The Excalidraw Migration

저는 Excalidraw를 좋아해서 마이그레이션을 결정했습니다(tldraw는 상업용 라이선스가 필요합니다). 예상보다 어려웠는데, Excalidraw 문서에 모든 내용이 정리돼 있지 않아 GitHub 레포를 직접 파고들어 올바른 TypeScript 인터페이스를 찾아야 했습니다.

그 결과는 만족스러웠습니다:

• 전체 화면 캔버스.
• 하나의 집중된 입력 영역.
• 접을 수 있는 대화 패널.
• 명확한 시각적 계층 구조.

The Convex Streaming Problem

가장 어려운 부분이었습니다. 제출 전 마지막 3일을 이 문제에 매달렸고, 새벽 2시까지 작업했습니다.

목표: RAG를 이용해 원본 자료와 대조하면서 AI 응답을 실시간 스트리밍한다.

처음에 Kiro에게 잘못된 문서를 줬습니다—Convex Agents streaming docs. 이 문서는 코드를 실행하고 데이터베이스와 클라이언트에 델타를 스트리밍해야 하는 AI 에이전트를 만들기 위한 것이었습니다. AI Protégé는 에이전트가 아니며 코드를 실행하지 않습니다. 게다가 우리 모델(GPT‑4.1‑nano)은 응답이 너무 빨리 끝나서 클라이언트가 구독을 시도할 때 이미 스트림이 “finished” 상태가 되어버렸습니다.

Kiro는 에이전트 문서를 기반으로 코드를 생성했지만 스트리밍이 조용히 실패했습니다. 제안된 우회 방법은 Vercel AI 액션을 사용해 스트리밍하고, 별도의 Convex 호출로 RAG를 수행하는 것이었지만, 이는 API 호출이 두 번 발생해 지연이 늘어나고, 생성 시작 시점에 RAG 컨텍스트가 누락되는 문제가 있었습니다. 저는 이를 거부했습니다.

Convex 블로그 글을 찾아보다가 persistent text streaming에 관한 기사를 발견했습니다. 해결책은 더 간단했습니다: AI SDK의 streamText를 직접 호출하는 Convex HTTP 액션을 사용하는 것이었습니다. HTTP 액션이 RAG 청크를 가져와 프롬프트에 원본 컨텍스트를 삽입하고, 클라이언트에 스트리밍 응답을 반환합니다. 별도의 에이전트 프레임워크가 필요 없었습니다.

Working with Kiro: What Actually Helped

프로젝트 진행 중 다섯 개의 스펙을 만들었습니다:

• ai-protege-learning-app — 초기 프로토타입
• ai-protege-v2 — 다중 개념 교육 흐름을 위한 전면 재작성
• session-dashboard — 사용자 인증 및 세션 관리
• convex-agent-streaming — RAG 통합
• excalidraw-redesign — 캔버스 라이브러리 마이그레이션

스펙을 더 잘 활용하게 만든 몇 가지 실천법:

1. 먼저 아키텍처를 논의하고 스펙을 작성한다.
   아이디어를 탐색하고, 접근 방식을 토론하고, 엣지 케이스를 고려한 뒤에 스펙을 생성합니다. 이렇게 하면 실제로 이해하고 있는, 충분히 상세한 스펙이 나옵니다.

2. UI 전에 와이어프레임을 만든다.
   Claude는 디자인에 강하지 않으므로, Excalidraw로 와이어프레임을 만든 뒤 스펙에 포함시켜 Kiro에게 시각적 목표를 제시했습니다.

   

3. 관련 문서를 포함한다.
   필요한 페이지만 제공하세요. 잘못된 Convex 문서를 줬을 때 몇 시간을 낭비했지만, 올바른 블로그 글이 스트리밍 문제를 해결했습니다.

4. 깨진 UI는 스크린샷으로 공유한다.
   인터페이스가 이상하게 보일 때 스크린샷을 찍어 채팅에 첨부하면 Kiro가 시각적 문제를 더 잘 디버깅합니다.

5. 수동 테스트 절차를 명시한다.
   스펙의 모든 작업에 검증 단계를 명확히 적어두세요. AI는 자신이 만든 코드를 통과시키는 자동 테스트를 작성하는 경향이 있는데, 수동 체크는 품질을 유지하는 데 도움이 됩니다.

What I’d Do Differently

초기에 더 철저히 계획합니다: 상세 와이어프레임과 사용자 흐름을 먼저 설계하고, 코드 품질 기준을 위한 스티어링 문서를 미리 마련합니다. 마이그레이션은 Kiro와 함께 하면 쉬워집니다—방향을 바꿔야 할 때 새로운 스펙을 만들고 체계적으로 진행하면 됩니다. 스펙 덕분에 전체 과정을 관리하기 쉬웠습니다.

What’s Next

저는 이 앱을 제 개인 학습용으로 만들었기 때문에 계속 사용할 예정입니다. 앞으로의 개선 사항은 버그 수정, 음성 입력/출력, 그리고 AI 학생을 다양한 상황에서 브레인스토밍 파트너로 활용하는 기능 등이 있습니다.

• Try it:
• YouTube demo:
• Built with: Next.js, Convex, Excalidraw, OpenAI, Clerk, Kiro

This project was built for the Kiroween hackathon.