seo-headings-structure

seo-headings-structure (M7c)

ルートが1つの整理された見出しツリーと適切なセマンティックランドマークにより、ページのアウトラインが機械可読になります。これは、AI エンジンが回答ブロックを抽出し、検索エンジンがコンテンツの範囲を理解するために利用する構造と同じです。スキーマ／エンティティのコンテキストについては、references/schema-tier1.md を参照してください。

入力

ディスパッチエンベロープで指定された PageSnapshot を使用します。<run_dir>/pages/<slug>.json から parsed（region と landmarks を含む headings[]）を読み取り、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. H1 が1つであること：ページごとに <h1> がちょうど1つである必要があります。H1 が0個の場合も、複数ある場合も検出結果として報告します。
2. レベルを飛ばさないこと：入れ子は1レベルずつ深くなる必要があります（<h2> の後に続けられるのは <h3> であり、<h4> に直接飛ぶことはできません）。アウトラインを構築し、レベルの飛び越しを検出します。
3. 説明的なテキスト：各見出しは、人が理解できる表現でセクションの内容を示す必要があります。空の見出し、視覚的な装飾だけに使われている見出し、汎用的なプレースホルダー（「Section 1」「Welcome」）を検出します。
4. セマンティックランドマーク：<main>、<article>、<section>、<nav>、<header>、<footer> を検出します。見出しがセマンティックではない <div> ばかりの構造内にある場合、または <main> が複数ある場合は検出結果として報告します。
5. アウトラインとランドマークの整合性：セクショニング要素には、それぞれに対応する見出しが必要です。孤立したランドマークや、どのランドマーク内にもない見出しを検出結果として報告します。

適切な見出し構造は、AI による回答ブロックの抽出に役立ちます。明確な H2／H3 の区切りは、引用可能な候補箇所に対応します。

修正

• 見出しレベルの再構成 — レベルの飛び越しをなくす、または適切に入れ子にするために H2～H6 のレベルを変更します（修正可能：提案）。視覚的な階層が変わるため、項目ごとの承認が必要です。fix_preview の差分を出力し、自動書き込みは決して行わないでください。
• 不足している H1 を1つ追加 — ページに H1 がない場合、値が設定された <title>／og:title、または明らかなページタイトル要素を出典として H1 を提案します（修正可能：提案、項目ごとの承認が必要 — 表示される見出しの追加は編集上の判断を伴います）。内容が乏しい場合、H1 のテキストを捏造してはいけません。出典が曖昧な場合はユーザーに確認してください。
• セマンティックランドマークで囲む — <main>／<article> の採用を推奨することは助言です（このツールでは書き込まない構造的なリファクタリングです）。

各検出結果の fixable フィールドは、schema/finding.schema.json に従って（auto／proposed／advisory）設定してください。見出しのテキストを捏造したり、内容が乏しい状態で H1 を作り出したりしてはいけません。ユーザーに確認するか、明確に TODO と示したプレースホルダーを残してください。

検証

• 方法：dom_assert。スナップショットを再解析してアウトラインを再構築し、特定の条件（H1 が1つであること、レベルの飛び越しがないこと、ランドマークが存在すること）をアサートします。
• オフラインでの再現：node "${CLAUDE_PLUGIN_ROOT}/scripts/parse-html.mjs" --snapshot <pages/<slug>.json>（または --url <u>／--file <path>）。headings ブロック（各レベルの counts、h1_count、skipped_levels）を返します。このブロックは H1 の数を数え、H1～H6 のツリーをたどってレベルの飛び越しを確認します。
• レンダリング済み DOM の階層が必要なのに利用できない場合（見出しがクライアント側で挿入され、raw_html_path しか存在しない場合）、ステータスは needs_api とします。誤って pass にしてはいけません。

検出結果

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

• M7c.h1.multiple — ページ上に <h1> が複数ある（ステータス fail、重大度 3、fixable: proposed、軸 search、信頼度 established）。evidence.observed には各 H1 のテキストとセレクターを引用します。verification.reproduce は上記の parse-html.mjs コマンドです（h1_count を確認します）。
• M7c.outline.skipped_level — <h2> の直後に <h4> がある（ステータス fail、重大度 3、fixable: proposed、軸 search、信頼度 directional）。evidence.observed には隣接する2つの見出しとそのレベルを引用します。
• M7c.landmark.no_main — <main> 要素がなく、主要コンテンツが <div> 内にある（ステータス warn、重大度 3、fixable: advisory、軸 search、信頼度 directional）。

各検出結果には、ページからそのまま引用した evidence.observed と、実行可能な verification.reproduce が含まれます。expected_impact は、信頼度タグ付きの段階で示します（単独のパーセンテージは使いません）。

誠実さ

• 見出しでのキーワード詰め込みは検索順位の向上につながりません。読者のために見出しを書き、キーワード密度ではなく明確さを重視します。H1/H2 に用語を詰め込むことは推奨しないでください。
• H1 が複数あっても HTML5 では有効で、最新のパーサーや AI も許容します。実際の問題はアウトラインが不明瞭になることなので、重大な失敗ではなく重大度3の directional として扱います。見出しレベルの飛ばしは主にアクセシビリティ／構造上の問題です。順位向上を約束するのではなく、影響を誠実に（directional として）説明してください。