비개발자와 AI가 도장(道藏) 원문 검색기를 함께 만든 과정

안녕하세요. 노브(nomadmeve)입니다

저는 도교 원문을 연구에 활용하고 싶었습니다. 그런데 처음의 바람은 아주 막연했습니다. “도장(道藏) 원문에서 경전명과 저자를 찾고, 본문도 검색할 수 있으면 좋겠다” 정도였습니다. API, Docker, Cloudflare, local LLM 같은 말은 각각 들어 봤지만, 이들이 어떻게 이어지는지는 잘 몰랐습니다.

이번 글은 Hermes 안에서 활동하는 AI 에이전트 Pulses와 대화하며 DaoCanon을 만든 기록입니다. 개발을 부탁해 놓고 결과를 기다린 이야기라기보다, 제가 모르는 것을 묻고, AI가 설명하고, 제가 화면에서 이상한 점을 발견해 다시 묻고, 그 대화가 다음 구현을 바꿔 간 과정에 가깝습니다.

🌱 출발점 — 스터디에서 본 기술의 그림을 내 연구 과제로 옮기기까지

24시간AI서버 스터디장께서 Cloudflare Tunnel, Docker, Linux 서버, Caddy 같은 기술을 통해 “내 컴퓨터에서 만든 서비스를 어떻게 계속 실행하고, 필요하면 도메인을 통해 바깥에서 볼 수 있게 하는가”라는 기본 그림을 보여 주셨습니다.

당시 제 메모에는 짧게 이런 단어들만 남아 있었습니다.

Cloudflare Tunnel
Docker
Caddy
Tailscale은 개인 휴대폰 등 자신만 보기
Caddy server는 도메인을 통해 자기 서버를 바깥에서 보기

이때 이 단어들을 아직 정확히 연결하지 못했습니다. 하지만 “도교 원문 검색 도구도 언젠가 내 서버에서 계속 돌아가고, 휴대폰이나 웹에서 볼 수 있겠구나”라는 기술적 상상은 생겼습니다. 그 뒤 AI와 대화하며 함께 천천히 구현 작업을 진진행했습니다.
현재 완성된 DaoCanon은 도장 원문을 경전명·저자·본문으로 찾고, 검색 결과에서 실제 원문 행까지 들어갈 수 있는 작은 연구 도구입니다. 지금은 원문/간체/번체 보기와 로컬 모델을 이용한 한국어 번역 보조도 갖추고 있습니다.

📝 한줄 요약

도교 원문을 “AI에게 물어보는 서비스”부터 만들지 않았습니다. 먼저 원문과 물리 행 위치로 되돌아갈 수 있는 검색 도구를 만들고, 화면·Reader·사설 접속·공개 접속·읽기와 번역 보조를 차례로 붙였습니다. 그 사이 검색 결과가 틀릴 수 있다는 점, AI worker가 멈출 수 있다는 점, 재부팅 뒤 번역만 멈출 수 있다는 점을 대화와 검증으로 하나씩 통과했습니다.

한눈에 보는 흐름

기존 도장 원문 corpus
  → 무엇을 찾고 어떻게 보여줄지 설계
  → corpus 실측과 검색 API 기준선
  → catalog · 제목 · 저자 · 전문검색
  → 실제 browser 검색 화면과 Reader
  → Docker · Tailscale · Cloudflare 공개 경로
  → OpenCC 표시 변환 · local Ollama 번역
  → 재부팅 장애 복구와 운영 단순화

바쁘시면 이것만 읽어도 돼요:

• AI에게 “만들어줘”라고 한 번 말하는 대신, 모르는 개념을 질문하고 방향을 나누며 작은 단계로 진행했습니다.

• 검색 결과에는 제목만이 아니라 원문 상대경로와 실제 물리 행 위치를 남겼습니다.

• 자동 테스트가 통과해도 별도 AI 검토에서 발견한 오류를 다시 고쳤습니다.

• 화면을 직접 써 보고 “검색 결과에서 경전으로 들어가고 싶다”는 말이 Reader 기능으로 이어졌습니다.

• 간체·번체 변환과 한국어 번역은 원문을 바꾸지 않는 읽기 보조로 만들었습니다.

• 재부팅 뒤 번역이 실패했을 때도, “AI 모델이 문제일 것”이라고 짐작하지 않고 연결 경로를 살펴 원인을 찾았습니다.

🎯 이런 분들께 도움돼요

• 인문학·연구 자료를 검색 가능한 도구로 만들어 보고 싶은 비개발자

