CLAUDE.md

Overview

Keyword strategy and research tool for SEO campaigns. Expands seed keywords via our-seo-agent CLI or pre-fetched data, classifies search intent, clusters topics, performs competitor keyword gap analysis, and supports Korean market keyword discovery including Naver autocomplete.

Quick Start

# Install dependencies
pip install -r scripts/requirements.txt

# Keyword research from seed keyword
python scripts/keyword_researcher.py --keyword "치과 임플란트" --country kr --json

# Keyword gap analysis vs competitor
python scripts/keyword_gap_analyzer.py --target https://example.com --competitor https://competitor.com --json

Scripts

Script	Purpose	Key Output
`keyword_researcher.py`	Expand seed keywords, classify intent, cluster topics	Keyword list with volume, KD, intent, clusters
`keyword_gap_analyzer.py`	Find competitor keyword gaps	Gap keywords with opportunity scores
`base_client.py`	Shared utilities	RateLimiter, ConfigManager, BaseAsyncClient

Keyword Researcher

# Basic expansion
python scripts/keyword_researcher.py --keyword "dental implant" --json

# Korean market with suffix expansion
python scripts/keyword_researcher.py --keyword "치과 임플란트" --country kr --korean-suffixes --json

# With volume-by-country comparison
python scripts/keyword_researcher.py --keyword "dental implant" --country kr --compare-global --json

# Output to file
python scripts/keyword_researcher.py --keyword "치과 임플란트" --country kr --output report.json

Capabilities:

Seed keyword expansion (matching terms, related terms, search suggestions)
Korean suffix expansion (추천, 가격, 후기, 잘하는곳, 부작용, 전후)
Search intent classification (informational/navigational/commercial/transactional)
Keyword clustering into topic groups
Volume-by-country comparison (Korea vs global)
Keyword difficulty scoring

Keyword Gap Analyzer

# Find gaps vs one competitor
python scripts/keyword_gap_analyzer.py --target https://example.com --competitor https://competitor.com --json

# Multiple competitors
python scripts/keyword_gap_analyzer.py --target https://example.com --competitor https://comp1.com --competitor https://comp2.com --json

# Filter by minimum volume
python scripts/keyword_gap_analyzer.py --target https://example.com --competitor https://competitor.com --min-volume 100 --json

Capabilities:

Identify keywords competitors rank for but target doesn't
Opportunity scoring based on volume, KD, and competitor positions
Segment gaps by intent type
Prioritize low-KD high-volume opportunities

Data Sources

Source	Purpose
`our-seo-agent` CLI	Primary data source (future); use `--input` for pre-fetched JSON
WebSearch / WebFetch	Supplementary live data
Notion MCP	Save audit report to database

Output Format

All scripts support --json flag for structured output:

{
  "seed_keyword": "치과 임플란트",
  "country": "kr",
  "total_keywords": 150,
  "clusters": [
    {
      "topic": "임플란트 가격",
      "keywords": [...],
      "total_volume": 12000
    }
  ],
  "keywords": [
    {
      "keyword": "치과 임플란트 가격",
      "volume": 5400,
      "kd": 32,
      "cpc": 2.5,
      "intent": "commercial",
      "cluster": "임플란트 가격"
    }
  ],
  "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	Keyword Research
Priority	Select	Based on opportunity score
Found Date	Date	Research date (YYYY-MM-DD)
Audit ID	Rich Text	Format: KW-YYYYMMDD-NNN

Language Guidelines

Report content in Korean (한국어)
Keep technical English terms as-is (e.g., Keyword Difficulty, Search Volume, CPC)
URLs and code remain unchanged

4.3 KiB Raw Blame History