CLAUDE.md

Overview

SERP analysis tool for understanding search result landscapes. Detects Google SERP features (featured snippets, PAA, knowledge panels, local pack, video, ads), analyzes Naver SERP composition (blog, cafe, knowledge iN, Smart Store, brand zone, shortform, influencer), maps competitor positions, and scores SERP feature opportunities.

Quick Start

pip install -r scripts/requirements.txt

# Google SERP analysis
python scripts/serp_analyzer.py --keyword "치과 임플란트" --country kr --json

# Naver SERP analysis
python scripts/naver_serp_analyzer.py --keyword "치과 임플란트" --json

Scripts

Script	Purpose	Key Output
`serp_analyzer.py`	Google SERP feature detection and competitor mapping	SERP features, competitor positions, opportunity scores
`naver_serp_analyzer.py`	Naver SERP composition analysis	Section distribution, content type mapping
`base_client.py`	Shared utilities	RateLimiter, ConfigManager, BaseAsyncClient

SERP Analyzer (Google)

# Single keyword analysis
python scripts/serp_analyzer.py --keyword "dental implant cost" --json

# Korean market
python scripts/serp_analyzer.py --keyword "치과 임플란트 가격" --country kr --json

# Multiple keywords from file
python scripts/serp_analyzer.py --keywords-file keywords.txt --country kr --json

# Output to file
python scripts/serp_analyzer.py --keyword "dental implant" --output serp_report.json

Capabilities:

SERP feature detection (featured snippet, PAA, knowledge panel, local pack, video carousel, ads, image pack, site links)
Competitor position mapping per keyword
Content type distribution analysis (blog, product, service, news, video)
SERP feature opportunity scoring
Search intent validation from SERP composition
SERP volatility assessment

Naver SERP Analyzer

# Analyze Naver search results
python scripts/naver_serp_analyzer.py --keyword "치과 임플란트" --json

# Analyze multiple keywords
python scripts/naver_serp_analyzer.py --keywords-file keywords.txt --json

Capabilities:

Naver section detection (블로그, 카페, 지식iN, 스마트스토어, 브랜드존, 도서, 숏폼, 인플루언서)
Section priority mapping (which sections appear above fold)
Content type distribution per section
Brand zone presence detection
Shortform/influencer content analysis

Data Sources

Source	Purpose
`our-seo-agent` CLI	Primary data source (future); use `--input` for pre-fetched JSON
WebSearch / WebFetch	Live SERP data and Naver section analysis
Notion MCP	Save analysis report to SEO Audit Log database

Output Format

{
  "keyword": "치과 임플란트",
  "country": "kr",
  "serp_features": {
    "featured_snippet": true,
    "people_also_ask": true,
    "local_pack": true,
    "knowledge_panel": false,
    "video_carousel": false,
    "ads_top": 3,
    "ads_bottom": 2
  },
  "competitors": [
    {
      "position": 1,
      "url": "https://example.com/page",
      "domain": "example.com",
      "title": "...",
      "content_type": "service_page"
    }
  ],
  "opportunity_score": 72,
  "intent_signals": "commercial",
  "timestamp": "2025-01-01T00:00:00"
}

Notion Output (Required)

IMPORTANT: All audit reports MUST be saved to the OurDigital SEO Audit Log database.

Database Configuration

Field	Value
Database ID	`2c8581e5-8a1e-8035-880b-e38cefc2f3ef`
URL	https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef

Required Properties

Property	Type	Description
Issue	Title	Report title (Korean + date)
Site	URL	Audited website URL
Category	Select	SERP Analysis
Priority	Select	Based on opportunity score
Found Date	Date	Analysis date (YYYY-MM-DD)
Audit ID	Rich Text	Format: SERP-YYYYMMDD-NNN

Language Guidelines

Report content in Korean (한국어)
Keep technical English terms as-is (e.g., SERP, Featured Snippet, PAA)
URLs and code remain unchanged

4.1 KiB Raw Blame History