spec-to-readable-html

仕様書を読みやすい HTML に変換

このスキルは、仕様書を洗練された読みやすい HTML レポートに変換します。単なる Markdown レンダラーではありません。ソースを分析し、必要に応じて要約し、内容を理解しやすいように再構成し、文書を明確にする視覚的な補助を追加します。

呼び出し時に、$lang で出力言語を設定します（デフォルト：ja）。省略した場合は、日本語が使用されます。

このスキルを使用する場面

ユーザーから次のような依頼があった場合に、このスキルを使用します。

• 仕様書、要件定義書、設計書、API 仕様書、PRD、RFC、技術文書を HTML に変換する
• Markdown 仕様書を人が読みやすい形にする
• 文書に要約、図、グラフ、スクリーンショット、アイコン、視覚的な解説を追加する
• 詳細な要件を読みやすい Web ページやレポートにまとめる
• 仕様書からエグゼクティブサマリー、実装概要、API マップ、ワークフロー、アーキテクチャ図、意思決定の要約を作成する

ユーザーが忠実な変換を明示的に依頼していない限り、単純な Markdown から HTML への変換として扱わないでください。

基本原則

1. 単なる書式設定ではなく、理解しやすさを高める

   • 長いセクションを要約します。
   • 関連する情報をグループ化します。
   • 重要な意思決定、リスク、依存関係、未解決の質問を明確に示します。

2. 追跡可能性を保つ

   • 意味を暗黙のうちに変えないでください。
   • 推測した内容には Inferred または Assumption と明記します。
   • 可能な場合は、元のセクション名へのリンクまたは参照を付けます。

3. 役立つ場合にのみ視覚表現を使用する

   • フロー、関係性、アーキテクチャ、状態遷移、タイムライン、データモデルには図を追加します。
   • 元の内容に比較可能な数量、優先度、タイムライン、ステータス、カテゴリが含まれている場合にのみ、グラフを追加します。
   • 定量的なデータを捏造しないでください。

4. 出力をポータブルにする

   • CSS を埋め込んだ、単一のポータブルな HTML ファイルを優先します。
   • 基本テンプレートでは、Mermaid 図に Mermaid CDN をデフォルトで使用します。
   • Mermaid を使用する場合は、フッターまたはコメントに Mermaid CDN への依存を記載します。
   • オフライン、ネットワーク不要、または完全に自己完結した出力をユーザーが希望する場合は、Mermaid 図をインライン SVG に置き換え、CDN を読み込まないようにします。
   • ユーザーが許可していない限り、追加の外部依存関係は避けます。

入力の取り扱い

次のいずれの入力も受け付けます。

• Markdown ファイル
• プレーンテキストの仕様書
• 関連する複数の仕様書ファイル
• API スキーマ／OpenAPI の一部
• README 形式の製品または技術に関するメモ
• 改善が必要な既存の HTML

HTML を作成する前に、次の項目を特定します。

• 文書の種類：PRD、API 仕様書、技術仕様書、設計書、運用ランブックなど
• 対象読者：ビジネス、エンジニアリング、QA、運用、または混合
• 主な要素：ユーザー、システム、API、画面、ジョブ、データモデル
• 主なプロセス：ワークフロー、シーケンス、状態遷移
• 曖昧な点、未決定事項、リスク

対象読者や詳細度が不明な場合は、妥当なデフォルトを設定します。

• 対象読者：プロダクトとエンジニアリングの混合
• 詳細度：読みやすく、実装も考慮した内容
• 出力：CSS を埋め込んだ単一のポータブルな HTML 文書。オフライン／ネットワーク不要の出力が求められていない限り、Mermaid 図では CDN を使用できます

推奨ワークフロー

1. ソースを読み、内容を整理する

   • タイトル、目的、対象範囲、背景、要件、フロー、API、データ、制約、リスク、未解決の質問を抽出します。

2. 読みやすい構成を作る

   • エグゼクティブサマリー
   • このドキュメントで扱う内容
   • 主要な概念／用語集
   • 主なワークフローまたはユーザージャーニー
   • 機能要件
   • 非機能要件
   • システム／API／データの概要
   • 図表
   • リスク、前提、未解決の質問
   • 付録：ソースに沿った詳細

3. 内容を取捨選択して要約する

   • 要件、API コントラクト、制約、受け入れ基準は正確な詳細を維持します。
   • 背景、動機、繰り返される説明、長い文章は要約します。
   • 重要な注記にはコールアウトを使用します。

4. 視覚資料を選ぶ

   • 以下の視覚資料の選択ガイドを使用します。
   • 環境とユーザーの希望に応じて、インライン SVG、Mermaid のソース、または画像ファイルで図を作成します。
   • 必ずキャプションと代替テキストを付けます。

5. 洗練された HTML を生成する

   • section、article、nav、table、figure、figcaption などのセマンティック HTML を使用します。
   • 長いドキュメントには、固定表示またはページ上部の目次を含めます。
   • 読みやすいタイポグラフィ、余白、コントラストを使用します。
   • 必要に応じて、印刷に適した CSS を含めます。

