# 投稿審査を自動化する — 機密は決定的に落とし、重複はグループで1本に寄せる ユーザー投稿（記事・テンプレート・指示書・ナレッジ）を受け付けるサービスで、**承認が人手のままだと審査待ちが必ず滞留する**。この指示書は、審査を毎日1回の無人バッチで回し、滞留を常時ゼロ付近に保つ実装手順。AI エージェントに読ませればそのまま作れる粒度で書いてある。 対象読者: 投稿キューを持つ Web サービスの開発者／その開発を任された AI エージェント。 --- ## 0. 前提と成功条件 **前提** - 投稿レコードに `id / title / summary / body / 投稿者 / 投稿日時` がある - 管理用の API トークンを1本発行できる（環境変数で渡す） - 分類寄りの判定に使える安価な LLM が1つある（大きいモデルは不要。これは分類タスク） **成功条件（ここまで満たして「できた」）** 1. `--dry-run` で審査待ち全件の判定表（ID / 日付 / 判定 / 理由）が出る 2. 機密スキャンの単体テストがある（検知すべき例と、誤検出してはいけない例の両方） 3. 実適用を1回走らせ、**審査待ち件数が減ったことを API で読み直して**確認できる 4. 定期実行に登録し、**実際に1回起動して終了コードとログを確認**できる（登録できたことは動作の証拠にならない） --- ## 1. 判定は3段。LLM を使う場所を間違えない 落とす順に ①→②→③。前段で決まったものは後段にかけない。 | 段 | 何を見るか | 判定者 | 迷ったとき | |---|---|---|---| | ① 機密・危険情報の残存 | 本文にメール・実IDトークン・鍵・内部ホスト名等が残っていないか | **正規表現（決定的）** | ヒットしたら却下 | | ② 同主題の重複 | 同じ話が2本並んでいないか | 候補出しは機械、同主題か否かだけ LLM | 却下せず保留 | | ③ 一般化不足・再現不能 | 読者がこの文書だけで再現できるか | LLM | 却下せず保留（needs-human） | **①に LLM を使ってはいけない。** 見逃しの被害（秘密の公開）が非対称に大きく、判断がブレる余地を残せない。逆に③は機械では書けないので LLM に任せる。②は「候補出しは機械・最終判断は LLM」に割ると、全件を LLM に投げずに済んでコストが1桁減る。 **重要な非対称性**: 公開の取り消しは難しく、却下は書き直して再投稿できる。だから**迷ったら却下せず保留**にする。逆にしてはいけない（「とりあえず承認」は取り返せない）。 --- ## 2. ① 機密スキャン（決定的） 1ルール1関数にして、ルールごとに最初の1件だけ返す。ルール名・ラベル・**伏せ字化したサンプル**（先頭4文字＋…）を返すとログに秘密が残らない。 検知する対象: - メールアドレス、電話番号 - クラウドのファイルID・共有URL（ドキュメント／表計算／ストレージ） - Webhook URL、`Bearer <実トークン>`、`password: <実値>` - API キー（プロバイダごとの接頭辞。**自社が発行する接頭辞も必ず入れる**） - 秘密鍵ブロック、パスワード込みの DB 接続文字列 - 社内トンネル・内部ホスト名 - 個人のホームディレクトリを含む絶対パス - 実在の社名・顧客名（**環境変数で語彙を渡す**。既定は無効にしておく） ### 誤検出で審査が破綻する4パターン（実測で踏んだもの） ここを外すと「全部却下」になって使い物にならない。 1. **穴埋め記法**: `https://docs.example-cloud.com/document/d//export` は機密ではない。 URL 抽出の正規表現は `<` の手前で切れるので「プレースホルダ判定」が効かない。 → **URL のパスに実IDらしい区間（25文字以上の英数字）があるときだけ**ヒットさせる。 2. **変数名・環境変数参照**: `API_KEY: keyReadFromSomewhere` や `token: process.env.MY_TOKEN` は秘密ではない。 → 値が「英字と数字が混在」または「区切り文字入りで16文字以上」の時だけ秘密とみなし、 `process.env` / `os.environ` 参照や `ALL_CAPS` の環境変数名は除外する。 3. **設定ファイル名**: `.env.local` / `settings.local.json` は内部ホスト名ではない。 → `.local` を内部ホスト名のルールに入れない（`.internal` / `.lan` 等に限る）。 4. **汎用アカウント名**: Windows のユーザーフォルダ配下（パスの の次の区間がアカウント名になる形）や 配下は個人を特定しない。 → `user / username / you / admin / runner / ubuntu / root` 等は除外リストに入れる。 除外しないと、ほぼ全ての手順書が落ちる。 **バージョン番号を電話番号と誤認する**のもよくある（`0.147.0` など）。数字列は前後が数字でないことを境界条件にし、桁数で絞る。 単体テストは「検知すべき17ケース」と「誤検出してはいけない8ケース」を必ず両方書く。片方だけだと、緩めた時にも締めすぎた時にも気付けない。 --- ## 3. ② 重複（ここが一番設計を間違えやすい） ### 「数が多いほど良い」は成り立たない 同じ主題が2本並ぶと、読む側が毎回「どちらが正しいか」を判断させられ、探す時間が増える。**1主題1本**を保つことがサービスの価値になる。 ### 候補出し（機械） 題名の**文字 bigram の Dice 係数**と、題名＋要約の**語の重なり率**の大きい方を類似度とし、しきい値 0.3 で候補を出す。 日本語は空白で語が切れないので、語集合は「ASCII の単語（2文字以上）∪ 正規化後の文字3-gram」の和集合にする。空白分割だけに頼ると、日本語の題名がひとかたまりになって重なりが常に 0 になる。 ``` similarity(a, b) = max( bigramDice(a.title, b.title), wordOverlap(a.title + a.summary, b.title + b.summary) ) ``` ### 最終判断（LLM）— ただし「どちらを残すか」は聞かない 候補が出た組だけ LLM に投げる。**LLM に聞くのは2つだけ**: 1. `same`: 同じ問題・同じ対策を扱っているか（語が重なっていても別問題なら false） 2. 各投稿が本文で実際に扱っている項目: `detect`(検出) / `fix`(対策) / `verify`(検証) / `pitfalls`(前提・落とし穴) 残す1本の決定は**コード側**でやる: 網羅項目が多い方を残し、同数なら先に投稿された方を残す。 「どちらを残すか」を LLM に直接聞くと、返ってくる理由が「より詳細で古いため」のように**基準が混ざる**。事実抽出（何が書いてあるか）と方針（何を優先するか）を分けると、判定根拠が後から検証できる。 > **注意**: 類似度が高くても別主題のことがある。例えば「CIジョブが skipped のまま緑にならない」と > 「CIから自ホストへの配達が届かない日を成果物から埋める」は語が重なるが別問題。機械判定は候補出しまでにとどめる。 ### ペア単位で決めると壊れる（実害） ペアごとに「残す側」を決めると、**ある組で残した投稿が別の組では却下される**。3件以上が同主題のとき必ず起きる。実測では7件が同主題のグループで、残すはずの2件が却下側に回っていた。 → `same=true` を辺とする**グラフの連結成分**を作り、**成分ごとに survivor を1本だけ**決めて、残りを `supersededBy=` 付きで却下する。survivor は一度決めたら以後どの組でも却下しない。 ``` 辺: same=true のペア 成分: Union-Find で連結成分を作る survivor: 成分内で「網羅数が最大 → 同数なら投稿が古い → それも同じならID順」 却下: 成分の残り全部（理由に survivor の題名を入れる） ``` ### 人の指定が機械判定を上書きできる経路を作る 運用すると必ず「この組はこっちを残したい」が出る。そのとき**基準を書き換えて曲げるのではなく**、上書き用のファイル（`review-overrides.json` 等）に `keep / over / source / note` を書いて人の判断を優先させる。判定表には「人の明示指定」と出す。基準を曲げると他の全ての判定が壊れるが、上書きは1件で閉じる。 --- ## 4. ③ 品質（LLM） `title / summary / 本文の先頭3000文字` を渡し、次を判定させる。 - 読者がこの文書だけで再現できる手順になっているか - 前提条件・成功判定・失敗時の対処が書かれているか - 特定の1組織の業務フローに密着していて他所で使えない内容ではないか - 作業日記（「調べた」「直った」だけ）になっていないか 出力は `{"verdict":"ok"|"reject"|"unsure","reason":"..."}` の JSON のみ。**`unsure` と呼び出し失敗は却下しない**（needs-human）。却下理由は投稿者がそのまま書き直せる文にする（「前提条件・手順・成功判定・失敗時の対処を追記して再投稿してください」）。 --- ## 5. 保存側の落とし穴（ここで2回事故った） ### 5-1. 「却下」を保存する場所が無い設計 `status` を持たず「公開棚に載っているか」で状態を導出している設計は珍しくない（二重管理を避ける狙い）。だがこの設計だと**却下を記録する場所が無い**。却下しても状態APIは永久に `pending` を返し、審査待ち件数も減らない。 → 却下ストア（`rejections`）と保留メモ（`needs-human`）を別に持ち、状態の導出を `公開済み → published / 却下済み → rejected / それ以外 → pending` に変える。 却下レコードには **理由・ルール・supersededBy・日時・実行者**を残す。投稿者が理由を読んで書き直せることが目的。 ### 5-2. ストア障害が「空データ」に化けて二重公開を招く（fail-open） 表示側の耐障害性のために「読めなかったら最後に読めた値／空を返す」実装は普通にある。しかし**審査経路がそれを信じると「全件が審査待ち」に見え、既に公開済みのものを再承認して二重公開する**。 → 審査・承認の経路だけ **fail-closed** にする。「公開棚が空 かつ 投稿が一定件数以上」なら 503 で中断させる。判定を止める方が、間違って公開するより安い。 ### 5-3. GitHub をデータストアにしている場合の 1MB 壁 Contents API は **1MB を超えるファイルの本文を返さない**（`content: ""` / `encoding: "none"`、HTTP は 200 のまま）。棚のファイルが 1MB を越えた瞬間に「読めたのに空」になり、公開中の一覧が静的分だけに転落する。ファイル自体は無傷なので原因が見えにくい。 → 本文が空なら同じ sha を **Blobs API（100MB まで）で読み直す**フォールバックを最初から入れる。blob は sha 固定＝不変なのでキャッシュしてよい（静的生成される経路から `no-store` で叩くとビルドが動的化するので、キャッシュ指定は呼び出し元に合わせる）。数MBに達する前に分割保存へ移す。 --- ## 6. バッチの安全弁（緩めない） - **既定は dry-run**。`--apply` を明示しない限り書き込みゼロ。判定が妥当だと確認できてから適用に切り替える - **1回のバッチで却下できる上限**（既定10件）。基準がバグっていた時の被害を有限にする。 超過分は**黙って捨てず**「今回は N 件を次回へ繰り越し」と表示する - **冪等**。同じ投稿を二度処理しない（公開済み／却下済みは skipped 理由付きで返す） - **第三者投稿は自動承認しない**。信頼済みフラグは設定次第で緩むので、 「許可ドメイン」の二重ガードを持つ。実測で、信頼済みリストに外部のフリーメールが1件混ざっていた - **判定根拠を必ずログに残す**（LLM の生の判定・類似度・機密ヒットを JSON で保存）。 「なぜ通したか / なぜ落としたか」が追えないと基準を直せない - LLM 呼び出しは同時4件程度・失敗時1回だけ再試行。2回失敗したら needs-human --- ## 7. 検証（この順に実測する） ``` 1. 単体テスト : 機密スキャン（検知/誤検出の両方）＋類似度＋同主題の実例が候補に入ること 2. HTTPテスト : 認証401 / dryRunは書き込まない / 却下すると審査待ちから消え状態APIが rejected を返す / 二度却下しても増えない / 却下上限 / needs-human は保留のまま / 空指示は400 3. 実適用1回 : 適用後に API を読み直して「審査待ちが実際に減ったこと」を確認する（実行して終わりにしない） 4. 投稿者視点 : 却下された投稿の状態APIが rejected と理由を返すことを、投稿者のキーで確認する 5. 定期実行 : 登録して終わらせず、手動で1回起動し「終了コード0」とログの中身を確認する ``` 4 と 5 を省くと「動いたつもり」で終わる。特に 5 は、登録だけして実行時に環境変数やカレントディレクトリが違って落ちるのが定番の失敗。**バッチはトークンを環境変数だけに頼らず、設定ファイルからも読めるようにしておく**と、定期実行側に秘密を書かずに済む。 --- ## 8. AI エージェントへの実装指示（そのまま渡せる形） ``` 次の3段の審査バッチを実装してください。 ① 機密スキャン: 正規表現のみ。1ルール1関数、伏せ字サンプルを返す。 誤検出テスト（穴埋め記法・環境変数参照・設定ファイル名・汎用アカウント名・バージョン番号）を必ず書く。 ② 重複: 題名 bigram Dice と 語の重なり率（日本語は文字3-gram を語に混ぜる）の最大値、しきい値0.3で候補出し。 候補だけ LLM に投げ、聞くのは「同主題か」と「detect/fix/verify/pitfalls のどれを本文で扱っているか」だけ。 same=true を辺として連結成分を作り、成分ごとに survivor を1本決める（網羅数→古い順→ID順）。 残りを supersededBy 付きで却下する。人の明示指定ファイルがあればそれを最優先。 ③ 品質: LLM に verdict(ok|reject|unsure) を出させる。unsure と失敗は却下せず needs-human。 安全弁: 既定 dry-run / 却下上限10 / 冪等 / 第三者は自動承認しない / 判定根拠をJSONログに保存。 状態管理: 却下ストアを別に持ち、状態は 公開済み→published, 却下済み→rejected, それ以外→pending で導出。 検証: 単体テスト → HTTPテスト → 実適用1回 → 適用後にAPIを読み直して件数減を確認 → 定期実行を1回手動起動して終了コード確認。 ``` ## 9. コスト感 LLM を使うのは「候補が出た組の同主題判定」と「品質判定」だけなので、投稿100件規模でも安価な分類向けモデルで十分（実測で1回の全件審査が数円）。全件を大きいモデルに投げる設計にすると2桁変わる。**判定の大半は正規表現と類似度で決まる**ことを忘れないこと。 ---