웹사이트 통째로 문서 하나에 담는 법
어려운 쪽은 수집이 아니라 검증이었습니다
여러 페이지에 흩어진 자료를 하나의 파일로 모으는 작업이었는데, 정작 손이 많이 간 곳은 수집이 아니었습니다. 긁는 건 금방 끝났습니다. 프로그램이 도니까 몇 분이면 충분했습니다. 정작 시간을 잡아먹은 쪽은 그렇게 만든 문서가 “전부”가 맞는지 확인하는 일이었습니다. 같은 사이트를 세 번 수집했습니다. 첫 번째와 두 번째 결과물에는 모두 빠진 부분이 있었습니다. 최종 문서는 1,296개 URL에서 1,291개의 고유 본문을 담았고 104,867줄, 약 4.26MB짜리 마크다운 파일이 됐는데, 이건 첫 시도 결과물의 4배가 넘는 분량입니다.
이 글에는 그 과정에서 어디가 왜 빠졌는지, 그것을 어떻게 찾아냈는지를 적었습니다. 수집한 자료 자체는 다루지 않습니다.
왜 하나의 파일로 모으려 했나
제가 참고해야 하는 자료는 노션 기반으로 만들어진 공개 자료 사이트 여기저기에 흩어져 있었습니다. 가이드, 공지, 업데이트, 이벤트가 전부 별개 페이지로 나뉘어 있어서 뭐 하나 확인하려면 매번 사이트에 들어가 검색창에 단어를 넣고 결과를 훑어야 했습니다. 번거로웠습니다.
목적은 단순했습니다. 마크다운 파일 하나를 만들어 두고 Claude든 ChatGPT든 Gemini든 그때그때 쓰는 도구에 첨부한 다음 “이 문서를 지식 자료로 사용해서 답변해 달라”고 시키는 것. 도구를 하나로 묶어두지 않으려는 선택이기도 했습니다. 특정 서비스의 지식베이스 기능에 자료를 넣어두면 그 서비스를 벗어나는 순간 처음부터 다시 만들어야 하니까요. 그건 피하고 싶었습니다.
모델이 페이지를 읽게 하지 않았습니다
초반에 방식을 한 번 갈아엎었습니다. AI 에이전트가 페이지를 하나씩 열어 읽고 정리하는 방식이면 페이지 수만큼 토큰(토큰이 무슨 뜻인지 따로 정리해둔 글이 있습니다)이 그대로 붙습니다. 300개, 1,000개 단위가 되면 감당이 안 됩니다.
그래서 방향을 틀었습니다. 파이썬 크롤러를 만들어 돌리는 쪽으로요. 모델은 크롤러를 작성하고 결과 통계를 확인할 뿐이고, 페이지 본문은 프로그램이 직접 내려받아 파일에 씁니다. 이렇게 하면 1,000개를 긁어도 모델이 소비하는 토큰은 코드 몇 개 분량에서 끝납니다. 이 구분은 실무자에게 꽤 중요합니다. “AI로 자료를 모았다”고 말해도 실제로는 AI가 프로그램을 짜고 그 프로그램이 일한 겁니다.
1차 수집: 357개를 찾았고 356개를 담았습니다
크롤러는 메인 페이지에서 시작해 링크를 따라가며 파도처럼 범위를 넓히는 방식으로 돌았습니다. 로그가 그대로 남았습니다.
| 단계 | 가져온 페이지 | 그 시점까지 발견한 URL |
|---|---|---|
| 1차 | 1개 | 1개 |
| 2차 | 13개 | 14개 |
| 3차 | 197개 | 211개 |
| 4차 | 146개 | 357개 |
3차에서 197개가 한꺼번에 나왔습니다. 저는 그게 전체 페이지 수인 줄 알았습니다. 아니었습니다. 그 단계에서 새로 발견된 묶음일 뿐이었고, 4차까지 돌리자 357개가 됐습니다.
실패한 16개 URL은 재시도로 전부 회수했습니다. 여기까지는 순조로웠습니다. 결과는 발견 357개, 병합한 고유 문서 356개, 본문이 완전히 같은 중복 1개 제외, 수집 실패 0개였습니다. 파일은 24,154줄에 약 1.01MB였습니다.
여기서 끝났다고 생각했습니다. 통계상 실패가 0이었으니까요.
첫 번째 누락: 링크만 있고 본문이 없는 외부 문서
문서를 받고 나서 양이 생각보다 적다는 느낌이 들었습니다. 혹시 해서 공식 백서 내용이 들어 있는지 찾아봤습니다. 없었습니다.
원인은 금방 나왔습니다. 크롤러는 그 사이트 도메인 안의 내부 링크만 따라가도록 만들어져 있었는데, 백서는 별도 도메인에 올라가 있었기 때문에 문서에는 링크만 들어가고 본문은 통째로 빠져버린 겁니다. 크롤러 입장에서는 정상 동작이었습니다. 실패 0개라는 통계도 거짓말은 아니었습니다. 애초에 시도조차 하지 않은 영역이었을 뿐입니다.
이 대목이 이번 작업에서 가장 크게 배운 점입니다. 수집 실패 0개는 “빠진 게 없다”는 뜻이 아닙니다. “내가 시도한 것 중에 실패한 게 없다”는 뜻입니다.
llms-full.txt라는 지름길
다행히 백서 쪽에는 통합 원문 파일이 공개돼 있었습니다. 요즘 문서 사이트들이 AI가 읽기 좋으라고 전체 내용을 하나의 텍스트로 묶어 제공하는 `llms-full.txt` 방식이었고, 이 파일을 그대로 병합했습니다.
백서 96개 페이지 분량이 추가되면서 총 문서 섹션은 452개, 29,605줄, 약 1.35MB로 늘었습니다. 기존 파일은 별도 이름으로 백업해 두고 새 파일로 교체했습니다. 되돌릴 수 있게 남겨두는 습관은 이런 작업에서 몇 번이나 저를 구했습니다.
두 번째 누락: 접혀 있는 토글은 크롤러에 보이지 않았습니다
그런데 끝이 아니었습니다. 아카이브 페이지를 직접 스크롤해 보니 2026년 8월까지 월별로 자료가 차곡차곡 쌓여 있었습니다. 문서 452개로는 설명이 안 됩니다. 한 달에 스무 개에서 서른 개씩만 잡아도 훨씬 많아야 했습니다.
대조해 봤습니다. 이렇게 갈렸습니다.
- `~2023` 페이지: 포스팅 링크 117개가 화면에 그대로 노출돼 있어서 전부 수집됨
- `2024-01`부터 `2026-08`까지: 월별 항목이 접힌 토글 상태
- 텍스트 크롤러는 월 제목만 읽고, 토글 안쪽의 포스팅 링크는 읽지 못함
제가 만든 크롤러는 HTML에 이미 들어 있는 링크만 볼 수 있었습니다. 클릭해야 펼쳐지는 영역은 존재 자체를 몰랐습니다. 게다가 다른 가이드나 공지 페이지를 타고 우연히 들어온 2024년 이후 포스팅이 일부 섞여 있었던 탓에, 문서를 열어봐도 그 구간이 완전히 비어 있는 것처럼 보이지는 않았습니다. 이쪽이 더 위험합니다. 아예 없으면 눈에 띕니다. 일부만 있으면 있는 줄 알고 그냥 넘어가게 됩니다.
이 시점에 저는 그 문서를 “전체 자료”라고 부르는 걸 멈췄습니다. 32개 월별 토글을 전부 펼쳐 URL 목록을 뽑고 기존 357개와 하나씩 대조해 빠진 것을 채워 넣어야 비로소 확정할 수 있는 상태였기 때문입니다.
브라우저 원격 조작은 결국 쓰지 않았습니다
처음 잡은 방법은 크롬을 원격 디버깅 모드로 붙잡아 토글을 하나씩 실제로 클릭하게 만드는 것이었습니다. 잘 안 됐습니다.
권한을 허용하는 화면이 뜨는데, 안내대로 팝업을 아무리 찾아도 나오지 않았습니다. 몇 번 헤맨 뒤에야 알았습니다. 그 화면은 팝업이 아니라 크롬 상단의 두 번째 탭으로 열려 있었습니다. 게다가 이 권한 화면은 자동화 도구가 대신 클릭할 수 없도록 아예 막혀 있어서, 결국 사람이 직접 체크하고 허용 버튼을 눌러야 했습니다. 중간에는 응답 대기가 40초를 넘겨 그냥 끊긴 구간도 있었습니다.
결국 원격 디버깅 없이 다른 방식으로 월별 토글 안의 URL을 추출했고, 그러면서 따로 실행하려던 크롬 디버깅 명령어도 쓸 필요가 없어졌습니다. 시간은 버렸습니다. 다만 그 과정에서 “브라우저 자동화는 권한 화면 앞에서 멈춘다”는 점을 확인했습니다.
최종 수집: 1,296개
토글에서 937개 URL이 나왔습니다. 기존 357개와 합쳐 중복을 제거하니 후보가 1,292개, 그중 새로 내려받아야 할 것이 935개였습니다.
두 번째 크롤러의 로그는 이렇게 남았습니다. 1차에서 935개, 2차에서 새로 발견된 4개, 마지막 재시도 37건. 최종 집계는 이렇습니다. 페이지 1,296개, 고유 본문 1,291개, 실패 0개, 완전 중복 5개, 보존한 고유 이미지 URL 3,050개, 약 4.26MB. 실행 시간은 중간 확인 시점에 이미 14분을 넘겼습니다. 전체로는 그보다 더 걸렸습니다.
이미 받아둔 `~2023` 자료는 다시 내려받지 않고 최종 문서에 병합했습니다. 같은 페이지를 두 번 긁을 이유가 없습니다. 시간 낭비이기도 하고, 상대 서버에도 부담이 됩니다.
중복과 이미지 처리
본문이 완전히 같은 URL 5개는 본문을 한 번만 넣고, 대신 중복 출처 URL 5개를 함께 기록해 뒀습니다. 나중에 “이 내용이 어느 주소에 있었나”를 되짚을 수 있어야 하니까요.
이미지는 파일 안에 바이너리로 넣지 않았습니다. 원본 이미지 URL을 마크다운 형식으로 보존하는 쪽을 택했는데, 3,050개를 통째로 담으면 파일이 감당하기 어려운 크기가 되고 그러면 AI에 첨부할 수도 없기 때문입니다. 대신 이미지가 그 자리에 존재했다는 사실과 출처는 남습니다. 물론 이미지 서버가 내려가면 링크는 죽습니다. 감수한 부분입니다.
검증은 숫자 대조로 했습니다
마지막에 확인한 건 하나입니다. 월별 토글에서 발견한 URL 937개가 최종 문서에 전부 들어갔는가.
- 발견한 월별 URL: 937개
- 최종 문서에 포함된 월별 URL: 937개
- 누락: 0개
수집 단계의 “실패 0개”와 이 대조는 성격이 다릅니다. 아예 다른 이야기입니다. 앞의 것은 요청이 성공했다는 뜻입니다. 뒤의 것은 제가 알고 있는 목록이 결과물에 빠짐없이 들어갔다는 뜻입니다. 1차 수집에서 백서가 통째로 빠진 것도 결국 대조할 목록 자체가 없었기 때문이었습니다. 그래서 수집을 시작하기 전에 “무엇이 몇 개 있어야 하는지”부터 확정해 두는 편이 좋습니다.
그래도 보장할 수 없는 것
최종 문서를 두고도 “2022년부터 지금까지 전부”라고 말하지는 않았습니다. 정확한 표현은 따로 있습니다. “현재 공개돼 접근 가능한 자료와 공식 문서 전체”입니다.
지금은 삭제됐거나, 남아 있어도 어떤 페이지에서도 링크되지 않는 게시물이라면 링크를 따라가는 방식의 크롤러는 도달할 방법이 아예 없습니다. 구조적 한계입니다. 이 한계를 문서 앞에 적어두느냐 마느냐는 나중에 자료를 실제로 쓸 때 꽤 큰 차이를 만듭니다.
남은 것
같은 작업을 다시 한다면 순서는 이렇게 잡겠습니다.
- 수집 전에 사이트를 직접 스크롤하며 대략 몇 개가 있어야 하는지 감을 잡습니다
- 접히는 영역, 더 보기 버튼, 무한 스크롤이 있는지부터 확인합니다. 텍스트 크롤러의 사각지대가 정확히 여기입니다
- 외부 도메인으로 나가는 핵심 문서가 있는지 봅니다. 공식 문서 사이트라면 통합 원문 파일이 있는지 먼저 찾아봅니다
- 완료 후에는 “실패 0개”가 아니라 “내가 세어둔 목록과 결과물이 일치하는가”로 확인합니다
작업 자체는 AI 에이전트가 크롤러를 짜고 돌리는 것으로 끝났습니다. 사실상 전부 기계가 했습니다. 사람이 한 일은 하나뿐입니다. 결과물을 보고 “이것보다 많아야 하는데”라고 의심한 것. 그 의심이 없었다면 지금도 4분의 1짜리 문서를 완성본이라 믿고 쓰고 있었을 겁니다.
