logo hsb.horse

Architecture Decision Record

SEO/メタデータおよびAIO最適化方針

title/description、canonical/hreflang、OGP/Twitter、構造化データの出力を統一し、検索結果とAI要約の再利用性を高める。

採用 #seo #metadata #aio #structured-data #i18n

他の言語

ドイツ語 英語 フランス語 韓国語 ポルトガル語

SEO/メタデータおよびAIO最適化方針

Decision

  • メタデータ出力は「ページごとのバラバラ実装」を禁止し、共通レイヤー（Layout 配下の専用ヘッド責務）に集約する。
  • インデックス対象ページは、title / description / canonical / hreflang / og:url を相互に矛盾させない。
  • OGP/Twitterカードは、共有可能ページで必須とし、絶対URLの画像を使用する。
  • noindex は「意図的に検索結果へ出さないページ」のみで使用し、sitemap掲載有無と整合させる。
  • AIO（AI Overview 等）対策は、専用ハックを導入せず、構造化データと一次情報の明瞭さで対応する。

メタデータの必須項目と規約

項目規約
title全ページ必須。形式は原則 `{ページ固有タイトル}
description全ページ必須。平文で簡潔に記述し、本文要約と矛盾させない。
canonical絶対URL必須。クエリ・ハッシュを含めず、インデックスしたい正規URLを指す。
robots公開ページは index,follow,max-image-preview:large を標準。
og:urlcanonical と同一値を必須にする。

canonical / hreflang 運用

  • hreflang は「実在する翻訳ページのみ」出力する。
  • x-default はデフォルト言語（ja）の代表URLを使用する。
  • 翻訳が存在しない言語の hreflang は出力しない。
  • 各言語ページの canonical は、その言語ページ自身を指す（他言語canonical禁止）。

OGP / Twitterカード

  • 共有可能ページは以下を必須とする。
    • og:type（ページ特性に応じて website または article）
    • og:title
    • og:description
    • og:url
    • og:image（絶対URL）
    • og:image:alt
    • twitter:card（summary_large_image）
    • twitter:title
    • twitter:description
    • twitter:image
  • OGP画像が未指定の場合に備えて、サイト共通デフォルト画像は /brand/og.jpg を使用する（画像実体は後続タスクで配置）。

noindex / sitemap 連携

  • noindex: true のページは meta robots を noindex,nofollow とし、sitemapから除外する。
  • 本番公開しない検証環境URL（workers.dev 等）には X-Robots-Tag: noindex を維持する。
  • draft と noindex は意味を分離する。
    • draft: そもそも公開対象外
    • noindex: 公開はするが検索結果には載せない

構造化データ（AIO対応の中核）

  • 既存の Person / BreadcrumbList は維持する。
  • ページ種別ごとに以下を追加運用する。
    • 記事詳細（ブログ、リリースノート、ADR）: Article（必要に応じて TechArticle）
    • 一覧ページ（changelog, tools等）: CollectionPage
    • About: ProfilePage
  • JSON-LDは実際に表示される内容のみを記述し、架空の評価・数値・実績を記載しない。

AIO向けコンテンツ原則

  • AIO専用の隠し文言は作らず、本文先頭に「要点が短く分かる導入」を必ず置く。
  • 見出し階層を壊さず、1ページ1トピックを原則とする。
  • 用語・定義・手順はページ内で自己完結させ、外部リンク前提の説明を減らす。

Context

現状の実装では title / description / canonical / hreflang は一定整備されているが、以下が未統一または不足している。

  • OGP/Twitterカードの共通出力仕様
  • noindex と sitemap の運用ルール
  • ページ種別ごとのJSON-LD方針
  • 「検索結果向け」と「AI要約向け」を同時に満たす執筆・構造基準

多言語構成（ja をデフォルト、他言語はプレフィックス）を維持したまま、検索エンジンとAIクローラの双方で再利用されやすい情報設計が必要だった。

Options

  • Option A: ページごとに個別実装を続ける
  • Option B: 最小限タグ（title/description/canonicalのみ）に限定する
  • Option C: 共通規約を定義し、メタデータと構造化データを一元運用する（採用）

Rationale

  • 整合性: canonical/hreflang/og:url の不整合を防げる。
  • 運用性: 新規ページ追加時に必要項目の抜け漏れを防止できる。
  • 再利用性: 検索結果、SNSカード、AI要約で同じ一次情報を再利用しやすい。
  • 将来拡張: OGP自動生成やメタデータ検証スクリプトを段階導入しやすい。

Consequences

  • 実装タスクとして、共通SEOヘッド責務の導入（または Layout の責務拡張）が必要になる。
  • Content Collectionスキーマに ogImage / noindex 等のSEO項目を統一的に定義する必要がある。
  • CIで「必須メタタグ欠落」「canonical/hreflang矛盾」「noindexページのsitemap混入」を検知するチェックを追加する。
  • 成功基準は以下とする。
    • インデックス対象ページの必須メタ項目充足率 100%
    • canonical と og:url の一致率 100%
    • 構造化データ検証エラー 0 件