調査メモ: 「HTMLレポートを作るスキル」とは何か #

「HTMLレポートを作成するための Claude ないしはコーディングエージェント用の skill がほしい」と言われたときに、何を作ればよいかを考えた記録。レポートの種類の整理、配置の考え方、実在するスキルの分類、検証の設計の4つに分解して調べた。

問いの分解 #

  1. レポートとは何か(種類・目的・読者)
  2. 何を・どう書くか・どう配置するか(概念の探索)
  3. 見栄えの良いHTMLを生成・検証するには(物理的な破綻と人間工学的破綻)

レポートとは何か #

レポートは「読者の問いに、構造化して答える文書」。分類軸を先に決めると種類が整理できる。

  • 読者: 未来の自分 / 直属の上司 / 組織内の同僚 / 文脈を持たない別部署 / 社外(クライアント・公開)
  • 目的: 共有(知らせる) / 判断材料(決めてもらう) / 説得(動いてもらう) / 記録(後で辿る) / 学習(書くこと自体が目的)
  • 寿命: 定期(日報・週報) / 都度(調査・障害報告) / 単発(研究レポート)
  • 形式度: フォーマル(定型セクション・証跡) / インフォーマル(メモ)

軸の組み合わせで代表的な型が出る。

型読者目的構造の軸
週次進捗報告上司共有BLUF → 進捗/課題/次手
意思決定依頼上司・会議体判断材料結論 → 選択肢比較 → 推薦
技術調査レポート別部署・未来の誰か共有・記録背景 → 方法 → 結果 → 限界
インシデント報告関係者全般記録・説明時系列 → 影響 → 原因 → 再発防止
研究・サーベイ専門読者共有問い → 先行 → 結果 → 考察
個人の備忘録未来の自分記録・学習索引性(日付・タグ・検索)
理解のための草稿今の自分学習完成度不要、書くこと自体が目的

ビジネス文書の教科書的な分類でも informal/formal の2分が基本で、informal は「10ページ未満・簡素な見出し・memo/letter/web post形式」、formal は「構造化・包括的・引用と図表を持つ」とされる(biz.libretexts.org "Types of Reports"ほか)。日本の報告書文化では営業/業務/会計/リスク/研修/企画など目的別に分かれる(カオナビ人事用語集など)。

何を・どう書くか・どう配置するか #

何を書くかは読者との情報差分で決まる。上司なら「自分が判断に使う差分」だけ。別部署なら背景と用語から。自分用なら「なぜそうしたか」の文脈こそが価値で、結果は自明。

どう書くかの共通原則:

  • BLUF(Bottom Line Up Front): 結論・状態を先に。忙しい読者は最初の1画面しか読まない前提で組む。
  • 事実と推定の分離: 特にインシデント報告で致命的。観測したこと・仮説・未確認を分ける。
  • 次のアクション: 報告は指示書ではないが「次に何が起きるか」がないと読後感が宙に浮く。

どう配置するかは構造の軸:

  • 重要度順(ピラミッド/逆三角形): 進捗・意思決定系。結論→根拠→詳細。
  • 時系列: インシデント・作業ログ。再現性と因果の追跡に向く。
  • 話題順: 調査・共有系。TOCが重要になる(読者は興味の節だけ読む)。
  • 配置の物理: 冒頭にメタ(誰が・いつ・何について・状態バッジ)、表は比較にだけ使う。

見栄えの良いHTMLを生成するスキル #

