Claude Code로 워드프레스 404 내부 링크 자동 탐지하기

운영중인 워드프레스 404 에러를 경험하신적이 있나요? Claude Code 워드프레스 자동화가 아니었다면, 몇 백개의 글에 걸린 내부 링크를 하나씩 클릭해서 확인하는 건 불가능했습니다. 글이 쌓일수록 예전 포스트의 링크가 어느 순간 404가 되어 있어도 알아챌 방법이 없습니다. 주소가 바뀐 글, 삭제된 글, 슬러그를 수정한 글이 한 번이라도 있었다면 그 글을 가리키던 링크는 전부 깨진 상태로 남습니다.

이 문제를 해결하기 위해 Claude Code에 Python 스크립트 작성을 요청했습니다. WP REST API로 전체 포스트를 수집하고, 내부 링크를 추출해 실제 HTTP 상태 코드를 확인하는 방식입니다. 이 글은 그 과정과 결과, 그리고 한계를 솔직하게 정리한 기록입니다.

Claude Code와 WP REST API 조합

코딩을 모르는 분들을 위해 먼저 두 가지 개념을 간단히 짚고 넘어가겠습니다.

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 도구입니다. 채팅창이 아니라 실제 파일 시스템과 연결된 환경에서 작동하기 때문에 “이런 스크립트를 만들어줘”라고 요청하면 파일을 직접 생성하고 실행까지 도와줍니다. ChatGPT에게 코드를 물어보고 복사해서 붙여넣는 방식과 달리, Claude Code는 실행 결과를 보면서 오류를 수정하는 과정을 함께 처리합니다.

WP REST API는 워드프레스가 기본으로 제공하는 데이터 접근 인터페이스입니다. 블로그 주소 뒤에 /wp-json/wp/v2/posts를 붙이면 발행된 모든 글을 JSON 형태로 가져올 수 있습니다. 이 기능은 별도 플러그인 없이 워드프레스 자체에 내장되어 있습니다.

두 가지를 조합하면 이런 흐름이 만들어집니다. Claude Code가 작성한 Python 스크립트가 WP REST API를 통해 전체 포스트를 가져오고, 각 글의 본문에서 링크를 추출한 뒤, 해당 URL에 실제로 요청을 보내 404인지 확인합니다. 사람이 수작업으로 할 일을 코드가 대신하는 구조입니다.

실제 작동 방식: 3단계

실제로 클로드코드 프롬프트 한줄이면 됩니다.

Claude Code 열어서 이렇게 물어보세요.

현재 워드프레스 환경에서 내부 링크 깨진 것 404 페이지 찾아서 수정하거나 리다이렉트 거는 스크립트 만들어줘. Search Console에서 404 목록 CSV 내보내기 할 수 있으면 그것도 활용해줘.

1단계: 전체 포스트 수집

WP REST API는 한 번에 최대 100개의 글만 반환합니다. 몇 백개 글을 모두 가져오려면 페이지를 넘기면서 반복 요청을 해야 합니다. 스크립트는 이 과정을 자동으로 처리합니다. page=1부터 시작해서 더 이상 글이 없는 시점까지 반복 요청을 보내고, 수집한 데이터를 메모리에 쌓습니다.

이 단계에서 가져오는 정보는 글 ID, URL, 슬러그, 제목, 본문 HTML입니다. 인증은 워드프레스 애플리케이션 비밀번호를 사용합니다.

2단계: 내부 링크 추출

수집된 각 포스트의 본문 HTML에서 <a href="..."> 태그를 파싱합니다. 이 중에서 사이트 도메인(emotionte.com)을 포함한 URL만 추출합니다. 외부 사이트로 나가는 링크는 제어 범위 밖이므로 제외합니다.

링크 추출에는 Python 표준 라이브러리인 re(정규식)를 사용합니다. 별도 HTML 파서 없이도 href 속성값을 깔끔하게 뽑아낼 수 있습니다.

3단계: HEAD 요청으로 상태 확인

