빌린 책의 기록을 남기고 싶다

시립 도서관의 헤비 유저인 나. 반납 기한 사전 알림이나 예약 시스템에 불만은 없었지만, 빌린 책의 이력이 전혀 남지 않는 점에는 계속해서 어려움을 겪고 있었습니다.

개인정보 보호 관점에서 많은 도서관 시스템은 대출 기록을 반납과 함께 삭제한다고 합니다. 사상적으로는 아마 맞을 것입니다. 다만 이용자로서는 "작년 이맘때 무엇을 읽고 있었는지", "그 분야의 책을 어디까지 읽었는지"를 다시는 알 수 없게 됩니다.

독서 관리 앱을 사용하고는 있지만, 수동으로 기록하는 것은 다 읽은 소설 정도입니다. 도중에 반납한 책이나, 훑어보기만 한 기술서(Technical Book)는 기록할 정도는 아닙니다. 하지만 무엇을 빌렸었는지 정도는 나중에 되돌아보고 싶은 법입니다.

그래서 요구사항은 다음과 같이 정해졌습니다.

• 빌린 책이 완전 자동(Fully Automated)으로 기록된다
• 과거로 거슬러 올라가 검색할 수 있는 데이터베이스가 된다
• 덤으로, 반납 완료 감지나 대출 상황 확인도 사람의 손을 거치지 않고 돌아간다 (시스템에 로그인하면 알 수 있지만, Notion 같은 곳에서 볼 수 있으면 편하니까요)

원하는 것은 편리한 기록 기능이라기보다, "기록하는" 행위 그 자체를 없애는 것이었습니다. 이 기사는 그것을 Playwright와 AI 에이전트(사양서 주도 개발, Specification-Driven Development)로 만든 기록입니다.

완성형: 아무것도 하지 않아도 이력이 쌓인다

매일 아침 8시, Windows의 작업 스케줄러(Task Scheduler)가 스크립트를 자동으로 실행합니다. 헤드리스 브라우저(Headless Browser)로 도서관 사이트에 로그인하여 대출 목록을 취득하고, 이전 스냅샷(Snapshot)과 비교합니다. 그뿐입니다.

• 목록에 늘어난 책 → 신규 대출로서 이력 DB에 기록
• 목록에서 사라진 책 → 반납 완료로 기록 (반납일도 자동으로 확정)
• 변화 없음 → 아무 일도 일어나지 않음

도서관 시스템 측에서 이력을 삭제하더라도, 이쪽의 수중에는 대출부터 반납까지의 기록이 저절로 축적되어 갑니다. 운용 개시 후 약 1개월 동안 15권이 자동으로 기록되었습니다. 수동 입력은 제로입니다.

기술 구성

대상은 가나가와현 내의 모 시립 도서관의 OPAC(장서 검색·이용자 페이지)입니다. 흔히 볼 수 있는 레거시(Legacy) 업무용 Web 시스템으로, API는 없습니다.

스케줄러(작업 스케줄러)
└→ Python + Playwright(헤드리스 Chromium)
├→ 로그인 → 대출 목록 페이지로 이동
...

설계의 중심에 있는 것은 스냅샷 차분(Snapshot Diff)입니다. 도서관 시스템에는 "빌렸다", "반납했다"라는 이벤트 통지가 존재하지 않습니다. 하지만 대출 목록을 매일 저장하여 집합의 차분을 구하면 이벤트를 추정할 수 있습니다. 이력의 축적과 반납 감지가 동일한 하나의 메커니즘에서 나온다는 점이 마음에 듭니다.

또한, 이력의 실체는 로컬 JSON이지만, 열람용으로 Notion 데이터베이스에도 써넣고 있어 스마트폰에서도 살펴볼 수 있도록 했습니다.

레거시 OPAC 자동화의 핵심 포인트 3가지

동종의 레거시 Web 시스템을 자동화할 때 파악해 두어야 할 포인트를 일반론으로서 3가지 꼽아두겠습니다. 이 종류의 자동화에서 전형적으로 문제가 되는 부분들입니다.

로그인 플로우(Flow)는 작성하기 전에 완전히 관찰할 것. 레거시 OPAC의 로그인은 세션(Session)이나 숨겨진 파라미터, 화면 전환 순서에 의존하는 경우가 많습니다. 먼저 브라우저의 개발자 도구로 수동 로그인 흐름을 완전히 관찰한 뒤, 동일한 순서를 Playwright로 재현하는 것이 결국 지름길이었습니다.

"겉으로는 보이지만 뒤에서는 처리 중"임을 의심할 것. Playwright의 자동 대기(Auto-waiting)는 우수하지만, 오래된 사이트의 비동기(Asynchronous) 렌더링까지는 신경 써주지 않습니다. 동작이 불안정해지면 먼저 특정 요소의 출현을 명시적으로 기다리는 방식을 의심해 보는 것이 좋습니다.