• AI와 자연어로 대화하면서 작은 연구용 서비스를 만들어 보고 싶은 분

• AI가 만든 결과를 화면에서 직접 확인하고, 이상하면 다시 질문하는 방법이 궁금한 분

• “LLM을 붙이기 전에 무엇을 먼저 만들어야 하나” 고민하는 분

• 원문·출처·인용 위치가 중요한 자료를 다루는 분

😫 시작점 — “도장을 어떻게 활용할 수 있을까?”

DaoCanon의 출발점은 거창한 기술 계획이 아니라, 이미 가지고 있던 도장 원문을 어떻게 연구에 쓸 수 있을지에 대한 질문이었습니다.

제가 Pulses에게 이렇게 물었습니다.

결국 있는 Daocanon을 어떻게 활용할지.
검색(표제어, 저자, 경전명), 도장에서 경전순서 등을 보여주는 것을
어떻게 구현할지. 좀더 설명해주겠니?

처음에는 “검색 화면이 있으면 되지 않을까?”라고 생각했습니다. 그런데 대화를 이어 가며 검색이란 단어 안에도 여러 층이 있다는 것을 알게 됐습니다.

경전명으로 찾기
저자로 찾기
본문의 실제 글자로 찾기
찾은 결과가 원문 어디에 있는지 다시 열기

특히 마지막이 중요했습니다. 단어를 찾아 주는 것만으로는 연구용 도구가 되기 어렵습니다. 어떤 경전의 어느 부분인지 다시 확인할 길이 있어야 했습니다. 그래서 처음부터 “그럴듯한 답”보다 원문으로 돌아갈 수 있는 길을 남기는 쪽으로 방향이 잡혔습니다.

🛠️ 함께 사용한 도구

• AI 에이전트: Hermes Agent의 Pulses

• 구현·검증 협업: Qwen Code, Codex, AGY의 AI review lane

• 서버와 화면: JavaScript / Node.js, HTML·CSS·JavaScript

• 원문 자료: 읽기 전용 DaoCanon corpus

• 번역 보조: host에 설치된 local Ollama 모델

• 실행·접속: Docker, Tailscale, Cloudflare Tunnel

• 검증: 자동 테스트, 실제 브라우저, 휴대폰 확인, 독립 AI 검토

여기서 중요한 점은 AI 도구를 많이 썼다는 사실 자체가 아닙니다. Pulses가 전체 흐름을 정리하고, 구현 worker와 검증 worker를 나누고, 제가 실제 화면에서 확인한 결과를 다시 대화에 가져오는 방식이었습니다.

🔧 작업 과정

1. “AI가 바로 답하는 도구”보다 원문 검색 1단계부터 만들기로 했다

아주 초기에 저는 앞으로의 모습을 세 단계로 생각했습니다.

현재는 원문검색을 제시하는 1단계.
그 다음에는 도교대사전, 도교통사, 도교사상사 같은 자료를 더하는 2단계.
마지막에는 local LLM 혹은 cloud 모델이 API를 통해 자료를 살펴보고
관련 경전과 근거를 제시하는 3단계.

Pulses는 이 구분이 좋다고 하면서도, 세 번째 단계부터 만들지 말자고 했습니다. AI가 내용을 요약해 주기 전에, 무엇을 검색하고 무엇을 읽어야 하는지부터 신뢰할 수 있어야 한다는 설명이었습니다.

그래서 먼저 만든 것은 “질문에 답하는 AI”가 아니라 다음과 같은 기본 검색 도구였습니다.

원문 목록
→ 경전명 검색
→ 저자 검색
→ 본문 검색
→ 상대경로와 물리 행 위치

원문 파일은 수정하지 않았습니다. 원문이 기준이고, 검색 결과와 나중의 AI 해석은 그 원문을 가리키는 보조 층으로 두었습니다.

ALT

컴퓨터의 코드 편집기 스크린샷

홈페이지 화면을 만들기 전에, 실제 DaoCanon API가 원문 corpus를 검색할 수 있도록 만든 초기 단계.

ALT

한국어 웹사이트의 스크린샷

DaoCanon 첫 검색 화면. 부별 목록, 경전명·저자·전문 검색을 한 화면에서 고를 수 있고, 결과마다 원문 근거 위치를 확인하도록 만들었다.

2. “양이 많으니 느리지 않을까?”라는 질문에서 corpus 실측이 시작됐다

제가 실제로 걱정했던 것은 속도였습니다.

도장이 양이 많잖아. 검색의 경우 속도 문제는 크게 문제없니?

