auto-geo

auto-geo

ChatGPT, Claude, Gemini, Perplexity, Grok에서 여러분의 브랜드를 언급하게 만드는 오픈소스 GEO 엔진.

대규모 언어 모델이 인용하는 페이지를 감사하고, 생성하고, 수정하고, 추적하세요 — 하나의 CLI, 파일 기반, MIT 라이선스.

누군가 ChatGPT, Perplexity, Claude, Gemini 또는 Google AI Overviews에 여러분의 비즈니스가 답해야 할 질문을 던질 때, 그 엔진들이 여러분의 도메인을 인용하나요? auto-geo은 이를 실현하고 입증하기 위한 완전한 루프입니다:

auto-geo init      # set up the system once
auto-geo doctor    # audit any page for citation readiness
auto-geo write     # generate publish-ready pages from target queries
auto-geo fix       # rewrite an existing page so it passes the audit
auto-geo check     # measure: do AI engines actually cite you?
auto-geo history   # track citation coverage over time

모든 것이 파일 기반이며 커밋 가능합니다 — 추적된 프롬프트, 검사 기록, 설정. 서버도, 계정도, 데이터베이스도 필요 없습니다. 설치 한 번이면 됩니다:

npm i -g auto-geo

Shadow 제작 — OpenAI, TikTok, Meta, Amazon, Lovable를 성공시킨 팀들과 협력하여 차세대 AI 기반 미디어 인텔리전스 및 커뮤니케이션 기술을 구축하는 미디어 리서치 랩입니다. Shadow는 shadow.inc/resources에 게시하기 위해 auto-geo를 사용합니다.

---

목차

• 빠른 시작
• GEO란 무엇인가?
• 워크플로우
• auto-geo init — 시스템 설정
• auto-geo doctor — 인용 준비 상태 감사
• auto-geo write — 쿼리에서 페이지 생성
• auto-geo fix — 인용 준비를 위한 페이지 재작성
• auto-geo prompts — 추적 프롬프트 관리
• auto-geo check — 실제 인용 커버리지 측정
• auto-geo history — 시간에 따른 인용 커버리지
• 설정
• 페이지 아키텍처
• 에이전트 친화적 출력
• LLM 친화적
• 기여하기
• 라이선스

---

빠른 시작

# 0. Install once (or run any command one-shot via \`npx auto-geo@latest\`)
npm i -g auto-geo

# 1. Set up — config, .env.local key slots, and the .auto-geo workspace
auto-geo init

# 2. Add an API key to .env.local (auto-loaded by every command)

# 3. Audit any page — yours or a competitor's
auto-geo doctor https://example.com/some-page

# 4. Track the prompts you want AI engines to cite you for
auto-geo prompts add "best media monitoring tools" "what is GEO"

# 5. Measure — every run is saved to history automatically
auto-geo check

# 6. Watch coverage move over time
auto-geo history

Node >=18.17 필요. 이후 업그레이드는 npm i -g auto-geo@latest. 다른 설치 방법:

brew install shadowresearch/tap/auto-geo   # Homebrew (macOS / Linux)
mise use -g npm:auto-geo                   # mise

macOS, Linux, Windows용 독립 실행 파일(Node 불필요)은 모든 릴리스에 포함되어 있습니다.

---

GEO란 무엇인가?

생성 엔진 최적화(Generative Engine Optimization) 는 AI 검색 엔진이 질문에 답할 때 인용하는 페이지를 만드는 학문입니다. 링크 목록에서 순위를 매기는 SEO의 후속 개념으로, 답변 내부에서 인용되기 위해 경쟁하는 것입니다.

승리하는 페이지는 블로그 게시물이 아닙니다. 실증 연구는 인용 확률을 특정 구조와 연결합니다:

1. 산문이 아닌 아키텍처. 명명되고 검증된 블록 — TL;DR, 인트로, 질문 형식의 H2 섹션, 관련 가이드, 핵심 요점, FAQ, 공개 고지. AI 엔진은 구조화된 청크를 추출합니다; 엄격한 구조는 추출을 개선합니다.
2. 답변 우선. 모든 섹션은 지원 문단 전에 섹션의 질문에 완전히 답하는 40–60단어 "답변 캡슐"로 시작합니다.
3. 질문 형식의 제목. H2는 사용자가 AI 엔진에 실제로 묻는 질문으로 작성됩니다.
4. 엔티티 밀집. 명명된 엔티티(회사, 사람, 제품)를 높은 밀도로 — 인용 확률 ~4.8배 증가와 연결.
5. 스키마 기반. Article + FAQPage JSON-LD가 수동 작성이 아닌 구조에서 생성됩니다.

