Claude Code와 AI 에이전트로 4일 만에 완성한 토정비결 운세 웹사이트 개발기

들어가며: 전통과 기술의 만남

조선시대 토정 이지함 선생이 만든 것으로 알려진 토정비결(土亭秘訣). 새해가 되면 한 번쯤 찾아보게 되는 이 전통 운세 점술을 웹사이트로 만들어보면 어떨까요?

참고: 토정비결은 흔히 이지함의 저작으로 알려져 있지만, 학계에서는 이지함 사후에 그의 호를 빌려 만들어진 책이라는 '토정 가탁설'이 유력합니다. 그럼에도 수백 년간 한국인들에게 사랑받아온 전통 점술임은 분명합니다.

이번 포스팅에서는 Claude Code를 활용해 AI 에이전트 기반으로 토정비결 운세 웹사이트를 단 4일 만에 개발한 경험을 공유합니다. 144가지 괘 조합 데이터 수집부터 배포까지, AI와 함께한 개발 여정을 상세히 담았습니다.

---

프로젝트 개요

토정비결이란?

토정비결은 생년월일을 기반으로 상괘(1-8), 중괘(1-6), 하괘(1-3)를 계산하여 총 144가지 운세 조합 중 하나를 도출하는 점술입니다.

괘 종류	범위	계산 요소
상괘	1-8 (8가지)	나이수 + 태세수
중괘	1-6 (6가지)	월대소 + 월건수
하괘	1-3 (3가지)	생일수 + 일진수
총 조합	8 x 6 x 3 = 144가지

기술 스택

의도적으로 빌드 도구 없이 순수 기술만 사용했습니다.

• 프론트엔드: HTML, CSS, JavaScript (Vanilla)
• 데이터 수집: Python (requests, BeautifulSoup)
• 배포: Cloudflare Pages (무료 Static Hosting)

복잡한 프레임워크 없이도 충분히 실용적인 웹사이트를 만들 수 있다는 것을 보여주고 싶었습니다.

---

개발 일지: 4일간의 여정

1일차: 토정비결 원리 이해 및 프론트엔드 개발

첫날은 토정비결의 계산 원리를 파악하는 데 집중했습니다. 천간(天干)과 지지(地支)의 수치 체계, 음력 변환 로직 등 생각보다 복잡한 구조였습니다.

주요 작업:

• 토정비결 수리법 분석 및 문서화
• 양력/음력 변환 로직 구현 (1900-2099년 지원)
• 천간지지 수치 계산 모듈 개발
• 더미 데이터를 활용한 UI/UX 프로토타입 완성

// 괘 계산 공식 예시
상괘 = (나이수 + 태세수) mod 8  // 0이면 8
중괘 = (월대소 + 월건수) mod 6  // 0이면 6
하괘 = (생일수 + 일진수) mod 3  // 0이면 3

Claude Code가 복잡한 음력 변환 로직과 천간지지 계산을 빠르게 구현해줘서, 하루 만에 프론트엔드 골격을 완성할 수 있었습니다.

---

2일차: 144괘 데이터 수집 - AI 에이전트의 진가

이날이 프로젝트의 핵심이자 가장 도전적인 날이었습니다. 144개 괘 조합에 대해 각각 한글 해석본과 한자 원문, 총 288개 파일을 수집해야 했습니다.

서브에이전트 병렬 처리 전략

혼자서 288개 파일을 수집하려면 엄청난 시간이 걸립니다. 그래서 서브에이전트 5개를 병렬로 구동하는 전략을 선택했습니다.

서브에이전트 구성
- 에이전트 1: 1-x-x 괘 담당 (18개 조합)
- 에이전트 2: 2-x-x 괘 담당 (18개 조합)
- 에이전트 3: 3-x-x, 4-x-x 괘 담당
- 에이전트 4: 5-x-x, 6-x-x 괘 담당
- 에이전트 5: 7-x-x, 8-x-x 괘 담당

토큰 관리의 중요성

Sonnet 4.5 모델을 사용해 토큰을 절약했지만, 288개 파일을 처리하다 보니 결국 토큰이 바닥나는 상황이 발생했습니다.

실제 겪은 문제들:

1. Output 품질 저하: 토큰이 부족해지면서 마지막 작업들의 결과물 품질이 눈에 띄게 떨어졌습니다.

2. 일관성 유지 어려움: 서브에이전트마다 문제 해결 방식이 달랐습니다. 같은 지시를 줘도 에이전트별로 다른 접근법을 시도하더군요.

3. 지시 불이행: 샘플 포맷을 명확히 제공했음에도 일부 에이전트가 다른 형식으로 결과를 출력하는 경우가 있었습니다.

해결책: 파이썬 스크립트 활용

반복적인 작업은 AI에게 맡기기보다 파이썬 스크립트로 자동화하는 것이 토큰 효율 면에서 훨씬 유리했습니다.

# 블로그 URL 검색 스크립트
python3 scripts/find_post_urls.py 1-1-1

