調査メモ: 「HTMLレポートを作るスキル」とは何か #
「HTMLレポートを作成するための Claude ないしはコーディングエージェント用の skill がほしい」と言われたときに、何を作ればよいかを考えた記録。レポートの種類の整理、配置の考え方、実在するスキルの分類、検証の設計の4つに分解して調べた。
問いの分解 #
- レポートとは何か(種類・目的・読者)
- 何を・どう書くか・どう配置するか(概念の探索)
- 見栄えの良い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ティア:
- 静的解析(クラス名・属性・リンク整合)— 速い・網羅的だがレンダリングを見ない
- レンダリング済みDOM計測(overflow・contrast・CLS)— 客観、人間工学の一部も拾う
- スクリーンショット目視/LLMレビュー — 人間工学の残り全部、コスト最大
スキルへの含意(仮説) #
- 「レポート」は一枚岩ではない。スキルは型の選択(読者×目的)を最初に問うべき。型ごとに構造の軸(BLUF/時系列/話題順)と適するコンポーネントが違う。
- 美しさの担保は2層: デザインシステム遵守(物理)+読者の問いへの配置(人間工学)。後者はコンポーネントカタログでは担保できないので、型ごとの「配置ガイダンス」が要る。
- 検証は生成と別工程にして、少なくともティア2(DOM計測のoverflow/contrast)までは自動で回すのが現実的。
今回作ったバリエーション #
上の整理を元に、テーゼ/アンチテーゼの対で選んで少しずつずらした5種類を dads-html で作った。
- 週次進捗報告(テーゼ): 上司向け・フォーマル・BLUF重視。DADSが最も素直にハマる型
- 個人の調査メモ(アンチテーゼ): 読者=未来の自分。フォーマルさを捨てて密度と索引性だけ残す
- 技術調査レポート(ずらし): 文脈を持たない読者向け。背景と用語の補足が構造を支配する
- インシデント報告(ずらし): 時系列が軸。事実と推定の分離が構造に出る
- 意思決定依頼(ずらし): 1画面で判断できる密度。選択肢比較表が主役