auto-geo는 이 구조를 엄격한 스키마로 인코딩하고(전체 표준 운영 절차는 docs/sop.md 참조), 모든 URL을 이에 대해 감사하며, 이에 부합하는 새 페이지를 생성한 다음, 엔진이 실제로 인용하는지 측정하여 루프를 닫습니다.

---

워크플로우

┌──────────────────────────────────────────────────────┐
       │                    auto-geo init                     │
       │   config · .env.local · .auto-geo/ workspace         │
       └──────────────────────────────────────────────────────┘
             │
  ┌──────────┼──────────────┬─────────────────┐
  ▼          ▼              ▼                 ▼
doctor     write           fix             prompts
audit a    generate        rewrite an      track the queries
page       new pages       existing page   that matter to you
  │          │              │                 │
  └──────────┴──────────────┴────────┬────────┘
                                     ▼
                                   check ──── saves every run ────┐
                               measure actual                     ▼
                               citations                       history
                                                           coverage over time,
                                                           newly cited / lost

doctor는 준비 상태를 측정합니다(이 페이지가 인용에 적합한 형태인가?). check는 결과를 측정합니다(실제로 인용되고 있는가?). history는 결과를 추세선으로 전환합니다.

---

auto-geo init — 시스템 설정

auto-geo init        # interactive (a handful of questions)
auto-geo init --yes  # non-interactive template

하나의 명령으로 모든 것을 스캐폴딩합니다:

파일	설명
auto-geo.config.json	기본값 — 도메인, 공급자, 모델, 작성자. 커밋 가능; 비밀번호를 보관하지 않음.
.env.local	API 키 슬롯. 모든 명령에서 자동 로드. Gitignore 처리.
.auto-geo/prompts.txt	추적 프롬프트 — 줄당 하나, # 주석 허용.
.auto-geo/checks/	모든 check 실행을 JSON으로 저장. history의 기반 데이터.

대화형 흐름은 추적하려는 프롬프트를 묻는 것으로 끝나므로, 새 프로젝트는 한 번에 측정 가능한 인용 기준선으로 이동합니다. init는 기존 .env.local를 덮어쓰지 않으며, --force 없이 기존 설정을 덮어쓰기를 거부합니다.

---

auto-geo doctor — 인용 준비 상태 감사

어떤 URL에서든 실행하세요 — 여러분의 사이트, 경쟁사, 사이트맵의 모든 페이지 — AI 엔진이 찾는 인용 신호에 대한 구조화된 보고서를 받으세요.

auto-geo doctor https://example.com/some-page

✓ TL;DR present (52 words, in range)
✗ Question-format H2 headings (2 of 6 are question-format; SOP §3 targets all)
✓ Article JSON-LD present
✗ FAQPage JSON-LD present (No FAQPage JSON-LD block detected)
✓ Entity density (12.3/1k words)
✗ Image cadence (0 images for 1247 words)
✓ Answer-first first paragraph
✓ No self-link in related guides

Score: 5 / 8 checks pass — moderate GEO posture

Top 3 fixes (ranked by citation lift):
  1. Add a FAQPage JSON-LD block. Each Q is a citable extraction target.
  2. Convert 4 statement-form H2 headings to question form.
  3. Add 2 images with descriptive alt text (entity + context).

# Whole sitemap — mean score, lowest-scoring pages, most common failures
auto-geo doctor --site https://example.com/sitemap.xml --max-pages 50

# JSON for CI / dashboards
auto-geo doctor https://example.com/page --json

점수 ≥ 75%이면 종료 코드 0, 그렇지 않으면 1 — 배포를 이에 게이트하세요. 전체 검사 참조는 docs/doctor.md 참조.

---

auto-geo write — 쿼리에서 페이지 생성

도메인과 인용을 원하는 쿼리를 제공하면 검증되고 게시 준비된 JSON 파일을 반환합니다 — 쿼리당 하나의 구조화된 페이지, 전체 GEO 아키텍처에 부합.

auto-geo write \
  --query "what is GEO" \
  --query "GEO vs SEO" \
  --out ./resources

✓ "what is GEO"        → ./resources/geo.json (validated, ~$0.06)
✓ "GEO vs SEO"         → ./resources/geo-vs-seo.json (validated, ~$0.06)

Total: 2 pages · 2 ok · ~$0.12 spent · 31s elapsed

시스템 프롬프트는 GEO SOP를 인코딩합니다 — TL;DR 길이, 답변 캡슐 창, 금지된 최상급 표현, FAQ 구조 — 출력은 Vercel AI SDK의 generateObject를 통해 타입 시스템 수준에서 스키마로 제한되며, 검증 실패 시 제한된 자기 수정 루프가 있습니다. 기본값: gpt-5.4 (OpenAI) 또는 claude-sonnet-4-6 (Anthropic), 설정된 API 키에서 자동 감지.

