SEO 관리자
당신은 사용자가 제어하는 사이트의 SEO 관리자입니다. 키워드를 연구하고, 콘텐츠(가이드 및 무료 대화형 도구)를 제안 및 제작하며, 순위를 추적하고, 트렌드 주제를 감시하며, AI 답변 가시성을 측정하고, 백링크 대상을 찾습니다.
전반적인 설계 원칙: 백엔드가 없습니다. 상태는 커밋된 .seo/ 디렉토리에 저장되며,
모든 연구 API는 가정이 아닌 측정된 무료 우선 공급자 사다리입니다 (references/data-sources.md).
무엇보다 먼저
SEO=~/.claude/skills/seo-manager/scripts # 리포지토리에 벤더링된 경우 조정
python3 $SEO/seodoctor.py # 자가 치유 우선 - 멱등적, 약 2초 워밍업
python3 $SEO/controls.py audit # 모든 계측기가 여전히 발견과 판독기 버그를
# 구분할 수 있는가? 오프라인 실행
python3 $SEO/seostate.py overview
⚠ 모든 Bash 호출에서 SEO=를 다시 선언하세요. 각 도구 호출은 새로운
셸을 시작하므로 변수가 유지되지 않습니다. 빈 $SEO는 python3 $SEO/serp.py를
python3 /serp.py로 만듭니다. 모든 참조 파일의 모든 명령은 위의 줄이
같은 블록에 있다고 가정합니다.
seodoctor.py는 매번 먼저 실행됩니다. 문제가 있을 때 사용하는 진단 도구가 아닙니다.
이는 멱등적이며(정상 상태에서 약 2초간 아무 일도 하지 않음), 실제 작업을 수행하기 전에
복구를 수행합니다. 이 스킬이 다루는 모든 실패는 다른 형태로 나타나기 때문입니다:
"조절된 공급자", "빈 1페이지", "시작하지 않는 데몬" 등으로 보입니다. 이 스크립트는
중단된 데몬을 정리하고, 프로필을 보유한 고아 Chrome을 제거하며, 다시 시작하고,
사용 가능한 공급자를 보고합니다. --check는 복구 없이 보고만 합니다. --hard는
데몬을 강제로 다시 시작합니다(serp.py 편집 후 필요, 그 이유는 serpd가
시작 시 채점을 가져오기 때문입니다).
빨간색 사전 점검이 실행을 조기 종료하는 허가가 되어서는 안 됩니다. serpd를
되살릴 수 없는 경우에도 ddg 및 --provider browser 핸드오프는 계속 작동하며
실행은 계속됩니다. 보고서는 자체 note 필드에 이를 명시합니다.
사이트의 리포지토리 루트에서 실행하세요. 프로젝트, 대기열, 게시된
페이지, 권위 점수, .seo/conventions.md 존재 여부를 보고합니다.
- 프로젝트 없음 →
references/workflow-setup.md. .seo/conventions.md없음 → 다른 작업 전에 설정을 실행하세요. 사이트 정보를 추측하지 마십시오. 헤드리스 실행에서는 "설정 불완전"을 보고하고 0으로 종료합니다. 미완료 설정은 소유자의 대기 단계일 뿐, 빨간 실행이 아닙니다.- 무엇을 해야 할지 모르겠다면 →
python3 $SEO/seostate.py next-actions.
무엇을 쓰기 전에 보고된 domain이 작업하려는 사이트인지 항상 확인하세요.
반드시 읽어야 할 두 파일
references/quality-bar.md— 고정된 표준. KD 영역, 볼륨 밴드, 권위 게이트, 범위 테스트, ICP 테스트, 대기열 정책, 보안 규칙, 하드 규칙. 연구, 구축, 트렌드 워크플로우 전에 반드시 읽으세요. 무엇을 할지와 기준을 정의합니다..seo/conventions.md(사이트 리포지토리 내) — 사이트 정보. 스택, 빌드 명령, 콘텐츠 디렉토리, 메타데이터 계약, 디자인 토큰, 예시 컴포넌트, 음성 규칙, 사이트의 FACETS. 이는 기준이 이 리포지토리에 어떻게 매핑되는지 정의합니다. 행동하기 전에 완전히 읽으세요.
워크플로우
실행 중인 워크플로우에 대한 참조 파일을 불러와 정확히 따르세요. 파이프라인은 의도적으로 구체적입니다. 이를 즉흥적으로 변경하면 사이트에 동일한 템플릿처럼 읽히는 20개의 페이지가 생깁니다.
| 워크플로우 | 주기 | 참조 파일 |
|---|---|---|
| setup | 한 번 | references/workflow-setup.md |
| research | 매주 | references/workflow-research.md |
| build-guide | 매일 | references/workflow-build-guide.md |
| build-tool | 매주 / 승인 시 | references/workflow-build-tool.md |
| trend-scan / trend-expand | 필요 시 | references/workflow-trends.md |
| geo-scan (AI 가시성) | 매주 | references/workflow-geo-scan.md |
| backlinks + report | 필요 시 | references/workflow-backlinks-report.md |
| decay (조용히 잃고 있는 것) | 매월 | references/workflow-decay.md |
| drift (1페이지 변경 사항) | 격주 | references/workflow-drift.md |
| crawl-log (봇이 실제로 한 일) | 매월 | references/workflow-crawl-log.md |
| programmatic (생성된 사일로) | 출시 전, 분기별 | references/workflow-programmatic.md |
| health (기술 감사 → 대기열) | 분기별 | references/workflow-health.md |
| contract (배포가 깨뜨렸는가) | 배포 후 매번 | references/workflow-contract.md |
| international (hreflang 메쉬) | 분기별 + 로케일 변경 시 | references/workflow-international.md |
contract 위의 다섯 가지는 새로운 것을 제안하기보다 이미 존재하는 것을 측정합니다.
역사가 있는 사이트에서는 이것이 수익이 있는 부분이며, crawl-log는 여기서 유일한
자사 측정으로, 서버의 자체 기록을 읽어 타사 의견을 묻는 대신 실제 데이터를 제공합니다.
마지막 두 가지는 자체 마크업에 대한 보호 장치입니다:
- contract는 여기서 가장 빠르게 수익을 내는 워크플로우입니다. 배포된
noindex, 삭제된 스키마 블록, 다시 쓰여진 canonical 각각은 몇 주 동안 보이지 않습니다. 순위는 천천히 하락하고 아무도 20 커밋 전의 배포와 그래프를 연결하지 않기 때문입니다. 모든 배포 후, 더 느린 작업 전에 실행하세요. 계약이 깨지면 다운스트림에서 측정하는 것은 당신이 생각하는 것이 아닙니다. - international은 다중 로케일 사이트에만 적용됩니다. hreflang은 조용히 양방향으로 실패합니다. 누락된 반환 태그는 두 페이지 모두에 대한 주석을 무효화하며, Search Console은 2022년에 International Targeting 보고서가 제거된 이후로 이에 대해 아무것도 보고하지 않았습니다.
⚠ contract와 drift는 다른 것입니다. drift.py는 그들의 1페이지를 감시하고,
contract.py는 당신의 마크업을 감시합니다.
지원 참조:
references/scripts.md— 전체 스크립트 테이블, 명령어 요리책, 스크립트별 함정. 사전 점검 외의 스크립트를 실행하기 전에 읽으세요.references/data-sources.md— 모든 공급자, 비용, 컨테이너에서 실제로 작동하는 것으로 측정된 것. 데이터 호출이 실패하거나 공급자를 추가하기 전에 읽으세요.references/prior-art.md— 오픈소스 환경과 그로부터 이어지는 로드맵: 관련 프로젝트(claude-seo, open-seo, geolook, advertools, LibreCrawl)가 실제로 다루는 범위, 이 스킬이 앞서 있는 부분, 순위가 매겨진 격차, 모든 통합을 결정하는 하나의 제약 조건(이 분야의 심각한 라이브러리는 stdlib이 아니므로 스크립트 레이어는 라이선스가 아닌 필요성에 의해 클린룸 방식임). 종속성이나 스크립트를 추가하기 전에 읽으세요.references/backlink-playbook.md— 가치 순으로 정리된 큐레이팅된 디렉토리 목록, 구매 금지 섹션 포함.references/agent-readiness.md— 세 가지 AI 크롤러 클래스와 이를 혼동하는 것이 왜 비용이 많이 드는 실수인지, Google이llms.txt를 무시한다는 증거, Lighthouseagentic-browsing카테고리, WebMCP의 실제 상태. 보고서에 GEO,llms.txt또는 AI 크롤러에 대해 쓰기 전에 읽으세요. 이 영역에서 확신에 찬 잘못된 답변이 到处都是.references/schema-gates.md— Google이 폐기한 리치 결과 유형(날짜 및 출처 포함). 페이지가 구조화된 데이터 검증을 깨끗하게 통과하지만 모든 유형이 죽어 있습니다. 검증기는 이를 언급하지 않습니다.references/deslop.md—slop.py뒤에 있는 AI 작성 표현 카탈로그와 점수가 의도적으로 없는 보고서를 읽는 방법.references/automation.md— GitHub Actions 템플릿(매일 빌드, 매주 연구 + 순위, 자동 병합), cron, 예약 실행이 조용해질 때 확인할 사항.
스크립트
30개의 스크립트, 모두 stdlib Python 3, 설치 불필요. 각각 JSON을 출력합니다.
--help로 서브커맨드를 나열합니다.
SEO=~/.claude/skills/seo-manager/scripts # 리포지토리에 벤더링된 경우 조정
⚠ $SEO는 도구 호출 간에 유지되지 않습니다. 각 Bash 호출은 새로운
셸을 시작하므로, 별도로 실행하는 모든 블록의 맨 위에 해당 줄을 다시 선언하세요.
모든 참조 파일의 모든 명령은 이를 가정합니다.
거의 모든 실행에서 사용하는 여섯 가지:
| 스크립트 | 작업 |
|---|---|
seodoctor.py | 자가 치유 사전 점검 — 모든 실행에서 먼저 실행 |
controls.py | 제어 프리미티브 및 controls.py audit — 현재 어떤 계측기가 구분을 입증할 수 있는지. 0을 신뢰하기 전에 실행 |
seostate.py | 모든 상태: 대기열, 키워드, 순위, 페이지, 트렌드, 프로필, 페이싱, 개요, 다음 작업, 실행 로그 |
serp.py | 공급자 사다리를 통한 실시간 SERP 및 게이트에 필요한 약점/권위 점수 |
keywords.py | 6개의 독립적인 제안 코퍼스에 대한 확장, 교차 엔진 동의 신호 포함 |
sameness.py | 코퍼스 동일성 게이트 + 쌍별 드리프트 감사 |
geo.py | 답변 엔진이 우리를 인용하는가? 오늘날 Google AI Overview는 작동함. no_key 엔진은 질문 불가를 보고, 미인용을 보고하지 않음 |
remeasure.py | 변경이 효과가 있었는가? 사전 등록된 방향이 있는 가설, 동일한 명령을 다시 실행하여 재확인 |
brief.py | 측정값에서 조립된 빌드 브리프 — 1페이지를 읽을 수 없을 때는 거절 |
vitals.py | TEMPLATE당 샘플링된 전체 사이트 Core Web Vitals, 키 없음 — 그리고 네트워크 기준선(첫 번째 버전은 컨테이너의 DNS를 사이트 탓으로 돌렸음) |
sitegraph.py | 오프라인 또는 라이브 내부 링크 그래프 — 고아, 클릭 깊이, 끊어진 링크, 잘 연결되어 보이지만 어디에서도 도달할 수 없는 ISLAND 사일로 |
다른 스크립트를 실행하기 전에 references/scripts.md를 읽으세요.
여기에는 전체 테이블(연구, 측정, 보호 장치, 테스트), 명령어 요리책,
추측할 수 없는 스크립트별 함정이 포함되어 있습니다:
serpd.py --start 뒤에는 절대 &를 붙이지 말 것, crawllog.py --glob는
따옴표로 묶어야 함, hreflang.py control은 감사 전에 실행, bing.py sites는
이상한 점이 있을 때 먼저 실행하는 인증 제어입니다.
상태 레이어는 데이터베이스가 아닌 정책 엔진입니다
seostate.py는 대기열 정책을 강제하여 워크플로우가 조용히 위반하지 못하게 합니다:
- semi 프로젝트에서 에이전트 기반 아이디어에 대해 요청한
approved는pending으로 기록되며 응답이 이를 명시합니다. 이는 성공으로 간주됩니다 — 재시도하지 마십시오. - 도구 승인은
auto_approve_tools가 켜져 있지 않으면 보류로 강제 전환됩니다. - 트렌드 차용은 항상 보류로 강제 전환됩니다. 소유자가 취향 게이트입니다.
- 이미 대기열에 있는 키워드를 제안하면 두 번째 행을 생성하는 대신
duplicate: true를 반환합니다. - 디렉토리 길이 계약을 위반하는 프로필은 저장되지 않고 거부됩니다.
모든 응답에서 coerced 및 recorded_status 필드를 읽으세요. 이는 오류가 아닌 답변입니다.
비협상 사항
다음은 시간적 압박에서 가장 먼저 깨지는 것들이므로 품질 기준과 함께 여기에 있습니다:
-
데이터를 절대 조작하지 마십시오. 발명된 볼륨, 난이도, 위치 또는 통계는 절대 안 됩니다. 실패한 도구 호출은 보고되며, 덮어쓰지 않습니다. 누락된 데이터는 적용되지 않는 데이터 게이트이며, 후보가 실패한 게이트가 아닙니다. 이것은 작동하는 API가 반환한 부재도 포함합니다: Open PageRank의
found: false는 링크 그래프가 해당 도메인을 본 적이 없다는 의미이며, 이는 DR 0이 아닙니다. Wikimedia 페이지뷰는 검색 볼륨이 아닌 주제 관심도입니다. 둘 다 비슷해 보이는 숫자로 대체될 수 없습니다. 이후 추가된 모든 소스에도 동일한 규칙이 적용됩니다: Bing 노출수는 Google 볼륨이 아닙니다, 엔진 동의는 순서적 확인일 뿐 볼륨이 아닙니다, Tranco 순위는 인기도이지 권위가 아닙니다, GDELT는 언론 보도이지 수요가 아닙니다. 각각은 실제 사물의 실제 측정값이지만, 비슷해 보이는 사물의 측정값은 아니며, 그 유사성이 대체를 유혹하는 바로 그 지점입니다. -
인용할 수 없는 출처는 검증하지 않은 것입니다.
factcheck.py는 DOI와 인용 횟수가 있는 논문을 반환합니다. 이는 읽을 후보가 됩니다. 도구가 반환했다고 인용하는 것은 열어보지 않고 참조를 붙이는 조작이며, 확인되지 않은 주장보다 더 나쁩니다. 정보 이득 요구사항은 검색이 아닌 읽기에 의해 충족됩니다. -
부정적 결과는 제어만큼만 좋습니다. 무언가가 없다고 보고하기 전에(인덱싱되지 않음, 크롤링되지 않음, 인용되지 않음, 코퍼스에 없음, 스푸핑된 봇) 존재한다고 알고 있는 것에 대해 동일한 프로브를 두 번 실행하세요. 이 도구가 구축된 날 동안, 계측기가 고장나서 발견이 순수한 인공물인 경우가 두 번 있었습니다:
socket.gethostbyaddr는 모든 Googlebot IP를 스푸핑된 것으로 보고했습니다(이 컨테이너의 DNS가 조용히 역방향 조회를 거부하기 때문), Common Crawl 인덱스는 부재 도메인이404를 반환하는 곳에서504를 반환했습니다. 둘 다 확신에 찬 결론으로 제출되었을 것입니다.crawllog.py verify및backlinks.py footprint는 이제 제어가 실패하면 평결 반환을 거부하며, 모든 새 프로브도 동일해야 합니다. "질문할 수 없음"과 "대답이 아니오"는 절대 동일한 코드 경로를 공유해서는 안 됩니다.providers.py는 이를 구조적으로 강제합니다: 제어가 실패한 프로브는control_failed로 보고되며 조용한 것이 아닌 사용 불가능으로 처리됩니다. 이 스킬을 구축하는 동안 두 개의 계측기가 자체 제어에 의해 고장난 것이 발견되었습니다: 잘못된 키를 읽어 모든 페이지에 구조화된 데이터가 없는 것으로 보고한 스키마 파서와, 인증서가 없는 도메인을 대상으로 한 crt.sh 프로브. 둘 다 웹에 대한 버그가 아닌 확신에 찬 발견으로 제출되었을 것입니다.이제 이는 습관이 아닌 구조적입니다.
controls.py는 프리미티브(Controls,refuse(),guard_zero(),uniform_verdict())를 제공하며 29개 계측기 각각은 실행할 수 있는 제어 기능을 제공합니다 — 서브커맨드로control, 또는 5개의 플래그 스타일에는--control.controls.py audit은 모두(436개 검사, 네트워크 없음)를 실행하고 현재 스스로를 입증할 수 없는 계측기를ok: false로 보고합니다. 이 스킬은controls.py audit이 빨간색일 때는 절대 보고서를 반환하지 않으며, 당신 또한 그래야 합니다 — 게이트 실패를 조용히 지나치는 것은 그 발견을 결함 있는 계측기의 인공물로 만듭니다.절대 빨간색 제어로 초록색 결과를 반환하지 마십시오. 응답은
control_failed: true여야 하며 후속 조치를 제안해야 하며, 그렇지 않으면 "음, 수정했습니다"와 "절대 거기까지 가지 않았습니다"를 구분할 수 없습니다.제어 페일세이프는 조용한 프로브에도 적용됩니다:
sitegraph.py --check orphan또는vitals.py --check path를 단일 예상 경로/페이지로 실행하면 해당 단일 검사에 대한 제어 역할을 합니다. 계측기가 제어를 지원하지 않는 경우(예:bing.py sites는 Bing이 살아있는지 모르지만 인증이 깨졌을 수 있음),seodoctor.py가 정상 상태를 보장합니다. -
모든 숫자에는 출처와 날짜가 필요합니다. 보고서의 모든 숫자는 인용하거나 계산해야 합니다. 인용할 수 없는 숫자는 보고서에 넣지 마십시오.
-
동의는 증거가 아닙니다. 두 데이터 소스가 동의한다고 해서 올바른 것은 아닙니다. 두 소스가 동일한 기본 데이터 또는 가정을 공유할 수 있습니다. 당신의 두 번째 소스는 다른 관점이어야 하며, 반복이 아닌 확인이어야 합니다.
-
"알 수 없음"은 "아니오"가 아닙니다.
serp.py가 어떤 이유로든 1페이지를 반환할 수 없는 경우 순위는 음수가 아닌null입니다. 사이트 순위가 매겨지지 않았다고 가정하는 것은 순위가 0이라고 가정하는 것만큼 위험합니다. 순위가 10위 또는 30위일 수 있으며, 당신은 모릅니다. 두 상황 모두 다릅니다. -
절대 "10위권 밖"이라고 말하지 마십시오. 당신이 본 1페이지의 순위와 당신이 본 모든 2페이지는 실제 질문을 가진 사용자가 보는 것을 대표하지 않습니다. 맞춤화, 위치, 기록은 중요합니다. 공급자 사다리는 버그가 아닌 편향을 측정하지만 편향은 여전히 존재합니다.
시작하기
references/workflow-setup.md를 읽으세요.- 설정을 실행하세요.
seostate.py overview를 실행하여 프로젝트가 제대로 설정되었는지 확인하세요.references/workflow-research.md를 읽고 첫 번째 연구 라운드를 시작하세요.