실제로 바로 실행 가능한 6가지 AI 앱 보일러플레이트 구축 (RAG, 리드 스코어링, 고객 지원 분류, 이력서 파서 포함)

Ko-fi: https://ko-fi.com/s/7296aa7d89

AI 기능을 프로토타이핑(prototype)해야 할 때마다, 저는 깔끔한 시작점을 찾아 헤맵니다. 90%의 경우, 제가 발견하는 것은 버전도 추측해야 하는 3개의 패키지를 임포트(import)하고, openai.ChatCompletion.create(구형 API)를 호출하며, 에러 처리(error handling)도 되어 있지 않은 40줄짜리 Python 코드뿐인 Medium 기사입니다. 실행하면 깨지고, 저는 엉뚱한 것을 디버깅(debugging)하느라 한 시간을 허비합니다.

그래서 제가 실제로 시작하고 싶은 버전들을 직접 만들었습니다.

내가 만든 것들

Anthropic SDK를 사용하는 TypeScript 및 Python 기반의 6가지 완전한 AI 앱 레포지토리(repos)입니다:

rag-pdf-chat — PDF를 업로드하면 토큰 인식 분할(token-aware splitting) 방식으로 청킹(chunking)하고, 임베딩(embedding)한 뒤, 벡터 스토어(vector store, 기본값은 인메모리, 환경 변수를 통해 Pinecone 사용 가능)에 저장하여 문서와 채팅할 수 있습니다. 답변에는 소스 청크(source chunks)로 연결되는 인용(citations)이 포함되어 있어, 모델이 환각(hallucination)을 일으키지 않는지 확인할 수 있습니다. Next.js 14 App Router를 사용하며, API 라우트(API routes)로만 구성된 최소한의 UI 페이지를 갖추고 있습니다.

lead-scoring-api — 리드(lead) JSON 페이로드(payload)와 함께 POST /score를 호출하면 { score: 0-100, reasons: string[], tier }를 반환합니다. 가중치(Weights)는 설정 가능합니다 (JSON 파일 또는 환경 변수 사용). 점수가 임계값(threshold)을 넘으면 웹훅(webhook)을 발송하므로, 잠재 고객(hot leads)을 CRM이나 알림 시스템으로 즉시 전달할 수 있습니다.

support-triage-agent — 고객 지원 티켓을 수신하여 분류하는({ category: bug|billing|howto|feature, priority: P0-P3, confidence }) FastAPI 웹훅입니다. 신뢰도(confidence)가 임계값보다 높으면 답장 초안을 작성하고, 낮으면 상담원에게 에스컬레이션(escalate)합니다. LangChain은 사용하지 않았으며, 전체 과정에서 Anthropic SDK와 Pydantic v2 모델만을 사용했습니다.

resume-parser — PDF 또는 DOCX 파일과 함께 POST /parse를 호출하면 Pydantic 스키마(schema)로 검증된 구조화된 JSON을 반환합니다: 연락처 정보, 기술(skills) 배열, 경력(experience) 배열(날짜, 회사, 역할, 불렛 포인트 포함), 학력(education) 배열이 포함됩니다. 텍스트 추출을 위해 pypdf와 python-docx를 사용합니다. 스캔된 이미지 PDF를 위한 OCR 폴백(fallback) 관련 참고 사항이 문서화되어 있습니다.

slack-ai-bot — app_mention 이벤트가 발생하면 채널의 마지막 N개 메시지를 컨텍스트 (context)로 사용하여 Claude가 생성한 응답으로 답장합니다. 이를 통해 응답이 대화 흐름과 일관성을 유지합니다. /summarize 슬래시 커맨드 (slash command)는 스레드 (thread)를 요약합니다. 스레드별 대화 기록은 인메모리 저장소 (in-memory store, 교체 가능한 인터페이스)에 유지됩니다.

