SoDam SeoMedic

SeoMedic

어느 프로젝트에서나 설치해 쓰는 Claude Code 플러그인. 웹사이트 URL 하나만 있으면 검색엔진(SEO)·AI 검색(GEO) 노출 상태를 진단해줍니다.

**지금 버전이 할 수 있는 것: 진단 + 회귀(원복) 감지 + 로컬 Next.js 프로젝트 승인 기반 자동 수정 + GitHub 저장소 대상 자동 수정 제안(Pull Request, 실험적).** 이 문서는 "지금 실제로 되는 것"만 정직하게 설명하며, 아직 검증이 끝나지 않은 부분은 숨기지 않고 그대로 표시합니다.

이 문서가 처음이신 분: **컴퓨터·터미널·AI 도구가 처음이어도** 아래 순서대로만 따라 하면 됩니다. 낯선 단어는 "쉬운말(원문)" 형태로 풀어 씁니다. 이 문서와 영문판(**[README.en.md](./README.en.md)**)의 내용은 완전히 동일합니다 — 필요한 언어로 읽으시면 됩니다.

---

목차

1. 한눈 소개
2. 사전 준비물·필요 프로그램
3. 다운로드·설치
4. 빠른 시작(5분)
5. 실행·사용·작동 방법
6. 명령어 레퍼런스
7. 워크플로우
8. 업데이트 내용 요약
9. 보안·데이터 흐름
10. 아키텍처(쉽게)
11. 파일·문서 위치
12. 문제/오류 대처
13. FAQ
14. 법률·저작권·라이선스·상업적 용도
15. 개발자·기여자 가이드

---

1. 한눈 소개

SeoMedic은 "내 사이트(또는 권한이 있는 사이트)가 구글 검색과 AI 검색(ChatGPT/Perplexity 같은 답변형 검색)에 잘 노출될 수 있는 상태인지"를 자동으로 점검해주는 도구입니다.

비유하자면: **건강검진 같은 도구**입니다. 사람 몸을 검사해 "여기가 안 좋으니 이렇게 고치세요"라고 알려주듯이, 웹페이지를 검사해 "이 부분이 검색엔진에 잘 안 보이니 이렇게 고치세요"라고 리포트를 만들어줍니다. 그리고 **Next.js로 만든 사이트**라면, 사용자 승인을 거쳐 실제로 코드까지 고쳐줄 수 있습니다(로컬 폴더 또는 GitHub 저장소 대상).

• 이미 만들어진 아무 웹사이트(https://...)에 대해 진단만 실행할 수 있습니다(내 것이든 남의 것이든, 권한이 있는 경우만).
• 실제로 브라우저를 띄워서(Playwright) 페이지를 열어보고, 검색엔진이 보는 원본 HTML과 실제로 화면에 그려지는 결과를 비교합니다.
• 두 번째 진단부터는 "예전보다 나빠진 게 있는지"(회귀)도 잡아줍니다.
• Next.js 프로젝트라면 "없는 것만 추가"하는 안전한 수정은 자동으로, 검색 결과 표시에 영향을 주는 수정은 사용자 승인을 받은 뒤에만 실제 파일에 반영합니다.
• 로컬 폴더뿐 아니라 GitHub 저장소 주소를 대상으로도 같은 수정을 시도해, 결과를 Pull Request(변경 제안)로 제출할 수 있습니다(실험적 기능 — 아래 8번 "업데이트 내용 요약"과 14번 참고).

2. 사전 준비물·필요 프로그램

준비물	왜 필요한가	확인 명령(복붙)	없으면 설치
Node.js 22 이상	SeoMedic의 진단 엔진이 Node.js로 만들어져 있습니다	node -v	https://nodejs.org (LTS 버전 다운로드)
Claude Code	이 플러그인이 설치되는 프로그램 자체입니다	claude --version	https://claude.com/claude-code
git	마켓플레이스 등록·업데이트, 로컬 수정 기능(`/seo-fi