도덕경 학습 AI v0.1.5 구축 기록 — NotebookLM 공부에서 제한 베타 준비까지

2026년 6월 9일

도덕경학습AINotebookLMClaude Code로컬MVP제한베타AI협업개발

요약

개인 학습 목적으로 NotebookLM에 도덕경 자료를 올리며 공부를 시작했다. 문서를 읽고 정리하는 것만으로는 학습 확인이 부족하다는 판단이 들어, Claude Code와 협업해 질문-답변형 로컬 웹 학습 도구를 만들었다. v0.1에서 v0.1.5까지 단계를 거치며 사용자 분리, 개인정보 안내, 기록 삭제, 계정 삭제, 원문 참조 패널, 1~10장 한자 사전 확장 등 제한 베타 준비 요소를 반영했다. 현재는 일반 공개 서비스가 아니라 대표 직접 검증 및 가족·지인 대상 제한 베타 준비 단계다.

이 기록의 핵심은 도덕경 해석 방식이 아니라, 개인 학습을 AI 협업 로컬 MVP와 제한 베타 준비 단계까지 시스템화한 운영 과정이다.

시작 배경: 왜 도덕경 학습 도구를 만들기 시작했는가

도덕경은 가볍게 읽기 어렵다. 한자 원문, 번역본, 주석, 현대적 해설이 뒤섞여 있어서 무엇을 어떻게 공부해야 할지 기준을 잡기 어렵다. 그래서 NotebookLM에 원문, 번역본, 강의 자료를 올려 학습 도구로 쓰기 시작했다.

처음에는 문서를 정리하고 AI의 요약을 읽으며 이해를 쌓아가는 방식이 충분할 것 같았다. 그러나 실제로 써보니 한계가 있었다. 내가 정말 이해한 것인지 아닌지를 확인할 방법이 없었다. 읽고 납득한 것과 나의 언어로 설명할 수 있는 것은 다르다.

여기서 방향이 바뀌었다. “문서를 읽는 도구”에서 “질문을 던지고 답을 확인하는 도구”가 필요하다는 판단이 생겼다.

NotebookLM 학습에서 로컬 MVP로

NotebookLM은 학습 재료 정리와 AI 보조 질의응답 도구로 계속 사용했다. 원문, 주석, 강의 해설 자료를 올려 두고 검색하거나 요약 요청을 하는 방식으로 기초 자료 관리에 활용했다.

다만 NotebookLM만으로는 다음 요소가 부족했다.

내가 직접 답을 쓰고 그것을 기록·추적하는 기능
장별, 주제별로 구조화된 학습 진행 확인
나중에 가족이나 지인과 함께 쓸 수 있는 공유 구조

이 필요를 채우기 위해 로컬 웹 학습 도구를 만들기로 했다.

역할 분리

이번 개발에서도 역할은 명확히 나눴다.

대표: 학습 목적, 사용자 흐름, 검증 기준, 공개 범위, 운영 리스크를 판단했다. 무엇을 만들고, 누구를 위해, 어디까지 열 것인지의 기준을 정했다.
Claude Code: 기술 구조 설계, 코드 구현, 환경 문제 해결, 기능 확장을 담당했다.
NotebookLM: 도덕경 원문, 주석, 해설, 강의 자료 기반 학습 보조 도구로 사용했다.
메타철부지: 방향 정렬과 운영 자산화 판단을 맡았다.

대표가 코드를 직접 작성한 것이 아니라, 목적과 판단 기준을 잡고 Claude Code에 구현을 맡겼다.

기술 구조

프론트엔드: React + Vite
백엔드: FastAPI (Python)
데이터베이스: SQLite
인증: JWT + PIN 기반 사용자 구분
실행 방식: 로컬 개발 서버 (프론트엔드 + 백엔드 병렬 실행)

공개 배포 서버가 아니라 로컬 환경에서 실행하는 구조다.

v0.1에서 v0.1.5까지: 단계별 확장

v0.1 — 기본 질문·답변 구조

1~5장을 중심으로 장별 질문을 제시하고 답을 입력하는 기본 구조를 만들었다. 단일 사용자 기준, 학습 기록 로컬 저장.