# 운세 내용 크롤링 스크립트
python3 scripts/crawl_fortune.py [URL]

# 한자 원문 형식 통일 스크립트
python3 scripts/fix_classical_format.py

교훈: AI 에이전트는 창의적인 작업에 강하고, 반복적인 작업은 스크립트로 처리하는 것이 효율적입니다.

---

3일차: 데이터 통합 및 Cloudflare 배포

데이터 가공 및 적용

수집한 288개 마크다운 파일을 웹사이트에서 사용할 수 있도록 JavaScript 객체로 변환했습니다. 최종 fortunes.js 파일은 약 950KB 크기가 되었습니다.

프로젝트 구조
tjbg/
├── data/           # 288개 운세 데이터 파일
│   ├── 1-1-1.md
│   ├── 1-1-1_classical.md
│   └── ...
├── js/
│   ├── fortunes.js # 웹앱용 통합 데이터 (950KB)
│   ├── app.js      # 메인 로직
│   └── ...
└── index.html

Cloudflare Pages 무료 배포

Cloudflare Pages의 Direct Upload 기능을 활용해 무료로 배포했습니다.

Cloudflare Pages 제한사항
- 최대 파일 수: 20,000개
- 파일당 최대 크기: 25MB
- 무료 플랜으로 충분히 사용 가능

배포 명령어:

# 배포용 디렉토리 생성
mkdir -p dist
cp -r index.html css js _headers ads.txt dist/

# Cloudflare Pages 배포
npx wrangler pages deploy dist --project-name=tojung

Claude Code에게 자연어로 "Cloudflare Pages로 배포해줘"라고 요청하니, 배포 프로세스를 정립하고 README.md에 문서화까지 해주었습니다. AI와의 협업이 빛나는 순간이었습니다.

---

4일차: 데이터 품질 개선

마지막 날은 수집된 데이터의 품질을 점검하고 정제하는 작업을 진행했습니다.

주요 정제 작업:

• 한자 원문의 음(한글 발음) 표기 오류 수정
• 월별 섹션 헤더 형식 통일
• 누락된 데이터 보완
• 포맷 불일치 파일 재작업

데이터 수집 자동화의 한계를 느낀 부분이기도 합니다. 아무리 좋은 AI 도구를 사용해도 최종 품질 검수는 사람의 몫이라는 것을 다시 한번 깨달았습니다.

---

AI 에이전트 개발에서 얻은 인사이트

1. 서브에이전트 병렬 처리의 양날의 검

병렬 처리로 시간은 단축되지만, 일관성 유지가 어렵습니다. 각 에이전트가 독립적으로 판단하기 때문에 같은 문제도 다르게 해결합니다.

해결책:

• 명확한 샘플 파일 제공
• 검증 스크립트로 결과물 자동 체크
• 포맷 통일용 후처리 스크립트 준비

2. 토큰은 전략적으로 사용해야 한다

대량 작업 시 토큰 소진은 필연적입니다. 토큰이 부족해지면 output 품질이 저하됩니다.

해결책:

• 반복 작업은 스크립트로 자동화
• 가벼운 모델(Sonnet)과 강력한 모델(Opus)을 용도에 맞게 사용
• 작업 우선순위를 정해 중요한 작업 먼저 처리

3. AI는 창의적 작업에, 스크립트는 반복 작업에

AI 에이전트의 강점은 유연한 문제 해결과 창의적인 접근입니다. 단순 반복 작업은 파이썬 스크립트가 더 효율적이고 일관성 있습니다.

---

결과물

👉 완성된 웹사이트 바로가기: 토정비결 운세

완성된 웹사이트 기능

• 양력/음력 생년월일 입력 지원
• 144가지 운세 조합 완벽 지원
• 총운(總運) + 12개월 월별 운세 제공
• 한자 원문 함께 제공
• 상세 계산 과정 표시
• 모바일 반응형 디자인

프로젝트 규모

항목	수량
운세 데이터 파일	288개
괘 조합	144가지
JavaScript 모듈	5개
Python 스크립트	3개
개발 기간	4일

---

마치며

한국 전통 점술인 토정비결과 최신 AI 기술의 만남. 어울리지 않을 것 같은 조합이지만, 오히려 전통 콘텐츠를 현대적으로 전달하는 좋은 시도였다고 생각합니다.

Claude Code와 AI 에이전트를 활용한 개발은 확실히 생산성을 크게 높여줍니다. 다만 만능은 아닙니다. 토큰 관리, 일관성 유지, 최종 품질 검수 등 사람이 신경 써야 할 부분은 여전히 존재합니다.

AI 도구를 잘 활용하는 방법을 아는 것, 그것이 앞으로 개발자에게 필요한 역량이 아닐까요?

곧 설날이 다가오는데 토정비결 웹사이트에서 운세 확인하면서 가족들과 좋은시간 보내시길 바랍니다.

긴 글 읽어주셔서 감사합니다!