LLM で既存スプレッドシート明細の「更新案」を作る — 本番で壊れない書き方（GAS）

既存の見積・発注・在庫などの明細シートを、議事録やメールの最新情報から LLM に更新させ、人がそのまま貼り付けて反映できる「更新案シート」を作る手順。本番 6 回の失敗から確定した設計をそのまま書く。

ゴール

• 元シートは触らない。元シートの複製に更新案を書き、ユーザーが A〜G 列を「値のみ貼り付け」すれば本体へ反映できる。
• 右側の空き列に 変更種別／変更前値／根拠／原価 などの補助列を置き、貼付範囲（A〜G）と分離する。
• 顧客向け説明文も別シートに作る。

設計 7 か条（失敗順）

1. 見出し行は SS 全体から探す。「管理画面」と「明細」は別シートに分かれていることがある。見出し判定はラベル一致（例: A='カテゴリ' B='項目' E='単価'）で行い、シート名を決め打ちしない。
2. LLM に「全行を順序どおり返せ」と要求しない。現行 10 行に対し 28 行が返るのが普通。現行各行に 1 始まりの rowIndex を振って渡し、LLM には「変更・削除する行だけ rowIndex 付きで返す。新規は rowIndex:null」と指示。言及の無い行はコード側で自動「据置」。存在しない rowIndex は無視して確認事項に積む。
3. 明細は元の行位置に書く。見出し直下から詰めて書くと、テンプレのガード行（案内文・カテゴリ見出し・空行）とズレて値が落ち、SUM 範囲も壊れる。各現行行に sheetRow を持たせ、据置/変更はその行へ、削除はその行の A〜G を空欄に（行は消さない）、新規は現行最終行の直後に 1 回の insertRowsAfter でまとめて挿入し、小計列の数式は最終行から copyTo で延ばす。
4. 合計・差分・変更種別はコードで計算。LLM の足し算を信じない。金額が読めない行は現行値に据え置き、確認事項へ。
5. LLM API に渡す system/cached ブロックは空文字を除去。議事録が空・マニュアルがヒットしない時に空ブロックが混じると text content blocks must be non-empty の 400 で落ちる。
6. 書込後の read-back は正規化比較＋非致命。String(v).trim()／数値は Number で比較し、不一致は verify.mismatches と確認事項に残して ok を返す。成果物を書いた後の記録処理（ログ・通知・台帳）も個別 try/catch で postErrors に積む。全部書けているのに最後の 1 行で全体失敗にすると、LLM 3 分ぶんが無駄になる。
7. 顧客向け文は 2 系統の理由を取る。reason（社内向け・率直に）と customerReason（顧客にそのまま見せる一言・20 字以内）を LLM に別フィールドで書かせ、顧客文は後者だけ使う。さらに 原価|粗利|仕入|要確認|未読込|未確認|社内 と仕入先名を含む行はガードで削除し確認事項へ。

出力 JSON の形

{"mgmtFields":[{"label":"","value":""}],
 "detailRows":[{"rowIndex":null,"category":"","itemName":"","spec":"","note":"","unitPrice":0,"qty":1,"unit":"式",
   "change":"新規|変更|据置|削除","before":{"unitPrice":0,"qty":0},"reason":"","customerReason":"","source":"",
   "cost":{"amount":0,"source":"","confidence":"high|mid|low"}}],
 "customerLetter":{"subject":"","greeting":"","closing":""},
 "confirmations":[{"category":"","content":""}]}

source は根拠（議事録の日付／メール件名／ファイル名）を必須にし、根拠の無い変更は現行値へ戻す。

検証

• 純関数（突合・合計・顧客文ガード・行位置計算）を分離して単体テスト。スタブシートで「ガード行は書込も clear もされない」「L/M 数式列は触らない」を検証。
• 本番は 1 案件で実行し、生成シートのセルを読み戻して（シート名・行番号・A〜M）目視する。シート読取は MCP の文書読取では値が取れないことがあるので、GAS 側に readCells(ssId, sheetName, a1Range) 相当のデバッグ関数を用意しておく。