Pulses는 바로 괜찮다고 답하지 않았습니다. 먼저 실제 corpus를 조사했습니다. 원문이 몇 개인지, 제목과 파일명이 얼마나 다른지, 같은 제목이 있는지, INDEX.md 같은 안내 파일을 검색 대상에 넣어도 되는지를 살폈습니다.

그 과정에서 확인한 큰 기준은 다음과 같습니다.

• 원문은 약 1,700여 개의 Markdown 파일로 구성되어 있음

• 제목과 파일명, 저자 표기가 늘 깔끔하게 맞지는 않음

• 같은 제목이나 비슷한 표기가 존재함

• 검색 결과는 파일명만으로 구분하면 안 됨

이 조사 덕분에 검색 결과에는 단순한 제목이 아니라, 경전마다 고유한 ID·상대경로·물리 행 위치를 남기게 됐습니다. 비개발자인 제게는 그때까지 “검색이 된다”는 말이 결과 목록이 나온다는 뜻이었는데, 이제는 “그 결과가 어느 원문인지 되짚을 수 있다”는 뜻으로 바뀌었습니다.

3. 테스트가 다 통과했는데도, AI 검토가 여러 번 실패를 찾아냈다

작업을 하면서 가장 인상 깊었던 장면은 “테스트가 통과했으니 끝난 것 아닌가?”라고 생각했던 순간들입니다.

처음에는 검색 API와 화면의 자동 테스트가 초록색으로 보였습니다. 그런데 독립 검토를 맡은 AI가 다음과 같은 문제들을 찾아냈습니다.

• 화면이 실제 API에 없는 정보를 그럴듯하게 만들어 보여 주는 문제

• URL을 정리하는 과정에서 우회될 수 있는 경로 처리 문제

• 화면이 바뀌었다는 표시와 실제 검색 결과가 모두 바뀐 시점이 다른 문제

• 작은 화면에서 원문 상대경로가 사라지는 문제

• 너무 좁은 화면에서 가로 스크롤이 생기는 문제

저는 이 과정에서 AI가 한 번에 완벽하게 만든다는 느낌보다, 서로 다른 AI와 실제 브라우저가 각자 다른 허점을 찾아낸다는 느낌을 받았습니다.

Pulses도 구현 worker의 보고를 그대로 믿지 않았습니다. 한 worker가 실제 구현 대신 placeholder만 남겼을 때는 “완료”로 처리하지 않고, 테스트와 화면을 다시 보고 구현 방식을 바꿨습니다. 저도 중간에 결과를 직접 확인하고, 잘 모르겠는 부분은 “이게 지금 실제로 된 상태니?”라고 다시 물었습니다.

이 과정에서 DaoCanon은 예쁜 mockup이 아니라, 실제 원문을 검색하고 다시 열 수 있는 화면으로 바뀌었습니다.

4. “검색 결과에서 경전으로 들어가고 싶다”는 한 문장이 Reader를 열었다

검색이 된 뒤에는 또 다른 부족함이 보였습니다. 검색 결과는 나오지만, 결국 경전 원문을 읽고 싶은데 결과 목록에서 멈추는 것입니다.

제가 Pulses에게 이렇게 말했습니다.

검색결과 보여주는 단계에서,
해당 사항 더블클릭하면 바로 경전으로 넘어가는 단계가 있으면 좋겠어.
저자와 경전명을 누르면 해당 경전명으로,
경전내용을 누르면 해당 경전의 경전내용 부분을 보여주는 방식.

이 말은 화면 버튼 하나를 추가하는 일이 아니었습니다. Pulses는 “더블클릭”을 살리되, 클릭과 키보드 Enter로도 들어갈 수 있도록 만들었습니다. 또 제목·저자 검색은 경전의 첫 행으로, 본문 검색은 실제로 일치한 행으로 들어가도록 구분했습니다.

예를 들어 黄庭内景经을 본문 검색하면, 결과에서 三洞珠囊의 실제 해당 행으로 이동합니다. 검색 결과가 연구 메모에서 멈추지 않고, 원문 확인으로 이어지는 길이 열린 것입니다.

이 경험은 AI와 대화할 때의 작은 팁이 되었습니다. 처음부터 완벽한 기능 명세를 말하지 못해도 됩니다. 화면을 보고 “여기서 나는 다음에 무엇을 하고 싶은가?”를 말하면, AI가 그것을 기능·데이터·검증의 질문으로 다시 나눠 줄 수 있습니다.

5. Docker와 공개 접속은 “먼저 열기”가 아니라 “한 단계씩 확인하기”였다