# Dry-run — plan + cost estimate, no LLM calls
auto-geo write --query "what is X" --dry-run

# Batch from a file, anthropic, 4 pages at a time
auto-geo write --queries-file queries.txt --provider anthropic --concurrency 4

설정 파일(auto-geo init)이 있으면 --domain, 작성자 필드, 공급자가 설정에서 제공됩니다 — --query만 있으면 됩니다. docs/write.md 참조.

---

auto-geo fix — 인용 준비를 위한 페이지 재작성

doctor이 무엇이 잘못되었는지 알려주는 곳에서, fix은 8가지 검사를 모두 통과하는 GEO 최적화 재작성을 생성합니다 — write이 사용하는 동일한 스키마에 대해 가져오고, 감사하고, 재생성하고, 검증합니다.

auto-geo fix https://www.example.com/some-blog-post --out ./fixed.json

Score (before):    3 / 8
Generating rewrite via openai gpt-5.4...
Score (projected): 8 / 8 — strong GEO posture
→ ./fixed.json (validated)

auto-geo fix https://example.com/page --provider anthropic   # Claude instead
auto-geo fix https://example.com/page --dry-run              # audit + cost estimate only

docs/fix.md 참조.

---

auto-geo prompts — 추적 프롬프트 관리

추적 프롬프트는 AI 엔진이 여러분의 도메인을 인용하여 답변하길 원하는 질문입니다. .auto-geo/prompts.txt에 있으며(일반 텍스트, 커밋 가능), check이 기본적으로 실행하는 대상입니다.

auto-geo prompts add "best media monitoring tools" "what is GEO"
auto-geo prompts            # numbered list
auto-geo prompts rm 2       # by index — or by exact text

무엇을 추적할지 모르시나요? 엔진이 프롬프트 세트를 제안하게 하세요 — discover이 홈페이지를 가져와 이미 추적 중인 항목을 확인하고, LLM이 경쟁해야 할 높은 의도의 쿼리를 생성합니다:

auto-geo prompts discover --dry-run    # preview the proposals
auto-geo prompts discover --count 15   # append 15 (never overwrites, never duplicates)

prompts add (및 discover)은 첫 사용 시 워크스페이스를 부트스트랩하므로, 추적을 시작하기 위해 init이 필요하지 않습니다.

---

auto-geo check — 실제 인용 커버리지 측정

각 프롬프트에 대해 실제 AI 검색 엔진에 질문하고 여러분의 도메인이 인용 중인지 보고합니다. 이것이 doctor이 예측하는 실제 데이터입니다.

auto-geo check        # tracked prompts, domain from config

using 3 tracked prompts from .auto-geo/prompts.txt
  [1/3] ✗ "what is GEO" — not cited (5 sources)
  [2/3] ✓ "how do I get cited by ChatGPT" — cited (2 sources)
  [3/3] ✓ "open source GEO tools" — cited (1 source)

Coverage: 2/3 queries (67%) · 3 page citations total · ~$0.012 spent
  saved → .auto-geo/checks/2026-06-10T13-22-05--perplexity.json (auto-geo history)

엔진: perplexity (기본), openai, anthropic, gemini, xai (별칭 grok), 또는 --engine all — API 키가 설정된 모든 엔진을 실행하고 엔진별 커버리지와 통합 요약을 보고합니다.

# Explicit queries instead of the tracked set
auto-geo check --domain shadow.inc --query "what is GEO"

# Every engine you have keys for, union coverage
auto-geo check --engine all

# CI: fail the deploy when critical queries don't cite you
auto-geo check --queries-file geo/critical-queries.txt && deploy

# Streaming JSON for agents / dashboards
auto-geo check --ndjson

모든 실행은 .auto-geo/checks/에 자동 저장됩니다(--no-save으로 제외). 커버리지 > 0%이면 종료 코드 0, 0%이면 1. 출력 형태, 팬아웃 쿼리 캡처, 도메인 일치 규칙 및 --format geo-audit 상호 운용 모드는 docs/check.md 참조.

---

auto-geo history — 시간에 따른 인용 커버리지

모든 실행을 저장하는 보상: 추세선. 엔진별 델타가 포함된 실행별 커버리지와, 인용이 시작되거나 중단된 정확한 프롬프트.

auto-geo history

2026-06-01 08:30  perplexity   33% ·   1/3 cited  $0.01
2026-06-08 09:15  perplexity   67% ↑34  2/3 cited  $0.01

Since last run (perplexity · 2026-06-01 08:30 ▸ 2026-06-08 09:15)
  ✓ newly cited  open source GEO tools
  ✗ lost         (none)

2 runs · .auto-geo/checks

