seo-cluster

セマンティックトピッククラスタリング（v1.9.0）

共有データキャッシュ

ステップ 0 -- 共有データキャッシュを確認します：

情報を収集する前に、.seo-cache/ を確認し、関連する SEO スキルから再利用できるコンテキストがないか調べます。 スキーマと依存関係マップについては、../seo/references/shared-data-cache.md を参照してください。

以下のキャッシュファイルが存在する場合は確認します：

• .seo-cache/site-meta.json でドメイン、ビジネスタイプ、業界、クロールのコンテキストを確認します

• .seo-cache/audit-scores.json で以前のフル監査の優先事項を確認します

• URL が指定されている場合は、.seo-cache/pages/{url-slug}/page-analysis.json でページレベルのコンテキストを確認します

• 見つかった場合：明らかに有効なフィールドを解析して使用します（「[日付] のキャッシュ済み [X] を使用」と記録します）

• 見つからない場合、破損している場合、または関連性がない場合：新たなエビデンスを使って続行します

• ユーザーが「refresh」または「re-run」と指定した場合：キャッシュの読み取りを無視し、書き込み時に上書きします

テキストの類似性ではなく、Google が実際にランキングしている結果（上位 10 件に共通する結果）に基づく、SERP 重複主導のキーワードクラスタリングです。 内部リンクマトリックスを備えたハブ＆スポーク型のコンテンツクラスターを設計し、インタラクティブなクラスター マップのビジュアライゼーションを生成します。

スクリプト： プラグインルートの scripts/ ディレクトリにあります。

---

クイックリファレンス

コマンド	動作
/seo cluster plan <seed-keyword>	計画ワークフロー全体：拡張、クラスタリング、設計、ビジュアライゼーション
/seo cluster plan --from strategy	既存の /seo plan の出力をインポートします
/seo cluster execute	計画を実行します：codex-blog を使ってコンテンツを作成するか、ブリーフを出力します
/seo cluster map	インタラクティブなクラスターのビジュアライゼーションを再生成します

---

計画ワークフロー

ステップ 1：シードキーワードの拡張

WebSearch を使って、シードキーワードを 30～50 個のバリエーションに拡張します：

1. 関連検索 — シードを検索し、「関連検索」と「他のユーザーも検索したキーワード」を抽出します
2. People Also Ask（PAA） — SERP の結果から PAA の質問をすべて抽出します
3. ロングテール修飾語 — 一般的な修飾語を追加します：「best」、「how to」、「vs」、「for beginners」、「tools」、「examples」、「guide」、「template」、「mistakes」、「checklist」
4. 質問の抽出 — who／what／when／where／why／how のバリエーションを生成します
5. 検索意図の修飾語 — 商用の修飾語を追加します：「pricing」、「review」、「alternative」、「comparison」、「free」、「top」

重複の除去： バリエーションを正規化し（小文字に変換し、冠詞を削除）、完全に一致する重複を削除します。 目標：重複のないキーワードバリエーションを 30～50 個用意します。30 個未満の場合は、上位の PAA 質問をシードとして 2 回目の拡張を行います。

ステップ 2：SERP 重複クラスタリング

これが中核となる差別化要素です。完全なアルゴリズムについては、references/serp-overlap-methodology.md を読み込んでください。

プロセス：

1. 最初に推定した検索意図に基づいてキーワードをグループ化します（ペアごとの比較を減らします）
2. グループ内の候補ペアごとに、両方のキーワードを WebSearch で検索します
3. オーガニック検索結果の上位 10 件に共通する URL の数を数えます（広告、強調スニペット、PAA は除外します）
4. しきい値を適用します：

共通する検索結果	関係	対応
7-10	同じ記事	1 つの対象ページに統合します
4-6	同じクラスター	同じスポーククラスターの下にまとめます
2-3	相互リンク	隣接するクラスターに配置し、クロスリンクを追加します
0-1	別々	異なるクラスターに割り当てるか、除外します

最適化： キーワードが 40 個の場合、すべてのペアを比較すると 780 回になります。代わりに：

