136 lines
4.3 KiB
Markdown
136 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```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
|
|
|
|
## 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:
|
|
|
|
```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
|