ntaksh42 html-report
会話で出したレビュー・調査・バグ解析などの結果を、読みやすい HTML レポートとして保存する。
ターミナルの平文は、指摘が 10 件並んだり比較軸が 3 つ以上あると急に読みづらくなる。このスキルは、そういう「構造を持つ長い成果物」を一覧できる形に変えるためにある。
進め方
本文を Markdown で書き、スクリプトに渡す。HTML の組み立て・番号採番・保存先解決はスクリプトが行うので、中身の執筆に集中する。
1. 種別を判定
2. 本文を Markdown で書く（一時ファイルへ）
3. New-HtmlReport.ps1 を実行
Step 1: 種別を判定
会話の内容から選ぶ。判断に迷ったら investigation。
| 種別 | 対象 | 色 |
|---|---|---|
review |
コードレビュー、PR レビュー | 青 |
bug |
バグ調査、不具合解析 | 赤 |
investigation |
コード調査、動作調査 | 紫 |
research |
技術調査、リサーチ、比較検討 | シアン |
security |
セキュリティ監査 | オレンジ |
proposal |
改善提案、ブラッシュアップ案、設計案、仕様書 | ティール |
investigation と proposal は紛らわしい。今どうなっているかを説明するなら investigation、これからどうするかを提案するなら proposal。「改善アイデア」「〜案」は後者。
種別は色とバッジと保存先を決めるだけで、本文の書き方に制約は無い。
Step 2: 本文を書く
Markdown で書いて一時ファイルに保存する。使える記法は references/markdown-syntax.md を参照 — 表・Mermaid 図・SVG・進捗バー・重要度バッジなどがある。
## がセクションカードになるので、これがレポートの骨組みになる。3〜6 個が読みやすい。5 個以上になると目次が自動で付く。
種別ごとの構成例（そのまま使う必要はなく、内容に合わせて調整してよい）:
- review: レビュー概要 / 重大な指摘 / 改善提案 / 良い点 / まとめ
- bug: 概要・再現方法 / 調査結果 / 根本原因 / 修正方針 / まとめ
- investigation: 背景・目的 / 調査結果 / 原因分析 / 推奨対応 / まとめ
- research: 調査目的 / 調査結果 / 比較・評価 / 結論・推奨 / 参考情報
- security: 監査概要 / 脆弱性 / リスク / 問題なし / まとめ
- proposal: 現状と課題 / 提案内容 / 案の比較 / 想定コスト・リスク / 推奨
構成を機械的に埋めるより、その調査で実際に分かったことの形に合わせるほうがよい。原因が特定できなかった調査に「根本原因」の空セクションを置くくらいなら、「絞り込んだ範囲」と書いたほうが伝わる。
内容の忠実さ
会話で出した結論を要約し直さない。指摘が 12 件あったなら 12 件すべて載せる。レポートは後から見返すためのもので、そのとき「会話ではもっと詳しく言っていたはず」となるのが一番困る。
一方、会話の試行錯誤（読んだファイル、外した仮説）は不要。結論と根拠を残し、過程は落とす。
会話から読み取れない項目（PR 番号など）は推測せず「-」と書く。
図を使う判断
文章で説明すると 3 文以上かかる関係性があるなら図にする。処理フロー、状態遷移、コンポーネント間の依存などが該当する。装飾目的では入れない。
Mermaid は CDN で描画する。オフラインでは図の代わりに定義がコードとして表示される（読めなくはないが図にはならない）ので、確実に残したい図は SVG で書く。
Step 3: 生成する
& "$HOME\.claude\skills\html-report\scripts\New-HtmlReport.ps1" `
-Kind bug `
-Title "ログイン断続失敗の調査" `
-Subtitle "src/auth/session.ts" `
-BodyPath "<本文.md のパス>" `
-Cards "バグID|#142","ステータス|原因特定","影響範囲|認証全体"
| パラメータ | 説明 |
|---|---|
-Kind |
種別（必須） |
-Title |
タイトル（必須） |
-Subtitle |
対象の説明。ブランチ名、調査対象など |
-BodyPath |
本文 Markdown のパス（必須） |
-Cards |
サマリーカード。ラベル|値|補足 を最大 3 つ |
-Number |
番号を明示指定。省略時は自動採番 |
-NoOpen |
ブラウザで開かない |
ユーザーが「PR #123」のように番号に言及していれば -Number 123 を渡す。無ければ自動採番に任せる。
サマリーカードは「開いた瞬間に把握したい 3 つ」を選ぶ。値は 12 文字以内が収まりよく、長いと自動で縮小される。
件数だけを並べない。アイデア数 28件 / 対応不要 18件 / 推奨 6件 のようなカードは、要約に見えて「28 件を読め」と言っているだけで、読み手の負荷はむしろ増える。同じ枠を使うなら、読まなくても行動が決まる一言を入れる。
- 良い:
まず着手\|内訳タブの拡張、結論\|Grafana 採用、ステータス\|修正済み - 惜しい:
改善案\|30件、調査対象\|3製品
件数そのものは、重大度サマリー（[!red] の総数を自動集計してヘッダー下に表示）と目次の項目数バッジが自動で見せるので、カードで重ねる必要はない。
生成後は保存先パスを報告する。スクリプトが自動でブラウザを開く。
保存先
output-config.toml で設定する。既定は ~/reports/<種別>/<prefix><番号>.html。
番号は保存先の既存ファイルから自動採番される（最大番号 + 1）。
トラブル時
文字化けする: 本文 Markdown を UTF-8 で保存しているか確認する。
図が出ない: 「図を描画できませんでした（オフライン）」と出ていれば CDN に届いていない。SVG に書き換えれば依存なしで残せる。注記が出ずに図だけ崩れる場合は Mermaid 記法自体の誤りで、Mermaid Live Editor で確認できる。
表が崩れる: セル内の | は \| にエスケープする。
スクリプトが見つからない: claude/install.ps1 を再実行して ~/.claude/skills/ へ展開する。