• 検索意図ごとに事前にグループ化します（約 10 個のグループ 4 つ = 4 x 45 = 180 回の比較）
• グループ境界をまたぐキーワードのみを相互確認します
• 両方が同じヘッドタームのロングテールバリエーションであるペアはスキップします（同じクラスターと見なします）

DataForSEO 連携： DataForSEO MCP が利用可能な場合は、SERP データの取得に WebSearch の代わりに serp_organic_live_advanced を使用します。各バッチの前に python scripts/dataforseo_costs.py check serp_organic_live_advanced --count N を実行します。 "status": "needs_approval" の場合は、費用の見積もりを表示してユーザーに確認を求めます。 "status": "blocked" の場合は、WebSearch に切り替えます。

Step 3: インテント分類

各キーワードを、以下の4つのインテントカテゴリのいずれかに分類します。

インテント	シグナル	クラスターに含めるか
情報収集型	how、what、why、guide、tutorial、learn	はい
商用型	best、top、review、comparison、vs、alternative	はい
取引型	buy、price、discount、coupon、order、sign up	はい
ナビゲーション型	ブランド名、特定の製品名、login	いいえ（除外）

ナビゲーション型のキーワードをクラスタリング対象から除外します。判断が難しいケースには、手動レビューのフラグを付けます。キーワードが複数のインテントを持つ場合もあります（例：「best CRM software」は商用型と情報収集型の両方）。優勢なインテントで分類します。

Step 4: ハブ＆スポーク型アーキテクチャ

完全な仕様については、references/hub-spoke-architecture.md を読み込みます。

クラスター構造を設計します。

1. ピラーキーワードを選択する — 検索ボリュームが最も多く、インテントが最も広く、他のキーワードとのSERP重複度が最も高いもの
2. スポークをクラスターに分類する — 各クラスターはサブトピック領域です（ピラーあたり2～5クラスター）
3. 投稿をクラスターに割り当てる — 各クラスターに2～4件のスポーク投稿を設定します
4. 投稿ごとにテンプレートを選択する — インテント分類に基づきます。

インテントのパターン	テンプレートの選択肢
情報収集型（広範）	ultimate-guide
情報収集型（方法）	how-to
情報収集型（リスト）	listicle
情報収集型（概念）	explainer
商用型（比較）	comparison
商用型（評価）	review
商用型（ランキング）	best-of
取引型	landing-page

5. 目標文字数を設定する：

   • ピラーページ：2500～4000語
   • スポーク投稿：1200～1800語

6. カニバリゼーションを確認する — 同じ主要キーワードを共有する投稿がないようにします。SERP重複度が7以上の場合、それらのキーワードを1つの投稿に統合し、両方をターゲットにします。

Step 5: 内部リンクマトリクス

双方向のリンク構造を設計します。

リンクの種類	方向	要件
スポークからピラー	spoke -> pillar	必須（すべてのスポーク）
ピラーからスポーク	pillar -> spoke	必須（すべてのスポーク）
スポーク間（クラスター内）	spoke <-> spoke	投稿あたり2～3リンク
クラスター間	spoke -> spoke（別のクラスター）	投稿あたり0～1リンク

ルール：

• すべての投稿に、最低3つの内部リンクからの流入が必要です
• 孤立ページを作らないでください（すべての投稿にピラーから2クリック以内で到達できるようにします）
• アンカーテキストには、ターゲットキーワードまたはその類義語を使用します（「ここをクリック」は不可）
• リンクは本文内に配置し、ナビゲーションやサイドバーだけに配置しないでください

リンクマトリクスをJSONの隣接リストとして生成します。

{
  "links": [
    { "from": "pillar", "to": "cluster-0-post-0", "type": "mandatory", "anchor": "keyword" },
    { "from": "cluster-0-post-0", "to": "pillar", "type": "mandatory", "anchor": "keyword" }
  ]
}

Step 6: インタラクティブなクラスターマップ

templates/cluster-map.html のテンプレートを使って、cluster-map.html を生成します。

