출처 대조 B게시 2026-10-29최종 확인 2026-10-29읽기 6분

Claude Code SEO 플러그인 claude-seo로 블로그 점검하기

오픈소스 claude-seo 플러그인을 레포 한 곳에만 설치하고, 정적 블로그를 세 번 진단해 76점에서 82점까지 올린 과정. 받아들인 권고와 버린 권고를 나눠 적었다.

30초 요약

  • claude-seo는 Claude Code 안에서 사이트를 진단하는 오픈소스 플러그인(MIT)이다. 하위 에이전트 여러 개가 기술·콘텐츠·구조화 데이터·성능을 나눠 보고, 우선순위를 매긴 보고서를 Markdown으로 남긴다.
  • --scope local로 설치하면 그 레포에서만, 나에게만 켜진다. 다른 프로젝트에는 영향이 없다.
  • 세 번 진단하는 동안 점수는 76 → 80 → 82로 올랐다. 점수는 플러그인의 휴리스틱이지, Google의 신호가 아니다. 쓸모는 점수가 아니라 「무엇이 빠졌는지」를 목록으로 받는 데 있다.
  • 권고 중 다섯 가지는 버렸다. 버린 기준을 글 끝에 적었다.

증상/목표

AdSense 심사에서 「가치가 별로 없는 콘텐츠」로 거절됐다. 글 내용은 손보고 있었지만, 사이트 구조에서 무엇이 빠졌는지는 감으로만 알고 있었다. 저자 표기, 사이트맵, 내부 링크, 구조화 데이터 같은 항목을 한 번에 점검할 도구가 필요했다. 외부 SEO 서비스는 월 구독이고, 결과를 레포에 바로 반영하려면 Claude Code 안에서 도는 게 편하다.

해결 방법

1. 레포 한 곳에만 설치한다

Claude Code 플러그인은 설치 범위를 고른다. user는 이 PC의 모든 프로젝트, project는 레포 작업자 전원(설정 파일을 커밋), local은 나와 이 레포만이다. 진단 도구는 혼자 쓰면 되고 레포 설정을 바꾸고 싶지 않아서 local을 골랐다.

Terminal window
cd ~/workspace/blog
claude plugin marketplace add AgriciDaniel/claude-seo
claude plugin install claude-seo@agricidaniel-claude-seo --scope local
claude plugin list

마켓플레이스 이름이 레포 이름과 다르다. agricidaniel-claude-seo는 레포의 .claude-plugin/marketplace.json에 적힌 값이다. list 결과에서 Scope가 local이면 끝이다. 설정은 .claude/settings.local.json에 들어가며, 이 파일이 .gitignore에 있는지 git check-ignore로 확인했다.

2. 런타임을 준비한다

/claude-seo:seo setup

플러그인은 파이썬 가상환경과 Chromium을 따로 만든다. Ubuntu 26.04의 파이썬 3.14에는 ensurepip이 없어서 첫 실행이 여기서 멈췄다. sudo apt install python3.14-venv를 터미널에서 직접 실행한 뒤 setup을 다시 돌리니 통과했다. 플러그인이 전역 pip로 우회하지 않고 멈춘 점이 마음에 들었다.

3. 진단은 「진단만」 시킨다

같은 세션에 아래처럼 지시했다. 핵심은 첫 줄이다.

claude-seo 플러그인으로 진단만 하라. 레포의 파일은 하나도 고치지 마라. 커밋·push도 하지 마라.
1. https://example.com 를 audit하라.
2. 대표 글 4편에 content 분석을 실행하라.
3. 보고서는 레포 밖 ~/seo-reports/날짜/ 에 저장하라.
4. Google 계정 연동, 이미지 생성, 유료 확장은 쓰지 마라.
5. 항목마다 근거(Google 문서인지 플러그인 휴리스틱인지)와 범위(사이트 전체/글 단위), 심각도를 적어라.

5번이 중요했다. 플러그인은 Google 문서에 근거한 항목과 자체 휴리스틱을 섞어 내놓는다. 근거를 적게 하면 나중에 받아들일지 판단하기 쉽다.

4. 보고서를 읽고 고칠 것을 고른다

세 번의 진단에서 받아들인 항목은 다음과 같다. 모두 Google 문서가 근거였다.

발견조치
글에 저자 표기가 없다바이라인과 소개 페이지의 「누가·어떻게」 절
사이트맵에 <lastmod>가 없다글 수정일로 채움
슬래시 없는 내부 링크가 301로 넘어간다링크 헬퍼 하나를 고쳐 대부분 해결
본문에 다른 글 링크가 없는 글이 24편(첫 진단 기준)실제로 이어지는 쌍에만 한 문장씩
홈페이지 Organization에 @id가 없어 블로그 참조가 끊김@id·sameAs 추가
같은 글 목록을 가진 태그·카테고리 페이지겹치는 태그 페이지에 noindex

