# CLAUDE.md

## Overview

Keyword strategy and research tool for SEO campaigns. Expands seed keywords via Ahrefs APIs, classifies search intent, clusters topics, performs competitor keyword gap analysis, and supports Korean market keyword discovery including Naver autocomplete.

## Quick Start

```bash
# 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

```bash
# 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

```bash
# 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

## Ahrefs MCP Tools Used

| Tool | Purpose |
|------|---------|
| `keywords-explorer-overview` | Get keyword metrics (volume, KD, CPC) |
| `keywords-explorer-matching-terms` | Find matching keyword variations |
| `keywords-explorer-related-terms` | Discover semantically related keywords |
| `keywords-explorer-search-suggestions` | Get autocomplete suggestions |
| `keywords-explorer-volume-by-country` | Compare volume across countries |
| `keywords-explorer-volume-history` | Track volume trends over time |
| `site-explorer-organic-keywords` | Get competitor keyword rankings |

## Output Format

All scripts support `--json` flag for structured output:

```json
{
  "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