1. テンプレートファイルを読み込みます
2. クラスタープランから CLUSTER_DATA JSONオブジェクトを作成します。

   {
     pillar: { title, keyword, volume, template, wordCount, url },
     clusters: [{ name, color, posts: [{ title, keyword, volume, template, wordCount, url, status }] }],
     links: [{ from, to, type }],
     meta: { totalPosts, totalClusters, totalLinks, estimatedWords }
   }
   

3. テンプレート内の CLUSTER_DATA プレースホルダーを、実際のJSONに置き換えます
4. 完成したHTMLファイルを出力ディレクトリに書き込みます
5. ユーザーに次のように伝えます：「ブラウザーで cluster-map.html を開くと、インタラクティブなクラスターマップを確認できます。」

---

戦略のインポート

--from strategy を指定して実行する場合：

1. 現在のディレクトリで最新の /seo plan の出力を探します（*SEO*Plan*、*strategy*、*content-strategy* に一致するファイルを検索します）
2. Markdownの表から、キーワード、ページ種別、コンテンツのピラー、URL構造を解析します
3. 抽出したデータを検証します：重複、キーワードの欠落、不完全なエントリーを確認します
4. SERPデータで情報を補完します：抽出したキーワードのSERP重複分析を実行します
5. インポートしたキーワードを初期セットとしてクラスタープランを作成します（Step 1はスキップします）

戦略ファイルが見つからない場合は、ユーザーに次のように促します：「現在のディレクトリに既存のSEOプランが見つかりません。まず /seo plan を実行するか、新しいクラスタリング用のシードキーワードを指定してください。」

---

実行ワークフロー

/seo cluster execute が実行された場合：

codex-blog の確認

Test: Does ~/.codex/skills/blog/SKILL.md exist?

codex-blog がインストールされている場合：

1. 完全なアルゴリズムについて references/execution-workflow.md を読み込みます
2. 現在のディレクトリから cluster-plan.json を読み込みます
3. 再開状態を確認します：出力ディレクトリをスキャンして、すでに書き込まれた記事を確認します
4. 優先順位に従って実行します：最初にピラー、次にボリュームの多い順にスポークを処理します
5. 各記事について、クラスターのコンテキストとともに blog-write スキルを呼び出します：
   • クラスター内の役割（ピラーまたはスポーク）
   • クラスター内の位置（クラスターのインデックス、記事のインデックス）
   • ターゲットキーワードと副次キーワード
   • テンプレートの種類と目標文字数
   • 含める内部リンク（アンカーテキスト付き）
   • 後続の記事からリンクを受け取る箇所（プレースホルダーマーカー）
6. 各記事の執筆後、以前の記事をスキャンして、後方リンクのプレースホルダーに 新しい記事の URL を挿入します
7. すべての記事の執筆後、クラスターのスコアカードを生成します

codex-blog がインストールされていない場合：

1. クラスタープラン内の各記事について、詳細なコンテンツブリーフを生成します
2. 各ブリーフには以下を含めます：
   • タイトルとメタディスクリプション
   • 主要キーワードと副次キーワード
   • テンプレートの種類と推奨構成（H2/H3 のアウトライン）
   • 目標文字数
   • 含める内部リンク（アンカーテキスト付き）
   • 取り上げるべき重要なポイント
   • 差別化する競合ページ
3. ブリーフを個別の Markdown ファイルとして cluster-briefs/ ディレクトリに書き込みます
4. ユーザーに次のように伝えます：「コンテンツを自動作成するには、codex-blog をインストールしてください。ブリーフは cluster-briefs/ に保存しました。」

---

クラスタースコアカード

実行後の品質レポートです。/seo cluster execute の実行後に自動で実行するか、 出力ディレクトリの分析を通じてオンデマンドで実行します。

指標	目標	測定方法
網羅率	100%	執筆済み記事数 / 計画記事数
リンク密度	記事あたり 3 件以上	記事ごとの内部リンク数をカウント
孤立ページ	0	被リンクが 1 件未満の記事
カニバリゼーション	競合 0 件	主要キーワードの重複を確認
画像数	記事あたり 1 件以上	画像が少なくとも 1 枚ある記事
ピラーリンク	100%	すべてのスポークがピラーにリンクし、その逆も成立
クロスリンク	80% 以上	推奨されるスポーク間リンクの実装率
コンテンツギャップ	0	スキップされた、または未完了の計画記事数

