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

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

# 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

# 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

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

4.3 KiB Raw Blame History