HTML, CSS, JavaScript를 사용하여 현대적인 AI 어시스턴트 구축하기

AI 기반 애플리케이션은 어디에나 있지만, 많은 튜토리얼이 단순히 API를 연결하고 응답을 표시하는 데에만 집중합니다.

저는 실제 세계의 애플리케이션에 더 가까운 무언가를 만들고 싶었습니다.

그래서 저는 스트리밍 응답 (streaming responses), 마크다운 렌더링 (markdown rendering), 구문 강조 (syntax highlighting), 채팅 기록 (chat history), 테마 전환 (theme switching), 그리고 배포 (deployment)와 같은 기능들을 갖춘 순수 HTML, CSS, JavaScript를 사용한 현대적인 AI 어시스턴트를 제작했습니다.

이 글에서는 아키텍처 (architecture), 주요 기능, 배운 점, 그리고 피해야 할 일반적인 실수들에 대해 살펴보겠습니다.

최종 결과물

애플리케이션에는 다음이 포함됩니다:

✅ 현대적인 반응형 UI (responsive UI)

✅ 다크 모드 및 라이트 모드 (Dark and Light Mode)

✅ 스트리밍 AI 응답 (Streaming AI Responses)

✅ 마크다운 렌더링 (Markdown Rendering)

✅ 구문 강조 (Syntax Highlighting)

✅ 채팅 기록 지속성 (Chat History Persistence)

✅ 클립보드 복사 지원 (Copy-to-Clipboard Support)

✅ 에러 핸들링 및 재시도 로직 (Error Handling and Retry Logic)

✅ GitHub Pages 배포 (GitHub Pages Deployment)

많은 초보자용 프로젝트와 달리, 이 프로젝트는 사용자 경험 (user experience)과 유지보수성 (maintainability) 모두에 초점을 맞추고 있습니다.

이 프로젝트를 만든 이유

많은 AI 챗봇 튜토리얼은 API로부터 응답을 표시하는 단계에서 멈춥니다.

하지만 실제 애플리케이션에는 훨씬 더 많은 것이 필요합니다:

더 나은 사용자 경험 (user experience)
에러 핸들링 (error handling)
상태 관리 (state management)
반응형 디자인 (responsive design)
안전한 콘텐츠 렌더링 (safe content rendering)
지속적인 대화 (persistent conversations)

제 목표는 개발자들이 실무적인 프론트엔드 개발 (frontend development) 개념을 배우면서 포트폴리오 프로젝트로 사용할 수 있는 무언가를 만드는 것이었습니다.

기술 스택 (Tech Stack)

이 프로젝트는 다음을 사용합니다:

프론트엔드 (Frontend)

HTML5
CSS3
Vanilla JavaScript

라이브러리 (Libraries)

Marked.js
DOMPurify
Prism.js

AI 통합 (AI Integration)

Google Generative AI SDK

배포 (Deployment)

GitHub Pages

프레임워크는 없습니다.

빌드 도구도 없습니다.

오직 현대적인 JavaScript뿐입니다.

대부분의 AI 튜토리얼이 저지르는 한 가지 실수

AI 튜토리얼에서 제가 보는 가장 큰 문제 중 하나는 AI가 생성한 콘텐츠를 페이지에 직접 렌더링하는 것입니다.

이는 보안 위험을 초래할 수 있습니다.

대신, 저는 AI 응답을 표시하기 전에 DOMPurify를 사용하여 이를 정화 (sanitize)했습니다.

예시:

const cleanHtml = DOMPurify.sanitize(rawHtml);

작은 추가 사항 하나가 보안을 크게 향상시킬 수 있습니다.

스트리밍 응답 (Streaming Responses)을 통한 사용자 경험 개선

전체 응답이 완료될 때까지 기다리는 대신, 애플리케이션은 콘텐츠가 생성되는 즉시 스트리밍합니다.

이를 통해 더욱 부드럽고 자연스러운 채팅 경험을 제공할 수 있습니다.

사용자는 로딩 표시기(loading indicator)를 멍하니 바라보는 대신 즉각적인 피드백을 받게 됩니다.

