はじめに

日々の開発で、Claude や Codex に何のハーネスも与えずに HTML 資料を作らせていた。すると後で見返すときに「どこに置いたっけ」となり、探すために AI に聞くことすらあった。そこで資料の「置き場」を作り、AI には JSON で書かせて、ブラウザで描画・編集できる仕組みにした。

GitHub - GentaAmeku/ai-handout-studioTurn a conversation with Claude Code or Codex into slides, HTML documents and question sheets — design templates, PDF/PPTX/HTML export, and a gamebook-style setup. - GentaAmeku/ai-handout-studioGitHub

AI が作った資料の課題感

1. 資料が散らばる

セッションのプロジェクトが違えば、そのフォルダに HTML や PPTX が生まれ、あとで探しづらい。 全体で確認できるようにプロンプトを変えると、ホームの tmp/ のような場所に作りがち。

2. 修正時にトークン消費がかかる

「ここだけ直して」という指示が多く、資料の確認と修正を繰り返すたびにトークンを消費する。 見た目の直しも重なるので、スライド資料だとより面倒だった。

3. 資料毎の見た目にバラツキがある

複数の AI エージェントをまたいで使っていて、かつデザインシステムもハーネスも作っていない場合に起きがちで、デザインに統一感がない。

AI Handout Studio

AI に全てを任せて作ってもらうより、まず「置き場」を用意して JSON 形式で作ってもらい、その後は WebUI で見た目の変更や内容の微調整を行えるようにした。

資料一覧

どのフォルダの会話から頼んでも、できた資料はここに並ぶ。検索とお気に入りがあり、同じネットワークならスマートフォンからも開ける。

資料編集

WebUI 上で、作られたものを仕上げる。HTML 資料は1枚の HTML に書き出せる。

テンプレート編集

デザインテンプレートも WebUI 側で設定でき、レイアウトやフォントサイズも調整できる。

仕組み

構成図

構成図。AI エージェントがスキルを読み、CLI で JSON を保存し、ローカルサーバーがテンプレートの CSS を当てて描画・編集・書き出しをする

資料の正本はJSON1つ

AI が書くのは JSON 1ファイルだけ。文章と構造だけを持ち、色や余白は持たない。たとえば HTML資料の document.json はこんな形になっている。

{
  "title": "社内での AI エージェント利用状況 調査結果",
  "summary": { "label": "要約", "text": "結論を先に書く" },
  "toc": "auto",
  "sections": [
    {
      "heading": "分かったこと",
      "blocks": [
        { "type": "table", "props": { "headers": ["用途", "人数"], "rows": [["コードを書かせる", "10"]] } },
        { "type": "text",  "props": { "text": "人数は聞き取りで「使っている」と答えた人を数えた。" } },
        { "type": "cards", "props": { "columns": 3, "items": [{ "title": "はじめての人の理由", "body": "…" }] } }
      ]
    }
  ]
}

章の中に「表」「本文」「カード」といったブロックを並べるだけで、それをどう描くかはアプリとテンプレートが決める。数値や固有名詞は依頼にあるものだけを使い、分からないところは [[要確認]] と書かせる。保存はコマンドが行うので、AI は置き場のパスも知らなくてよい。

似たツールとの違い

AI に JSON を書かせてアプリが描く発想は、Presenton や AWS の Spec-Driven Presentation Maker にもある。違いは、どのフォルダの会話からでもエージェントが直接保存すること、スライド・HTML 資料・質問票を同じ置き場で扱うこと、そして人が仕上げる画面を省かないことの3点。Marp や PPTX Skill との違いは、中間物が Markdown や HTML ではなく、見た目の語彙を持たない JSON であること。

スライド資料

スライドも同じで、AI が作ったあとにテンプレートの変更、レイアウトの微調整、テキストの変更やパーツの配置を画面で行える。書き出しは PNG・HTML・PPTX・PDF に対応している。

スライド編集

質問票：AskUserQuestionをもっと見やすく、認知負荷を下げる

Claude には AskUserQuestion のツールがあるが、あの形で質問が来ると認知負荷が高く、「はい、推奨で…」となりがちだった。 そこで AI Handout Studio の仕組みを使い、HTML として視覚的に分かりやすい質問を作らせて、読む負担を下げた。 また「置き場」でもあるので、過去にどんな質問が来て、どう答えたかを見返せる。

質問票

答え終わると、回答が Markdown でクリップボードに入る。会話へ貼ると、エージェントが続きを進める。

おわりに

AI が作った資料を画面で直せるようにしたことで、見た目の直しを AI に頼む往復がなくなった。 セットアップコマンドが用意されていて、ゲームブック形式でインストールできるので、気になった方は試してみてほしい。