v0.1.1 — 학습 기록 저장과 진행 확인

답변 기록을 저장하고 학습 진행 현황을 확인하는 기능을 추가했다. 장별 진행률을 표시하고 이전 답변 이력을 볼 수 있도록 했다.

v0.1.2 — 1~10장 확장과 원문 참조 패널

학습 범위를 1~10장으로 확장했다. 질문에 답할 때 원문 한자와 번역을 바로 확인할 수 있는 참조 패널을 추가했다. 원문을 보면서 스스로 이해를 점검하는 것이 목적이었다.

v0.1.3 — 한자 사전 확장

1~10장 주요 한자에 대한 간략한 사전 설명을 추가했다. 이 설명은 학술적으로 검증된 해석이 아니라 초심자용 학습 보조 설명임을 명시했다. 특히 다음 항목은 단정하지 않고 향후 검증이 필요한 설명으로 표시했다.

2장: 유무상생, 무위 — 개인 학습용 이해, 해석에 이견이 있을 수 있음
5장: 芻狗(추구), 橐籥(탁약) 표현 — 오해 가능성이 있어 설명을 최소화함
8장: 上善若水(상선약수) 흐름 — 대표가 공부하며 정리한 임시 이해
10장: 玄德(현덕), 抱一(포일), 玄覽(현람) — 단정하지 않고 초심자용 설명으로 제한

v0.1.4 — 사용자 분리와 베타 코드

단일 사용자에서 멀티 사용자 분리로 전환했다. 베타 참여자 확인을 위한 코드 입력 구조를 추가했다. 사용자별 학습 기록이 분리되어 저장되도록 구조를 바꿨다.

v0.1.5 — 제한 베타 준비 요소 전체 반영

다음 요소를 추가했다.

PIN 기반 접근 제한 (PIN 자동입력 문제 해결 포함)
개인정보 안내 화면
기록 삭제 기능 (사용자 본인의 학습 기록 직접 삭제)
계정 삭제 또는 이용 중단 흐름
JWT 기반 세션 관리 개선

해결한 실행 환경 문제

개발 과정에서 다음 문제를 만나고 해결했다.

포트 점유 문제: 이전 세션의 백엔드 프로세스가 남아 있어 포트 충돌이 발생했다. 실행 전 포트 상태 확인과 프로세스 종료 절차를 운영 루틴에 넣었다.

학습자 등록 입력 버그: 사용자 등록 폼에서 특정 조건 아래 입력값이 초기화되는 버그가 있었다. 폼 상태 관리 로직을 수정해 해결했다.

PIN 자동입력 문제: 브라우저 자동완성 기능이 PIN 필드에 기존 저장값을 채워 넣는 문제가 있었다. autocomplete 속성 설정을 통해 해결했다.

현재 상태: 일반 공개가 아닌 이유

현재 도덕경 학습 AI v0.1.5는 다음 단계를 거치지 않았다.

대표 직접 학습 검증: 대표가 실제 학습 도구로 충분히 사용하며 흐름을 확인하는 단계가 남아 있다.
가족·지인 제한 베타 리허설: 외부 접속 연결과 사용 흐름 전체를 실제로 돌려보는 리허설이 남아 있다.
해석 검토: 한자 사전의 초심자용 설명이 오해를 줄 가능성이 있는지 추가 검토가 필요하다.

이 세 단계를 거치지 않은 상태에서 외부에 공개하는 것은 적절하지 않다.

이 작업을 6월 시스템화 사례로 보는 이유

이번 작업은 단순히 “앱 하나를 더 만든 것”이 아니다.

개인 학습이라는 목적에서 시작해 NotebookLM으로 자료를 정리하고, 로컬 MVP를 만들고, 단계적으로 기능을 확장하며 제한 베타 준비 단계까지 끌고 갔다. 이 과정에서 대표는 판단을, Claude Code는 구현을, NotebookLM은 학습 보조를 맡았다.

하네스를 세우고, 역할을 나누고, 단계적으로 검증하며, 결과를 운영 자산으로 기록했다. 이것이 6월 운영 주제인 시스템화, 하네스, AI 협업 운영의 실제 사례다.