Content
# SeoMedic
> 어느 프로젝트에서나 설치해 쓰는 Claude Code 플러그인. 웹사이트 URL 하나만 있으면 검색엔진(SEO)·AI 검색(GEO) 노출 상태를 진단해줍니다.
>
> **지금 버전이 할 수 있는 것: 진단 + 회귀(원복) 감지 + 로컬 Next.js 프로젝트 승인 기반 자동 수정 + GitHub 저장소 대상 자동 수정 제안(Pull Request, 실험적).** 이 문서는 "지금 실제로 되는 것"만 정직하게 설명하며, 아직 검증이 끝나지 않은 부분은 숨기지 않고 그대로 표시합니다.
이 문서가 처음이신 분: **컴퓨터·터미널·AI 도구가 처음이어도** 아래 순서대로만 따라 하면 됩니다. 낯선 단어는 "쉬운말(원문)" 형태로 풀어 씁니다. 이 문서와 영문판(**[README.en.md](./README.en.md)**)의 내용은 완전히 동일합니다 — 필요한 언어로 읽으시면 됩니다.
---
## 목차
1. [한눈 소개](#1-한눈-소개)
2. [사전 준비물·필요 프로그램](#2-사전-준비물필요-프로그램)
3. [다운로드·설치](#3-다운로드설치)
4. [빠른 시작(5분)](#4-빠른-시작5분)
5. [실행·사용·작동 방법](#5-실행사용작동-방법)
6. [명령어 레퍼런스](#6-명령어-레퍼런스)
7. [워크플로우](#7-워크플로우)
8. [업데이트 내용 요약](#8-업데이트-내용-요약)
9. [보안·데이터 흐름](#9-보안데이터-흐름)
10. [아키텍처(쉽게)](#10-아키텍처쉽게)
11. [파일·문서 위치](#11-파일문서-위치)
12. [문제/오류 대처](#12-문제오류-대처)
13. [FAQ](#13-faq)
14. [법률·저작권·라이선스·상업적 용도](#14-법률저작권라이선스상업적-용도)
---
## 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-fix`)에 사용 | `git --version` | https://git-scm.com |
| **인터넷 연결** | 페이지 진단(크롤)과 최초 설치에 필요 | - | - |
| **디스크 여유 공간 500MB 이상** | 브라우저 엔진(Chromium) 자동 설치 때문 | - | - |
| (선택) **GitHub 계정 + Personal Access Token** | GitHub 저장소 대상 자동 수정 제안 기능을 쓸 때만 필요 | - | 아래 5번 "GitHub 저장소 절차" 참고 |
> "명령 실행"이 처음이신 분: Windows는 `PowerShell`(시작 메뉴에서 검색), Mac/Linux는 `터미널(Terminal)`을 여신 뒤 위 명령을 그대로 입력하고 Enter를 누르시면 됩니다.
> **확인 명령을 실행하면 무엇이 보여야 하나요?** `node -v`는 `v22.4.0`, `git --version`은 `git version 2.43.0`, `claude --version`도 이와 비슷하게 **버전 번호**가 나오면 전부 정상입니다(정확한 숫자는 달라도 됩니다). 반대로 `'node'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다` 같은 **오류 문구**가 나오면, 그 프로그램이 아직 설치되지 않은 것입니다 — 위 표의 "없으면 설치" 링크에서 설치한 뒤, **터미널 창을 새로 연 상태에서** 다시 시도하세요(이미 열려있던 창은 방금 설치한 프로그램을 인식하지 못합니다).
>
> **Node.js가 정확히 뭔가요?** 자바스크립트라는 프로그래밍 언어로 만들어진 프로그램을 컴퓨터에서 실행할 수 있게 해주는 도구입니다. SeoMedic의 내부 진단 엔진이 이 언어로 만들어져 있어서 필요하며, 설치만 하면 되고 사용자가 직접 코드를 작성할 일은 없습니다.
## 3. 다운로드·설치
SeoMedic은 별도 설치 파일을 "다운로드"하는 방식이 아니라, **Claude Code 안에서 마켓플레이스 명령으로 설치**합니다(따로 실행 파일을 내려받아 실행하지 않습니다 — Claude Code가 알아서 필요한 파일을 받아옵니다).
```
/plugin marketplace add sodam-ai/SoDam-SeoMedic
/plugin install seomedic@sodam-seomedic-marketplace
```
(위 두 값은 이 프로젝트의 실제 GitHub 저장소 주소와 마켓플레이스 이름입니다. 그대로 복사해서 사용하시면 됩니다.)
**⚠️ 이 저장소는 현재 GitHub에서 비공개(Private) 상태입니다.** 저장소 소유자 본인 계정이거나, 저장소에 접근 권한을 부여받은 계정으로 로그인한 상태에서만 위 설치 명령이 성공합니다(권한이 없으면 "저장소를 찾을 수 없다"는 오류가 납니다). 나중에 공개(Public)로 전환되면 이 제한은 사라집니다.
**⚠️ 설치 후 반드시 Claude Code를 완전히 종료했다가 다시 켜주세요.** (실측 확인된 사실: 새로 설치한 플러그인은 다시 시작해야 인식됩니다. 그냥 새 대화창만 여는 것으로는 부족합니다 — 프로그램 자체를 껐다 켜야 합니다.)
설치가 잘 됐는지 확인:
```
/plugin list
```
목록에 `seomedic`이 "enabled" 상태로 보이면 성공입니다.
## 4. 빠른 시작(5분)
Claude Code 대화창에 아래처럼 입력하세요(원하는 사이트 주소로 바꾸세요):
```
/seo-audit https://example.com
```
- 처음 실행 시 브라우저 엔진(Chromium) 자동 설치로 1~2분 정도 더 걸릴 수 있습니다.
- **성공하면 이렇게 보여요**: `## SEO 진단 리포트 — https://example.com` 로 시작하는 Markdown 표가 나오고, 발견된 문제가 심각도(🔴🟠🟡)와 함께 나열됩니다.
- 문제가 하나도 없으면 "위반 사항 없음"이라고 나옵니다.
## 5. 실행·사용·작동 방법
### `/seo-audit` — 진단하기
```
/seo-audit https://내사이트.com
```
페이지를 실제로 열어보고(크롤+렌더링) 검색엔진 관점에서 문제가 있는지 확인합니다. **어떤 파일도 수정하지 않습니다.** 진단하려는 사이트가 본인 소유이거나 진단 권한이 있는지 먼저 확인해달라고 물어봅니다.
### 베이스라인 저장하기 (회귀 비교의 기준점)
audit을 실행해 결과를 확인한 뒤, "이 상태를 기준으로 저장해줘"라고 요청하면 `seomedic_save_baseline`이 호출됩니다. **자동으로 저장되지 않습니다** — 실수로 잘못된 상태가 기준이 되는 걸 막기 위해 항상 명시적으로 요청해야 합니다.
### `/seo-check` — 회귀(원복) 확인하기
```
/seo-check https://내사이트.com
```
저장해둔 베이스라인과 지금 상태를 비교해 "예전엔 없던 문제가 다시 생겼는지" 알려줍니다. 베이스라인이 없으면 먼저 진단→저장을 안내합니다.
### `/seo-fix` — 로컬 Next.js 프로젝트 자동 수정하기
```
/seo-fix ./내-nextjs-프로젝트-폴더
```
**Next.js 프로젝트 폴더만** 지원합니다(다른 프레임워크는 아직 미지원). 동작 순서:
1. **계획(dry-run)**: 로컬에서 잠깐 서버를 띄워 진단하고, 아직 어떤 파일도 고치지 않은 채 "이렇게 고칠 수 있어요"라는 계획만 보여줍니다.
- **"없는 것 추가"**(예: sitemap에 빠진 페이지 추가)는 자동으로 계획됩니다.
- **검색 결과 표시에 영향을 주는 변경**(canonical·robots·sitemap 구조 등)은 반드시 **승인**해야만 적용됩니다 — diff(변경 내용)를 먼저 보여드리고, 승인/거부 의사를 여쭤봅니다.
2. **적용**: 승인이 끝나면 실제로 파일에 반영하고, 곧바로 `next build`를 다시 돌려 빌드가 여전히 통과하는지 확인합니다. **빌드가 실패하면 자동으로 원래 상태로 되돌립니다.**
3. **되돌리기(필요시)**: 적용된 수정이 마음에 안 들면 "되돌려줘"라고 요청하면 됩니다.
⚠️ **git 저장소여야 하고, 커밋되지 않은 변경사항이 없는(clean) 상태여야 합니다** — 안전하게 되돌릴 수 있는 지점이 없으면 아예 수정을 시작하지 않습니다. 그리고 **자동 수정도 실제 파일 변경입니다** — 적용 후에도 커밋·배포 전에 diff를 한 번 더 검토하세요("safe하니까 무해하다"고 자동으로 가정하지 않습니다).
### `/seo-fix` — GitHub 저장소 대상 자동 수정 제안(Pull Request) — ⚠️ 실험적
```
/seo-fix https://github.com/소유자/저장소
```
로컬 폴더 대신 **GitHub 저장소 주소**를 넣으면, 그 저장소를 임시로 복제(clone)해 같은 진단·수정 로직을 실행한 뒤, 결과를 **새 브랜치 + Pull Request(변경 제안)**로 제출합니다. 자세한 단계는 아래를 참고하세요.
1. **GitHub Personal Access Token(개인용 접근 토큰) 준비**
- `https://github.com/settings/personal-access-tokens/new` 접속 → 로그인
- **Repository access**: "Only select repositories" 선택 → 대상 저장소 선택
- **Repository permissions**: `Contents` → Read and write, `Pull requests` → Read and write 로 설정 (반드시 이 두 가지를 각각 명시적으로 추가해야 합니다 — 저장소만 선택하고 권한을 안 넣으면 작동하지 않습니다)
- **Generate token** 클릭 → 표시되는 토큰 값을 복사(한 번만 보여줍니다)
2. **⚠️ 토큰 값을 Claude Code 대화창에 절대 붙여넣지 마세요.** 아래처럼 컴퓨터에만 등록합니다.
- Windows(PowerShell): `setx SEOMEDIC_GITHUB_TOKEN "복사한토큰값"`
- Mac/Linux(터미널, 셸 설정파일에 추가 권장): `export SEOMEDIC_GITHUB_TOKEN="복사한토큰값"`
- **등록 후 Claude Code를 완전히 종료했다가 다시 실행**해야 합니다(설치 직후와 동일한 이유 — 이미 켜져 있는 프로그램은 새로 등록한 값을 모릅니다).
3. Claude Code 대화창에 `/seo-fix https://github.com/소유자/저장소` 입력
4. **한 번의 호출로 진단→"없는 것 추가" 자동 적용→Pull Request 생성까지 전부 진행됩니다** — 로컬 폴더 모드와 달리 중간에 대화형으로 승인받는 단계가 없습니다(한 번에 끝나는 구조라 기술적으로 불가능). 그래서 **검색 결과 표시에 영향을 주는 항목은 자동으로 적용되지 않고, "승인이 필요해 적용 안 함" 목록으로만 보고됩니다.**
5. 결과에 Pull Request 링크가 나오면, **저장소 관리자가 직접 내용을 검토한 뒤 병합 여부를 결정**해야 합니다 — 자동으로 병합되지 않습니다.
**절대로 하지 않는 것**: 기본 브랜치(main/master)에 직접 반영, 강제 push(force-push), 자동 병합(merge). 항상 새 브랜치 + Pull Request로만 제안합니다(코드 구조상 강제 push 기능 자체가 없습니다).
> ⚠️ **실험적 기능 정확한 현재 상태**: "내가 소유한 저장소"에 브랜치+Pull Request를 만드는 흐름은 실제 GitHub 환경에서 실행해 정상 작동을 확인했습니다. "내 소유가 아닌 저장소를 복제(fork)해서 제안하는 흐름"은 fork 생성과 복제까지는 실제 GitHub 환경에서 검증했습니다(실제로 fork 저장소가 만들어지는 것까지 확인함). 다만 그 뒤 Pull Request를 실제로 만드는 마지막 단계까지는 아직 확인하지 못했습니다(검증에 사용한 테스트 저장소에 Next.js 프로젝트 파일이 없어 그 앞 단계에서 멈췄습니다). 사용 전 이 사실을 알고 계셔야 하며, 실행 시에도 이 안내가 다시 표시됩니다.
## 6. 명령어 레퍼런스
| 명령어 | 설명 | 참고 옵션(자연어로 요청 가능) |
|---|---|---|
| `/seo-audit <url>` | URL 진단(분석 전용) | 사이트 전체 크롤 여부, 최대 페이지 수(기본 200)·깊이(기본 3)·초당 요청수(기본 1) |
| `/seo-check <url>` | 베이스라인 대비 회귀 확인 | - |
| `/seo-fix <로컬폴더>` | 로컬 Next.js 프로젝트 자동 수정(승인형) | 승인/거부는 대화로 진행 |
| `/seo-fix <GitHub 저장소 주소>` | GitHub 저장소 대상 자동 수정 제안(PR, 실험적) | `SEOMEDIC_GITHUB_TOKEN` 환경변수 필요 |
> 현재 버전은 옵션을 `--플래그` 형태가 아니라 **대화로 자연어 요청**하는 방식입니다(예: "사이트 전체를 depth 2까지만 돌려줘"). 별도 커맨드라인 실행 파일은 이번 버전에 포함되지 않았습니다.
## 7. 워크플로우
```
사이트 주소 준비
│
▼
/seo-audit https://... 실행 ──► (진단 전용, 수정 없음)
│ │
│ ▼
│ Markdown 리포트 확인
│ (심각도순 위반 목록 + Core Web Vitals)
▼
"베이스라인으로 저장해줘" 요청
│
▼
(시간이 지난 뒤) /seo-check https://... 재실행
│
▼
원복(회귀) 있으면 경고 / 없으면 "원복된 항목 없음"
(선택) Next.js 프로젝트를 가지고 있다면:
│
▼
/seo-fix ./로컬폴더 또는 /seo-fix https://github.com/소유자/저장소
│ │
▼ ▼
로컬: 계획 확인→승인/거부→적용→ GitHub: 진단→자동 적용→
빌드 재검증→(필요시) 되돌리기 Pull Request 생성→관리자 검토
```
## 8. 업데이트 내용 요약
이 프로젝트는 위험이 큰 기능(실제 파일 수정)을 단계적으로 나눠 만들었습니다. 항목을 눌러 펼치면 자세한 내용을 볼 수 있습니다.
<details>
<summary><strong>✅ Phase 1 — URL 진단 + 회귀(원복) 감지 (완료)</strong></summary>
크롤+렌더링+Core Web Vitals 측정, 그리고 회귀(원복) 감지 기능입니다. 실제 라이브 사이트를 대상으로 처음부터 끝까지(end-to-end) 실제 실행으로 검증했습니다.
</details>
<details>
<summary><strong>✅ Phase 1.5a — 로컬 Next.js 프로젝트 자동 수정 (완료·실제 실행으로 검증)</strong></summary>
"없는 것만 추가"(add_safe)하는 안전한 수정은 자동으로, 검색 결과 표시에 영향을 주는 변경(gated)은 사용자 승인 후에만 적용됩니다. 적용 후 빌드 재검증과, 빌드 실패 시 자동 롤백까지 실제 실행으로 확인했습니다.
</details>
<details>
<summary><strong>🟡 Phase 1.5b — GitHub 저장소 대상 자동 수정 제안 (구현 완료·부분 검증)</strong></summary>
"내 저장소"에 새 브랜치 + Pull Request를 만드는 흐름은 실제 GitHub 환경에서 Pull Request 생성까지 실제로 검증했습니다. **"내 소유가 아닌 저장소를 fork해서 제안하는 흐름"은 fork 생성과 복제까지는 실제 GitHub 환경에서 검증했습니다**(실제로 fork 저장소가 만들어지는 것까지 확인함). 다만 그 뒤 Pull Request를 실제로 만드는 마지막 단계까지는 아직 확인하지 못했습니다(검증에 사용한 테스트 저장소에 Next.js 프로젝트 파일이 없어 그 앞 단계에서 멈췄습니다). 사용 전 14번 항목과 실행 시 안내를 꼭 확인하세요.
</details>
<details>
<summary><strong>✅ Phase 2 Stage 1 — 구조화 데이터(JSON-LD) 탐지 (완료)</strong></summary>
페이지에 구조화 데이터(JSON-LD, 검색엔진이 콘텐츠를 더 정확히 이해하도록 돕는 특수 표시)가 없거나 형식이 깨져 있는지 자동으로 찾아 리포트에 알려줍니다. **탐지만 하고 자동으로 고쳐주지는 않습니다**(값을 새로 만들어 넣는 건 위험할 수 있어 의도적으로 제외했습니다).
</details>
<details>
<summary><strong>✅ Phase 2 Stage 2 — Open Graph(소셜 공유 미리보기) 탐지 + 일부 자동 수정 (완료)</strong></summary>
소셜 미디어(카카오톡·페이스북 등)에 링크를 공유했을 때 보이는 제목·주소(Open Graph 태그)가 없는지 확인합니다. 그중 **제목과 주소는 이미 페이지에 있는 실제 값을 그대로 복사하는 것**이라 안전해서, 승인을 거쳐 자동으로 채워드릴 수 있습니다(설명 문구는 새로운 문장을 만들어야 해서 자동 수정 대상에서 제외했습니다).
</details>
<details>
<summary><strong>✅ Phase 2 Stage 3 — AI 크롤러 정책(GEO) 탐지 (완료)</strong></summary>
ChatGPT·Claude 등 AI 검색·AI 학습에 쓰이는 크롤러(GPTBot·ClaudeBot 등 11종)가 이 사이트의 `robots.txt`에서 허용되는지 차단되는지를 확인해 리포트에 보여줍니다. **탐지만 하고 "이렇게 바꾸세요"라는 정책 권고는 하지 않습니다**(허용·차단 중 어느 쪽이 맞는지는 사이트 운영자의 정책 판단 영역이라, 사실만 중립적으로 알려드립니다).
</details>
<details>
<summary><strong>✅ Phase 2 Stage 4 — 콘텐츠 기본 요소(제목·제목태그·이미지 설명) 탐지 (완료)</strong></summary>
검색엔진이 페이지 내용을 이해하는 데 가장 기본이 되는 요소들을 확인합니다: 페이지 제목(`<title>`)이 없는지, 핵심 제목 태그(`<h1>`)가 없거나 여러 개인지, 이미지에 설명(alt 텍스트)이 빠져 있는지를 찾아 리포트에 알려줍니다. **탐지만 하고 자동으로 고쳐주지는 않습니다**(제목·이미지 설명은 페이지마다 내용이 달라 임의로 만들어 채우면 오히려 부정확해질 수 있어 의도적으로 제외했습니다).
</details>
<details>
<summary><strong>✅ Phase 2 Stage 5 — 상품(Product) 구조화 데이터 필수 항목 검증 + Q&A 구조 탐지 (완료)</strong></summary>
두 가지를 추가로 확인합니다: (1) 상품 페이지의 구조화 데이터(JSON-LD)에 Google이 요구하는 필수 항목(상품명, 그리고 후기·평점·가격 중 최소 하나)이 빠져 있는지, (2) 자주 묻는 질문(Q&A) 형태의 구조화 데이터가 있는지. **둘 다 탐지만 하며, 내용을 새로 만들어 채워 넣지 않습니다**(실제와 다른 내용을 자동 생성하면 오히려 신뢰도를 해칠 수 있어서입니다). Q&A 구조를 추가한다고 AI 검색 노출이 보장되는 것도 아니라는 점도 함께 안내합니다.
</details>
<details>
<summary><strong>🔧 2026-07-06 — 품질 자동검증(CI) 도입 + 실제 결함 발견·수정</strong></summary>
Windows·Mac·Linux 3개 운영체제 전부에서 자동으로 빌드와 테스트가 통과하는지 확인하는 절차(CI)를 새로 만들었습니다(2026-07-06 당시 260개였던 테스트는 이후 기능이 계속 늘어 **현재 427개**입니다 — 아래 항목들 참고). 그 과정에서 지금까지 Windows에서만 개발·확인해와서 미처 몰랐던 실제 문제 몇 가지를 찾아 고쳤습니다(예: GitHub 자동 수정 기능이 Mac·Linux 환경에서 내부적으로 필요한 프로그램 경로를 못 찾던 문제). 지금은 3개 운영체제 모두에서 빌드·테스트 통과가 자동으로 확인되지만, **사람이 Mac·Linux에서 직접 명령을 실행해보는 수동 검증까지 마친 것은 아닙니다** — 자동 검증으로 위험을 낮춘 것이지, 완전히 없앤 것은 아닙니다.
</details>
<details>
<summary><strong>✅ Phase 2 Stage 4 — 콘텐츠 구조(제목·소제목·이미지 설명) 탐지 + Core Web Vitals 3종 완결 (완료)</strong></summary>
페이지에 제목(title)이 없거나, 소제목(H1)이 아예 없거나 반대로 여러 개 중복돼 있거나, 이미지에 대체 텍스트(alt — 시각장애인용 화면낭독기와 검색엔진이 이미지 내용을 이해하는 데 쓰이는 설명)가 빠져 있는지 자동으로 찾아 리포트에 알려줍니다. 같은 시점에 Core Web Vitals(속도 지표) 중 마지막으로 남아 있던 TBT(체감 반응성 지표 — 실제 INP는 사용자의 실제 클릭이 있어야 측정 가능해 자동 진단에서는 그 근사치로 이 지표를 씁니다) 임계값 규칙도 추가되어, 속도 지표 3종(LCP·CLS·TBT)이 전부 갖춰졌습니다. **탐지만 하고 자동으로 고쳐주지는 않습니다**(값을 새로 만들어 넣는 게 아니라 "있고 없고"만 확인하는 항목들이라, 자동 수정보다 사람이 직접 채우는 게 맞다고 판단했습니다).
</details>
<details>
<summary><strong>✅ Phase 2 — Q&A 구조·JSON-LD 상품(Product) 필수 정보 검증 (완료)</strong></summary>
자주묻는질문(FAQ) 형태의 구조화 데이터가 있는지 확인합니다(AI 검색 답변에 인용되기 쉬운 형태인지 보는 용도일 뿐 **AI 검색 노출을 보장하지는 않습니다**). 그리고 JSON-LD로 "상품(Product)"을 표시해 둔 페이지라면, 상품명(name)과 리뷰·평점·가격 정보 중 최소 하나가 실제로 채워져 있는지 확인합니다(둘 다 없으면 검색결과에 별점·가격 같은 추가 정보가 표시될 자격을 잃을 수 있습니다). **탐지만 하고 자동으로 고쳐주지는 않습니다.**
</details>
<details>
<summary><strong>✅ Phase 2 — JSON-LD 상품명이 실제 페이지 내용과 일치하는지 검증("환각 0") (완료)</strong></summary>
JSON-LD(구조화 데이터)에 적어놓은 상품 이름이 실제로 그 페이지 화면에 나오는 글자와 일치하는지 확인합니다 — 검색엔진에 알려주는 구조화 정보가 실제 화면 내용과 다르면("환각"이라고 부릅니다) 검색엔진이 스팸으로 간주해 불이익을 줄 수 있기 때문입니다. 가격·할인 정보는 쉼표·통화 기호 등 표시 형식이 사람마다 달라 "다르다"는 판정 자체가 오히려 틀릴 위험이 커서, 검사 대상에서 의도적으로 제외했습니다(상품명만 결정론적으로 안전하게 비교 가능). **탐지만 하고 자동으로 고쳐주지는 않습니다.**
</details>
**앞으로 계획된 것(아직 시작 안 함)**: Google Search Console/Analytics **실연동**(Phase 2 — 현재는 인터페이스 골격과 가짜 클라이언트만 있으며 실제 계정 연동은 안 돼 있습니다, 사용자의 실제 Google 서비스계정 자격증명이 있어야 착수 가능), 네이버·Bing 지원(Phase 3). 이 문서는 실제로 구현·검증된 것만 다루며, 계획 단계 기능을 이미 되는 것처럼 설명하지 않습니다.
## 9. 보안·데이터 흐름
- **`.seomedic/` 폴더에만 저장됩니다.** 진단을 실행한 프로젝트 폴더 안에 SQLite 데이터베이스 파일(`.seomedic/seomedic.db`) 하나가 생기고, 여기에 진단 이력·베이스라인·회귀 기록이 저장됩니다. 이 폴더는 자동으로 git 추적에서 제외되도록 안내됩니다.
- **결과가 저장되는 파일은 소유자만 열어볼 수 있도록 잠급니다**(Mac/Linux 환경 — Windows는 운영체제 구조상 이 방식이 적용되지 않아, Windows에서는 아직 별도 확인이 필요한 상태입니다).
- **크롤한 페이지 원문은 저장하지 않습니다.** 해시값(지문)과 500자 이하 짧은 요약만 남깁니다(저작권 보호 목적).
- **텔레메트리(사용 데이터 외부 전송)가 전혀 없습니다.** 사용자가 지정한 진단 대상 URL(그리고 GitHub 모드에서는 지정한 저장소) 외에는 어디로도 데이터를 보내지 않습니다.
- **사설 IP·내부망 주소는 진단 대상으로 삼지 않습니다**(SSRF 방지 — `127.0.0.1`, `192.168.x.x`, 클라우드 내부 메타데이터 주소 등은 자동 차단됩니다).
- **`/seo-fix`(로컬 수정)는 git이 clean일 때만 동작하고, 적용 전 대상 파일을 자동 백업합니다.** 색인·표시에 영향을 주는 변경은 사용자 승인 없이 절대 적용되지 않으며, 적용 후 빌드가 실패하면 즉시 자동으로 되돌립니다.
- **GitHub 토큰은 환경변수(`SEOMEDIC_GITHUB_TOKEN`)로만 읽습니다.** 코드에 하드코딩되지 않고, 대화창·명령어 인자·로그·에러 메시지 어디에도 토큰 값 자체가 출력되지 않습니다. 토큰이 없으면 GitHub 모드는 이유를 밝히고 스스로 거부합니다.
- **GitHub 저장소 수정은 항상 새 브랜치 + Pull Request로만 제안됩니다.** 기본 브랜치(main/master) 직접 push, 강제 push(force-push), 자동 병합(merge) 기능은 코드 구조상 아예 존재하지 않습니다.
- **이미 열려 있는 동일한 제안이 있으면 중복으로 새로 만들지 않습니다**(중복 Pull Request 방지).
## 10. 아키텍처(쉽게)
```
[Claude Code] ──(대화 중 /seo-audit, /seo-fix 등 입력)──► [SeoMedic 플러그인]
│
(명령어를 실제 작업으로 연결)
▼
[SeoMedic 진단 엔진(MCP 서버)]
│
┌───────────────┬────────────────┬─────────────┼───────────────┐
▼ ▼ ▼ ▼ ▼
웹사이트 크롤 브라우저 렌더링 성능 측정 로컬 Next.js GitHub 저장소
(SSRF 안전장치) (Playwright) (Lighthouse) 자동 수정 자동 수정 제안
│ │ │ (git clean 확인 (임시 복제→수정→
└───────────────┴────────────────┘ +빌드 재검증) PR 생성, 실험적)
│
▼
결과 저장(.seomedic/*.db)
```
플러그인(가벼운 껍데기)과 진단 엔진(무거운 실제 작업)이 분리되어 있습니다 — 마치 리모컨(플러그인)과 실제 가전제품(엔진)처럼, 리모컨은 가볍고 실제 일은 엔진이 합니다. GitHub 저장소 모드는 이 엔진이 저장소를 컴퓨터 임시 폴더에 잠깐 복제해와 로컬 수정과 동일한 로직을 실행한 뒤, 끝나면 임시 폴더를 정리합니다.
## 11. 파일·문서 위치
| 무엇 | 어디에 |
|---|---|
| 진단 결과 데이터베이스 | 진단을 실행한 프로젝트의 `./.seomedic/seomedic.db` |
| GitHub 모드의 회귀 이력 데이터베이스 | 사용자 홈 폴더 하위 `.seomedic-github-cache/`(저장소별로 분리 보관 — 임시 복제 폴더와 별개로, 삭제되지 않고 유지됨) |
| 이 플러그인 자체 소스 | `packages/plugin/`(설치되는 부분), `packages/mcp-engine/`(엔진) |
| GitHub 연동 관련 소스 | `packages/mcp-engine/src/github/` |
| 기획 문서(PRD) | `.PRD/` |
| 진행 상태·검증 기록 | `CHECKPOINT.md`(Phase 1), `CHECKPOINT_1.5.md`(Phase 1.5), `CHECKPOINT_2.md`(Phase 2) |
| 보안 정책 | `packages/plugin/SECURITY.md` |
| 면책·이용조건 | `packages/plugin/DISCLAIMER.md` |
| 라이선스 | `LICENSE`, `THIRD_PARTY_NOTICES.md` |
| 문제 해결 | `TROUBLESHOOTING.md`(한국어), `TROUBLESHOOTING.en.md`(영문) |
| 자주 묻는 질문 | `FAQ.md`(한국어), `FAQ.en.md`(영문) |
## 12. 문제/오류 대처
자주 발생하는 문제와 해결책은 **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)**에 증상→원인→해결 순서로 정리되어 있습니다. 가장 흔한 것 3가지만 먼저 안내합니다:
1. **설치했는데 `/seo-audit`이 안 보여요** → Claude Code를 완전히 종료 후 재시작하셨나요? (새 창만으로는 부족합니다)
2. **첫 실행이 너무 오래 걸려요** → 브라우저 엔진(Chromium) 자동 설치 중일 수 있습니다(수백 MB, 1~2분 소요).
3. **"결과가 비어 있습니다"** → 대상 사이트가 로봇 차단(robots.txt) 또는 방화벽으로 접근을 막고 있을 수 있습니다.
## 13. FAQ
자주 묻는 질문은 **[FAQ.md](./FAQ.md)**에 정리되어 있습니다.
## 14. 법률·저작권·라이선스·상업적 용도
**엄격하게, 축소·과장 없이 안내드립니다.**
### 라이선스
- 이 프로젝트는 **MIT 라이선스를 채택할 예정**입니다(수정·복제·재배포·상업적 사용을 폭넓게 허용하되, 저작권 고지문을 그대로 유지해야 하는 조건). 정확한 전문은 `LICENSE` 파일을 확인하세요.
- **⚠️ 현재 `LICENSE` 파일은 저작권자를 임시로 "SoDam AI Studio"(2026년)로 채워둔 초안 상태입니다.** 이는 "이름을 무엇으로 할지"라는 사실관계만 채운 것이며, **MIT 라이선스 채택 자체와 이 저작권자 표기의 최종 확정은 여전히 법무 검토 대기 중**입니다. 최종 확정 전까지는 라이선스 조건이 법적으로 완전히 발효됐다고 보기 어려우니, 상업적 배포·재배포 전에는 반드시 이 파일이 최종 확정됐는지 먼저 확인하세요.
- 이 프로젝트가 사용하는 외부 오픈소스 라이브러리 목록과 각각의 라이선스는 `THIRD_PARTY_NOTICES.md`에 정리되어 있습니다. 확인 결과 **저작권 카피레프트(GPL 등 재배포 시 소스공개 의무가 있는 라이선스) 계열은 발견되지 않았습니다.**
### 할 수 있는 것
- 개인·회사 프로젝트에 자유롭게 설치해 진단하기
- 소스 코드 수정·재배포(위 라이선스 최종 확정 및 조건 준수 하)
- 상업적 사용(라이선스가 최종 확정된 이후, MIT 조건 하)
### 할 수 없는 것 / 반드시 주의할 것
- **본인 소유가 아니거나 명시적 권한이 없는 사이트·저장소를 무단으로 진단·수정하는 것** — 법적 책임은 전적으로 사용자에게 있습니다. SeoMedic은 실행 전 권한 여부를 항상 확인하도록 설계돼 있지만, 확인 질문에 사실과 다르게 답하는 것까지 막을 수는 없습니다.
- **"검색 1위 보장", "AI 검색 노출 보장" 같은 과장된 주장을 이 도구의 결과를 근거로 하는 것** — 아래 무보증 조항 참고.
- **크롤한 웹페이지의 원문 전체를 수집·재배포하는 것** — SeoMedic 자체는 해시값과 500자 이하 요약만 저장하도록 설계돼 있어 이런 용도로 쓸 수 없으며, 별도로 원문을 수집하는 행위는 대상 사이트의 저작권·이용약관을 별도로 검토해야 합니다.
- GitHub 저장소 대상 기능을 쓸 때, **저장소 소유자의 동의 없이 무단으로 Pull Request를 대량 생성하는 것**(스팸성 행위로 간주될 수 있음).
### 무보증(경고)
- 이 도구는 **참고용 진단 도구**이며, 검색 순위·AI 검색 노출·트래픽 증가를 **일절 보장하지 않습니다.**
- 자동 수정 기능(`add_safe`)이 적용한 변경도 **무해함이 보장되지 않습니다** — 반드시 적용 후 diff를 직접 검토한 뒤 커밋·배포하세요.
- 자세한 면책 조항은 `packages/plugin/DISCLAIMER.md`를 확인하세요.
### 제휴 관계
- **본 도구는 Google·Anthropic(Claude)·OpenAI(ChatGPT)·Perplexity 등 이 문서·진단 결과에 언급되는 어떤 서비스와도 공식적으로 제휴·제공·보증 관계가 없습니다.** 진단 대상 검색엔진/AI 서비스의 이름은 오직 설명 목적으로만 언급됩니다.
### 아직 법무 검토가 끝나지 않은 항목
- 저작권자 최종 확정(위 라이선스 항목)
- 크롤 콘텐츠에 대한 저작권 문제 소지 여부
- 상표(제품명 등) 관련 fair use 범위
- AI가 생성한 코드/문서 산출물의 저작권 귀속 문제
- 이 프로젝트 자체의 제품명("SeoMedic")에 대한 상표 등록 여부
⚠️ **위 내용은 법률 자문이 아닙니다.** 상업적 배포·납품·타인에게 서비스로 제공하기 전에는 반드시 전문 법률가의 검토를 받으시길 강력히 권장합니다.
---
이 문서(README.md)가 설치부터 사용까지의 왕초보용 단계별 안내를 전부 담고 있습니다(별도 GUIDE 문서는 2026-08-04부로 이 문서로 통합되어 더 이상 존재하지 않습니다). 문제가 생기면 **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)**, 궁금한 점은 **[FAQ.md](./FAQ.md)**를 확인하세요.
Connection Info
You Might Also Like
No recommendations available