こんにちは、エムスリーエンジニアリンググループの福林 (@fukubaya) です。
AIエージェントに調査や分析をさせると、成果そのものは十分な質で出てきます。ところが、それを人に配る段になると一手間かかります。ターミナルに流れた結果をそのままSlackに貼っても読んでもらえませんし、Markdownのままでは図表の表現力が足りません。かといってHTMLで出力させると、実行するたびにデザインも文章構成も安定せず、チームの成果物として見たときに揃いません。
そこで、成果物の「見た目」と「構成」をプラグイン側に固定してしまうことにしました。社内のデザインシステムをレポートに適用し、目的別の文書構成テンプレートを持たせ、グラフや図の作り方まで含めて決め打ちにする。さらに、同じ材料からGoogle Slidesの資料も作れるようにしています。
本記事では、この u4report というClaude Codeプラグインについて、実装した機能と、そこに至るまでのツール選定・設計判断を紹介します。

- AIの成果物はHTMLで配るのがちょうどいい
- きれいに作ってくれる。ただし毎回違う
- u4report の全体像
- HTMLレポートの実装
- スライドも作りたくなった
- 使ってみて
- まとめ
- We are hiring!
AIの成果物はHTMLで配るのがちょうどいい
前回、Unit4(m3.comサービスの開発を担当するチーム)のAWSインフラ監視・障害調査を支援するClaude Codeプラグイン u4sre を紹介しました。
u4sre に限らず、エージェントに障害調査やログ分析をやらせると、最後に必ず「で、これをどう共有するか」という問題が残ります。
当初はMarkdownで出力させていました。Markdownは原本として扱いやすく、差分も追えるので、入力や下書きには今も適しています。ただ、そのまま人に配る出力としては、グラフ・構成図・レイアウトといった表現が持てません。githubに貼るならある程度表現できますが、事業側・企画側のメンバーに渡すことを考えると、もう一段の表現力が欲しくなります。
したがって、配布を考えるとHTMLを選択したくなります。AIエージェントはHTMLとCSSを書くのが得意で、何も指示しなくてもそれなりに整った資料を作ってくれます。グラフも図もレイアウトも自由に組めますし、ブラウザで開けるので相手を選びません。
この「AIの出力をMarkdownではなくHTMLにする」という発想は、最近あちこちで語られるようになってきました。入力・原本・差分管理はMarkdown、人間が読む出力はHTML と役割を分けるという整理がされています。
もうひとつ追い風になったのが、社内の別チームが運用しているサービスです。Google Driveの共有フォルダに置いたHTMLを、そのまま社内向けWebページとして配信してくれます。
- デプロイ = Driveに置くだけ。共有設定済みフォルダにHTMLを置けば公開される
- 権限はDriveに委譲。共有サービス自身は認可ロジックを持たず、閲覧者のOAuthトークンでDrive APIを叩くので、Driveの共有設定がそのまま公開範囲になる
- アクセスは社内ネットワークからに限定されているので、社内資料を置ける
ホスティングの手配もアクセス制御の設計も不要で、「AIに書かせたHTMLをDriveに置く」だけで社内公開URLが手に入ります。これで、資料を配るための最後の一歩が一気に軽くなりました。
きれいに作ってくれる。ただし毎回違う
ところが、AIエージェントにHTMLを書かせる上で問題があります。実行するたびにデザインも文章構成もバラバラになるのです。
あるときはカード型のモダンなレイアウト、あるときはグラデーション多用の派手なもの、あるときは素朴な白黒。見出しの粒度も、結論を冒頭に置くか末尾に置くかも、毎回違います。1本ずつ見れば悪くないのですが、チームで何本も出していくと同じチームが出した資料に見えません。
統一しようとすると、毎回「配色はこれ、見出しはこの構成で、結論は冒頭に」と細かく指定することになります。これでは、せっかくエージェントに任せた意味が薄れます。
さらに、運用していく中で「これは毎回言わないといけないな」という要求が溜まっていきました。
- ファイルが複数になると配りにくい。画像やCSSを別ファイルにされると、共有時に取りこぼす
- PDFに変換したときに図が汚い。ラスタ画像で図を作られると、印刷・PDF化で潰れる
そこで、これらをまとめてプラグイン側に固定してしまうことにしました。それが u4report です。
u4report の全体像
u4report は、会話で得られた分析・調査・作業の成果を資料にまとめ、Google Driveに保存して社内共有するスキルです。出力は2種類あります。
| 出力 | agentが書くもの | 共有のされ方 | 人による編集 |
|---|---|---|---|
| HTMLレポート | body.html + charts.json + diagrams/*.d2 |
共有サービスの社内公開URL | しない前提(作り直す) |
| Google Slides デッキ | deck.yaml + charts.json + diagrams/*.yaml |
Slidesの編集URL | する前提(人が手を入れる土台) |
どちらも共通しているのは、agentは「中身」だけを書き、見た目はビルダーが決めるという構造です。agentが <style> を書くことも、座標や色を指定することもありません。
ワークフローはこうなっています。
# HTMLレポート 1. body.html(本文・セマンティックHTML)と charts.json(グラフ定義)を書く 2. uv run scripts/build-report.py <dir> --title "…" --toc → dist/index.html 3. scripts/publish-report.sh <dir>/dist unit4 u4sre 5xx障害分析 → 公開URL発行
保存先は <root>/<担当>/<YYYYMMDD_カテゴリ_件名_担当>/index.html という規則で、1レポート1フォルダで管理します。担当名は gws(Google Workspace CLI) の認証アカウントのメールlocal部から自動で決まるので、指定を忘れても崩れません。
実際に出てくるレポートはこんな見た目です。以降に載せる例はすべて、架空のサービスを題材に本記事用に生成したもので、数値もサンプルです。

冒頭のリード文、主要な数値を並べた統計タイル、前提条件の定義リスト、検知からの時系列。この並びも体裁も、agentは一切指定していません。
HTMLレポートの実装
デザインシステムで見た目を固定する
見た目のバラつきを止めるために採ったのは、デザインシステムをそのまま適用するという方法です。
M3には独自に開発しているデザインシステムがあります。レポートもこれに乗せてしまえば、見た目は考えるまでもなく決まりますし、他のプロダクトと並べても違和感がありません。
ただし、共有サービスのCSPは default-src 'self' です。外部CDNもWebフォントも使えません。そこで、デザインシステムのリポジトリをクローンしてビルドし、アイコンのSVGをすべてdata URI化した自己完結CSSを生成するスクリプトを用意して、その出力をプラグインに同梱しています。
| ファイル | 内容 |
|---|---|
| デザインシステム本体のCSS | リポジトリから自動生成(編集禁止) |
| アイコンのCSS | 本文で使われている分だけ抽出して埋め込む |
report_layer.css |
レポート固有の層(用紙・見出しマッピング・統計タイル・目次・タイムライン等) |
この3層構成にしたことで、「デザインシステムの更新に追従する部分」と「レポート固有の調整をする部分」が分かれました。追従させたいときだけ取り込みスクリプトを実行すればよく、普段のレポート作成では触りません。
そのうえで、agentへの指示は徹底的に単純化しました。
<style>やstyle=は書かない。まずクラスなしのセマンティックHTMLで書く。素のHTMLがそのままデザインシステム準拠の見た目になる。
見出し・段落・表・リスト・引用・<details> といった素のタグに対してスタイルが当たるようにしてあるので、agentは本当に本文を書くだけで済みます。メッセージパネル・統計タイル・タイムラインといったコンポーネントが欲しいところだけ、カタログ (components.md) から選んでクラスを足します。
文章構成もテンプレートで固定する
見た目が揃っても、構成が毎回違えば「同じチームの資料」にはなりません。そこで、これまで社内で作ってきた文書を参考に、目的別の構成テンプレートを report-types.md としてまとめ、「本文を書き始める前に必ず読む」ように指示しています。
種別は4つです。
| 依頼の内容 | 種別 |
|---|---|
| 「5xxが増えた件をまとめて」 | A. 障害・インシデント報告 |
| 「この施策の効果を検証して」 | B. 調査・データ分析 |
| 「どちらの方式がいいか判断してほしい」「稟議に使いたい」 | C. 提案・意思決定依頼 |
| 「◯◯の仕組みを調べて」「設計案をまとめて」 | D. 技術調査・設計メモ |
たとえば障害報告(A)なら、見出し構成はこう決まっています。先ほどのサンプルレポートは、このテンプレートに沿って生成されたものです。
<div class="report-lead"> <!-- 何が・いつ・どれだけ・現在の状態を4文以内で --> <div class="report-stats"> <!-- 影響時間 / 影響ユーザー数 / エラー件数 / エラー率 --> <h1>影響範囲</h1> <h1>時系列</h1> <h1>原因</h1> <h2>直接原因</h2> <h2>根本原因</h2> <h1>対応</h1> <h1>再発防止策</h1> <!-- 表: 施策 / 担当 / 期限 / ステータス --> <h1>検知と対応の振り返り</h1> <details>付録: 調査に使ったクエリ・ログ</details>
面白いのは、構成そのものよりも「そこに書かれた原則」のほうが効いたことです。テンプレートには、これまで人間がレビューで何度も指摘してきたことを併記しています。
- 時系列は「発生」ではなく「検知」から書く。 検知が遅れたなら、それ自体が課題
- 再発防止策は担当と期限が入っていないと意味がない。 決まっていないなら「未定」と書く
- 影響ユーザー数が出せないときは「出せない」と書く。 推定値を出すなら根拠を添える
- 事実・解釈・提案を書き分ける。 「〜だった」「〜と考えられる」「〜すべき」を混ぜない
- 確認できていないことは「未確認」と書く。 埋めるために推測を断定で書かない
エージェントは放っておくと、空いている節を推測で埋めてそれらしく仕上げてしまいます。「埋めない」「分からないと書く」を明示的に指示しておくのは、意外と重要でした。サンプルレポートで「影響ユーザー数は…未確認です」と書かれ、再発防止策の担当が「未定」になっているのは、この原則が効いている結果です。
同様に、読み手による書き分けも原則として渡しています。同じ調査結果でも、SRE向けと事業側向けでは書くべきものが変わるためです。
| 観点 | eng 向け | 非eng 向け(事業・企画・営業) |
|---|---|---|
| 結論の位置 | 先頭に要約。詳細は後段で追える構成に | 先頭に結論。それ以降を読まなくても意思決定できるように |
| 数値 | 生の件数・率・パーセンタイルを出す | 生の数字より影響の大きさ(何人が / 何分間 / 売上換算)に翻訳する |
| クエリ・ログ・コード | 本文または <details> に載せて再現可能にする |
載せない。 必要なら付録に畳む |
読み手が依頼から判断できない場合は、勝手に決めずユーザーに確認するようにしています。
1ファイルで完結させる
レポートの共有において地味に効くのが、ファイルが1つで済むことです。画像やCSSが別ファイルになっていると、Slackに貼るときも、あとで誰かに転送するときも、確実に取りこぼします。
そこで build-report.py は、すべてを1つの index.html に埋め込んだ自己完結HTMLを出力します。
- CSSはインライン展開(アイコンはdata URI)
- グラフはSVGで生成し、
data:URIとして埋め込み - 図も同じくSVGを
data:URIで埋め込み
出力サイズはCSSのインライン分で250KB前後になりますが、1ファイルで完結する価値のほうが上回ります。agentは本文の置きたい位置に
<div data-chart="err-rate"></div> <div data-diagram="infra"></div>
と書くだけで、ビルド時にSVGへ置換されます。
グラフに matplotlib を選んだ理由
グラフの描画には matplotlib を使っています。決め手は単純で、uv run だけで完結することです。スクリプト冒頭のインラインメタデータに依存を書いておけば、uv が勝手に解決してくれます。
# /// script # requires-python = ">=3.11" # dependencies = [ # "matplotlib>=3.8", # "matplotlib-fontja>=1.0", # ] # ///
社内デザインシステムにもグラフのガイドラインはあるのですが、そちらはReact向けのチャートライブラリ(Recharts)を前提にしたものでした。一方こちらはJavaScriptを使わない静的HTML(共有サービスのCSPと、そもそも再現性のために動かさない方針)なので、そのままは使えません。配色パレット(Sequential / Diverging)と、グラフ種別ごとの使い分けの指針だけを移植して、描画はmatplotlibが担う形にしました。
対応しているのは棒 / 横棒 / 折れ線 / 帯(100%積み上げ) / 複合(棒+折れ線・第2軸) / 円 / ドーナツ / 散布図 / ヒストグラム / 箱ひげ図 / ヒートマップの11種類です。値ラベル・桁区切り・基準線(目標値など)・注釈(デプロイ時刻など)・ソートも指定できます。
{ "id": "err-rate", "chart_type": "line", "title": "5xx率の推移", "value_format": "percent", "value_decimals": 2, "value_labels": true, "reference_lines": [{"value": 0.10, "label": "目標ライン 0.10%", "color": "warning"}], "annotations": [{"at": "9/10", "label": "デプロイ"}], "series": [{"name": "catalog-api", "data": [{"label": "9/1", "value": 0.01}]}] }
この定義から出てくるのがこれです。
「目標のラインを超えたかどうか」「何をきっかけに変化したか」は、グラフの脇に文章で書くより線を引いたほうが速く伝わります。ここを毎回指示しなくて済むように、定義のフィールドとして用意しました。
単位の違う指標を1枚に載せたいときは複合グラフを使います。これを用意していないと、エージェントは件数と率を同じ軸に載せてしまい、率の側が0付近に潰れて読めないグラフになりがちです。
図のツールは、制約から絞り込んだ
構成図・フロー図の作図ツールは、かなり迷ったところです。どれも作図ツールとしては優れているのですが、「プラグインの利用者に追加インストールを求めない」という制約を先に置いたため、そこで絞り込む形になりました。
| 候補 | 今回の判断 | 理由 |
|---|---|---|
Graphviz (dot) |
見送り | 描画品質は申し分ないが、OSパッケージのインストールが前提になる |
| PlantUML | 見送り | 同上(加えてJavaの用意も要る) |
Mermaid (mmdc) |
見送り | Node + Chromium が必要で、プラグインの前提としては重い |
| blockdiag / nwdiag | 見送り | pure Pythonで条件は満たすが、最終リリースが2021年で、CJKフォントの設定も別途必要 |
| matplotlib の上に自前の作図レイヤ | 保留 | 依存は増えないが、レイアウトエンジンを自作することになる |
| D2 | 採用 | go run で取得でき、日本語も正しく出る。レイアウトが忠実 |
最初は「uv だけ」という制約で考えていたため、matplotlibの上に宣言的な作図レイヤを自前で載せるという案まで検討していました。グラフと同じSVGパイプラインに乗せられるのは魅力だったのですが、レイアウトエンジンの自作は本筋から外れます。
そこに「go と npx も使える前提でよい」と条件が緩んだことで、D2 が一気に本命になりました。d2 が入っていればそれを使い、無ければ go run github.com/d2lang/d2@v0.8.2 で自動取得します。初回だけモジュールの取得とビルドに1分ほどかかりますが、以降はGoのキャッシュが効いて1秒未満です。
D2のSVGは自前のフォントを埋め込むため1枚30KB前後になります。埋め込みを剥がして軽くすることも試したのですが、ラベルの位置がずれてしまうため、そのまま残す判断にしました。
デザインシステムのセマンティックカラーに対応したクラス定義を自動で差し込んでいるので、agentは class: accent class: warning のように書くだけで配色が揃います。
# title: 5xx が返るまでの流れ
shape: sequence_diagram
user: 利用者 { class: node }
alb: ALB { class: accent }
cat: catalog-api { class: strong }
meta: "外部API" { class: external }
user -> alb: "GET /catalog/search"
alb -> cat: forward
cat -> meta: メタデータ取得
meta -> cat: "タイムアウト (3s)" { class: warn }
cat -> alb: 500 { class: warn }
alb -> user: 500 { class: warn }
構成図も同じ書き方で描けます。障害報告なら注目すべき箇所に warning、提案なら追加するものに added / 廃止するものに removed を当てる、といった使い分けまで含めてドキュメント化しています。
なお、図が横に広がりすぎると本文の表示幅(約850px)に収まらず縮小されてしまうので、ビルド時に警告を出すようにしています。
warning: 図 'infra' は横 1966px あり、表示時に 43% まで縮小されます。
要素を減らすか direction を down にして縦長にしてください
図はすべてベクターで描く
グラフも図もSVGに揃えているのは、配りやすさだけが理由ではありません。PDFにしても劣化させないためです。社内共有ではHTMLのまま読んでもらいますが、社外提出や印刷でPDF化されることがあります。ここで図がラスタ画像だと一気に見栄えが落ちます。
ただ、SVG化で1つハマりどころがありました。matplotlibのSVG出力は既定でフォントをアウトラインパス化するのですが、そうするとヒンティングが効かず、小さい日本語がザラついて見えるのです。
# 既定('path')だと文字がアウトラインパスとして出力され、ヒンティングが効かないため # 小さい日本語がザラついて見える。'none' にして <text> のまま出力し、ブラウザに # 描画させることで、日本語もくっきりレンダリングされる。 matplotlib.rcParams["svg.fonttype"] = "none"
none にすると文字が <text> 要素のまま出力され、ブラウザがフォントで描画してくれます。日本語がくっきりするうえ、グラフや図の中の文字を検索・選択できるという副次的な効果もありました。
なお、ここまでに載せたグラフと図は、u4report が生成したSVGをそのままこの記事に貼っています。 画像に変換していないので、拡大しても潰れませんし、軸ラベルやノードの文字を選択・検索できます。ベクターで出しておくと、こうして別の媒体へ持っていくのも楽になります(このあとに出てくるスライドのスクリーンショットはPNGです)。
ただし、SVGを他のHTMLに貼るときは少し注意が要ります。SVGの中の <style> は、貼り先のページ全体に効きます。 matplotlibの出力は全称セレクタで線の端点の形を指定しているので、そのまま置くとページ内の他のSVGにまで影響します。今回は <style> を消し、同じ指定を継承されるプレゼンテーション属性としてルートの <svg> に移しました。
もう1点は id です。matplotlibは figure_1 のような汎用的な名前を使い、マーカーの定義を xlink:href="#..." で参照します。同じ id を持つ図を1ページに複数貼ると、参照が先に出てきた図のほうを拾ってしまいます。 図ごとに接頭辞を付けて回避しました。D2のSVGは最初から図ごとのハッシュで id・クラス・フォント名がすべてスコープされているため、こちらは無加工で貼れています。
追加インストールが必要なツールは使わせない
改めて整理すると、u4sre と同じく 実行環境に依存させないことを強く意識しています。使ってよいのは uv / go / npx / gws の範囲だけです。
- Pythonスクリプトは
uv runで実行。matplotlib・pyyamlといった依存はuvが自動解決するので事前インストール不要 - 図のD2は
d2が無ければgo runで自動取得 - Driveへのアップロードは
gws
プラグインを配る以上、「まず環境構築してください」が必要になった時点で使われなくなります。この制約が、結果的にツール選定を素早く収束させてくれたのは、やってみて分かった副産物でした。
スライドも作りたくなった
HTMLレポートが安定してくると、次に来るのは「これをそのまま定例で説明したい」「障害報告会の資料にしたい」という要求です。
スライドについても、事情はHTMLレポートとまったく同じでした。エージェントに自由に作らせると見た目はよいが、毎回バラバラになります。スタイルと構成を安定させたい、という動機は共通です。
ただ、スライドにはHTMLレポートと決定的に違う点があります。できあがったものを人間が編集する前提だということです。
HTMLレポートは「完成品として配る」ものなので、直したければ作り直せば済みます。一方スライドは、発表者が自分の言葉に直したり、順番を入れ替えたり、コピペして別のスライドに使ったりします。配ったあとに人が触ることが前提です。
エージェントに自由に作らせてみると、見た目は整っているものの、人が手を入れにくいファイルができあがりがちです。図が1枚の画像として貼られていて箱ひとつ動かせない、グラフが画像なので数値を直せない、テキストが凝ったレイアウトに焼き込まれていて書き換えられない。発表者が当日に一言直す、ということができません。
生成方式の比較
そこで、「図表・オブジェクトを人が編集できること」を要件の芯に置いて、生成方式を比較しました。どれも良い選択肢ですが、この要件に照らすと差がはっきり出ました。
| 案 | 編集可能性 | スタイル統一 | ビルドのしやすさ | 今回の判断 |
|---|---|---|---|---|
A. Slides API (gws) で直接生成 |
◎ 全要素がネイティブ。テキスト・図形・表・コネクタを個別に編集できる | ◎ マスター/レイアウト継承。後からテーマ変更も効く | △ 座標を扱う抽象化レイヤが要る | 採用 |
| B. python-pptx → pptx → Drive変換 | △ テキスト・図形は編集できるが、グラフは画像として入る | △ pptxテンプレートに依存し、Slidesのマスターは継承されない | ◎ ローカル完結・高速 | 見送り |
| C. Marp / Slidev / md2googleslides | △ PDF・HTML出力は編集対象にできない。md2googleslidesは認証方式が独自 | - | ◎ Markdownから書ける | 見送り |
Bのローカルで高速に反復できる点は魅力でしたが、要件の芯である「編集できること」との相性で見送りました。Aの弱点であるビルドのしにくさは、後述するビルダーとサムネイル検証ループで補えると判断しています。
Google Slidesを操作するCLIは gws(Google Workspace CLI) を使いました。HTMLレポートのDriveアップロードで既に使っており、依存が増えないのが決め手です。
すべてネイティブオブジェクトで作る
採用したのは、Slides APIの batchUpdate ですべてネイティブオブジェクトとして組み立てる方式です。実機で1つずつ検証しました。
| 要素 | 実装 | 人ができること |
|---|---|---|
| テキスト | レイアウトのプレースホルダに insertText |
マスターの書式を継承しつつ、そのまま書き換え |
| 図 | createShape + createLine(BENT) の startConnection / endConnection |
本物のコネクタ。箱を動かすと矢印が追従する |
| 表 | createTable + セル単位の insertText |
セルの編集・行列の追加 |
| グラフ | Sheetsに addChart → createSheetsChart(linkingMode: LINKED) |
元シートで数値を直して「更新」で反映 |
| スタイル | マスターから継承 | テーマを変えれば全体の色が変わる |
つまり、HTML版と同じグラフ・表・図を、できるだけGoogle Slides上で再現するという方針です。
agentが書くのは deck.yaml だけで、座標・色・文字サイズは一切書きません。
title: catalog-api 5xx 障害の事後報告 subtitle: 2026-09-11 / Unit4 SRE / yuichiro-fukubayashi slides: - layout: stats title: 影響範囲 lead: 9/10 14:02〜14:20 に 5xx が集中して発生した stats: - {value: "1,284", label: エラー件数} - {value: "18分", label: 影響継続時間} - {value: "0.41%", label: 期間中の5xx率} caption: "出典: ALB アクセスログ(Athena)" notes: 発表者ノート。スライドに載せない補足はここへ
レイアウトは表紙 / 章扉 / 箇条書き / 2カラム / 統計 / グラフ / 表 / 図 / 画像 / 引用の10種類を用意し、見た目は共有ドライブ上のテンプレートのマスターとレイアウトが決めます。
この deck.yaml から出てくるのがこのスライドです。

タイトルに主張を書き、数値の出所をキャプションに置く、という原則もテンプレート側が持っています。
スライドの図はD2ではなくネイティブ図形で描く
HTMLレポートではD2を使っていますが、スライドではD2を使いません。D2が出すのはSVGで、Slidesに貼っても図形として編集できないからです。「人が動かせない図」は、スライドでは価値が落ちます。
代わりに、ノードとエッジだけを書くと、ビルダーが段(rank)を決めて自動配置し、Slidesのネイティブ図形とコネクタに展開します。
direction: right nodes: - {id: user, label: 利用者} - {id: alb, label: ALB, style: pale} - {id: ecs, label: catalog-api, style: primary} - {id: meta, label: 外部API, style: warning} edges: - {from: user, to: alb} - {from: alb, to: ecs, label: HTTP} - {from: ecs, to: meta, label: timeout} groups: - {label: Unit4 VPC, nodes: [alb, ecs]}

ここでの割り切りは、自動配置が完璧である必要はないということです。図形がネイティブである以上、人が開いて少し動かせば整います。ビルダーの役目は「動かせば整う状態」まで持っていくことだ、と位置づけました。座標を指定する手段はあえて用意していません。
一方で、複雑な図はスライドに向かないことも明示しています。シーケンス図(ライフライン付き)や分岐が2本を超えるフローは非対応で、「HTMLレポート側でD2を使い、スライドからは参照する」という逃がし方をドキュメントに書いています。
グラフはSheets連携にした
スライドのグラフは、Googleスプレッドシートのグラフへのリンクとして貼ります。ダブルクリックすると元データが開き、数値を直して「更新」すれば反映されます。元データのスプレッドシートはデッキと同じフォルダに作られます。
charts.json はHTMLレポートと同じ形式のまま使えるようにしたので、同じ調査からHTMLレポートとデッキの両方を作るときに、グラフ定義を書き直さずに済みます。


ただし、Slides / Sheets API には固有の作法がいくつかあり、実機検証で次の点に対応しました。
| 症状 | 原因・対応 |
|---|---|
| 散布図が動かない | {x, y} 形式を読んでいなかった。横軸も数値として扱うよう修正 |
| 複合グラフで率が0付近に潰れる | 系列ごとの形(棒/折れ線/面)と、axis: right による第2軸に対応。単位の違う指標を1枚にするならこれが必須 |
| 横棒がAPIに弾かれる | BAR は値軸が下。targetAxis: LEFT_AXIS を送ると拒否される |
| 折れ線がAPIに弾かれる | stackedType は棒と面にしか指定できない |
| 円・ドーナツがGoogle既定の赤黄緑で出る | スライス色は系列単位で指定できない。スプレッドシートのテーマ色をデザインシステムの配色に差し替えて解決 |
reference_lines / annotations / value_labels のような細かい装飾はSlidesでは使えません。ここが必要な場面では、HTMLレポートを併せて作ってデッキから参照する、という使い分けにしています。
画像だけは人がコピペする
自動化しきれなかったのが画像です。Slides APIの createImage は「認証なしで取得できるURL」しか受け付けず、共有ドライブ上のファイルはどのURL形式でも拒否されました。
| 形式・経路 | 結果 |
|---|---|
| 公開URLのPNG / JPG | OK |
| 公開URLのSVG | supported formats で拒否 |
共有ドライブのPNG(uc?export=download) |
not accessible |
共有ドライブのPNG(thumbnailLink) |
forbidden |
挿入するには画像を一時的に「リンクを知る全員」へ公開する必要がありますが、社内のスクリーンショットを一瞬でも外部公開する判断を勝手にすべきではないと考えて、これは行わないことにしました。
代わりに、ビルダーは画像をデッキと同じDriveフォルダに置き、スライドには枠と「ここに <ファイル名> を貼る」という指示を描きます。人がSlidesを開いて枠にドラッグ&ドロップすれば数秒で終わります。ユーザーにURLを渡すときは、この操作が残っていることを必ず伝えるようにスキルに書いています。黙って渡すと、枠だけのスライドが入ったまま共有されてしまうためです。
SVGは上の表のとおり公開URLでも通らないので、rsvg-convert(librsvg)で1600pxのPNGに焼いてから置きます。deck.yaml には .svg のまま書けるので、D2やmatplotlibの出力をそのまま渡せます。
なお、ここでも採らなかった案があります。
- EMF経由でベクター図形として貼る — Drive APIで
application/x-msmetafileをアップロードすると「Google図形描画」に変換でき、結果は本物のベクター(SVGに戻すと<path>63個、ラスタ0)でした。しかし、①SVG → EMF の変換器がuv/go/npxの範囲に存在せず(実用的なのはLibreOfficeかInkscapeだけ)、②変換できてもテキストがアウトライン化されて文言を直せず、③図形描画→スライドのコピペにAPIが無いので手間も減らない。3点とも噛み合わなかったので不採用にしました - macOS標準の
qlmanageによるSVG変換 — フォールバックとして実装していたのですが、縦長のSVGでは下部が入りきらないことがあると分かりました(200×500 のSVGが 799×1199 になり、下部の図形が欠けた)。エージェントに任せる処理では「エラーにならずに結果だけ変わる」経路は扱いにくいので、フォールバックとしても持たない判断にしました
サムネイルを目視確認させる
スライドで一番苦労したのは、テキストの溢れを検知できないことでした。
Slides APIは、プレースホルダの自動縮小をエディタで開くまで再計算しません。つまりAPI側からは「入りきっているか」が分からないのです。文字を詰め込みすぎたスライドが、そのまま「成功」として返ってきます。
対策は2段構えにしました。
- 文字数バジェット — ビルド時に自動で警告を出す。スライドタイトルは26字、箇条書き1行は42字、統計タイルの値は7字、といった目安をテーマ側に持たせている
- サムネイルの目視 —
--verifyでpages getThumbnailから全ページの画像をthumbs/に書き出し、agentに1枚ずつ画像として開かせて確認させる
特にタイトルは別格で、超えると壊れます。タイトルが折り返すと2行目が枠の外に押し出され、画面上から消えるのです。本文のように下にはみ出すのではなく、見えないまま切れるので気づけません。ここは「警告が出たら必ず短くする」と強く書いています。
もうひとつ、運用上の注意として 「渡したあとは再ビルドしない」 を明記しています。--presentation <ID> での再ビルドは全スライドを作り直すため、人が加えた編集が失われます。レビュー→修正→再ビルドは共有前に済ませ、渡したら以降は人の領域、という線引きです。
使ってみて
効果は3つありました。
1つ目は、資料の見た目と構成が揃ったことです。これが当初の目的でした。誰がどのエージェントに作らせても同じ体裁で出てくるので、受け取る側が毎回「今回はどういう構成だろう」と読み方を切り替えなくて済みます。デザインシステム準拠なので、社内の他プロダクトと並べても浮きません。
2つ目は、「共有するところまで」が会話の中で終わるようになったことです。調査した流れのまま「レポートにしてUnit4向けに上げて」と言えば、数分後に社内公開URLが返ってきます。ファイルをどこに置くか、誰に権限を渡すか、といった作業が消えました。Driveの命名規則もスクリプトが担保するので、あとから探せなくなることもありません。
3つ目は、構成テンプレートがレビューの代わりになったことです。これは予想外でした。「再発防止策には担当と期限を書く」「事実と解釈を分ける」といった、これまで人間がレビューで指摘してきたことがテンプレートに入っているので、最初から一定の水準を満たした状態で出てきます。レビューで指摘する内容が、細部の事実確認に集中するようになりました。
もちろん万能ではありません。スライドは結局のところ人が手を入れる前提ですし、画像の貼り込みは人の操作が残ります。複雑な図はスライドでは再現しきれず、HTMLレポートに逃がすことになります。それでも、「AIが8割作り、人が自分の言葉で仕上げられる資料」という形に落とせたのは、大きな前進でした。
まとめ
本記事では、AIエージェントの成果を社内共有できる資料にまとめるClaude Codeプラグイン u4report を紹介しました。
- AIの成果物は、表現力と共有しやすさから Markdownより HTML がよい。社内の共有サービスのおかげで「Driveに置くだけ」で公開できるようになった
- 放っておくと毎回デザインも構成もバラバラになるので、社内デザインシステムを取り込んで見た目を固定し、目的別の構成テンプレートで文章構成も固定した
- 配りやすさのために画像もグラフもすべて1つのHTMLに埋め込み、PDF化でも劣化しないよう図はすべてSVGで生成させた
- 図表のツールは「追加インストール不要」の制約から絞り込み、グラフはmatplotlib(
uv run)、図はD2(go run) に落ち着いた - スライドは人が編集する前提なので、python-pptxやMarpではなく Slides APIで全要素をネイティブオブジェクトとして生成し、図もD2ではなくネイティブ図形+コネクタで描いた
- Slides APIは溢れを検知できないため、サムネイルをagentに目視確認させる手順を必須にした
見た目や構成をエージェントの裁量に委ねると、1回ごとの品質は高くても、チームの成果物としては揃いません。「何を任せ、何を固定するか」を決めて、固定するものはコードとテンプレートに落とす。これは前回の u4sre と共通する設計方針でした。
We are hiring!
エムスリーでは、AIを活用して開発・運用を加速し、その成果をチームの資産にしていく仲間を募集中です。お気軽にお問い合わせください。