처음에는 Cloudflare나 Caddy 같은 이름이 먼저 눈에 들어왔습니다. 하지만 Pulses와 대화하면서 공개 접속을 먼저 여는 대신 순서를 정했습니다.

원문 검색과 Reader 완성
→ Docker로 실행 단위 정리
→ Tailscale로 휴대폰에서 먼저 확인
→ 그 뒤 Cloudflare Tunnel 공개 경로 구성

이 순서가 좋았던 이유는 문제가 생겼을 때 어디를 봐야 할지 분리할 수 있기 때문입니다. 먼저 내 컴퓨터에서 되고, 다음에는 사설 네트워크에서 휴대폰으로 되고, 그 다음에야 외부 경로를 붙였습니다.

DaoCanon의 현재 기술 관계도. 사례글에서는 세부 포트보다 원문→검색 API→읽기·번역 보조→인증된 공개 접면으로 이어지는 역할 분리가 핵심이다.

여기에도 수정이 있었습니다. 처음의 Caddy basic auth는 사용자 이름과 비밀번호를 함께 요구했습니다. 제가 실제로 쓸 때는 비밀번호만 쓰고 싶었고, 이 작은 사용성 문제는 단일 비밀번호 로그인 gate를 따로 만드는 계기가 됐습니다. “보안이 있으니 그대로 쓰자”가 아니라, 실제 사용자가 어떻게 들어가는지도 함께 확인한 것입니다.

6. 번역 기능은 “원문을 바꾸지 않는 보조”로 만들었다

검색과 Reader가 안정된 뒤, 저는 두 기능을 더하고 싶었습니다.

현재 상태에서 두 가지 기능을 추가했으면 해.
하나는 간체-번체 변환 기능,
다른 하나는 특정 문단을 복사해서 붙여놓고 한국어로 번역하는 기능.

처음에는 단순히 버튼 두 개를 더하는 일처럼 보였습니다. 하지만 대화를 하다 보니, 번체로 바꾼 글자가 검색 근거와 섞이면 “원문은 어디에 있나”가 흐려질 수 있다는 점을 알게 됐습니다.

그래서 원칙을 정했습니다.

표시는 바꿀 수 있다.
번역은 이해를 도울 수 있다.
그러나 검색·행 위치·인용 근거는 원문에 남긴다.

간체/번체 버튼은 Reader에서 보이는 글자만 바꿉니다. 주소나 행 번호, 검색 결과의 근거는 그대로입니다. 번역도 Reader 안의 원문을 자동으로 고쳐 쓰지 않고, 필요한 문단을 붙여넣어 클릭했을 때만 local Ollama 모델이 한국어 번역을 보여 주도록 했습니다. 번역 입력과 결과는 자동으로 저장하지 않게 했습니다.

ALT

한국사이트 스크린샷

원문/번체/간체 전환과 한국어 번역 패널. “행 번호·URL·근거 위치는 보존된다”, “결과는 저장되지 않는다”는 문구를 화면에 직접 남겼다.

7. 모델을 비교하고, 다음 날 번역 장애를 함께 해결했다

번역은 처음에 네 개의 로컬 모델을 비교할 수 있도록 했습니다. 직접 문단을 넣어 보고 나서 저는 이렇게 말했습니다.

토큰과 성능을 고려할 때 번역은 gemma4:12b가 가장 적절해보이네.
ornith 9b는 좀 모자라고, gemma4 12b, 26b는 큰 차이 없고,
qwen3.6:35b는 크기에 비해 gemma4보다 못미치는 느낌이네.

여기서 중요한 것은 AI가 “가장 좋은 모델”을 단정한 것이 아니라, 제가 실제 화면에서 같은 종류의 문단을 보고 판단했다는 점입니다. 이후 운영 모델은 gemma4:12b, gemma4:26b 두 가지로 좁혔습니다.

그런데 다음 날, “한국어로 번역” 버튼을 눌렀는데 세 번이나 실패했습니다.

Daocanon에서 gemma4:12로 “한국어로 번역”을 눌렀는데,
“요청을 완료하지 못했습니다. API 상태를 확인해 주세요.”라는 메시지가 3번 나왔어.
한번 확인해주렴.

처음에는 모델 문제처럼 보였습니다. 그러나 Pulses는 모델을 다시 설치하거나 외부에 열지 않았습니다. Docker 안의 번역 서비스에서 host의 Ollama로 이어지는 연결, 그리고 재부팅 뒤 사라진 방화벽 예외를 차례로 확인했습니다.

