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을 골랐다.
cd ~/workspace/blogclaude plugin marketplace add AgriciDaniel/claude-seoclaude plugin install claude-seo@agricidaniel-claude-seo --scope localclaude 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가 최신 커밋 날짜만 돌려준 것이었다. 다른 하나는 아래 주의에 적었다.
확인
세 번 진단한 점수는 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인데, 그 마켓플레이스에서 설치한 플러그인이 함께 지워진다.