Rimo Brand Guidelines Design Decision Records

DDR-0015

AI ファーストな情報構造（セマンティック HTML / JSON-LD / llms.txt）

Status

Accepted

Date

2026-03-25

Context

Issue #11912 で、ブランドガイドラインサイトを AI が読み取りやすい構造にする方針が議論された。Claude による回答として、以下のような情報構造の推奨が提示されている（同 Issue のコメント参照）。

  • セマンティック HTML（<main>, <article>, <section>, <header>）
  • JSON-LD による構造化データ（Schema.org CreativeWork / TechArticle）
  • <meta> タグでのコンテンツヒント（ai:content-type 等）
  • 代替フォーマット（JSON API）の提供
  • llms.txt の提供
  • セクション間の関連性を <a href="#anchor"> で明示

Decision

サイトは「人が見てもわかりやすく、AI が読み取っても誤解しない」情報構造を採用する。

採用する具体的な技術要素:

  1. セマンティック HTML: <main>, <article>, <section>, <header>, <dl> 等を意味的に使用
  2. JSON-LD: ページ全体と各セクションを Schema.org の CreativeWork / TechArticle でマークアップ
  3. メタデータ: <meta name="ai:*"> 系で AI 向けヒントを記載
  4. 代替フォーマット: ブランドデータを application/json で取得可能にする（例: /api/guidelines.json）
  5. llms.txt: ルートに配置し、AI に向けたサイト概要を記載
  6. アンカー / ARIA 属性: 各セクションに ID と aria-labelledby を付ける
  7. 「AI へコピー」ボタン: 各セクションの内容を構造化テキストとしてクリップボードに渡す UI

Alternatives Considered

  • 人向けのみ最適化: AI ファーストというコンセプトと矛盾する
  • JSON のみ提供（HTML を簡素化）: 人向けの体験が損なわれる

Consequences

  • Positive:
    • AI（Claude / ChatGPT 等）がページから正確に情報を抽出できる
    • SEO にもプラスに働く（リッチスニペット候補）
    • 「AI と働く」コンセプトの体現として象徴的
  • Negative:
    • 実装の複雑度が上がる（JSON-LD やメタデータの整合性維持）
    • コンテンツ更新時に複数フォーマット間の同期が必要
  • Implications:
    • サイトのコンテンツソースは構造化データ（YAML / JSON / MDX 等）にして、HTML と JSON を同時生成する設計が望ましい
    • 各コンポーネントは AI 向けヒント属性を出力する責務を持つ

Source

  • DDR-0008: ブランドガイドラインサイトを構築する
  • DDR-0012: AI 連携機能は Skill 提供を主、MCP を補とする
Copied!