---

マップの再生成

/seo cluster map が呼び出された場合：

1. 現在のディレクトリから cluster-plan.json を読み込みます
2. 出力ディレクトリをスキャンし、記事のステータスを更新します（計画済み／執筆済み）
3. ステータスを更新した cluster-map.html を再生成します
4. 執筆済み記事数と計画記事数、リンク完了率を報告します

---

出力ファイル

すべての出力は現在の作業ディレクトリに書き込まれます：

ファイル	説明
cluster-plan.json	機械可読なクラスタープラン（全データ）
cluster-plan.md	人が読めるクラスタープランの概要
cluster-map.html	インタラクティブな SVG ビジュアライゼーション
cluster-briefs/	コンテンツブリーフ（codex-blog がない場合）
cluster-scorecard.md	実行後の品質レポート

---

スキル間の連携

スキル	関係
seo-plan	インポート元：戦略のインポートで seo-plan の出力を読み込みます
seo-content	品質チェック：生成コンテンツの E-E-A-T 検証
seo-schema	スキーママークアップ：クラスターのページに Article、BreadcrumbList、ItemList を適用
seo-dataforseo	データソース：DataForSEO MCP が利用可能な場合の SERP データ
seo-google	レポート：クラスタープランとスコアカードの PDF レポートを生成

クラスターの計画または実行が完了した後、次のように案内します： 「PDF レポートを生成しますか？ /seo google report を使用してください」

---

エラー処理

エラー	原因	解決方法
"No seed keyword provided"	引数がありません	シードキーワードまたは URL をユーザーに尋ねます
"Insufficient keyword variants"	拡張で得られたキーワードが 15 個未満です	PAA の質問を使って 2 回目の拡張を実行します
"SERP data unavailable"	WebSearch と DataForSEO の両方で障害が発生しています	30 秒後に再試行します。問題が続く場合は、警告を添えてインテントのみでクラスタリングします
"No strategy file found"	--from strategy が指定されていますが、計画がありません	まず /seo plan を実行するようユーザーに促します
"cluster-plan.json not found"	計画せずに実行しようとしています	まず /seo cluster plan を実行するようユーザーに促します
"codex-blog not installed"	ブログスキルなしで実行しようとしています	代わりにコンテンツ概要を生成し、インストールを提案します
"DataForSEO budget exceeded"	コストチェックの結果が "blocked" でした	WebSearch に切り替え、ユーザーに伝えます
"Duplicate primary keywords"	カニバリゼーションが検出されました	該当する投稿を統合するか、キーワードを再割り当てします
"Orphan page detected"	投稿に流入リンクがありません	同じクラスター内で最も近いページからリンクを追加します
"Resume state corrupted"	計画と出力が一致しません	出力ディレクトリをスキャンして状態を再構築します

---

セキュリティ

• すべての URL は python scripts/fetch_page.py を介して取得します（validate_url() による SSRF 対策）
• 認証情報は保存も送信もしません
• 出力ファイルに PII や API キーは含まれません
• すべての API 呼び出しの前に DataForSEO のコストチェックを実行します

FLOW フレームワークとの統合

プロンプトに沿ったキーワード調査とギャップ分析には、/seo flow find [url|topic] を使用します。FLOW の 5 つの find ステージのプロンプトは、構造化された発見プロンプトにより、SERP の重複に基づくクラスタリング手法を補完します。

共有データキャッシュへの書き込み

すべての作業が完了した後、ワークフローで永続的な知見が得られた場合は、.seo-cache/ に簡潔な JSON サマリーを書き込みます。 ../seo/references/shared-data-cache.md のスキーマと命名規則を使用し、少なくとも cache_type、analyzed_at、ソース URL／ドメイン、主な知見、問題点、推奨事項、ツールの制限事項を含めます。.seo-cache/ が .gitignore にない場合は追加します。