5. 고친 뒤 다시 돌린다

같은 지시로 재진단하면 보고서가 「해결됨 / 부분 해결 / 새로 생김」으로 나뉘어 나온다. 두 번째 진단은 첫 수정의 부작용을 잡아 줬다. 하나는 고정 페이지의 lastmod가 전부 배포일로 찍히는 문제였는데, 배포 워크플로의 checkout이 얕아서 git log가 최신 커밋 날짜만 돌려준 것이었다. 다른 하나는 아래 주의에 적었다.

진단 실행에서 보고서, 사람이 받아들일 항목을 고르고, 수정 PR, 재진단으로 이어지며, 새 부작용이 있으면 다시 고르는 단계로 돌아가는 순환 흐름도있음없음진단 실행보고서근거·범위·심각도받아들일 항목 고르기수정 PR재진단새 부작용?마무리
진단 → 선별 → 수정 → 재진단 순환. 파랑은 자동, 보라는 사람이 정하는 단계, 회색은 조건이다.

확인

세 번 진단한 점수는 76 → 80 → 82였다. 분야별로는 Technical 80 → 89, Schema 72 → 82, Content 70 → 77이 올랐고 Performance는 82 → 78로 내려갔다. 성능은 폰트 CSS를 손대지 않아서 실제로는 변화가 없고, 랩 측정 편차로 본다.

검증 범위: 이 글은 한 PC(WSL Ubuntu 26.04, Claude Code 터미널)에서 플러그인 v2.5.0을 실행한 기록이다. 점수와 발견 항목은 플러그인이 낸 값이며 Google 검색 결과나 AdSense 심사 결과로 확인한 것이 아니다. 러너에서 재현하지 않았다.

주의

  • 하위 에이전트의 오보가 있다. 「홈페이지에 JSON-LD가 없다」는 보고가 있었는데 실제로는 블록 두 개가 있고 @id만 없었다. 오케스트레이터가 걸러 주긴 했지만, 고치기 전에 curl로 직접 확인하는 습관이 필요하다.
  • 수정일을 한꺼번에 바꾸지 않는다. 내부 링크 한 줄을 넣은 글 스무 편 남짓의 updatedDate를 그날로 갱신했다가 재진단에서 지적받았다. Google은 실질적 변경 없이 날짜만 갱신하는 것을 좋게 보지 않는다. 사실·코드·결론이 바뀐 글만 갱신하도록 규칙을 문서에 적었다.
  • 사용량이 크다. 전체 진단은 에이전트 11개가 병렬로 돌아 10분 이상 걸리고, 구독 사용량을 꽤 쓴다. 홈페이지 같은 작은 사이트부터 돌려 보고 블로그는 따로 돌리는 게 낫다.
  • 설치하면 훅이 하나 붙는다. 파일을 수정할 때마다 JSON-LD를 검사하는 훅이다. local 범위면 그 레포에서만 돈다.

버린 권고

  • llms.txt 같은 AI 전용 파일: 플러그인 스스로 Google 문서를 인용해 필요 없다고 적어 두었다.
  • 글자 수 늘리기: 플러그인도 「목표가 아니라 참고」라고 한다. 오류 해결 글을 늘릴 이유가 없다.
  • 이미지 생성, 유료 API 확장: 비용이 생기고 지금 필요 없다.
  • 검증 범위 밖 내용 추가(예: Windows 절 추가): 실행해 보지 않은 내용은 쓰지 않는다는 이 블로그의 원칙과 맞지 않는다.
  • 종류만 같은 글끼리 내부 링크(CVE 글 세 편 서로 연결): 독자가 그 자리에서 찾을 글이 아니면 넣지 않는다.

자주 묻는 질문

점수가 오르면 검색 순위도 오르나?

모른다. 플러그인 문서도 점수는 휴리스틱이고 Google 내부 신호가 아니라고 밝힌다. 이 글의 점수는 「빠진 항목이 줄었다」는 뜻으로만 읽는다.

Search Console이나 GA4 연동 기능은 왜 안 썼나?

OAuth 인증 정보를 로컬에 둬야 한다. 진단만 하는 데는 필요 없었고, 쓰더라도 인증 정보를 레포 밖에 두는 설정이 먼저다.

플러그인을 지우려면?

claude plugin uninstall claude-seo@agricidaniel-claude-seo --scope local로 지운다. 마켓플레이스까지 지우려면 claude plugin marketplace remove agricidaniel-claude-seo인데, 그 마켓플레이스에서 설치한 플러그인이 함께 지워진다.

참고 자료