145 lines
4.3 KiB
Markdown
145 lines
4.3 KiB
Markdown
# 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
|