추출된 내부 링크 각각에 HTTP HEAD 요청을 보냅니다. HEAD 요청은 GET 요청과 달리 본문을 받지 않고 상태 코드만 확인합니다. 속도가 빠르고 서버 부하가 적습니다.

응답 코드가 404이거나 연결 자체가 실패하면 해당 링크를 오류 목록에 기록합니다. 200이면 정상, 301이나 302면 리다이렉트가 걸려 있는 상태입니다. 스크립트는 각 요청 사이에 0.3초 딜레이를 두어 서버에 과도한 부하가 걸리지 않도록 처리합니다.

결과는 JSON 파일로 저장됩니다. 어떤 글의 어떤 링크가 404인지 구조화된 형태로 남기 때문에 이후 수정 작업에 활용할 수 있습니다.

실행 결과: 약 400개 포스트 스캔

스크립트를 실행하자 400개 포스트에서 내부 링크를 추출하고 상태를 확인하는 과정이 시작됐습니다. 처음에는 잘 작동하는 것처럼 보였지만, 한국어 슬러그에서 문제가 발생했습니다.

워드프레스는 한글 제목을 슬러그로 변환할 때 URL 인코딩 형태로 처리합니다. 예를 들어 “AI 도구 비교”라는 제목의 글 주소는 ai-%eb%8f%84%ea%b5%ac-%eb%b9%84%ea%b5%90 같은 형태가 됩니다. 슬러그를 나중에 영문으로 수정하면 이전 한국어 슬러그를 가리키던 링크는 404가 됩니다.

스크립트에는 유사도 매칭 기능이 포함되어 있습니다. Python의 difflib.SequenceMatcher를 사용해 404 URL과 현재 존재하는 슬러그 사이의 유사도를 계산하고, 가장 근접한 후보를 리다이렉트 대상으로 추천하는 방식입니다.

문제는 한국어 슬러그와 영문 슬러그 사이의 유사도가 0.6 이하로 낮게 나온다는 점입니다. %eb%8f%84%ea%b5%ac와 ai-tools-comparison 사이의 문자열 유사도는 사람이 보기엔 같은 글이지만 알고리즘은 전혀 다른 것으로 인식합니다. 자동 매칭 정확도가 낮아 수동 검토가 필요한 케이스가 많이 나왔습니다.

이 한계를 보완하기 위해 Google Search Console(GSC) CSV 모드를 추가했습니다.

5가지 실행 모드

스크립트는 상황에 따라 다른 모드로 실행할 수 있습니다.

--scan: 전체 포스트 내부 링크를 스캔해 404를 탐지합니다. 처음 실행 시 사용합니다. 포스트 수에 따라 수 분이 소요됩니다.

--gsc CSV파일경로: Google Search Console에서 404 페이지 목록을 CSV로 내보내 분석합니다. GSC에는 실제 유저가 접근해서 404를 만난 URL이 기록되기 때문에 자동 스캔보다 정확도가 높습니다. Search Console의 색인 생성 탭에서 “찾을 수 없음(404)” 항목을 CSV로 내보내면 됩니다.

--fix-content: 스캔 결과를 바탕으로 포스트 본문의 href를 직접 교체합니다. WP REST API의 글 수정 엔드포인트를 사용합니다. 실행 전 반드시 백업을 권장합니다.

--export-redirects: 404 URL과 리다이렉트 대상을 Redirection 플러그인이 읽을 수 있는 CSV 형태로 내보냅니다. 자동 수정이 부담스러운 경우 이 파일을 플러그인에서 직접 임포트할 수 있습니다.

--apply-redirects: Redirection 플러그인의 REST API를 통해 리다이렉트 규칙을 자동으로 등록합니다. Redirection 플러그인이 설치되어 있어야 하고, 플러그인 측 API 인증이 별도로 필요합니다.

이 방법의 한계

실제로 써보면서 느낀 한계를 솔직하게 정리합니다.