6. 出力を検証する

   • ソースの意味が維持されていることを確認します。
   • 前提が明記されていることを確認します。
   • 図表がソースと一致していることを確認します。
   • 依存関係を明示的に選択した場合を除き、HTML が単独で開けることを確認します。

視覚資料の選択ガイド

内容に応じて視覚資料を選びます。

ソースの内容	最適な視覚資料
段階的なビジネスプロセスまたはユーザープロセス	フローチャート
システム間の API 呼び出し	シーケンス図
システムのコンポーネントと依存関係	アーキテクチャ図
ステータスのライフサイクル	状態遷移図
エンティティと関係を示すテーブル	ER 図／関係マップ
マイルストーンまたは段階的なロールアウト	タイムライン
優先度、ステータス、カテゴリの件数	棒グラフ／積み上げグラフ
選択肢の比較	比較マトリックス
画面遷移	ユーザージャーニー／サイトマップ
長いセクションの構成	サマリーカード

推奨形式：

1. スタンドアロンの視覚的な図表には、特に完全に自己完結している場合やオフライン出力が必要な場合、インライン SVG を使用します。
2. ソースコードの読みやすさが重要な場合、アーキテクチャ図、フローチャート、シーケンス図、状態遷移図、ER 図には Mermaid を使用します。基本テンプレートでは、Mermaid は CDN に依存します。
3. 要約や比較には HTML/CSS のカードとテーブル を使用します。
4. ラスター画像 は、画像生成やスクリーンショットが明示的にリクエストされている場合、または利用可能な場合に限り使用します。

Mermaid を使用する場合は、後から編集できるよう、HTML または付録に Mermaid のソースを含めます。また、Mermaid がインライン SVG に事前レンダリングされていない場合は、CDN への依存を記載します。

HTML 出力要件

完全な HTML ファイルを生成する場合は、基本 HTML テンプレートとして references/template.html を、コンポーネントガイドとして references/html-output-template.md を使用します。テンプレートから <style> ブロック全体とセクション構成をコピーし、{{PLACEHOLDER}} トークンをソースから得た内容に置き換えます。

通常、HTML には以下を含めます。

• ドキュメントのタイトルと短いサブタイトル
• 生成日または判明している場合はソースのバージョン
• エグゼクティブサマリー
• 目次
• 重要なポイントをまとめたサマリーカード
• 簡潔な見出しを付けた主要セクション
• 要件、API、データフィールド、決定事項、リスク、未解決の質問を示すテーブル
• キャプション付きの視覚的な図表
• ソースの追跡可能性に関する注記
• 印刷に適したスタイル

詳細な技術仕様には、次のようなバッジを含めます。

• Must、Should、Could
• Confirmed、Inferred、Assumption、Open Question
• High Risk、Medium Risk、Low Risk

HTML の安全性とエスケープ

• ソース由来の文章、表のセルの内容、キャプション、メタデータ、プレースホルダーの置換内容は、デフォルトで信頼できないテキストとして扱ってください。
• 生成した安全なマークアップを意図的に出力する場合を除き、ソーステキストをテキストノードまたは属性に挿入する前に、&、<、>、"、'を HTML エスケープしてください。
• デフォルトでは、未加工のソース HTML をそのまま通過させないでください。限定的な HTML が必要な場合は、セマンティックタグと安全な属性の小規模な許可リストを使用してください。
• コードブロックとソースの抜粋は、<pre><code>または同等のコンテナ内でエスケープ済みテキストとして保持してください。
• ソースの内容を Mermaid のラベル内で使用する場合は、ユーザー提供の HTML、イベントハンドラー、javascript: URL がページに出力されないよう、ラベルを引用符で囲むかエスケープしてください。
• インライン SVG はエージェントが生成してもかまいませんが、ソースからコピーした SVG や HTML はサニタイズするか、安全な生成図に置き換えてください。

要約と推論に関するルール

• 要約したことを明示せずに、契約上または規範上の要件を削除してはなりません。
• MUST、SHOULD、SHALL、required、optional、deprecated などのキーワードは保持してください。
• ID、エンドポイントパス、フィールド名、ステータス名、列挙値、エラーコード、制限値は正確に保持してください。
• 図の解釈が必要な場合は、推論に基づく見解であることを明記してください。
• ソースが曖昧な場合は、推測せずに未解決の質問セクションを作成してください。

言語

出力言語はデフォルトで日本語（<html lang="ja">）です。ユーザーが別の言語を指定した場合は、見出し、バッジ、ラベル、本文のすべてにその言語を使用してください。技術用語（API 名、フィールド名、パス、コード識別子など）は、元の言語のまま保持してください。

品質チェックリスト

最終確定する前に、以下を確認してください。

• 出力は単なる変換ではなく、ソースより読みやすくなっています。
• 重要な要件と制約が保持されています。
• 要約によって意味が変わっていません。
• 図が正確で有用です。
• 推論に基づく内容と前提が明示されています。
• 構造化された詳細には表が使われています。
• HTML に目次があります。
• ファイルは単体で完結しているか、Mermaid CDN などの依存関係が記載されています。
• アクセシビリティの基本事項（見出し、コントラスト、代替テキスト／キャプション）が網羅されています。