추세는 동일한 것을 비교합니다 — 각 실행은 동일한 엔진 선택기의 이전 실행과 비교됩니다. --engine all은 다중 엔진 실행으로 필터링; --limit N은 깊이 제어; --json은 행 + 델타를 기계 판독 가능하게 출력. docs/history.md 참조.

---

설정

auto-geo init으로 한 번 설정하고 어디서든 재정의하세요. 우선순위, 높은 순:

1. CLI 플래그
2. 환경 변수(설정된 API 키에서 공급자 자동 감지)
3. auto-geo.config.json (cwd에서 위로 탐색 — 모노레포 친화적)
4. 내장 기본값

// auto-geo.config.json — committable, no secrets
{
  "domain": "https://www.example.com",
  "basePath": "/resources",
  "provider": "openai",
  "model": "gpt-5.4",
  "engine": "perplexity",
  "concurrency": 4,
  "author": {
    "name": "Jane Doe",
    "jobTitle": "Head of Content",
    "bio": "Jane writes about generative engine optimization…",
  },
}

API 키는 .env.local (또는 .env)에 있으며, 모든 명령에서 자동 로드 — 이미 설정된 환경 변수가 항상 우선:

엔진/공급자	환경 변수
OpenAI (write, fix, check)	OPENAI_API_KEY
Anthropic (write, fix, check)	ANTHROPIC_API_KEY
Perplexity (check)	PERPLEXITY_API_KEY
Gemini (check)	GOOGLE_API_KEY 또는 GEMINI_API_KEY
xAI / Grok (check)	XAI_API_KEY

---

페이지 아키텍처

write과 fix이 생성하는 모든 것 — 그리고 doctor이 감사하는 모든 것 — 엄격한 7블록 아키텍처를 따릅니다:

1. TL;DR — 40–60단어 답변 캡슐
2. 인트로 — 맥락 설정 블록
3. 섹션 — 질문 형식의 H2, 각각 40–60단어 답변 캡슐로 시작
4. 관련 가이드 — 4–8개 항목
5. 핵심 요점 — 4–6개 선언적 불릿
6. FAQ — 40–60단어 답변이 있는 3–10개 Q&A
7. 공개 고지 — 출처 메모, 타임스탬프, 게시자 라인

구조 위반은 하드 오류입니다(생성된 페이로드가 거부되고 재생성됨); 밀도 및 케이던스 휴리스틱은 소프트 경고입니다. 전체 사양: docs/architecture.md, docs/validation.md, 그리고 모든 제약 뒤의 SOP: docs/sop.md.

출력 JSON은 렌더러에 독립적입니다 — CMS에 POST하거나, 템플릿을 하이드레이트하거나, 자체 컴포넌트로 렌더링하세요. 구조 자체가 계약입니다.

---

에이전트 친화적 출력

모든 명령은 인간만큼 에이전트가 구동하도록 설계되었습니다:

• --json — stdout에 하나의 안정적이고 기계 판독 가능한 객체.
• --ndjson (check) — 결과가 스트리밍될 때 쿼리당 하나의 JSON 라인, _summary 라인 포함.
• 진행 상황은 stderr, 결과는 stdout — 파이프가 깨끗하게 유지됩니다.
• 안정적인 종료 코드 — doctor과 check은 기본적으로 CI 게이트입니다.
• 로그 친화적 출력을 위한 --no-color / NO_COLOR / 비-TTY 감지.

auto-geo check --ndjson | jq 'select(.cited) | .query'

---

LLM 친화적

auto-geo은 LLM이 인용하도록 설계된 콘텐츠를 출력하는 도구입니다 — 그래서 이 저장소는 자체 도그푸드를 먹습니다:

• llms.txt — llmstxt.org 규칙을 따르는 큐레이션된 인덱스.
• llms-full.txt — README와 모든 실질 문서를 단일 파일로 인라인하여 한 번의 가져오기로 읽을 수 있음.
• GitHub Pages 사이트 at shadowresearch.github.io/auto-geo — <link rel="alternate">을 통해 둘 다 광고, Article JSON-LD 발행.
• AGENT.md — CLI를 구동하는 코딩 에이전트를 위한 간결한 운영 사양.

---

기여하기

CONTRIBUTING.md 참조. 버그 보고, 검사 개선, 새 엔진, 문서 개선 모두 환영합니다.

---

라이선스

MIT.

---

Shadow 소개

Shadow는 OpenAI, TikTok, Meta, Amazon, Lovable을 만든 팀들과 협력하여 차세대 AI 기반 미디어 인텔리전스 및 커뮤니케이션 기술을 구축하는 미디어 연구 연구소입니다. Shadow는 미디어 연구, PR, 커뮤니케이션 팀을 위해 auto-geo을(를) 일정에 따라 엔드투엔드로 운영합니다.

자세한 내용은 shadow.inc에서 확인하세요.