서버 부하: 딜레이를 0.3초로 설정했지만 수백 개 URL에 연속으로 요청을 보내는 것 자체가 서버에 부담입니다. 공유 호스팅을 사용하고 있다면 트래픽 제한에 걸릴 수 있습니다. 딜레이 값을 늘리거나 야간에 실행하는 것을 권장합니다.

속도: 400개 포스트 스캔에 실제로 수 분이 걸립니다. 글이 많을수록 시간은 선형으로 늘어납니다. 백그라운드에서 실행하고 결과를 기다리는 방식으로 사용하는 것이 현실적입니다.

한국어 슬러그 매칭 정확도: 앞서 언급했듯 영문 슬러그로 바꾼 글에 대한 자동 매칭은 신뢰도가 낮습니다. GSC CSV 모드를 병행해도 리다이렉트 대상은 수동으로 확인하는 과정이 필요합니다.

인증 설정 필요: WP 애플리케이션 비밀번호를 발급하고 환경 변수에 등록해야 합니다. 이 부분이 기술적으로 가장 허들이 높습니다. 워드프레스 관리자 > 사용자 > 프로필 > 애플리케이션 비밀번호에서 발급할 수 있습니다.

콘텐츠 자동 수정 리스크: --fix-content 모드는 글 본문을 직접 수정합니다. 매칭 오류가 있으면 엉뚱한 링크로 교체될 수 있습니다. 이 모드를 사용하기 전에는 반드시 데이터베이스 백업을 먼저 해야 합니다.

FAQ

Q. 코딩을 전혀 모르는데 이 방법을 쓸 수 있나요?

Claude Code 자체는 터미널에서 실행하는 도구이기 때문에 코딩 경험이 없으면 진입 장벽이 있습니다. 다만 Python과 환경 변수 설정 정도의 개념만 익히면 실행 자체는 어렵지 않습니다. Claude Code가 오류가 발생할 때마다 원인을 설명하고 수정 방법을 제안하기 때문에 단계별로 따라가는 방식으로 진행할 수 있습니다.

Q. Redirection 플러그인 없이도 쓸 수 있나요?

--scan과 --gsc 모드는 플러그인 없이도 작동합니다. 404를 탐지하고 결과를 JSON으로 저장하는 것까지는 가능합니다. 리다이렉트 자동 등록 기능(--apply-redirects)만 Redirection 플러그인이 필요합니다.

Q. 외부 링크 404도 확인할 수 있나요?

현재 스크립트는 내부 링크만 대상으로 합니다. 외부 링크는 상대방 서버 사정에 따라 상태가 달라지고, 요청을 보내는 것 자체가 상대방 서버에 부담을 줄 수 있어 의도적으로 제외했습니다.

Q. GSC에서 404 목록을 내보내는 방법은요?

Search Console > 색인 생성 > 페이지 탭으로 이동 후 “찾을 수 없음(404)” 항목을 클릭합니다. 오른쪽 상단 내보내기 버튼에서 CSV를 선택하면 됩니다. 이 파일을 --gsc 옵션에 경로로 지정하면 분석이 시작됩니다.

마치며

수백개 글이 넘는 블로그를 운영하다 보면 어느 순간부터 내부 링크 관리가 손에서 벗어납니다. Claude Code 덕분에 스크립트 작성에 시간을 쓰지 않고도 자동화 도구를 만들 수 있었습니다. 코드를 작성한 것이 아니라 문제를 설명하고 결과물을 검토하는 방식으로 접근했습니다.

완벽하지는 않습니다. 한국어 슬러그 매칭 문제는 여전히 수동 검토를 피할 수 없고, 서버 부하 문제도 남아 있습니다. 그럼에도 수백 개 링크를 하나씩 클릭해서 확인하는 것보다는 훨씬 현실적인 접근입니다.

블로그 SEO에서 내부 링크 404는 생각보다 조용하게 손해를 줍니다. 유저 경험을 해치고, 크롤러가 해당 경로를 포기하게 만들기 때문입니다. GSC에서 404 리포트를 주기적으로 확인하면서 이 스크립트를 병행하는 것이 현재로서는 가장 현실적인 관리 방식입니다.