안녕하세요? 정리하는 개발자 워니즈입니다.
내 블로그가 검색에서 왜 안 잡히는지 사람이 눈으로 하나씩 뜯어보는 대신 커맨드 한 줄로 감사를 받아볼 수는 없을까요? Claude Code 플러그인인 claude-seo가 정확히 그 일을 하겠다고 내걸고 있는 도구인데요, 필자가 어제 이 플러그인을 직접 설치해서 운영 중인 블로그를 그대로 감사에 올려봤습니다.
이 글은 claude-seo 사용법을 설치 순서부터 커맨드별 용도까지 정리하고 필자 블로그가 첫 감사에서 어떤 지적을 받았는지, 그리고 무엇을 확인하지 못했는지까지 그대로 적은 기록입니다.
【한 줄 요약】 claude-seo 사용법의 요지는 간단합니다. 마켓플레이스 등록과 설치 두 줄이면 준비가 끝나고 /seo audit 한 줄로 사이트 전체 감사가 돌아갑니다. 필자 블로그에서는 정적 자산 캐시 헤더 누락과 검색 스키마 누락 두 건이 잡혀서 그날 바로 고쳤는데요, 대신 감사 한 번이 세션 사용량을 크게 먹는다는 점은 미리 알고 시작하셔야 합니다.
먼저 이 글에서 확인한 것 세 가지만 추려두겠습니다.
- 설치는 마켓플레이스 등록과 플러그인 설치 두 줄이면 되고 나머지 준비는
/seo setup이 알아서 합니다 - 첫 감사에서 나온 결함 두 건은 원인이 둘 다 관리자 화면이 아니라 서버 설정 쪽에 있었습니다
- 한국어 검색 특성 지원 여부와 정식 리포트의 품질은 이번에 확인하지 못했습니다
목차
- claude-seo는 어떤 플러그인인가요?
- claude-seo 사용법의 뼈대가 되는 커맨드 6개
- 설치 순서, 마켓플레이스 등록부터 setup까지
- 직접 확인 1: 설치 전에 코드부터 열어봤습니다
- 직접 확인 2: 첫 감사에서 나온 결함 2건
- 직접 확인 3: 한국어 지원은 확인 불가
- 감사 결과를 어디까지 믿어도 될까요?
- 무료로 쓸 수 있나요, 숨은 비용은 없나요?
- 안 되는 것과 미리 알아둘 제약
- 정리, 누구에게 맞고 누구에게는 굳이인가
1. claude-seo는 어떤 플러그인인가요?
claude-seo는 Claude Code에 설치해서 /seo 커맨드로 부르는 검색 최적화 감사 플러그인입니다. 사이트 주소를 넘기면 페이지를 실제로 열어보고 구조화 데이터와 성능 지표까지 모아서 무엇이 빠졌는지 알려주는 방식인데요, 브라우저 확장이나 웹 서비스가 아니라 내 터미널 안에서 도는 도구라는 점이 다른 검색 최적화 도구와 갈리는 지점인 것 같습니다.
공개된 저장소 정보를 정리하면 이렇습니다.
| 항목 | 값 |
|---|---|
| 형태 | Claude Code 플러그인 (마켓플레이스 설치형) |
| 라이선스 | MIT |
| 별 | 15,808개 |
| 포크 | 2,320개 |
| 구성 | 서브스킬 25개와 병렬 서브에이전트 18개 |
| 동시 실행 | 최대 15개 |
| 필자 설치 버전 | 2.2.5 |
메인테이너가 한 명인 개인 프로젝트인데 별이 1만 5천 개를 넘어섰다는 점이 먼저 눈에 띄었습니다. 다루는 범위도 좁지 않아서 기술 점검과 콘텐츠 품질 평가부터 Schema.org 구조화 데이터, AI 검색 대응, 지역 검색, 이커머스, 다국어 사이트까지 서브스킬로 나뉘어 있습니다. 감사 항목을 하나의 거대한 프롬프트에 몰아넣지 않고 스킬 단위로 쪼갠 다음 서브에이전트를 여러 개 붙여 병렬로 돌리는 구조입니다.
AI 검색 대응 부분이 특히 반가웠는데요, 이 플러그인은 AI 검색 최적화를 따로 떨어진 분야처럼 다루지 않고 검색 최적화의 연장으로 정의한 다음 문단 단위 인용 가능성을 점수로 봅니다. 구글이 자주 묻는 질문 리치 결과를 걷어낸 뒤로 가치가 문단 인용 쪽으로 옮겨갔다는 판단이 도구 안에 그대로 들어가 있는 셈입니다. 필자도 구글이 검색 결과 제목을 바꿔 쓰는 이유를 정리하면서 같은 방향에 닿았던 터라 따로 만들어진 도구가 같은 결론을 가리키는 것을 보니 판단에 조금 더 힘이 실렸습니다.
2. claude-seo 사용법의 뼈대가 되는 커맨드 6개
claude-seo 사용법은 사실상 커맨드 여섯 개를 익히는 일에 가깝습니다. 필자가 문서를 읽고 정리한 용도는 이렇습니다.
| 커맨드 | 하는 일 | 쓰는 때 |
|---|---|---|
/seo audit 주소 | 사이트 전체 감사 | 처음 한 번, 10분에서 15분 소요 |
/seo page | 페이지 하나만 점검 | 글 한 편을 고쳐 올릴 때 |
/seo schema | 구조화 데이터 생성과 검증 | 스키마 누락이 의심될 때 |
/seo geo | AI 답변에 인용될 가능성 점수 | 문단 단위로 다듬을 때 |
/seo google | 서치 콘솔과 페이지스피드, GA4, CrUX 연동 | 실데이터를 붙여서 볼 때 |
/seo drift | 고친 항목이 되돌아갔는지 감시 | 조치 이후 유지 확인 |
여섯 개를 한꺼번에 익히실 필요는 없고 처음 쓰신다면 /seo audit부터 돌리시는 편이 낫습니다. 전체 그림을 한 번 받아둬야 이후에 /seo page나 /seo schema로 좁혀 들어갈 지점이 정해지기 때문입니다. /seo google은 구글 API 연동이 필요한 선택 항목이라 처음부터 붙이지 않으셔도 됩니다.
여섯 개 중에 필자가 오래 쓰게 될 것 같은 쪽은 오히려 /seo drift입니다. 감사에서 나온 항목을 고치는 일보다 고친 상태가 그대로 유지되는지 지켜보는 일이 실제로는 훨씬 어렵기 때문입니다. 설정 하나가 조용히 되돌아간 채로 몇 달을 모르고 지나가는 일이 바로 아래 5번에서 실제로 일어났습니다.
3. 설치 순서, 마켓플레이스 등록부터 setup까지
claude-seo 사용법에서 설치는 가장 짧은 단계라서 막히는 지점이 거의 없습니다. 마켓플레이스를 등록하고 플러그인을 설치한 다음 초기 설정 커맨드를 한 번 부르면 끝입니다.
claude plugin marketplace add AgriciDaniel/claude-seo
claude plugin install claude-seo두 줄이 끝나면 Claude Code 안에서 /seo setup을 한 번 실행합니다. 이 단계에서 격리된 파이썬 런타임과 Playwright용 Chromium을 내려받아 준비하는데요, 페이지를 진짜로 열어서 렌더링 결과를 보는 도구라서 브라우저 엔진이 필요한 구조입니다. 필자 환경에서는 이 준비 단계가 가장 오래 걸렸고 그 뒤로는 다시 하지 않았습니다.
설치 범위는 사용자 단위와 프로젝트 단위 중에 고를 수 있습니다. 필자는 블로그 말고 다른 곳에서도 부를 일이 있을 것 같아 사용자 단위로 넣었는데요, 특정 프로젝트에서만 쓰실 계획이라면 프로젝트 단위가 컨텍스트 부담이 훨씬 적습니다. 컨텍스트 부담이 왜 생기고 얼마나 붙는지는 아래 8번에서 따로 다루겠습니다.
4. 직접 확인 1: 설치 전에 코드부터 열어봤습니다
claude-seo 사용법을 소개하는 글이 건너뛰기 쉬운 단계가 하나 있습니다. 서드파티 플러그인을 설치한다는 것은 내 개발 환경에 실행 권한을 하나 더 여는 일입니다. 별이 많다는 사실은 인기의 근거이지 안전의 근거가 아니라서 필자는 설치 커맨드를 치기 전에 저장소를 받아서 세 가지를 먼저 봤습니다.
첫째로 플러그인이 등록하는 훅이 무엇을 하는지 봤습니다. 도구 실행이 끝난 뒤에 붙는 훅이 하나 있었는데 하는 일이 로컬 스키마 검증뿐이었고 바깥으로 나가는 네트워크 호출은 한 건도 없었습니다.
둘째로 설치 스크립트가 외부에서 무언가를 받아 실행하는지 봤습니다. 원격 스크립트를 내려받아 그 자리에서 실행하는 패턴은 공급망 사고에서 가장 자주 나오는 형태인데 저장소를 훑어봐도 그런 코드는 보이지 않았습니다.
셋째로 사용 기록을 모아서 어딘가로 보내는 코드가 있는지 찾아봤습니다. 텔레메트리로 볼 만한 코드는 나오지 않았고 문서에도 전부 로컬에서 돈다고 적혀 있었습니다.
세 가지가 모두 깨끗해서 설치를 진행했습니다. 별 개수나 포크 수는 이 판단에 넣지 않았습니다. 인기와 안전은 다른 축이라고 보기 때문입니다.
5. 직접 확인 2: 첫 감사에서 나온 결함 2건
claude-seo 사용법의 본론은 여기서부터입니다. 준비가 끝나고 블로그 주소를 그대로 넘겨서 감사를 돌렸는데 화면 앞에 앉아 십여 분을 기다리고 있기는 아까워서 헤드리스로 실행했습니다.
claude -p "/seo audit https://blog.wonizz.com"결과부터 말씀드리면 페이지 기본기는 건강했습니다. 정규 주소 태그와 robots 지시문과 오픈그래프 태그가 모두 제자리에 있었고 이미지 대체 텍스트도 거의 전부 채워져 있었습니다. 예전에 사이트맵에서 글이 통째로 빠져 있던 사고를 겪은 뒤로 이쪽은 계속 손을 봐온 영역이라 예상한 결과이기도 했습니다.
문제는 그 아래에 있었습니다.
| 발견 | 원인 | 조치 |
|---|---|---|
| 정적 자산에 캐시 헤더가 하나도 없음 | 서버 기본 설정이 디렉터리 단위 설정 파일을 읽지 않도록 잠겨 있었고 만료 헤더 모듈도 올라와 있지 않았음 | 가상 호스트 설정에 헤더 블록을 추가. CSS와 JS는 1년, 이미지와 폰트는 30일, HTML은 무캐시 유지 |
| 검색 스키마에 사이트 검색 액션이 빠짐 | 쓰고 있던 검색 최적화 플러그인의 기본 출력에 해당 항목이 없음 | 구조화 데이터 필터에 항목을 덧붙이는 작은 플러그인을 직접 만들어 해결 |
첫 번째가 특히 뼈아팠는데요, 캐시 플러그인 관리 화면에서는 브라우저 캐시 설정이 분명히 켜져 있었는데 정작 서버는 그 설정 파일을 아예 읽지 않고 있었습니다. 화면에는 켜져 있다고 표시되지만 실제 응답에는 아무 헤더도 붙지 않는 상태가 몇 달째 이어지고 있었던 셈입니다. 관리 화면의 표시와 서버의 실제 응답이 어긋나는 일은 워드프레스 캐시 때문에 새 글이 홈에만 안 보이던 때와 성격이 같았습니다.
확인은 응답 헤더를 직접 받아보는 쪽이 빠릅니다.
curl -sI https://blog.wonizz.com/wp-includes/js/jquery/jquery.min.js | grep -i cache-control이 명령이 아무것도 출력하지 않으면 헤더가 안 붙고 있다는 뜻입니다. 재방문자의 브라우저가 매번 같은 파일을 새로 받아 간다는 이야기라서 체감 속도에도 손해가 나고 서버 쪽 요청 수도 그만큼 늘어납니다.
조치 순서는 백업, 설정 추가, 문법 검사, 재시작, 라이브 헤더 재조회였습니다. 설정 파일을 건드리기 전에 백업을 먼저 뜬 다음 문법 검사를 통과시키고 나서야 재시작했는데요, 웹 서버 설정은 한 글자만 틀려도 기동이 막히기 때문에 이 순서를 건너뛰면 블로그 전체가 내려갑니다.
두 번째 결함은 성격이 조금 다른 종류였습니다. 사이트 검색 액션은 구글에 이 사이트 안에 검색 기능이 있다고 알려주는 구조화 데이터 항목입니다. 검색 결과에 사이트 내부 검색창이 함께 노출될 여지를 만드는 자리인데 쓰고 있던 검색 최적화 플러그인이 기본으로 넣어주지 않고 있었습니다. 구조화 데이터를 내보내기 직전에 끼어드는 필터가 열려 있어서 거기에 항목 하나를 덧붙이는 작은 플러그인으로 해결했고, 넣은 다음 실제 페이지에서 다시 읽어 확인까지 마쳤습니다.
6. 직접 확인 3: 한국어 지원은 확인 불가
세 번째 확인은 끝내 결론을 내지 못했는데 확인하지 못한 것은 확인하지 못했다고 그대로 적어두겠습니다.
문서에는 다국어 사이트를 다루는 서브스킬이 있다고 나와 있지만 한국어 콘텐츠나 국내 검색 결과의 특성을 어디까지 반영하는지는 문서만으로 판단할 수 없었습니다. 네이버 검색처럼 구글과 로직이 다른 곳까지 봐주는지도 마찬가지입니다. 감사에서 나온 지적이 전부 구글 기준의 일반 항목이라 한국어 특성이 걸린 사례 자체를 만나지 못했습니다.
감사가 마지막에 내놓는 정식 리포트의 품질도 이번에는 끝까지 보지 못했습니다. 데이터 수집 단계까지는 정상으로 끝났는데요, 페이지 캡처와 구조화 데이터 수집, 스크린샷 촬영, 성능 측정 스크립트 실행까지 마친 다음 종합 리포트를 쓰기 직전에 세션 사용량 한도에 걸려서 멈췄습니다. 그래서 위 5번의 결함 2건은 완성된 리포트가 아니라 필자가 원데이터를 직접 읽어서 정리한 것입니다.
다른 검색 최적화 도구와 나란히 놓고 비교하는 일도 이번 범위 밖이었습니다. 같은 사이트를 다른 감사 도구에 올려서 지적 항목이 겹치는지 갈리는지를 봐야 비교가 성립하는데 이번에는 claude-seo 한 쪽만 돌렸습니다. 한 도구가 잡은 항목을 다른 도구도 잡는지 확인하지 않은 상태라서 어느 쪽이 더 촘촘한지는 말씀드릴 수 없습니다.
이 세 가지는 다음 감사 때 다시 보고 따로 적을 생각입니다.
7. 감사 결과를 어디까지 믿어도 될까요?
도구가 내놓은 항목은 그대로 받아 적지 마시고 한 번 더 재현해보시는 편이 안전합니다. 자동 감사는 응답을 기계적으로 읽기 때문에 조회 방식이 조금만 달라도 반대 결론이 나올 수 있습니다. claude-seo 사용법에서 빠뜨리면 안 되는 습관이 이 재현 단계라고 보는데요, 필자도 이번에 오판 직전까지 갔습니다.
필자가 하마터면 틀린 결론을 그대로 적을 뻔한 자리가 압축 설정이었습니다. 헤더만 받아보는 요청으로 확인했더니 압축 관련 항목이 안 보여서 압축이 안 걸려 있다고 판정할 뻔했는데요, 본문까지 받아보는 요청으로 다시 확인하니 103KB짜리 문서가 19KB로 줄어서 내려오고 있었습니다. 헤더만 받는 요청에는 압축 표시가 붙지 않았을 뿐이고 실제로는 정상이었습니다. 압축 여부는 헤더 조회만으로 판정하지 않는다는 것을 이번에 배웠습니다.
감사가 내놓은 백링크 항목도 그대로 읽으면 안 되고 해석이 한 번 필요했습니다. 공개 크롤 데이터셋에서 이 도메인을 찾지 못했다는 결과가 나왔는데요, 링크가 하나도 없다는 뜻이라기보다 그 데이터셋에 담기기에는 아직 규모가 작다는 쪽에 가깝습니다. 도구의 결함이 아니라 재료가 없는 상태라서 이 항목은 판정 보류로 남겨뒀습니다. 없는 데이터를 근거 삼아 대책을 세우면 엉뚱한 곳에 시간을 쓰게 됩니다.
8. 무료로 쓸 수 있나요, 숨은 비용은 없나요?
플러그인 자체는 MIT 라이선스로 공개되어 있어서 돈을 낼 일이 없습니다. 계정 등록도 없고 결과를 외부로 보내지도 않으며 구글 API 연동은 원하는 사람만 붙이는 선택 항목입니다.
다만 돈으로 계산되지 않는 비용이 하나 붙는데요, claude-seo 사용법을 익힌 다음 바로 마주치는 문제가 이것입니다. 플러그인을 켜두기만 해도 세션을 열 때마다 5천 토큰 가까운 설명문이 먼저 올라갑니다. 감사를 안 하는 날에도 매번 그만큼을 먼저 깔고 시작하는 셈이라 필자는 감사가 끝난 뒤에 비활성화해두고 다음 감사 직전에 다시 켜는 쪽으로 정리했습니다.
claude plugin disable claude-seo
claude plugin enable claude-seo감사 자체의 소모도 가볍지 않습니다. 서브에이전트가 최대 15개까지 동시에 붙어서 페이지를 열고 측정하기 때문에 한 번 돌리면 사용량이 눈에 띄게 줄어듭니다. 필자가 종합 단계 직전에 한도에 걸린 것도 결국 이 구조 탓이었습니다. 사용량이 넉넉한 시간대를 골라서 돌리시는 편이 마음이 편할 것 같습니다.
9. 안 되는 것과 미리 알아둘 제약
claude-seo 사용법과 별개로 미리 알고 계셔야 할 제약도 있어서 써보면서 확인한 것을 그대로 적어둡니다.
| 제약 | 내용 |
|---|---|
| 한 번에 안 끝날 수 있음 | 병렬 감사가 사용량을 크게 먹어서 종합 직전에 멈출 수 있습니다 |
| 상시 컨텍스트 부담 | 켜두기만 해도 세션마다 5천 토큰 가까이 깔립니다 |
| 원데이터 휘발 | 수집 결과가 임시 폴더에 쌓여서 세션이 끝나면 사라집니다 |
| 유지보수 위험 | 메인테이너 한 명이 끌고 가는 프로젝트입니다 |
| 한국어 검증 미확인 | 국내 검색 특성 반영 여부를 이번에 확인하지 못했습니다 |
표에서 세 번째로 적어둔 원데이터 휘발이 은근히 걸리는 항목입니다. 감사에서 나온 스크린샷과 측정값이 임시 폴더에만 쌓이기 때문에 나중에 다시 볼 자료가 있다면 세션이 살아 있을 때 옮겨두셔야 합니다. 필자는 이번에 결함 2건의 근거만 옮겨두고 나머지는 날렸는데요, 다음번에는 수집이 끝난 직후에 통째로 복사해둘 생각입니다.
네 번째로 적은 유지보수 위험은 도구를 고르는 기준의 문제이기도 합니다. 개인 프로젝트라 하루아침에 갱신이 멈출 수 있으니 이 도구의 판정을 유일한 기준으로 삼지 마시고, 나온 항목을 내가 재현할 수 있는 형태로 남겨두시는 편이 낫습니다. 감사 자동화의 값어치는 판정을 대신해주는 데 있는 것이 아니라 사람이 놓치던 자리를 목록으로 만들어주는 데 있는 것 같습니다.
10. 정리, 누구에게 맞고 누구에게는 굳이인가
claude-seo 사용법을 한 문장으로 줄이면 설치 두 줄에 감사 한 줄이고 그다음부터가 사람의 몫입니다.
맞는 분은 이런 경우입니다. 워드프레스나 정적 사이트를 직접 운영하면서 서버 설정까지 손댈 수 있는 분이라면 잡아준 항목을 바로 고칠 수 있어서 얻는 것이 많습니다. 이미 Claude Code를 쓰고 계신다면 설치 비용도 사실상 두 줄이라 부담이 적습니다.
굳이인 분도 있습니다. 서버 설정에 접근할 수 없는 임대형 블로그를 쓰신다면 나온 지적의 상당수를 조치할 방법이 없어서 목록만 늘어납니다. 국내 검색 유입이 대부분인 사이트라면 이 도구의 판정이 얼마나 맞는지부터 따로 확인해보셔야 합니다.
필자의 한 줄 후기는 이렇습니다. 몇 달 동안 관리 화면만 보면서 정상이라고 믿고 있던 설정 두 개가 사실은 서버에서 통째로 무시되고 있었다는 사실을 하루 만에 찾아냈다는 점에서 값어치를 했습니다. 다만 종합 리포트를 못 본 채로 원데이터를 직접 읽어야 했다는 점, 그리고 상시 컨텍스트 부담을 감수해야 한다는 점은 감안하고 시작하시는 것이 좋겠습니다. 도구가 내놓은 결과를 사람이 다시 확인해야 하는 이유는 humanizer로 AI 문체를 걸러낸 기록에도 비슷한 결로 적어뒀습니다.
플러그인의 전체 서브스킬 목록과 설치 안내 원문은 claude-seo 깃허브 저장소에서 확인하실 수 있습니다.