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つは起きない。