한줄 요약
가족 5명의 도서관 대출/예약 현황을 매번 로그인해서 확인하던 불편함을, Claude Code와 함께 모바일 웹앱으로 해결했습니다.
이런 분들께 도움돼요
가족 여러 명의 도서관 계정을 관리하시는 분
Vercel 무료 플랜에서 Puppeteer 스크래핑을 시도하시는 분
AI와 협업할 때 "방향은 내가, 구현은 AI가"라는 역할 분담이 궁금하신 분
소개: 시도하고자 했던 것과 그 이유
문제 상황
가족 5명이 각자 도서관 앱에 로그인해서 반납일을 확인하는 게 너무 번거로웠습니다. 특히 아이들 책은 부모가 대신 확인해야 하는데, 매번 5개 계정을 왔다갔다 하기가 힘들었어요.
"5명 책을 한눈에 볼 수 있으면 좋겠다"는 생각을 계속 하고 있었습니다.
목표
한 화면에서 가족 5명의 대출/예약/책나르샤 현황을 한눈에 보기
반납일 임박한 책은 빨간색으로 강조해서 놓치지 않기
모바일에서 편하게 확인할 수 있는 웹앱
진행 방법: 어떤 도구를 사용했고, 어떻게 활용했나요?
사용한 도구
Claude Code (CLI 환경에서 코딩 협업)
Next.js 16 + TypeScript + Tailwind CSS
Puppeteer (도서관 사이트 스크래핑)
Vercel (무료 플랜 배포)
AI와 협업한 과정
1. Vercel 60초 타임아웃 문제
Vercel 무료 플랜은 API 실행 시간이 60초로 제한됩니다. 5명을 한 번에 조회하면 타임아웃이 걸렸어요.
Claude는 계속 "안 된다"는 진단만 했지만, 저는 안티그래비티에서 비슷한 프로젝트를 해본 경험이 있어서 방법이 있다는 걸 알고 있었습니다.
제가 "1명씩 순차 조회하는 API로 분리하자"고 방향을 제안했고, Claude가 빠르게 구현해줬어요.
기존: /api/status (5명 전체 조회) → 타임아웃
변경: /api/member/1, /api/member/2, ... (1명씩 조회) → 성공
배운 점: AI가 모든 걸 해결해주진 않습니다. 결국 방향은 내가 잡고, AI는 빠르게 구현해주는 역할이었어요.
2. 도서관 사이트 봇 차단 문제
로그인이 자꾸 실패했습니다. 아이디/비밀번호는 맞는데 로그인 페이지에서 안 넘어가는 거예요.
Claude가 "User-Agent 문제일 수 있다"고 진단하고, 모바일 Safari로 위장하는 코드를 추가했더니 바로 해결됐습니다.
await page.setUserAgent('Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15');
3. 환경변수 느낌표(!) 이스케이프 문제
비밀번호에 !가 포함되어 있었는데, Vercel CLI로 환경변수를 설정할 때 자꾸 \!로 저장되는 문제가 있었어요.
쉘 이스케이프 문제라는 걸 찾아내고, heredoc을 사용해서 해결했습니다.
cat > /tmp/pw.txt << 'EOF'
비밀번호!
EOF
cat /tmp/pw.txt | vercel env add USER_1_PW production
결과와 배운 점
결과물
https://seocho-lib2.vercel.app
가족 5명 현황을 한 화면에서 확인
1명당 약 16~18초에 조회 완료
반납일 임박(3일 이내)은 빨간색으로 강조
연체 도서는 별도 경고 표시
배운 점
AI가 모든 걸 해결해주진 않는다
Claude가 "안 된다"고 할 때, 경험을 바탕으로 방향을 잡아줘야 했어요
방향은 사람이, 구현은 AI가 — 이 역할 분담이 중요합니다
Vercel 무료 플랜으로도 Puppeteer 스크래핑이 된다
@sparticuz/chromium-min으로 원격 바이너리 다운로드60초 제한 안에서 1명씩 처리하면 충분히 가능
제약 조건 안에서 해결책을 찾는 게 재밌다
유료 플랜 쓰면 쉽게 해결되지만, 무료 플랜 안에서 방법을 찾는 과정이 오히려 재밌었어요
재사용 가능한 프롬프트
Vercel + Puppeteer 조합 시작할 때
Vercel 무료 플랜(60초 타임아웃)에서 Puppeteer로 [사이트명] 스크래핑하는
Next.js API를 만들어줘. @sparticuz/chromium-min 사용해서 서버리스 환경에서
동작하도록 해줘.
스크래핑 봇 차단 우회
[사이트명] 로그인이 안 되는데, 봇 차단 때문인 것 같아.
User-Agent를 모바일 브라우저로 설정하고, 필요하면 추가 헤더도 설정해줘.
API 타임아웃 분리
현재 /api/status에서 5명을 한 번에 조회하는데 타임아웃이 걸려.
/api/member/[id]로 1명씩 조회하는 API로 분리하고,
프론트엔드에서 순차적으로 호출 하도록 변경해줘.
도움 받은 자료
특별히 참고한 글은 없고, 안티그래비티에서 동일한 프로젝트를 했던 경험이 가장 큰 도움이 됐습니다.
"이건 된다"는 확신이 있었기 때문에, Claude가 안 된다고 해도 방향을 밀어붙일 수 있었어요.
실은 클로드코드 리밋 걸렸을 때, 안티그래비티로 먼저 같은 프로젝트를 만들어봤습니다.
다 만들고 나서, 클로드코드로 다시 한번 만들어본 거에요.
안티그래비티 Gemini 3 Pro (High) Planning 모드로 했는데, 클코보다 좀 더 편하고 컨텍스트도 길고 좀 더 똑똑한 느낌을 받았습니다. 클코는 좀 다루기 까다롭다면 상대적으로 안티그래피티가 좀 쉽게 느껴진달까..
클코에 좀 더 적응을 해야겠습니다..
아래는 안티그래비티로 작업한 결과물 및 내용 요약입니다. (UI는 이게 좀 더 이쁜듯!)
https://seocho-lib.vercel.app/
부록..
서초구 내곡도서관 현황판 개발 일지 (with Antigravity)
이 문서는 "가족 도서관 현황판" 프로젝트의 개발 과정, 직면했던 기술적 문제들, 그리고 해결 방법을 요약한 기록입니다.
1. 프로젝트 개요
목표: 가족 구성원(5명)의 서초구 내곡도서관 대출 현황, 예약 현황, 책나르샤 신청 내역을 한눈에 볼 수 있는 대시보드 제작.
기술 스택: Next.js (App Router), Puppeteer (Core), Vercel (Deployment).
2. 개발 및 문제 해결 과정
2.1. 크롤링 로직 구현 (Local)
Puppeteer를 사용하여 도서관 로그인 및 페이지 이동 자동화.
아이디/비밀번호 입력 후 이벤트 디스패치(
dispatchEvent)를 통해 프론트엔드 유효성 검사 우회.대출 리스트, 예약 리스트, 책나르샤 페이지를 순회하며 데이터 파싱.
2.2. Vercel 배포와 크로미움(Chromium) 이슈
로컬 환경과 달리 Serverless(Lambda) 환경인 Vercel 배포 과정에서 여러 난관이 있었습니다.
바이너리 경로 문제 (
ENOENT):증상: 배포된 환경에서
chromium.br 파일을 찾지 못함.
해결:
findChromium 헬퍼 함수를 작성하여
node_modules,.next/server,/var/task등 가능한 모든 경로를 탐색하여 동적으로 실행 경로를 주 입.
공유 라이브러리 오류 (
libnss3.so):증상: Chromium 실행 시 시스템 라이브러리 누락 에러 발생.
원인: 사용 중이던 버전(v123)이 Vercel의 최신 런타임(Node 20 / Amazon Linux 2023)과 호환되지 않음.
해결:
@sparticuz/chromium과puppeteer-core를 최신 버전(v131+, v24+)으로 업그레이드.
브라우저 크래시 (
ConnectionClosed):증상: 브라우저가 실행되자마자 연결이 끊김.
원인: 5명의 유저를
Promise.all로 동시에 처리(병렬 실행)하면서 메모리 및 CPU 리소스 초과. 또한 Serverless 환경에서createBrowserContext의 불안정성.해결:
순차 처리(Sequential Processing): 1명씩 차례대로 처리하도록 변경 (
for ... of루프).단일 컨텍스트: 컨텍스트 분리 기능을 제거하고
browser.newPage()를 직접 사용.안전 장치: 실행 인자에
--no-sandbox,--disable-dev-shm-usage,dumpio: true등 안정성 플래그 및 디버깅 옵션 추가.
2.3. UX 고도화 (사용자 경험 개선)
실시간 스트리밍 UI (
Streaming API):기존: 5명의 데이터가 다 수집될 때까지(약 1분) 사용자는 멈춘 화면만 봐야 했음.
개선: Next.js API가
ReadableStream을 반환하도록 변경(NDJSON 방식).결과: "강수혁 님의 데이터를 가져오는 중..." 메시지가 실시간으로 뜨고, 데이터가 수집되는 즉시 화면에 카드가 하나씩 "탁, 탁" 나타나는 생동감 있는 경험 제공.
디테일 & 인터랙션 폴리싱:
Pending Card: 로딩 중일 때 단순히 글자만 뜨는 게 아니라, 다음 카드가 나올 위치에 "로딩 카드"를 배치하고 귀여운 아이콘 애니메이션(롤링 북, 점프 도트) 추가.
상세 보기 모드: 상단 요약 카드를 클릭하면 "반납 임박 도서만 모아보기" 또는 "전체 도서 리스트 보기" 모드로 전환되는 기능 추가.
데이터 무결성 및 보안 강화:
D-Day 정확도 향상: 서버의 UTC 시간대와 관계없이, 한국 시간(KST) 자정을 기준으로 정확한 남은 일수를 계산하도록 로직 강제 (
new Date()오차 수정).봇 탐지 우회(Stealth Mode):
User-Agent를 최신 Chrome으로 위장하고,Sec-CH-UA,Referer등 실제 브라우저와 동일한 헤더를 전송. 또한navigator.webdriver속성을 은폐하여 차단 가능성 최소화.
3. 최종 성과
안정성: Vercel Serverless 환경의 제약 사항을 모두 극복하고 안정적으로 크롤링 수행.
사용성: 정적인 대기 시간을 없애고 실시간 피드백을 제공하여 체감 대기 시간 단축.
직관성: 가족 전체의 도서 현황을 요약 및 상세 보기로 제공하여 도서관 이용 편의성 증대.
작성일: 2026-01-24 작성자: Antigravity (Agentic AI)
--