환경 차이는 코드 외부로 몰아낼 것. 저는 Windows(작업 스케줄러)에서 운용하고 있지만, Mac에서 돌린다면 cron이 될 것이고, 실행 시의 현재 디렉토리, Python 환경 해결, 로그 저장 위치 등의 전제가 달라집니다. 본 도구는 "ZIP 파일 하나로 배포, 첫 실행 셋업 스크립트 동봉, 경로는 스크립트 위치로부터의 상대 경로로 해결"하는 구성으로 하여, 환경 의존성을 설정과 셋업 측으로 몰아넣었습니다.

SPEC.md를 먼저 작성하고, AI에게 구현하게 했다

이 도구의 구현 대부분은 AI 에이전트에게 맡겼습니다. 이번에 사용한 것은 Antigravity입니다. 이러한 원샷(One-shot) 구현은 Claude나 Codex보다 훨씬 빠르고 확실한 퀄리티의 결과물을 만들어준다는 인상입니다. 다만 "만들어줘"라고 막연하게 던진 것이 아니라, 먼저 SPEC.md를 작성했습니다. 내용은 다음과 같습니다.

• 목적과 「아무것도 하지 않아도 되는 상태」의 정의
• 화면 전환 절차 (수동 관찰 결과를 그대로 문서화)
• 데이터 모델 (대출 스냅샷의 JSON 구조와 키 설계)
• 예외 처리 (로그인 실패 시·취득 실패 시·최초 실행 시의 동작)
• 수락 조건 (어떠한 상태가 되면 완성인가)

흔히들 하는 말이지만, 사양(Specification)을 먼저 문서화하면 구현 시 발생하는 재작업(rework)이 눈에 띄게 줄어듭니다. 인간의 업무는 사양을 작성하는 것과 리뷰하는 쪽으로 기울어갑니다. 반대로, 예외 처리와 수락 조건을 작성하지 않고 AI에게 던지면, 일단은 동작하지만 운영을 견디지 못하는 결과물이 나오기 쉽습니다.

이 SPEC.md 작성 방식은 수요가 있다면 별도의 기사나 템플릿으로 정리할 예정입니다.

소요된 비용과 시간

• 개발 시간: 약 1.5시간 (사양서 작성 및 리뷰 포함. 구현은 AI 에이전트)
• 금전적 비용: 거의 제로 (AI 이용은 기존 계약 범위 내, 실행은 로컬)
• 운영 수고: 버그 대응 0회. 기능 추가 2회 (카테고리·출판사 정보 취득)
• 구성: Python 스크립트 + 설정 파일 + 셋업 스크립트 ZIP 일체

중요한 주의사항

이러한 종류의 자동화를 수행할 때의 전제 조건을 명확히 해둡니다.

• 본인 계정의, 본인 대출 데이터에 대한 개인적 이용으로 한정하고 있습니다. 축적된 이력도 로컬에만 저장합니다.
• 액세스는 하루에 1회. 사람이 매일 아침 한 번 로그인하여 확인하는 것과 동일한 부하입니다.
• 도서관 사이트의 이용 약관과 공공 시스템에 대한 예의를 지키는 범위 내에서 운영하고 있습니다.

「자동화할 수 있다」와 「고빈도로 요청해도 된다」는 별개의 문제입니다. 특히 공공 서비스에 대해서는 더욱 그렇습니다. 이 전제를 무너뜨리면 편리한 개인 도구가 그저 민폐 행위가 됩니다.

덧붙여, 도서관 시스템이 이력을 남기지 않는 것은 프라이버시 보호라는 정당한 설계입니다. 이 도구는 그것을 본인이 자신의 의지로 수중에 다시 기록하는 것이지, 설계 사상에 대한 불만이 아닙니다.

마치며

한 번 만들어두면 계속 돌아가는 개인 자동화는 생활의 인지 부하(cognitive load)를 하나 줄여줍니다. 동일한 메커니즘(로그인 → 취득 → 이전 데이터와의 차이 → 변화만 기록·통지)은 사내 시스템의 신청 현황, 각종 포털, 포인트 소멸 모니터링 등 로그인이 필요한 사이트의 정기 체크 전반에 응용할 수 있습니다.

다음에는 인근 지역에서 실시 중인 캐시리스(cashless) 캠페인 대상 점포를 검색할 수 있는 도구를 만들고 있는 이야기를 쓸 예정입니다. AI 에이전트에게 구현시키기 위한 SPEC.md 템플릿도 정비 중이므로, 이 방향에 관심이 있으신 분은 X(@waka_ds_tech)를 팔로우해 주시면 감사하겠습니다.

블로그(waka-ds.com)에서는 멀티 에이전트(multi-agent) 체제나 하네스 엔지니어링(harness engineering) 등 한 단계 더 깊은 설계 이야기도 쓰고 있습니다.

Discussion