# 「そのPCにしか直せない障害」をAIに自分で気付かせて着手させる指示書 複数PC・複数AIエージェントで開発していると、**特定の1台にしかリポジトリが無い機能**が必ず出てくる。 そこが壊れていても、他のPCのAIは「直せない」ことしか分からず、当のPCのAIは「自分が当事者だ」と気付かない。 結果、修正手順をドキュメントに書いても**誰にも実行されないまま放置される**。 この指示書は、その放置を機械的に終わらせる型をまとめたもの。実運用で発生した「審査キューが一度も処理されず、 API経由の投稿が8日で66件滞留し、最終的に94件まで積み上がった」障害を、この型で解消した実例に基づく。 対象読者は AI コーディングエージェント（Claude Code / Cursor / Codex 等）。そのまま読ませて実装させられる粒度で書いてある。 --- ## 前提となる状況 - ある機能の実装リポジトリが、チームの中の**特定の1台**にしかない（本人が別アカウントでデプロイしている等） - 他のPCからは、公開APIやデプロイ済みサイトを通じてしか触れない - 修正手順そのものは書ける。**書いた指示が当該PCへ届かない**ことがボトルネック 「ドキュメントに書いた」「オンボーディング資料に載せた」は届いたことにならない。 人が読んで気付く前提の仕組みは、**当事者が自分を当事者だと知らない**限り機能しない。 --- ## 1. まず「本当に他の経路が無いか」を潰す（ここを飛ばさない） 当該PCへ手渡しする前に、次を**実際に叩いて**確認する。想像で「無いはず」と判断しない。 - 公開APIに管理系・状態問い合わせ系のエンドポイントが本当に無いか、候補を総当たりする （`/api/v1/admin/...` `/api/v1/submissions` `/api/v1/me` `/api/v1/publish` `/api/v1/moderation` など）。 HTTPステータスを記録する。404 が並ぶことが「無い」の証拠になる - デプロイ先（Vercel 等）のプロジェクト一覧を自分のアカウントで列挙し、対象が**自分の管理下に無い**ことを確認する - ソース管理（GitHub 等）に対象リポジトリが無いことを、所有リポ一覧と検索の両方で確認する - 自分のPCのファイルシステムを走査し、対象リポジトリが無いことを確認する この4点の実測結果は、あとで「なぜ手渡しが必要だったか」の根拠になる。**根拠なしに人へ振らない。** --- ## 2. 当該PCのAIに自分で気付かせる（SessionStart hook） エージェントのセッション開始フックで、**そのPCに対象リポジトリがあるかを判定し、あった時だけ**指示を出す。 無ければ完全に沈黙する。全PCに同じフックを配って構わない。 ```js // 判定はパス構造で行う。本文 grep は遅すぎてフックに載らない // 例: Next.js App Router なら **/api/v1/<対象リソース> というディレクトリの存在で判定できる ``` 実装で外してはいけない点: - **探索先はエージェントが既に知っているプロジェクトパスを最優先にする**。 対象リポジトリがあるPCでは、そこでエージェントを開いている可能性が高い。 設定ファイル（`~/..json` の projects キー等）や、セッションログの先頭数KBから `cwd` を拾うのが速い。 スラッグ化されたディレクトリ名から元パスを**逆算しない**（区切り文字と元のハイフンが区別できない） - **時間予算で必ず打ち切る**（例: 全体4秒・1ルート1.5秒）。フックはセッション開始を止めてはいけない - **打ち切ったルートは次回セッションで続きから走査する**。走査済みルートをキャッシュに持ち越す。 これが無いと、毎回同じルートの先頭から始まって深い場所に永遠に到達しない - **走査しきれていない状態を「無い」と確定させない**。`found` / `absent` / `unknown` の3値で持つ。 同じルートで N 回連続で打ち切られたら諦めた印を付け、その事実も残す - 例外・パース失敗を含めて**必ず正常終了**する。フックが原因でセッションが止まってはいけない ### なぜ「時間予算だけ」では足りないか 最初の実装は予算切れで `unknown` を返して終わりだった。これだと**対象PCでも一度も指示が出ない**可能性がある。 さらにキャッシュのTTLが切れて再実行しても、毎回同じ順序で走査するので前進しない。 「打ち切り＝次回の続き」にして初めて、数セッション以内に必ず結論へ到達する。 --- ## 3. 完了したら指示書に状態を書き戻す（これを忘れると事故になる） **最重要。** 2 の仕組みは「対象PCで開くたびに指示を出す」。実装が終わったあとも同じ指示を出し続けると、 そのPCのAIは**毎セッション作り直しに走る**。 - 指示書の先頭を「実装済み（日付）。再実装しないこと」に書き換える - 残っている作業だけを独立した節（例: `§6 残作業`）にまとめ、フックの文言も 「**残作業だけ実行。既存部分は作り直さない**」に変える - 実装時に**指示書から意図的に逸脱した判断**があれば、その理由ごと記録する。 記録が無いと、次に読んだAIが「指示書と違う」と判断して元に戻してしまう 配布する指示は、完了状態まで含めて1つのライフサイクルとして設計する。 --- ## 4. 「メール一致で自動承認」は成立しない（セキュリティ上の落とし穴） 投稿・出品の自動承認を作るとき、「APIキーに紐づくメールアドレスが信頼済みリストに含まれていれば自動公開」 という設計にしたくなる。**多くの場合これは破れる。** キー発行APIが**メールアドレスの所有確認をしていない**なら、第三者が信頼済みドメインのアドレスを名乗って キーを取得し、そのまま自動公開できる。 正しい形: - 信頼済みキーは**別のシークレットで署名**し、署名済みキーからの投稿だけを自動承認する - 署名なしのキーは、たとえメールが一致していても従来どおり審査待ちに落とす - **秘密情報スキャンは絶対に外さない**。自動化してよいのは「審査の人手」であって「安全チェック」ではない - 第三者からの投稿の自動承認は作らない（スパムと秘密情報の公開に直結する） 実装後は「信頼済みドメインを騙った通常キーが審査待ちで止まること」を**本番で実測**して確認する。 --- ## 5. 状態問い合わせAPIを必ず用意する クライアント側が「自分の投稿が公開されたか」を機械的に判定できないと、同じ放置が再発する。 ``` GET /api/v1/<リソース>/{id} → { ok: true, id, status: "pending" | "published" | "rejected", ... } ``` - 認証は投稿時と同じ。**自分が出したものだけ**返す - 存在しないIDも他人のIDも 404 にする（存在を漏らさない） ### タイトル一致での突合は破綻する 状態APIが無い間、クライアントは「公開一覧のタイトルと自分の投稿ログのタイトルを正規化して突き合わせる」 best-effort をやっていた。承認時に**タイトルが改名され本文も編集される**ため、本文ハッシュの一致は0件だった。 状態APIができたら、そちらを正とし、個別に失敗したものだけ従来方式へ落とす。 - 照会は**同時実行数を絞る**（4本程度）。全件を一斉に投げない - `rejected` は published でも pending でもない第3の状態として独立集計し、滞留の警告対象から外す - ネットワークが全滅しても、確認コマンド自体は正常終了させる --- ## 6. 鍵の配り直しを人の手作業にしない 自動承認のために新しいキーへ差し替える場合、**各PCに手で貼らせない**。 チームに鍵の自動配布経路があるなら、そこへ1回入れれば全端末へ届く。 - 配布ファイルは「メールアドレス → キー」の JSON にして、各端末が**自分のアドレスに一致する1本だけ**を使う （配布経路は全端末に同じ内容を配るため、端末ごとに違う値を配れないことが多い） - 受け取り側は、ファイルが無い・JSONが壊れている・値が空、のいずれでも**静かに従来のキーへフォールバック**する - ログに**キーの値そのものを出さない** - 配布クライアントが「既存ファイルには書かない」仕様か「キー単位でマージする」仕様かを**実装を読んで確認する**。 前者だと既存ファイル名に入れた値は永久に届かない（エラーも出ない） --- ## 7. 通知は「前回と違うとき」だけ出す 滞留を検知して通知する仕組みを入れると、状態が変わっていなくても実行のたびに飛ぶ。 実際に同じ内容の通知が短時間に4連投され、通知そのものが無視されるようになっていた。 - 前回通知した内容（滞留IDの集合など）を保存し、**集合が変わったときだけ**送る - 変化が無くても一定期間（7日程度）で1回だけリマインドする。沈黙が「解決した」と誤読されるのを防ぐ - 強制送信のオプションは残す --- ## 検証（ここまでやって完了とする） 1. 対象リポジトリが**無い**PCでフックを実行し、出力が空・正常終了であること 2. 対象リポジトリが**ある**状態を再現し（テスト用の一時ディレクトリで可）、指示が出ること 3. 走査を予算切れさせ、次回実行が**未走査ルートから再開**すること 4. 信頼済みでないキーからの投稿が、本番で審査待ちに落ちること 5. 状態APIが、自分の投稿には状態を返し、存在しないIDには 404 を返すこと 6. 通知が、同一内容の2回目で送信されないこと --- ## この型が効く場面 - 特定の1台にしかない管理機能・デプロイ権限が原因で、修正が誰にも着手されない - 「ドキュメントに書いたのに誰もやらない」が繰り返されている - 配布した指示書が、完了後も同じ作業を促し続けている - 自動承認・自動公開の権限設計を、なりすまし耐性のある形にしたい ---