社内フィードバックを毎日AIの作業キューへ自動取り込みする（安全ゲート付き）

何を解決するか

社内アプリに「不具合・要望フォーム」を付けると、投稿はスプレッドシートやDBに溜まる。 ここで 溜めるところまで作って満足し、それを読むジョブを作り忘れる のが典型的な失敗になる。 結果、報告は誰にも気付かれず埋もれ、担当者が口頭で伝えたときだけ着手される。フォームがある分だけ質が悪い （利用者は「出したのに何も起きない」と学習し、二度と使わなくなる）。

この指示書は、溜まった要望を毎日自動で取得し、AIコーディングエージェントが次に読む作業キューへ積む 仕組みの作り方をまとめたもの。ただし「拾ったものを無人で実装させる」ことはしない。理由は後述の安全ゲートの節にある。

全体構成

フォーム投稿 → 台帳シート(状態=new)
                    │
                    │ ① 認証付きの読み取りAPI(未対応行のJSON)
                    ▼
        日次ジョブ(cron/スケジュールタスク)
                    │ ② 引き継ぎファイルの「残TODO」へ追記(冪等)
                    ▼
        AIエージェントの無人セッション ──③ 安全ゲートで着手しない──> 人がGOを出した分だけ実装
                    │
                    │ ④ 完了したら状態=done を書き戻す
                    ▼
                台帳シート

手順

1. 読み取りAPIを1本生やす

台帳がスプレッドシートなら、それに紐づくスクリプト実行環境（Google Apps Script 等）に token 認証付きの GET を1本足し、未対応行だけを JSON で返す。

{ "ok": true, "sheetUrl": "<台帳のURL>", "counts": { "open": 2, "total": 3 },
  "items": [ { "key": "<一意キー>", "rowNumber": 4, "ts": "2026-01-02 12:30",
               "kind": "要望", "title": "…", "body": "…", "status": "new",
               "note": "", "source": "<投稿画面>", "images": [] } ] }

注意点:

• 既に別用途のエンドポイントがある場合は action= で分岐させ、token 検証を分岐より前に置く。 既存経路の応答は1バイトも変えないこと（本番で他システムが叩いている）。
• 返り値に日時オブジェクトを混ぜない。 全部プリミティブ（文字列・数値・配列・真偽値）にする。 日時型はシリアライズ経路で静かに壊れる。「返り値のどの値も日時オブジェクトでない」ことをテストで固定する。
• 「未対応」の判定は正規化して比較する（前後空白除去・小文字化・done/完了/却下/見送り 等を対応済みとみなす）。
• 本文は長さ上限で切る（数千字）。切ったことが分かる印を付ける。
• 書き戻し（状態=done ＋ 対応メモ追記）は POST 側に用意し、排他ロックを取る。人が同じシートを手で編集している。 対応メモは既存の値を消さず [日付] 内容 を追記する。
• キー生成規則、未対応判定、日時整形は純関数に切り出して単体テストする。API本体はスタブしたシートで叩く。

2. 一意キーの決め方

• フォーム側が受付IDを発行しているならそれを使う（行の並べ替えに強い）。
• 受付IDが無い古い行だけ row<行番号>-<yyyyMMddHHmm> にフォールバックする。
• 行番号だけをキーにしてはいけない（並べ替え・行挿入で別物を指す）。

3. デプロイの落とし穴

スクリプトをアップロードしただけでは公開版に反映されない環境がある（Apps Script はまさにこれ）。 公開URLはバージョン固定なので、既存のデプロイIDを指定して再デプロイする必要がある。 開発用の「最新コードを指すデプロイ」はログインを要求するため cron からは使えない。

再デプロイ後は、新しい機能が生きていることと、既存の経路が壊れていないことを両方 curl で確認する。 既存経路が壊れて見えたときは、変更前のバージョンを一時デプロイして同じ入力を投げ、 自分の変更が原因かを切り分けてから報告する（一時デプロイは確認後すぐ削除する）。

4. 取り込みジョブ

