# Google ドキュメントを AI に作らせる時の落とし穴 — 「本文は更新できない」前提で設計する AI エージェント（MCP 経由の Drive 連携など）から Google ドキュメントを作って人に渡す運用は、 一度作ったあとの**更新**でつまずく。原因は Drive API のファイル更新が「メタデータ更新」と 「本文アップロード」で別物なのに、多くの連携ツールが**メタデータ側しか実装していない**ことにある。 知らずに始めると「直すたびに URL が変わる文書」を人に配ってしまう。 以下は実際に踏んだ4つの落とし穴と、最初からこうしておけばよかったという設計。 --- ## 1. 本文の更新手段が無い（最重要） 多くの Drive 連携ツールの「ファイル更新」は**タイトルと親フォルダ（移動）だけ**を変える。 本文の差し替えはできない。したがって内容を直す唯一の道は: 1. 新しい内容で**別のファイルとして作り直す** 2. 読み返して内容を確認する 3. **旧版をゴミ箱へ移す**（完全削除はしない） この結果 **ファイル ID と URL が必ず変わる**。ここから2つの設計上の結論が出る。 - **Doc の URL を配布物・手順書・コード・チャットのピン留めに埋め込まない。** 埋め込むと、直した瞬間に全員のリンクが古い版を指す。 - 人に繰り返し渡す文書なら、**URL が変わらない置き場**を1つ用意し、そこから Doc を指す。 「フォルダを渡す」「タイトルで検索してもらう」「安定 URL のページから Doc へリンクする」のいずれか。 作り直しは本文を丸ごと再送するのでトークンも食う。**推敲は Doc の外で終わらせてから1回で上げる**。 ### 事前に確認する 着手前に、使う連携ツールの更新系の説明文を読み、`title` / `parentId` 以外を受け取るか確認する。 受け取らないなら、この記事の前提がそのまま当てはまる。 --- ## 2. Markdown 記号がエスケープされて表示される `text/plain` で本文を上げると Google ドキュメントへ変換されるが、このとき `#` `-` `*` などの Markdown 記号は**エスケープされて `\#\#` のように画面に出る**。 Markdown をそのまま流し込むと、見出しが全部壊れた文書が人に届く。 **プレーン整形で書く。** 記号を装飾に使わず、文字そのもので構造を作る: ■ 1. 章タイトル ◆ 小見出し 　01　手順を全角スペースでぶら下げる 　02　… ・箇条書きは中黒 　→ 補足は矢印 見出しスタイル（Heading 1 等）を後から当てたいなら、それは変換では付かない。 構造が重要な文書は、**そもそも Doc ではなく HTML やページとして配る**方が早い。 --- ## 3. 作成レスポンスの `fileSize` を成功判定に使わない 変換を伴う作成では、レスポンスの `fileSize` が **`1`** のような無意味な値で返ることがある。 これは失敗ではない。逆に、ここが正常値でも本文が空のことはある。 **判定は必ず読み返しで行う。** 作成 → 本文取得 → 期待する文字列（節見出し、決定事項、日付など）が 入っていることを確認する。読み返しをスキップして「作成しました」と報告するのは、 やっていないのと同じ。 --- ## 4. 大きな読み返し結果はローカルに落ちる（むしろ安い経路） 本文取得の結果がコンテキスト上限を超えると、**エラーではなくローカルファイルに全文が保存され、 そのパスが返る**ことがある。これは失敗ではなく、**コンテキストを消費しない安い経路**なので、 大きな文書ではむしろ狙って使う。 落ちたファイルは `{fileContent: "..."}` の JSON。2点だけ注意がある。 - **`fileContent` は表示用にエスケープされている。** `\_` `\#` `\[` のような JSON 規格外のエスケープが混ざるため、そのままでは JSON パースが落ちる。先に外す: const clean = body.replace(/\\(?!["\\/bfnrtu])/g, ""); - **この正規表現をシェル経由のワンライナー（`node -e "..."` など）に渡すとバックスラッシュが 食われて壊れる。** 必ずスクリプトファイルに書いて実行する。層をまたぐ argv に バックスラッシュ・バッククォート・`$` を含む文字列を載せない、という一般則の一例。 --- ## まとめ: 最初からこう設計する | 決めること | 結論 | | --- | --- | | 本文の推敲 | Doc の外（ローカルのファイル）で完成させてから1回で上げる | | 本文の整形 | Markdown 記号を使わずプレーン整形（■ ◆ ・ →） | | 人に渡すリンク | 変わらない置き場を1つ作り、そこから Doc を指す。Doc の URL 直貼りは避ける | | 更新の手順 | 作り直す → 読み返して確認 → 旧版はゴミ箱へ（完全削除しない） | | 成功の判定 | 読み返して期待文字列を確認。レスポンスのサイズ値は見ない | | 大きな読み返し | ローカル保存経路を歓迎し、スクリプトファイルで解析する | この6行を先に決めておけば、「直すたびにリンクが変わる」「見出しが `\#\#` になっている」 「上げたつもりで空だった」の3つは起きない。 ---