코드 응답 시각화 개선

많은 AI 어시스턴트들이 코드 스니펫 (code snippets)을 생성합니다.

가독성을 높이기 위해, 구문 강조 (syntax highlighting)를 위한 Prism.js를 통합하고 다음과 같은 기능이 포함된 커스텀 코드 블록 헤더를 추가했습니다:

언어 라벨 (Language labels)
복사 버튼 (Copy buttons)
더 나은 포맷팅 (Better formatting)

이는 애플리케이션을 사용하는 개발자들에게 드라마틱한 경험 개선을 제공합니다.

채팅 기록 유지 (Chat History Persistence)

사용자들은 페이지를 새로고침한 후에도 대화 내용이 유지되기를 기대합니다.

이를 구현하기 위해 localStorage를 사용했습니다.

장점:

더 빠른 사용자 경험
백엔드 (backend) 불필요
간단한 구현

또한 이는 이 프로젝트를 GitHub Pages에 배포하기에 이상적으로 만들어 줍니다.

에러 핸들링 (Error Handling)의 중요성

대부분의 데모는 개발 단계에서는 완벽하게 작동합니다.

하지만 실제 애플리케이션은 그렇지 않습니다.

저는 다음과 같은 기능들을 추가했습니다:

재시도 로직 (Retry Logic)
API 에러 핸들링 (API Error Handling)
사용자 친화적인 메시지 (User-Friendly Messages)
로딩 상태 (Loading States)

이러한 기능들은 애플리케이션을 더욱 탄력적이고 프로덕션 환경에 적합하게(production-ready) 만들어 줍니다.

몇 분 만에 끝내는 배포

프로젝트가 완료된 후, 배포는 놀라울 정도로 간단했습니다.

GitHub Pages를 통해 전체 애플리케이션을 무료로 호스팅할 수 있었습니다.

덕분에 이 프로젝트를 포트폴리오로 보여주고 싶거나 공개적으로 공유하고 싶은 누구에게나 접근 가능하게 만들었습니다.

이 프로젝트를 만들며 배운 점

AI 애플리케이션을 구축하는 것은 단순히 API를 호출하는 것 그 이상입니다.

가장 가치 있는 교훈은 다음 항목들로부터 얻었습니다:

예외 케이스 (edge cases) 처리
UX 개선
상태 관리 (managing state)
AI 출력물 보안 (securing AI output)
프론트엔드 성능 최적화 (optimizing frontend performance)

이러한 영역들은 종종 AI 모델 자체보다 사용자에게 더 큰 영향을 미칩니다.

전체 단계별 영상 튜토리얼

전체 튜토리얼에서는 다음 내용을 다룹니다:

Gemini API 설정 (Setup)
프로젝트 구조 (Project Structure)
UI 디자인 (UI Design)
JavaScript 로직 (JavaScript Logic)
스트리밍 응답 (Streaming Responses)
구문 강조 (Syntax Highlighting)
에러 핸들링 (Error Handling)
GitHub Pages 배포 (Deployment to GitHub Pages)

전체 제작 과정을 여기서 시청하세요: 👉 [https://youtu.be/nbFKG_6DkSE]

마치며

AI 프로젝트는 다음과 같은 요소들을 결합하기 때문에 프론트엔드 개발 (Frontend Development) 기술을 향상시킬 수 있는 환상적인 방법입니다:

API
UI 디자인 (UI Design)
상태 관리 (State Management)
사용자 경험 (User Experience)
실전 문제 해결 (Real-World Problem Solving)

만약 여러분이 2025년에 개발자 포트폴리오 (Developer Portfolio)를 구축하고 있다면, 이와 같은 프로젝트를 만드는 것은 사용자들이 진정으로 즐겁게 사용할 수 있는 결과물을 만들어내면서 동시에 실무적인 기술을 배우는 데 도움이 될 수 있습니다.

다음에 어떤 기능을 추가하고 싶은지 정말 궁금합니다.

음성 입력 (Voice Input)?

파일 업로드 (File Uploads)?

메모리 (Memory)?

댓글로 알려주세요.