Claude Code 지역 분할 사이트 크롤링 스킬 — "동네별로만 검색된다" (region-sharded-crawling)

지역 기반 사이트는 검색이 동네 단위로 쪼개져 있습니다. 한 동네씩은 잘 보이는데, 전국을 한 번에 훑을 방법이 없습니다. 동네 목록부터 만들어야 하고, 그걸 모으다 보면 차단(HTTP 429)을 맞기 쉽습니다.

왜 만들었나

당근마켓 매물 검색 도구를 만들며 겪은 것들입니다. 처음엔 "SPA 니까 스텔스 헤드리스 브라우저가 필요하겠다"로 시작했고, 광역 검색 파라미터가 결과를 주길래 되는 줄 알았고, 병렬 8스레드로 몰아치다 차단당했습니다. 전부 실제 응답으로 확인한 뒤 순서와 스크립트로 정리했습니다.

무엇을 하나

• 헤드리스 브라우저가 필요한지 먼저 판별 — curl 로 받아 원하는 데이터가 HTML 에 문자열로 있으면 브라우저는 필요 없습니다. 압축 HTML 에서 한글 grep 이 0을 내도 Python 으로 다시 확인합니다.
• 광역 검색 착각 잡기 — 존재하지 않는 지역값을 대조군으로 함께 던져, 결과가 같으면 광역 검색이 아니라 폴백이라고 판정합니다.
• slug 의 어느 부분이 쓰이는지 확인 — 이름과 ID 중 ID 만 유효하다는 걸 확인하면 ID 순회로 사전을 모을 수 있습니다.
• 인접 지역 목록 역이용 — 페이지가 함께 주는 주변 지역 목록으로 조회 1회에 8개 지역을 얻고, 빈 번호(자기 자신이 이웃 목록에 없음)는 건너뜁니다.
• 동명이인 지역은 이웃 다수결 — 이웃 목록 전체를 행정구역 사전과 대조해 시·군·구를 정합니다.
• ID 블록 지도 먼저 — 성긴 샘플링으로 어느 구간에 어느 지역이 있는지 보고 필요한 구간만 돕니다.
• 429 피하기 — 동시 1개, 무작위 텀, 주기 휴식, 차단 시 즉시 중단, 짧은 본문도 차단으로 의심.

실측

헤드리스 브라우저를 썼다면 동네당 0.3초로 끝날 일이 1~3초로 늘어났을 겁니다. 이 사이트는 React 기반인데도 서버에서 완전한 HTML 을 내려줬습니다.

구성

설치

스크립트의 URL·ID 구간은 사례(당근) 기준입니다. 다른 사이트에 쓸 땐 파일 위쪽 상수를 바꿉니다.

요구 사항

• Claude Code
• python3(표준 라이브러리만), curl
• 공개 사이트라도 이용약관·robots.txt 확인은 사용자 몫입니다. 스킬은 IP 우회를 권하지 않습니다

이런 분께

• 동네·지점 단위로만 검색되는 사이트에서 전체 목록이 필요한 분
• 크롤러를 병렬로 돌리다 429 차단을 맞아 본 분
• 지역 이름이 겹쳐(중앙동 등) 행정구역을 붙이는 데 막힌 분