ある保護者が私たちのエージェントに、生徒のサイエンスフェアのレポート — 熱電式の飲料水 ディスペンサーについての Word 文書 — を、市レベルのイノベーションコンテスト用の プレゼンテーションに変えるよう依頼しました。本物の締め切りと、出力を読む本物の先生がいる、 本物のタスクでした。
完成したデッキは良い出来でした — 編集可能版が豪華なレンダリング版と同じくらい洗練されて 見えるほどでした。しかしそこに至るまでに4つの異なる壊れ方をし、どれも「実際に誰かがファイルを ダウンロードして学校のノート PC で開く」ときにだけ見つかる種類のバグでした。何が起きたか、 そしてその結果システムに何を変えたかをお伝えします。
失敗 1：3枚のスライドが空で返ってきた
プレビューは完璧に見えました。ダウンロードした HTML は違いました — 9枚の画像が真っ白に
レンダリングされました。原因：デッキが画像を相対パス（src="assets/chart.png"）で
参照しており、これはワークスペースのプレビュー内では正しく解決されますが、.html ファイルが
単体でダウンロードフォルダへ移ると行き先のないパスになります。
重要な修正は「画像を埋め込む」ことではなく、不変条件です：デッキを成果物と呼ぶ前に、 grep -c 'src="assets/' がゼロを返さなければなりません。画像を1枚ずつパッチする
やり方が、最初の修正で3枚のチャートを取りこぼした原因です。この物語のすべてのルールは
同じ結末をたどります：目で見るのではなく、チェックで輪を閉じる。
失敗 2：オンラインにしか存在しないチャート
インタラクティブなチャートライブラリは生きた canvas 上に描画します。私たちのプレビューの scroll-mode の DOM クローンでは描画されたピクセルが消え、オフラインでは CDN のスクリプトが そもそも届きません。教室で投影しなければならないデッキにとって、「オンラインなら動く」では 不十分です — そこでプレゼンテーション用デッキは、チャートをあらかじめ PNG にレンダリングして 画像として埋め込むようになりました。インタラクティブなチャートは、環境が分かっていて インタラクション自体が目的の場合に限り、選択肢として残ります。
失敗 3：収まりきらなかったエクスポート
ユーザーは2つのバージョンを求めました：洗練されたレンダリング版 PPTX と、発表前に生徒が 調整できる編集可能版です。ところが編集可能エクスポートのパイプラインには厳しい入力上限が あり — 完全に自己完結したデッキは大きすぎました — さらに相対パスの画像を落とし、テキスト ボックスの結合も誤っていました。そこで編集可能デッキは python-pptx でネイティブに作り直 されました。それによって、さらに3つの実運用の失敗が表面化しました：
- フォントサイズの計算は、画面ではなくスライドから来なければなりません。 16:9 のスライドは 960×540pt で、デザインキャンバスは 1920×1080px です。つまり
pt = px × 0.5— 直感的な 96dpi 換算ではすべての文字列が 50% 大きくなり、 テキストはあちこちで折り返されて衝突しました。 - レイアウトは、異なるフォントメトリクスでも生き残らなければなりません。 「大きな数字 + 小さなキャプション」のペアはブラウザでは美しく揃いましたが、グリフ幅の 異なる WPS では重なりました。縦に積むのは無敵です。固定オフセットで横並びにするのは 無敵ではありません。
- ジオメトリには lint が必要です。1枚の表紙画像がスライド端から 200px はみ出していました — 見つけたのはビルドではなく保護者の目でした。今ではすべてのシェイプが 保存前に境界チェックを受けます。
失敗 4：成果物を壊した検証
QA スクリプトはかつて、検証中に完成ファイルを本来の場所から動かしてしまいました — チェック
自体が、チェック対象を破壊したのです。さらに2つの静かな教訓も残りました：テキストの一括編集
には項目ごとの許容誤差と、残滓を探す leftover-grep が必要なこと。そしてチャートの
数字はソース文書の表からのみ取得すること — 小さなスクリーンショットから読み直してはいけません。
そこではかつて 4.62 が 5.89 になりました。
プロダクトで変わったこと
これらはすべて、今やエージェントのスキルセットに書き込まれたルールです — すべてのユーザーが 得るのと同じスキルです。配布状態の不変条件（外部参照ゼロ、ハッシュ検証済み）、エクスポート パイプラインの限界、python-pptx のジオメトリとレイアウトのルール、1枚だけ試してから一括 ビルドする手法、そして引き渡す前に全ページをレンダリングする QA ループ。生の記録もワーク スペーススキルとして残したので、実プロジェクトの教訓は蒸発せずに積み上がります。
これが「AI がスライドを作る」の誰もデモしない部分です：ファイルは学校のノート PC、WPS 環境、 プロジェクターへの旅を生き延びなければなりません。「プレビューでは素晴らしく見える」と 「どこでも正しく開く」の間のギャップこそが、クラフトが宿る場所です — だからこそ私たちは実際の タスクを自分たちのプロダクトに通し、壊れた箇所をすべて書き留めます。
同じパイプラインを Document to Slides で試せます — プレビューは無料、クリーンなファイルが欲しい場合だけ支払います。