実在のアプローチは4系統に分かれた。

  • テンプレート+スロット充填: Claude Code bundled skill の artifact-report。serif・masthead・TOC・appendix の長文レポート用HTMLテンプレートにプレースホルダを埋める。充填後のセルフチェック(残存マーカー、TOC→id整合)まで手順に含む。
  • コンポーネントカタログ+正本参照: dads-html。デジタル庁デザインシステムのCSS/カスタム要素を、使ったクラスから自動収集して単一HTMLにインライン化。不明な dads-* クラスはビルド時警告=タイポ検出が組み込み済み。
  • スキャフォールド+バンドル: web-artifacts-builder。React+Tailwind+shadcn/ui のプロジェクトを生成→Parcelで単一HTMLへ。重いがインタラクティブ性が上がる。
  • 美的ガイダンス: Anthropic の frontend-design 系の文脈。「ガイダンスなしだとInter+紫グラデ+白背景に収束する」(distributional convergence=いわゆるAI slop look)。タイポグラフィ・色・モーション・背景の4軸で「避けるべき既定値」と「寄せ先」を指示する方式。

観察: 「構造の正しさ」(テンプレート/コンポーネント系)と「見た目の固有さ」(ガイダンス系)は別レイヤー。デザインシステム系スキルは固有さを「製品らしさ」で解決する(DADSなら行政っぽさがむしろ正解)。

検証の仕組み — 物理的破綻と人間工学的破綻 #

物理的破綻(機械的に検出可能):

  • CSS/JSの欠落、不明クラス名(ビルドスクリプトの警告で検出)
  • 横スクロール・要素のはみ出し: headless Chromium で scrollWidth > clientWidth
  • カスタム要素の未登録、コンソールエラー
  • TOC/アンカーのリンク切れ(HTMLパーサで検査可能)
  • スクリーンショット差分(VRT)。DADS本体も複数reset CSSでのVRTをCIに持つ
  • 印刷時の破綻(レポートは印刷されうるので @media print 確認)

人間工学的破綻(見た目は整っているが読み物として失敗):

  • BLUFがない・情報階層が読者の問いに合わない
  • 色が意味を担っていない装飾、"AI slop"感のある無個性な配色・フォント
  • 行長が長すぎる、表の密度と可読性のトレードオフ
  • コントラスト不足・タッチターゲット不足(ここは一部axe等で計測可)

対応の実例: 複数ビューポート(1280/768/390)でheadlessレンダリング→スクリーンショットをLLMレビュアに戻して反復するループ(unicef/adt-studio)、axe+overflow+CLS+landmarkを実DOMで計測してgateする design-review スクリプト(aa-on-ai/agentic-design-system)、スコア化してfix-listをエージェントに返す verdict のような「閉ループ計測器」の試み(pranavkokati/verdict)。

整理すると検証は3ティア:

  1. 静的解析(クラス名・属性・リンク整合)— 速い・網羅的だがレンダリングを見ない
  2. レンダリング済みDOM計測(overflow・contrast・CLS)— 客観、人間工学の一部も拾う
  3. スクリーンショット目視/LLMレビュー — 人間工学の残り全部、コスト最大

スキルへの含意(仮説) #

  • 「レポート」は一枚岩ではない。スキルは型の選択(読者×目的)を最初に問うべき。型ごとに構造の軸(BLUF/時系列/話題順)と適するコンポーネントが違う。
  • 美しさの担保は2層: デザインシステム遵守(物理)+読者の問いへの配置(人間工学)。後者はコンポーネントカタログでは担保できないので、型ごとの「配置ガイダンス」が要る。
  • 検証は生成と別工程にして、少なくともティア2(DOM計測のoverflow/contrast)までは自動で回すのが現実的。

今回作ったバリエーション #

上の整理を元に、テーゼ/アンチテーゼの対で選んで少しずつずらした5種類を dads-html で作った。

  • 週次進捗報告(テーゼ): 上司向け・フォーマル・BLUF重視。DADSが最も素直にハマる型
  • 個人の調査メモ(アンチテーゼ): 読者=未来の自分。フォーマルさを捨てて密度と索引性だけ残す
  • 技術調査レポート(ずらし): 文脈を持たない読者向け。背景と用語の補足が構造を支配する
  • インシデント報告(ずらし): 時系列が軸。事実と推定の分離が構造に出る
  • 意思決定依頼(ずらし): 1画面で判断できる密度。選択肢比較表が主役