web-scraper-llm — { url, schema }를 포함한 POST /scrape 요청을 처리하며, 여기서 스키마 (schema)는 추출하고자 하는 내용을 설명하는 JSON 형태입니다. 앱은 페이지를 가져오고 (User-Agent 풀을 로테이션함), HTML을 텍스트로 정제한 뒤, 이를 Claude에 전달하여 사용자의 스키마와 일치하는 데이터를 반환합니다. 테스트 시 네트워크를 사용하지 않도록 로컬 피스처 (Local-fixture) 모드를 지원합니다.

이 앱들을 실제로 유용하게 만드는 것: 오프라인 테스트

모든 앱에는 API 키나 네트워크 접속 없이도 실행 가능한 테스트 스위트 (test suite)가 포함되어 있습니다. Anthropic 클라이언트는 팩토리 함수 (factory function)를 통해 주입되며, 테스트 시에는 가짜 객체 (fake)로 교체됩니다. Pinecone, Slack, 그리고 HTTP 모두 모킹 (mocked) 처리되었습니다.

app                   tests   result
──────────────────────────────────────
rag-pdf-chat          19      ✓ passed
...

제가 "깔끔하게 빌드된다"고 말하는 의미는 다음과 같습니다: 새로 클론 (clone) 받은 상태에서 npm install && npm run build && npm test가 통과(green)되고, pip install -r requirements.txt && pytest 또한 통과된다는 뜻입니다. CI (지속적 통합)를 위해 별도의 비밀 환경 변수 (secret environment variables)가 필요하지 않습니다.

이것이 생각보다 중요한 이유

AI가 생성한 코드가 실무에서 쓸모없는 경우가 많은 이유는 로직이 틀려서가 아니라, 다음과 같은 "지루한 부분들"이 빠져 있기 때문입니다:

• 락파일 (lockfile)이 없어, npm install 시 사용자의 환경마다 서로 다른 버전이 설치됨
• .env.example이 없어, 무엇을 설정해야 하는지 알 수 없음
• 재시도 로직 (retry logic)이 없어, LLM으로부터 429 에러가 한 번만 발생해도 프로세스가 중단됨
• 에러 핸들링 (error handling)이 없어, { error: "..." } 형태의 응답 대신 처리되지 않은 예외 (unhandled exception)가 발생함
• 테스트가 없어, 변경 사항이 정상 경로 (happy path)를 망가뜨리지 않았는지 확인할 방법이 없음

이 앱들은 이 모든 것을 갖추고 있습니다. 단순히 인상적이기 때문이 아니라, "이걸 복사해서 붙여넣었더니 바로 작동하네"와 "포기하기 전까지 하루 종일 디버깅만 했네"의 차이를 만드는 것이 바로 이 부분이기 때문입니다.

공통 컨벤션(Conventions) 및 프롬프트 라이브러리

여섯 가지 앱 모두 동일한 컨벤션(Conventions)을 따릅니다. TypeScript 앱은 Vitest, ESM, strict mode(엄격 모드), 그리고 입력 검증을 위한 Zod를 사용합니다. Python 앱은 테스트 클라이언트로 pytest와 httpx를 사용합니다. 모든 서버는 GET /health 엔드포인트를 노출합니다.

프롬프트 템플릿(Prompt templates)은 apps/_shared/prompts/에 위치하며, 앱당 하나의 Markdown 파일로 구성됩니다. 앱들은 런타임(Runtime)에 이를 로드하므로, 애플리케이션 코드를 수정하지 않고도 프롬프트를 조정할 수 있습니다.

비용 추정치

리드 스코어링(Lead scoring)과 이력서 파싱(Resume parsing)은 저렴합니다. 이들은 claude-haiku-4-5에서 실행되며 1,000회 요청당 1달러 미만의 비용이 발생합니다. RAG 채팅과 웹 스크래핑(Web scraping)은 품질을 위해 claude-sonnet-4-6에서 실행되므로 비용이 더 많이 듭니다. 전체 추정치(1k/10k/100k 요청 기준)는 COSTS.md에 정리되어 있습니다.

패키징 내용

여섯 가지 앱 모두 하나의 zip 파일에 담겨 있습니다. 처음부터 시작하는 대신 이러한 패턴 중 하나를 기반으로 구축을 시작하고 싶다면 다음을 확인하세요: https://ko-fi.com/s/7296aa7d89