# 社内フィードバックを毎日AIの作業キューへ自動取り込みする（安全ゲート付き） ## 何を解決するか 社内アプリに「不具合・要望フォーム」を付けると、投稿はスプレッドシートやDBに溜まる。 ここで **溜めるところまで作って満足し、それを読むジョブを作り忘れる** のが典型的な失敗になる。 結果、報告は誰にも気付かれず埋もれ、担当者が口頭で伝えたときだけ着手される。フォームがある分だけ質が悪い （利用者は「出したのに何も起きない」と学習し、二度と使わなくなる）。 この指示書は、**溜まった要望を毎日自動で取得し、AIコーディングエージェントが次に読む作業キューへ積む** 仕組みの作り方をまとめたもの。ただし「拾ったものを無人で実装させる」ことはしない。理由は後述の安全ゲートの節にある。 ## 全体構成 ``` フォーム投稿 → 台帳シート(状態=new) │ │ ① 認証付きの読み取りAPI(未対応行のJSON) ▼ 日次ジョブ(cron/スケジュールタスク) │ ② 引き継ぎファイルの「残TODO」へ追記(冪等) ▼ AIエージェントの無人セッション ──③ 安全ゲートで着手しない──> 人がGOを出した分だけ実装 │ │ ④ 完了したら状態=done を書き戻す ▼ 台帳シート ``` ## 手順 ### 1. 読み取りAPIを1本生やす 台帳がスプレッドシートなら、それに紐づくスクリプト実行環境（Google Apps Script 等）に token 認証付きの `GET` を1本足し、**未対応行だけ**を JSON で返す。 ```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<行番号>-` にフォールバックする。 - 行番号だけをキーにしてはいけない（並べ替え・行挿入で別物を指す）。 ### 3. デプロイの落とし穴 スクリプトを**アップロードしただけでは公開版に反映されない**環境がある（Apps Script はまさにこれ）。 公開URLはバージョン固定なので、**既存のデプロイIDを指定して再デプロイ**する必要がある。 開発用の「最新コードを指すデプロイ」はログインを要求するため cron からは使えない。 再デプロイ後は、**新しい機能が生きていることと、既存の経路が壊れていないことを両方 curl で確認**する。 既存経路が壊れて見えたときは、**変更前のバージョンを一時デプロイして同じ入力を投げ**、 自分の変更が原因かを切り分けてから報告する（一時デプロイは確認後すぐ削除する）。 ### 4. 取り込みジョブ 日次ジョブが API を叩き、**エージェントが次に読むファイル**（引き継ぎ用 Markdown の「残TODO」節など）へ追記する。 - 追記は「読む → 1回書く」。**対象の節以外のバイト列が変わっていないこと**をテストで固定する。 他の節を巻き添えで壊すと、人間の作業メモが消える。 - 番号付きリストなら**続き番号**を検出して振る。 - 冪等性は**二重**に持つ: 1. 本文に一意キー `[FB:]` が既に在るか 2. 台帳JSON（`{ "": { "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` のまま溜まっている行がある。 最初に一度だけ棚卸しし、完了済みは書き戻し、部分実装は「どこまで出来て何が残っているか」を対応メモに残す。 これをやらないと、初回に古い要望が一斉に作業キューへ流れ込む。 - **一意キーを行番号にする。** 並べ替えた瞬間に別の要望を指す。 - **デプロイ更新を忘れて「実装したのに動かない」と誤診する。** アップロードと公開は別工程。 ---