日次ジョブが API を叩き、エージェントが次に読むファイル（引き継ぎ用 Markdown の「残TODO」節など）へ追記する。

• 追記は「読む → 1回書く」。対象の節以外のバイト列が変わっていないことをテストで固定する。 他の節を巻き添えで壊すと、人間の作業メモが消える。
• 番号付きリストなら続き番号を検出して振る。
• 冪等性は二重に持つ:
  1. 本文に一意キー [FB:<key>] が既に在るか
  2. 台帳JSON（{ "<key>": { "firstSeen":…, "injectedAt":… } }）に注入済み記録があるか
• 本文の存在を正、台帳を履歴として扱う。 台帳に注入済みと書いてあっても、 本文から消えていて、その項目がまだ未対応なら再注入する。 引き継ぎファイルは他のセッション・他の人が丸ごと書き直すことがあり、 「台帳だけを見る」実装では消えた項目が二度と積まれない（実際にそれで2件消えた）。
• 取得失敗・タイムアウト・HTML（ログイン画面）が返ってきたときは、ファイルを書かずに正常終了(exit 0) する。 cron を赤くしないため。人が結果を知りたい操作（状態の書き戻し）だけ非ゼロ終了にする。
• HTTPには明示的なタイムアウトを付け、リダイレクトを追う設定にする。

5. 実行時刻

無人セッションの開始時刻より前に取り込みを走らせる（例: 03:00 取り込み → 03:20 無人セッション）。 後ろにすると、その日の要望が作業キューに乗るのが丸1日遅れる。

安全ゲート（この仕組みの肝）

取り込んだ項目を無人エージェントにそのまま実装させてはいけない。 任意の社員が自由記述で書いた文章が、レビューなしに本番コードを書き換える経路になるため。

実現方法はシンプルで、無人実行側が既に持っている「着手しない条件」に引っかかる語を、 取り込む項目の文面へ必ず含めること（例: 文末に「着手可否は担当者の判断待ち」と入れる）。 これで無人セッションはその項目を飛ばし、人が読んで GO を出したものだけが実装に進む。

そして その除外判定関数を実際に読み込んで、取り込んだ文面が除外されることを回帰テストで固定する。 「安全ゲートを設計した」だけでテストが無いと、後日の文面変更で静かに外れる。外れても誰も気付かない種類の欠陥になる。

テストで固定すること

1. 新着が対象セクションの末尾へ、続き番号で追記される
2. 追記された行に一意キーと除外語が含まれる
3. 同じ入力で2回流しても増えない（台帳あり／台帳を消しても本文キーで冪等、の2ケース）
4. 台帳に注入済みと書いてあっても、本文から消えた未対応項目は再注入される
5. 対象セクション以外のバイト列が変更前と完全一致
6. 対象セクションが無いファイルでも落ちずにセクションを作る
7. API が ok:false / タイムアウト / HTML を返したとき、ファイルを書かずに exit 0
8. 除外判定関数を import して、追記した文面が実際に除外されること

よくある失敗

• テストが片方のOSでしか通らない。 エージェントに書かせたテストが POSIX パス決め打ちで、 Windows 上では I/O スタブのキーと一致せず落ちた。テスト内のパスは実行環境の区切り文字で組み、 CI は Linux と Windows の両方で回す。
• 通知が二重に鳴る。 フォーム投稿時に通知が飛ぶなら、取り込みジョブからは送らない。 同じ出来事で2回鳴らすと、人はどちらも読まなくなる。
• 既存行の棚卸しを忘れる。 取り込みを作った時点で、既に実装済みなのに状態が new のまま溜まっている行がある。 最初に一度だけ棚卸しし、完了済みは書き戻し、部分実装は「どこまで出来て何が残っているか」を対応メモに残す。 これをやらないと、初回に古い要望が一斉に作業キューへ流れ込む。
• 一意キーを行番号にする。 並べ替えた瞬間に別の要望を指す。
• デプロイ更新を忘れて「実装したのに動かない」と誤診する。 アップロードと公開は別工程。