원인은 원문도, 검색 API도, 모델 자체도 아니었습니다. 재부팅 뒤 container에서 Ollama로 가는 아주 좁은 연결 경로만 막힌 것이었습니다. 그 경로에만 영구 규칙을 적용하고 실제 번역을 다시 확인했습니다.

이 일은 제게 AI 활용의 중요한 감각을 남겼습니다. 오류 메시지가 넓고 막연할수록, “뭐가 고장 났지?”라고 한 덩어리로 묻기보다 사용자가 본 현상부터 말하고, AI와 함께 연결 단계를 나눠 보는 것이 훨씬 낫다는 점입니다.

✅ 결과 — 만든 것은 검색창 하나가 아니었다

Before / After

실제로 남은 결과물

• DaoCanon 원문 1,721종의 read-only catalog와 검색

• 경전명·저자·literal 본문 검색

• 검색 결과의 상대경로·physical line locator·snippet

• 결과에서 실제 경전 passage로 들어가는 Reader

• 간체/번체 표시 변환

• local Ollama 기반 한국어 번역 보조

• Docker 기반 실행, Tailscale 확인, 인증된 Cloudflare 공개 경로

• 작업 과정·회고·아키텍처 관계도·테스트 증적 문서

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 모르는 말을 감추지 않고 그대로 묻기

   • “Cloudflare를 잘 몰라. 우선 무엇을 하기보다 설명해주면 좋겠어”라고 말한 뒤, 이해한 만큼만 다음 결정을 내렸습니다.

2. 화면에서 본 현상을 정확히 가져오기

   • “번역 버튼을 세 번 눌렀는데 이런 문구가 나왔다”는 관찰은 원인을 좁히는 가장 좋은 출발점이 됐습니다.

3. 한 번에 모든 것을 만들려 하지 않기

   • corpus 조사 → 검색 → Reader → Docker → 사설 접속 → 공개 → 번역 보조 순서로 나누니, 문제가 생겨도 현재 단계의 질문으로 돌아갈 수 있었습니다.

4. AI의 설명을 다시 내 말로 확인하기

   • “그럼 Caddy는 지금 바로 필요한 것이 아니라, 여러 서비스가 생길 때 중간에서 나누는 역할이구나?”처럼 다시 묻는 과정에서 개념이 실제 설계가 됐습니다.

5. 완료 보고보다 실제 사용 확인하기

   • 테스트 수치보다, 내가 직접 검색하고 Reader로 들어가 보고 휴대폰에서도 확인하는 순간이 더 중요한 acceptance가 됐습니다.

이렇게 하면 안 됐습니다

1. “AI가 만들어 줬으니 맞겠지”라고 넘기기

   • 검색·화면·번역은 모두 실제로 써 보고, 이상하면 다시 대화해야 했습니다.

2. LLM부터 붙이기

   • 원문 search/read와 locator가 없는 상태에서 AI 답변부터 만들었다면, 나중에 무엇을 근거로 답했는지 확인하기 어려웠을 것입니다.

3. 기술 용어를 이해하지 못한 채 운영 설정을 한꺼번에 바꾸기

   • Docker, Tailscale, Cloudflare를 순서대로 다루었기 때문에 공개 경로에서 난 문제와 서비스 자체 문제를 구분할 수 있었습니다.

🌍 다른 연구·업무에 적용한다면?

DaoCanon은 도교 corpus를 대상으로 시작했지만, 방식 자체는 다른 자료에도 적용할 수 있습니다.

• 고전 문헌 archive: 제목·저자·본문 검색 뒤 실제 문단으로 이동

• 연구 노트: 자료별 출처와 페이지/행 locator를 남긴 통합 탐색

• OCR 문서: 인식문과 원본 이미지의 위치를 함께 보존

• 사내 문서: AI가 요약하기 전에 원문 검색과 근거 링크를 먼저 제공

• 데이터 조사: AI가 답을 만들어 내기보다 검색 도구를 사용하고 출처를 남기게 설계

핵심은 “AI가 말을 잘하느냐”보다, AI와 사람이 함께 확인할 수 있는 원문과 근거의 길을 먼저 만드는 것입니다.

🚀 앞으로의 계획

DaoCanon은 아직 1단계의 중심을 다듬은 상태입니다.

다음에는 도교사전·도장제요 같은 1차 공구서, 중국도교통사·도교사상사 같은 2차 연구서를 자료별로 분리해 더할 계획입니다. 이후에 local LLM과 cloud model이 같은 검색·Reader 도구를 사용하고, 어느 자료의 어느 위치를 근거로 말하는지 보여 주는 연구 대화로 확장하려 합니다.