seo-internal-linking

seo-internal-linking（M10）

内部リンクはクロールの優先度とトピックの権威性を分散させ、ページ同士の関係を検索エンジン（および AI クローラー）に伝えます。参照先：このトポロジーが反映すべきエンティティ／@id の関連付けについては references/schema-tier1.md を参照してください。外部の sameAs は M6/seo-entity-linking が担当します。

入力

ディスパッチエンベロープで指定された PageSnapshot を使用してください。<run_dir>/pages/<slug>.json から parsed（region／internal／anchor を含む anchors[]、landmarks）を読み取り、<run_dir>/crawl.json からクロールグラフ（graph.edges、pages[].inlinks、templates[]）を読み取ります。逐語的な根拠については pages/<slug>.html を Grep してください。サイトのアーティファクトは <run_dir>/site/{robots.json,sitemaps.json,discovery.json} にあります。audit.mjs がすでに出力した決定論的な指摘は <run_dir>/findings.deterministic.json に記載されています。これらの ID は再出力せず、モデルの判定が必要な指摘のみを追加してください。スナップショットがなく、URL／パスを指定して直接呼び出された場合は、まず node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs" を実行し、出力されたスナップショットパスを使用してください。

監査

PageSnapshot（render.used が none でない場合は parsed_rendered、そうでない場合は parsed）を使用して、次の項目を監査します。

1. ピラー／クラスターのトポロジー：各 URL を分類（ピラーハブかクラスターのページか）し、クラスターの各ページからピラーへ、またピラーからクラスターへリンクしていることを確認します。リンクの欠落はハブアンドスポークモデルを崩します。
2. 本文内のコンテキストリンク：<main>／<article> 内の本文にあるリンク数を数えます（ページあたり、内容に即した本文内リンクを約 3～5 件にすることを目標とします）。本文内の内部リンクがゼロのページを指摘します。
3. アンカーテキストの具体性：一般的なアンカー（「ここをクリック」、「続きを読む」、「詳細を見る」、URL のみ）や、完全一致の過剰な繰り返しを指摘します。アンカーにはリンク先の内容を記述する必要があります。
4. 孤立ページ：サイトマップ／クロールにある URL のうち、クロールされた他のページからの内部リンクがないものを列挙します。
5. ナビゲーションと本文内リンクの比率：テンプレート内で定型的なナビゲーション／フッターリンクがコンテキストリンクを圧倒し、ページごとのリンクシグナルを弱めている場合は指摘します。
6. セマンティック HTML：<main>、<article>、<nav>、<header>、<footer>、<h1> が 1 つだけあること、見出しの順序が論理的であることを確認します。セマンティックな構造は、パーサーとアクセシビリティの両方に役立ちます。

修正

• 提案（fixable: proposed）：内部リンクの具体的な追加案です。リンク元ページ、リンク先 URL、推奨アンカーテキスト、リンクを付ける文またはセレクターを指定し、fix 用の統合差分として出力します。本文リンクの自動挿入は意味、文調、読み進め方を変える可能性があるため、項目ごとの承認が必要です。
• 助言（fixable: advisory）：コンテンツをセマンティックタグ（<main>／<article>／<nav>）で囲むことや、見出し順序の修正について説明します。テンプレート構造に関わるため、ツールが書き換えることはありません。
• スナップショット／クロールで確認できないリンク先 URL、アンカー文言、トポロジーを決して作り出さないでください。ユーザーに確認するか、TODO と明記したプレースホルダーを残してください。（このモジュールの指摘の重大度：3。）

検証

• ページごと：node "${CLAUDE_PLUGIN_ROOT}/scripts/link-graph.mjs" --snapshot <pages/<slug>.json>（または --url <u>／--file <path> --base <origin>）を実行すると、そのページのリンクプロファイル（verification.method: link_graph）が返されます。項目は total_links、internal_unique、external_unique、in_content_target、generic_anchors、empty_anchors、dropped です。1 ページだけからトポロジーを計算することはありません。
• サイトのトポロジー：<run_dir>/crawl.json（graph.edges、pages[].inlinks、templates[]）を読み取ります。クロール時にすでに構築されています。--crawl [--max 25] [--max-depth 3] [--no-robots] [--ua <preset>] を実行すると、同一サイト内の浅いクロールを新たに実行し、potential_orphans を含む crawl ブロックが追加されます（クロールしたページのうち、別のクロール済みページから内部リンクを受けていないページを指します。開始ページは該当せず、スクリプト自体もこの一覧は確定的なものではないとしています）。ピラー／クラスターの判定は、これらのエッジを基にモデルが行うものであり、スクリプトの出力ではありません。
• トポロジー全体と孤立ページの確認には、サイト全体を対象とするクロール階層が必要です。そのクロールデータを利用できない場合、ステータスは needs_api となり、誤って pass と判定することはありません。

検出結果

schema/finding.schema.json に従って検出結果を出力します。例：

• M10.contextual.too_few_inbody_links — 本文内の文脈に沿ったリンクが約3つ未満です（ステータス warn、重要度 3、fixable: proposed、軸 search、信頼度 directional）。
• M10.anchor.generic_text — アンカーテキストが「こちらをクリック」「続きを読む」などです（ステータス warn、重要度 3、fixable: proposed、軸 search、信頼度 directional）。
• M10.orphan.no_incoming_links — クロール結果に、ページへの内部リンクがありません（ステータス fail、重要度 3、fixable: advisory、軸 search、信頼度 established）。
• M10.semantic.missing_main — 主要コンテンツを囲む <main>／<article> ランドマークがありません（ステータス warn、重要度 3、fixable: advisory、軸 search、信頼度 directional）。 各検出結果では、evidence.observed にページから引用した内容（アンカーテキスト、リンク数、問題のある要素）を記載します。verification.reproduce には上記の実行可能な link-graph.mjs コマンドを記載します。expected_impact は、信頼度のタグを付けた範囲で示します（単独のパーセンテージは記載しません）。

誠実さ

• 「1 ページあたりリンク3～5件」という固定値は、ユーザビリティ／構造上のヒューリスティックであり、検索順位の法則ではありません。件数は目安として扱い、件数だけを理由にスコアに上限を設けないでください。
• 完全一致のアンカーテキストを詰め込むことや、「リンクが多いほど権威性が高い」という考えは誤りです。生の件数より関連性や編集上の文脈が重要であり、過剰なリンクは不自然に見えることがあります。読者にとって本当に役立つ場合にのみ、リンクを推奨してください。