# CLAUDE.md

## Overview

Position tracking tool for monitoring keyword rankings. Monitors ranking positions, detects position changes with threshold alerts, calculates visibility scores weighted by search volume, compares against competitors, and segments by brand/non-brand keywords.

## Quick Start

```bash
pip install -r scripts/requirements.txt

# Track positions for a project
python scripts/position_tracker.py --target https://example.com --json

# Generate ranking report
python scripts/ranking_reporter.py --target https://example.com --period 30 --json
```

## Scripts

| Script | Purpose | Key Output |
|--------|---------|------------|
| `position_tracker.py` | Monitor keyword ranking positions and detect changes | Position data, change alerts, visibility scores |
| `ranking_reporter.py` | Generate ranking performance reports with trends | Trend analysis, segment reports, competitor comparison |
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |

## Position Tracker

```bash
# Get current positions
python scripts/position_tracker.py --target https://example.com --json

# With change threshold alerts (flag positions that moved +-5 or more)
python scripts/position_tracker.py --target https://example.com --threshold 5 --json

# Filter by keyword segment
python scripts/position_tracker.py --target https://example.com --segment brand --json

# Compare with competitors
python scripts/position_tracker.py --target https://example.com --competitor https://comp1.com --json
```

**Capabilities**:
- Current ranking position retrieval via our-seo-agent CLI or pre-fetched data
- Position change detection with configurable threshold alerts
- Visibility score calculation (weighted by search volume)
- Brand vs non-brand keyword segmentation
- Competitor rank comparison
- Keyword segment grouping (by intent, cluster, landing page)

## Ranking Reporter

```bash
# 30-day ranking report
python scripts/ranking_reporter.py --target https://example.com --period 30 --json

# Quarterly comparison
python scripts/ranking_reporter.py --target https://example.com --period 90 --json

# Export with competitor comparison
python scripts/ranking_reporter.py --target https://example.com --competitor https://comp1.com --period 30 --json
```

**Capabilities**:
- Period-over-period ranking trends (improved/declined/stable)
- Top movers (biggest position gains/losses)
- Visibility score trend over time
- Segment-level performance breakdown
- Competitor overlap and position comparison
- Average position by keyword group

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

```json
{
  "target": "https://example.com",
  "total_keywords": 250,
  "visibility_score": 68.5,
  "positions": {
    "top3": 15,
    "top10": 48,
    "top20": 92,
    "top50": 180,
    "top100": 230
  },
  "changes": {
    "improved": 45,
    "declined": 30,
    "stable": 155,
    "new": 12,
    "lost": 8
  },
  "alerts": [
    {
      "keyword": "치과 임플란트 가격",
      "old_position": 5,
      "new_position": 15,
      "change": -10,
      "volume": 5400
    }
  ],
  "segments": {
    "brand": {"keywords": 30, "avg_position": 2.1},
    "non_brand": {"keywords": 220, "avg_position": 24.5}
  },
  "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 | Tracked website URL |
| Category | Select | Position Tracking |
| Priority | Select | Based on visibility trend |
| Found Date | Date | Tracking date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: RANK-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., Visibility Score, SERP, Rank Tracker)
- URLs and code remain unchanged