開発プロセスのAI指示書 129本
開発プロセスまわりの作業を AI にやらせるための指示書 (Markdown) を集めたページです。 全部まとめて使えば、ゼロから作らせた場合と比べて約921万トークン (約13,810円分) の節約になります。 すべて無料・登録不要で、URL をそのまま AI に読み込ませて使えます。
スマホ(Remote Control)から即相談できる Claude Code タブを VS Code に毎朝自動で用意する
自作VS Code拡張で公式Claude Codeのコマンド(editor.openLast/newConversation/renameSessionTab)を叩き、名前付きタブをN本自動補充。夜間はWM_CLOSE→再起動で毎朝揃える。--bg/ターミナル経路・タブ0でのnewConversation・SendKeys再読み込みが失敗する実測付き
夜間ジョブ異常を通知で終わらせず自動修復→AI修理PR→人へ引き渡す閉ループ
監視の『検知して通知』の後段に、決定的Playbook→AIコーダーの隔離worktree修理PR→持ち越し→人への3要素引き渡し、を足す実装指示書。argvで指示を渡すな等の実測の落とし穴つき
ドキュメント駆動開発プロセス CLAUDE.md — 作るものを固めてから書かせる
「AIが暴走して意図と違うものを作る」を根絶する開発プロセス指示書。UI仕様→機能設計→実装の順をAIに強制し、1ファイルごとに承認ゲートを挟む。受託開発・チーム開発向け。
依存ゼロのMCPサーバを作り、npm公開に詰まってもnpx github:で今日から配る
自作ツールをAIエージェントから使わせるMCPサーバを依存パッケージゼロで実装し、npm公開が2FA制約で止まっても配布を成立させる手順。JSON-RPC自前実装の要点4つ、二刀流bin、.mcp.json自動登録、実ハンドシェイク検証、そしてbinの./で公開物が壊れる罠まで。
Discord bot の Administrator を剥がす — 「自分では外せない」壁の越え方
bot は自分の最上位ロールを編集できない。position の測り方、明示 overwrite への置き換え(VIEW_CHANNEL 抜けの検算)、token が読めない上位 bot のデプロイ環境を使う唯一の経路、後片付けまで。
AIに指示書マーケットを自動参照させ、終了時に自動出品させるMD
開発依頼を受けた瞬間にマーケットの完成済み指示書を検索してAIに読ませ、セッション終了時には汎用ノウハウを自動出品させる仕組みの作り方。全台配布・秘密情報スキャン・実際に踏んだ配布バグ3つの回避込み。
「そのPCにしか直せない障害」をAIに自分で気付かせて着手させる
特定の1台にしかリポジトリが無い機能は、修正手順を書いても誰にも実行されず放置される。SessionStart hook で当該PCのAIだけに指示を出し、完了後は指示書へ状態を書き戻して再実装事故を防ぐ型。走査の時間予算とセッション跨ぎの再開、メール一致だけの自動承認がなりすまされる理由と署名キー方式、状態問い合わせAPI、鍵の自動配布、no-op通知の抑止まで、実際に94件の滞留を解消した実例に基づく手順。
複数PC・複数AIへ設定と秘匿値を配る仕組みの作り方（静かに壊れる7つの型）
AIエージェントを複数台運用する時の配布系(ルール・hook・スクリプト・APIキー)が、例外もエラーも出さず無言で死ぬ7つの型と潰し方。symlink判定・取得失敗の巻き添え・async内process.exit・設定JSONのBOM・秘匿値の捏造・過剰権限・鍵ローテーションで全台死亡。検証手順6つ込み。
ユーザー投稿の審査を無人化する — 機密は決定的判定・重複はグループで1本に寄せる
投稿キューが人手承認で滞留するサービスを、毎日1回の無人バッチで回す実装手順。機密は正規表現で決定的に落とし、重複は候補出しだけ機械＋LLMには同主題判定と網羅項目の抽出だけをさせて残す1本はコードで決める。ペア単位で決めると残した側が別の組で却下される罠、却下の保存先が無い設計、ストア障害が空データに化けて二重公開を招く fail-open、誤検出で全部却下になる4パターンまで。
既存スプレッドシートを正本にした業務アプリの列マッピングを壊れない設計にする
現場が使い続けるGoogleスプレッドシートをアプリから読み書きするときの列解決設計。ヘッダ名優先＋列レターfallback、同名列の検出、実ヘッダ診断CLI、検証手順まで。別の列に書き込んで台帳を壊す事故を防ぐ。
Beds24→Airbnb の料金同期が全日程で止まる原因（US0 未満の価格を含む送信は丸ごと拒否）と直し方・検証
Airbnb は1泊US0未満を含むカレンダー送信を丸ごと拒否し、無関係な日付まで凍結する。価格生成側の床を上げ、ホスト用マルチカレンダーで窓外日付を対照群に読み戻す手順。
複数PCの Claude Code を結ぶ PC 間メールは「配達済み」と「読まれた」を分ける — 13時間黙って止まった事故からの状態機械再設計
Sheet+Apps Script 経由の PC 間メールで、配達済み≠既読のまま 13 時間止まった事故の真因 10 件と、new→delivered→seen→done の状態機械・宛先完全一致・hook の新着順提示・サーバー側 SLA 監視・ループ遮断・Sheets 型変換の罠までをそのまま実装できる粒度で
Claude Code の auto-memory を複数PC・複数アカウントへ毎日自動配布する（配信口は鍵配布サーバと分離し、認証だけ委譲する）
auto-memory を夜間バンドル化し分割配信、認証は鍵配布サーバへ委譲して全PCへ日次同期する構成と落とし穴
別アカウントの Claude Code 同士を人の転記なしで直接やりとりさせる（共有メールボックス方式）
組み込みSendMessage/Remote Controlは同一アカウント限定。既存のトークン付きWeb App＋シートをメールボックスにして任意PC間を双方向・2分配達、promptは承諾制で読み取り専用headless実行
配布した自動化が「自分を更新できない」問題の根治と人手ゼロ復旧の3層設計
複数端末へ配ったhook/常駐スクリプトが無言で古いまま止まる原因(凍結コピー・実行シェル差)と、中央キュー/自己修復手順/生存digestの3層で人の操作ゼロで復旧させる設計。実測で踏んだ「緑なのに何も起きない」罠つき。
無人エージェントの夜間作業をKPI化する（「完走しました」を成果の証明にしない）
夜間の無人セッションが「N/N完走・失敗0」でも実は過半が空回り、という状態を数字で暴く指標設計。消化率・空回り率・コスト削減効果の3本と、空回り分を削減効果から差し引く理由、実測で機能しなかった指標を棄却した記録つき。
アプリ開発の主体を別アカウントの Claude Code へ移管する（権限付け替え＋判断依頼の経路つき）
引き継ぎ書・GitHub/Drive 権限付与・判断依頼プロトコル・カットオーバー条件・途中で移管先を変える手順を1セッションで完了させる型。相手側の人の操作は起動文1回と OAuth 同意1回
無人バッチの「黙った空振り」を発見して止める（冪等取込の設計）
定期バッチがエラーを出さないまま毎回同じ仕事をやり直している状態の検出法・典型的な真因（取込済み集合を実体の単一カラムで持つ）・台帳による修正・打ち切り付き再試行・CI課金での効果実測まで。
配布したツールが既存端末にだけ届かない障害の診断と再発防止
全PCへ配ったhook/スクリプトが、新規端末では動くのに既存端末にだけ永久に届かない。凍結コピー・拡張子を無視した重複判定・無言return の3重奏で、テストは全green・自己診断もNG 0のまま気づけない。実際に踏んで直した診断手順と、再発を止めるテスト設計(既存端末フィクスチャ/チェックリスト網羅性の機械照合/故障注入)。
Claude Code のログインアカウントを別アカウントへ切り替える（ブラウザ承認1回・auth login が終了しない罠つき）
同じPCで Claude Code の claude.ai ログインを別アカウントへ移す手順。認証ファイル1本の構造、事前棚卸し（env上書き・無人タスク・コネクタ・routine）、非同期ログイン＋status ポーリングのスクリプト骨子、logout が復元不能な点と切り戻しまで。
高額モデルを相談役に固定し、実行を安いAIへ自動で振り分ける hook の型（Claude Code）
上位モデルを既定にすると上限が倍速で減る原因は本体がツールを何十回も自分で叩く構造(消費の85%は入力側)。依頼をレーン分類して先頭に1行注入するUserPromptSubmit、本体の直接実行を数えて8回で止めるPreToolUse、サブエージェントのmodel省略を止めるガードの3本セットと、その検証・効果測定の手順。
GitHub Actions の課金分を実測ベースで削る
Actions の請求を推測でなく実測から削る手順。ジョブ単位の分切り上げという課金構造、ステップ別に時間を割る API の叩き方、短時間高頻度は統合・長時間は per-row 往復の一括化という打ち分け、並列度を上げても効かないケースの見分け方、そして『遅いステップが実は同じデータを毎回処理し直している欠陥』の見つけ方まで。本番の夜間ジョブを実測目的で再実行して重複レコードを大量生成した失敗例と、その巻き戻しの作法も含む。
自動同期システムの「窓」と「警報」を監査する
外部APIへ値を定期送信するシステムで、送信窓と検証窓のズレが作る『構造的に絶対に赤くならない領域』を潰す手順。窓の実測、窓外の期待値の導き方、既定値の再生成、管理方式変更に伴う警報の誤発報まで。
AIエージェントの「委譲率」を正しく測る指標設計
監督AIが実装を安いエージェントへ渡せているかを毎日自動計測する指標の作り方。トークン比が飽和する/分母を landed 行にすると100%に貼り付く/編集ツールだけ数えると逆向きに嘘をつく、の3失敗と対策・増分キャッシュでの高速化まで
fail-open のガードが「必要な場面でこそ効かない」のを設計段階で潰す
抑止・重複防止・レート制限を fail-open で作ると unknown の範囲を広く取りすぎてガードが常時 open になる。ユニットテストは緑のまま機能だけ死ぬ型。unknown と『不在という積極的な証拠』を分ける棚卸し表、3値判定、エラー粒度の分け方、実データで両側を観測する検証手順まで。
安いLLMプロバイダのフォールバック連鎖を本当に着地させる
無料枠が枯れて黙って死ぬのを防ぐ多段フォールバックの設計。失敗コードの2分類・プロバイダのクールダウン・日次上限・全呼び出し側の一本化・テストが実環境を壊す罠まで。
配布したツールが各PCで本当に最新版か検知する（版ドリフト検知）
全PCへGit経由で配るCLI/hookが「マージ済みなのに端末だけ旧版」で静かに止まるのを検知する。ツリーAPIのblob SHA照合、Windows CRLFで全滅しないindex SHA比較、ローカル編集と配布失敗の切り分け、await追加でprocess.exitが落ちる罠まで。
同期が「更新しました」と嘘をつく — 配布が届かない2つの欠陥を潰す
設定・ルールの配布処理が成功報告を出すのに実際は届いていない。pullの上流取り違えと、自分が配った旧版を人の編集として保護し続ける2欠陥を、実コミットの差分・テスト・読み戻し検証手順まで含めて潰す。
社内アプリの必須機能を、ルール文書ではなくデプロイ直前の hook で強制する（Claude Code）
「全アプリに○○を入れる」が文書だけで守られない問題を、本番反映コマンド直前の PreToolUse hook で未搭載・台帳未登録を deny して潰す型。除外ファイル・fail-open・全PC配布・テスト一覧つき
無人実行ジョブが「働いたのに何も残らない」を潰す設計
cron/タスクスケジューラからAIエージェントや長時間処理を無人で走らせる際の2大事故（タイムアウトkillで出力が丸ごと消える／実行されるコードがその瞬間のHEADで決まる）を構造的に潰す実装指示書。逐次進捗ファイル・待機時間の上限・作成時刻からの実行ID復元・固定worktreeへのpin・完走分だけの後片付けまで、テスト観点と完了条件付き。
「値が空」と断定する前に実表示をブラウザで読み戻す
API/DBの値ではなく実際に画面に出ている状態を読み戻してから断定する手順。変更の有無を問わず、価格・在庫・掲載文など外部露出状態の調査・報告に使う汎用スクリプト付き。
Claude Code のセッション一覧を「閉じたら自動で消える」ようにする
C:/Program Files/Git/clear は削除コマンドではない。hook + 閉じた台帳 + 常駐ウォッチャーで、セッションを閉じたら一覧から自動退避（削除せず move）する実装手順と、並行タブ・凍結コピー配布の落とし穴
GitHub Actions の課金分を実測して削る手順（cron 統合ダイエット）
GHA はジョブごとに分単位で切り上げ課金するため、数秒×高頻度の cron が最も割高になる。/timing API で全ワークフローの課金分を実測し、cron 式が完全一致するワークフローのステップへ統合して頻度も処理も変えずに削る手順。schedule は大量に間引かれるため分ゲートでの間引きが成立しないこと、統合すると前ステップの失敗で後続が silent skip されること、予算上限でジョブ未起動になった時の見分け方まで含む。
Claude Code の会話ログを自動退避しても VSCode のタブを壊さない（state.vscdb で開いているセッションを検出）
セッション一覧の自動整理で jsonl を動かすと VSCode 拡張のタブが「Couldn't load this conversation's saved history」になる。拡張が state.vscdb に平文で持つセッション ID をバイト検索して、参照中のログは理由を問わず動かさないガードの実装・テスト・復旧手順。
デプロイ/UI変更を必ず2段検証してから完了報告
コード・デプロイ・cron・env・UI変更後に、ロジック層(Node再現)とブラウザ層(Playwright)の2段でassert検証し、検証済みだけを完了報告させる手順。「画面で確認して」の丸投げを禁止。
無人実行が API を乱打しない設計 — 失敗打ち切りガード実装手順
cron/スケジュールトリガーで恒久的に失敗するレコードが無限リトライされる構造を塞ぐチェックリストと実装パターン。失敗カウンタは試行の前に保存、冪等なリソース生成、復帰コマンドの用意まで。API乱打によるアカウント凍結の予防。
AIに壊させない「変換」の作り方(不変条件とリトライ閾値)
AIに圧縮・移行・整理を任せると『指示どおり動いたのに情報が消える』。IDだけをassertしてタイトルと説明が消えた実例と、人間が読む全フィールドに不変条件を掛ける書き方。あわせて『N回失敗で打ち切り』が試行レート変更で1晩で発動した失敗と、異なる日数で数える実装。
予約データから『価格が高すぎるのか』を判定する手順（リードタイム・ペース曲線）
先の予約が薄い時に憶測で値下げせず、リードタイム別の実勢単価・過去の同じN日前のペース・提示価格の実表示を突き合わせて外れている帯を1つに絞る手順。在庫の穴の見つけ方つき。
Drive を AIルール共通ハブにする配布・統合同期
AI(Claude Code 等)のルール/スキルを Drive の1フォルダで正本管理し、pull(全員へ配布)と merge(inbox投稿を正本へ統合)の2モードで同期する仕組み。download_file_content 必須・latest-by-title・manifest 版管理など Drive コネクタの罠と対策込み。
非公開・preview API を相手にする前に「本当に使えるか」を確定する手順
limited preview の新機能に自動化を賭ける前に、公開ディスカバリ照合・403/404の対照実験によるホスト実在判定・管理画面の項目有無確認で「到達可能か」を一次ソースで確定する9手順。AIが推測でpreview APIを捏造するのを防ぐ逐語コード渡し、実在判定つき防御実装、宣言と実装の識別子照合まで含む。
Codex CLI が WSL 経由でだけ 401 token_revoked になる時の復旧（ブラウザ再ログイン不要）
Windows と WSL で別々の auth.json を持つ Codex の片方だけが失効した時の切り分け2コマンドと、生きている側の認証を安全にコピーして復旧する手順
Codex 委譲の指示書で「シェル禁止」を書くと変更ゼロで止まる — テンプレと差分ベースの成否判定
Claude→Codex の指示書に受け渡し規約の『シェル禁止』を転記すると Codex が確認待ちで止まり exit 0・変更ゼロになる。原因・指示書テンプレ・exit code でなく git diff とテスト件数で成否判定する手順。
検証したのに何も検証していなかった — 定期実行の反映を3層でexit code判定する
cronやバッチの反映確認が空振りする2つの型（exit 0だけ見る／ツールが既定ブランチに無い）と、A実行・Bデータ・C実表示を1本に繋いで機械判定するスケルトン。対照を入れて別要因の混入も検知する。
Node CLI が黙って exit 13 で止まる — ESM の動的 import 循環をテストで止める
トップレベル await の CLI と動的 import の循環で起きる exit 13 の原因・直し方と、循環を CI で検出する node:test 一式
内容は同じなのに PR が CONFLICTING — CRLF 混入の見かけ上の衝突を修正を壊さず解消する
別コミットの改行コード変更で PR 全体が衝突に見える問題を --ignore-all-space で判定し、rebase -X renormalize で元の修正だけを乗せ直す手順。検証コマンド、.gitattributes での再発防止、複数 PR を worktree で同時に扱う時の罠と報告文の型まで。
エージェント型の委譲が全滅したら「API 直叩きのファイル単位生成＋許可リスト書き出し」で実装を通す
Codex/gemini-cli/安価 agentic ランナーが全部落ちたとき、Chat Completions を1回叩いてファイル全文を出させ、許可リストのパスだけ書き出す。18ファイルを4並列・約$0.02 で通した実測と gen/split スクリプト、検品の要点。
アプリ内フィードバック→責任者DM→Issue→自動修正PR→1タップ承認
社内アプリの不具合報告を、責任者の個別DMに届け、Issueにして夜間に修正PRまで自動で作り、承認は既存のPR画面のMergeボタン1タップで済ませる設計。通知先を中継1箇所に集約してトークン拡散を防ぎ、既読は通知のリアクションで持ち、絵文字で自分の通知を拾う無限ループを断つ。
MCP stdio サーバが Windows で「接続済み」のまま死んでいるのを見抜く
MCPサーバ一覧が緑でもツール呼び出しだけ spawn ENOENT で死ぬ故障の3層構造と、initialize/tools-list/tools-call を層ごとに実測して証明する手順。npx形式が作る初回だけの接続タイムアウト、設定スキーマ移行による静かな認証無効化、自動修復コードが鍵を空文字で潰す罠も含む。
翌朝のバッチ結果で判定するゲートを朝を待たずに閉じる
夜間バッチの変更を明朝のレポートで確認する宿題を、--dry と出力先差し替えで当日中に判定する型。出力先を入力として読む前日比の処理が黙って壊れる罠と、grep exit 2 を0件と誤読しない判定手順つき。
複数LLMプロバイダの無料枠切れを検知して自動で次候補へ差し替える
安いLLMへ処理を逃がす構成は無料枠が切れると黙って落ち、記録も残らず一番高いモデルへ逆流する。402は即次候補/429のみリトライという分類、課金プールを跨ぐ候補列、失敗も残す台帳、1ホップ1行のログまでの実装手順。連鎖の順番を実測で決める方法（単価最安≠実効最安/ベンチ飽和/正規表現採点が上位モデルを落とす罠）も収録。
人にログインさせるブラウザ自動化を1回で済ませる（勝手に閉じない・正規Chrome・Cookie判定）
Playwright永続プロファイルで人にログインさせる時、2段階認証途中で閉じる・同梱Chromiumが落ちる事故を防ぐ共通関数とCIガードの型
Claude アプリの Code 一覧に溜まる古いリモートセッションを自動アーカイブする
PC側ログを消しても減らないスマホ/Webの切断済みセッションを、内部APIで24h超のものだけ6時間ごとにアーカイブする hook
別環境で作られた未マージPRを、現行コードへ安全に移植させる
放置された未マージPRは、競合よりも「設定の軸が二重になる」「文書の前提が古い」ほうが危険。AIに cherry-pick させず、設計だけ取り出して現行の語彙へ統合し直させる手順書。実装をAIへ委譲した時にテスト合格のために既存の設計判断が壊される実例と、その受け入れレビュー手順つき。
LLMの出力を実際に動かして採点するevalハーネスの作り方
安いモデルへ落として良いかを測る社内evalで、正規表現採点が正しい答えを落とす問題を解決する。生成コードをnode:vmで実行し振る舞いで採点する方法、課題自体の欠陥(設問が二義的/採点が実装スタイルを過剰指定)の切り分け方、そして多くの実装が踏むvmサンドボックス脱出経路の塞ぎ方まで。
並行AIセッションが共有リポジトリで事故らない型
複数のAIエージェントが同じ作業ツリーを共有する時の事故防止と、配布物を「配布可」と言う前の3層検証（コード・登録・配布）を手順化したMD
配布する PowerShell インストーラを CI で検査する（PS5.1・BOM の罠）
社内に1行コマンドで配る .ps1 が、JSのテスト緑のまま構文エラーで全PCへ届く穴を塞ぐ。パース+BOM検査スクリプトと、windows-latest の既定 pwsh では検出できない理由、故障注入での受け入れ確認まで。
AI が止められた操作を「ユーザーのダブルクリック1回」に落とす手渡しスクリプトの作り方（Windows）
権限ガードで AI が実行できない操作を手作業1回に圧縮して渡す型。.cmd に chcp と日本語を同居させると全行が壊れる罠、node のフルパス指定とログ退避、本番がリポジトリと乖離している前提の pull-patch-push 手順をまとめる。
配布したhookがWindowsで静かに死ぬのを塞ぐ — process.exit と top-level await
AIエージェントのhookが「出力は正しいのに反映されない」形で無効化される真因と、ネットワークに依存しない回帰テスト・変異テストの型
作業ツリーが汚れた端末にだけ配布が届かない — フォールバックの自家中毒まで含めて塞ぐ
複数端末へgit pullでツールを配る運用で、開発端末にだけ配布が永久に届かない障害。フォールバックの発動条件・人の作業の保護・自分の出力を人の編集と誤認して凍結する二次不具合・自己修復の循環・定期タスクの参照先ずれまで、実際に踏んで直した手順とチェックリスト。
止まった作業を毎晩検知し、進められるものだけ自動で前に進める
CI通過済みPRが18日放置された実例から、締切・通知・自動前進の3点を備えた夜間検知を作る。通知が埋もれない設計（行動できるものと在庫の分離）と、実測で踏んだ落とし穴まで含む。
Claude Code の邪魔なUI面を公式スイッチで消し、効いたことを実測する
アンケートバナー等のUI面は配布バイナリに CLAUDE_CODE_DISABLE_* の公式スイッチがある。grep で switch と gate を取り出し、settings.json の env に入れ、一時 SessionStart hook で env 到達を実測する。A/B が取れない面はコード読みで確定させ、実測と分けて報告する
WSL が「ディストリが無い」ように見える時、疑うのは導入状態ではなく滞留プロセス
wsl --status は即答するのに wsl -e が無限ハングする非対称が誤診を生む。真因は滞留した wsl.exe クライアント。切り分け・復旧・時間制限付き呼び出し・PATH interop の罠まで。
HMAC鍵配布サーバの締め出し事故を防ぐ設計（複数秘密＋使い捨てenrollトークン＋失敗の自己通報）
共有秘密で設定ファイルを配る構成は、秘密をローテーションした瞬間に未受領の端末を永久に締め出す。複数秘密の同時受付・使い捨てenrollトークン・失敗を端末自身が通報する設計と、実経路e2eテストの書き方まで。
ログインできないGitHubアカウントに縛られた開発を、止めずに前へ進める
パスワード不明・2FAで入れないGitHubアカウントのPATにworkflowスコープが無く、ワークフローをpushできない詰みの解き方。復旧に走る前に潰すべき5つの経路（手元アカウントのスコープ確認／依存を確認して置き換え／コミットauthorから登録メール特定／招待のAPI受諾でWebログイン回避／secrets登録はrepo+adminで足りる分担）を手順化。
GASウェブアプリの画面をjsdomで検証する — 単体テストでは原理的に見つからない画面バグを捕まえる
GASの画面JSはブラウザ無しでは検証できず、単体テスト全pass・API正常・データ正常のまま主要導線が死ぬ。Index/Style/Scriptを連結してjsdomで実行し、実データを流して要素の有無とボタンの活性まで自動判定するハーネスの作り方。
同じフォルダで複数のAIエージェントを走らせたときの衝突を検知して復旧する
2つ以上のコーディングエージェントを同一作業フォルダで走らせると、片方が片方の未コミット作業を静かに消す。資源ロックでは防げない理由、mtime による検知、git checkout--/stash/commit -a などの禁止動詞、壊したときの復旧手順、委譲した生成物が古くなる罠までをまとめた運用手順。
コーディングエージェント本体を「安い互換バックエンド」で走らせる
エージェントCLIの接続先を互換エンドポイントへ差し替えて実行コストを下げる手順。envを子プロセスにだけ注入する型、カタログ外モデルで窓が誤仮定される罠、エイリアス既定の罠、契約アカウントの実測判定、カード全滅時の決済切り分けまで。
「送らなかった行はゼロ」で在庫が消える事故を防ぐ
在庫・棚卸・名簿など全件置換APIに部分入力を通すと、入力しなかった行が静かにゼロで上書きされる。事故の見つけ方、省略時の3方針、書き込み前に現在値を取る据え置き実装、行を消さずに復旧する手順、拠点を取り違えないUI、そして「送らなかったキー」の回帰テストまでの型。
Windows で AI エージェント/Node が exit 3221226505 で突然死する時の診断手順
0xC0000409 の原因を「コミット制限枯渇 / libuv / V8 OOM / ネイティブモジュール」に根拠付きで切り分ける実測手順。誤診しやすい WER の読み方2点と、逆効果になる NODE_OPTIONS 対処の戻し方まで含む。
APIが success を返すのに反映されないときの切り分け手順
外部APIへの書き込みが HTTP 201 / success:true を返すのに値が変わらない——エラーが出ないため最も危険な失敗。差分エコー(modified)で判定し、書ける項目を道連れに送って行単位か項目単位かを切り分け、計算値と入力を見分けて『値の所有者』に書く、までの手順とチェックリスト。
「マージしたのに直らない」— デプロイ元と定期実行のブランチが違う罠の検出と対処
GitHub Actions の schedule は常にデフォルトブランチで走る。本番デプロイ元が別ブランチだと、同じスクリプトの版が2つ存在し「マージしてデプロイしたのに毎晩のバッチだけ古いまま」になる。検出コマンド、base の選び方、そして『デプロイ完了は証拠にならない』ことの確かめ方まで。
デプロイ済みの本番が git より新しいプロジェクトを、壊さずに触る
git 連携が無く CLI から直接デプロイされている本番は、clone して deploy すると本番にだけある機能が消える。触る前に本番ソースを API で回収して git と突き合わせる判定と手順、秘密ファイルの混入対応、既存認証コードに触らない判断基準まで。
エージェントの出力コストを正しく測る（usage複製の二重計上とthinkingが7割という現実）
会話ログJSONLから出力トークンを集計する時に必ず踏む2つの罠（usageがレコードごとに複製され2.27倍に膨らむ／thinkingは本文が保存されず按分では測れない）を検証コード付きで潰し、そこから品質を落とさない削減レバー=レスポンス数の削減を導く手順。
デプロイ更新の「狭間」が本番データを壊す — 新旧の版が同時に動く前提で冪等性を設計する
サーバレス/GAS Web App でデプロイ切替は即時でも原子的でもない。切替の狭間で新旧の版が混在し、旧版の書き戻しを新版の移行ロジックが無条件変換してデータを壊す型と、冪等性の定義拡張・修復関数・切り分け手順・read-back検証までをまとめる。
Discord webhook の死活監視と自動修復
削除された webhook で通知が無言停止するのを防ぐ。生存中にチャンネル台帳を作り、死んだら同一チャンネルの生存 webhook へ自動で差し替える設計と実装要件
起動時フックが増えすぎてエージェントが立ち上がらなくなるのを直す
Claude Code が全タブで 'Subprocess initialization did not complete within 60000ms' を出すのは認証でもネットワークでもなく、起動時フックの合計時間超過。合計の測り方、timeout を削らずに裏回し／cache-first で減らす型、npx 起動の MCP が 30秒タイムアウトする件、そして『速くなった理由』を取り違えないための検証まで。実例 93秒→18.7秒
Node.js ESM の CLI が無言で exit 13 — 循環 import × top-level await デッドロックの診断と修正
テストは通るのにCLI直接起動だけ止まる原因（TLAで待つエントリへ動的import先が循環import）の確認手順・コード無変更の回避策・恒久修正・スモークテスト
セッションを閉じたら次のセッションが自分から再開するようにする（2つの届け方と、その限界）
エージェントCLIの外から新セッション化は発火できない。その制約下で取りうる window / inline の2方式、暴走を止める条件、実測で踏んだ罠と検証項目までの実装指示書。
ずっと skipped だった CI ジョブを掘り起こして緑にする
CI が長期間赤いと needs: の後段ジョブは skipped のまま欠陥が隠れる。過去実行の確認方法、パッケージマネージャの二重指定・静的プリレンダーの DB 接続・Playwright の webServer 未起動という典型4段を、CI ローカル再現で往復を減らしながら順に潰す手順書。
ログオンしただけでIDEが開きAIエージェントが走り出す状態を作る（Windows/VS Code）
毎朝ターミナルを開いてエージェントCLIを打つ手間をゼロにする。folderOpenタスク+スタートアップ.lnkの構成に加え、素直に作ると必ず踏む3つの「エラーを出さずに何も起きない」失敗（8.3短縮名がワークスペース判定を壊す/サンドボックス下はexit 0を返すのにGUIが起動しない/Restricted Modeが自動タスクを無言で止める）と、プロセスの祖先で成否を判定する検証法まで。
CIから自ホストへpushする連携が「届かない日」を、artifactからのpullで埋める
自宅/社内PCやトンネル公開先へCIからPOSTする連携が到達できず落ちる問題を、配達先からartifactを取りに行くpull経路で埋める手順。生成と配達の切り分け、判定表の設計、CIの定時遅延による二重生成の回避、read-back、監視指標の付け替え、計測ツール自身の偽陽性の潰し方まで。
コードの既定を直したのに挙動が変わらない — 設定ファイルの env 注入を疑う
CLI エージェントの分岐を直しても効かない時の診断手順。設定ファイルの env 注入がコードの既定とユーザー環境変数より上位にある構造を優先順位表で示し、実効プロセス env の読み方・全コピーの dry-run・親プロセスでの実物確認までを機械的な順序で行う。
複数LLMプロバイダのフォールバック連鎖に新しい実行者を安全に追加する
安いLLMから順に試すフォールバック連鎖へ、新プロバイダを実測(成功率/単価/到達性)にもとづく正しい位置に差し込み、並行編集で静かに消えないよう配列全体をpinする回帰テストと4段階の実走検証まで通す手順。
CLIをラップしたMCPサーバが上流の無料枠終了で死んだらREST直叩きへ寄せる
外部AIのCLIを子プロセスで起動するMCPサーバが認証終了・旧モデル固定・機能別の枠切れで死ぬ。原因を4層で切り分け、ツール名を変えずに実行部だけRESTへ置き換える手順と、接続緑・テスト緑では足りない検証方法。
常駐ジョブを作業ツリーの HEAD に依存させない（固定 worktree ＋ 出力先分離）
毎朝走るジョブが Cannot find module で落ちるのは、実行場所が人や別セッションの作業ツリーで、HEAD が動くから。ジョブ専用 worktree でコードを固定し、成果物だけ --out-root で共有リポへ返す設計と、終了コードで取る5段階の検証手順。
汚れた作業ツリーから「レビュー済みの版だけ」を本番に出す（git worktree + Vercel）
未コミット差分だらけ・originとズレたローカルから誤った版を本番に出す事故を、detached worktree + .vercelコピー + 本番URLへの実描画検証で塞ぐ手順
ダッシュボードが「artifact が見つからない」で真っ赤になるのを塞ぐ
GitHub Actions の成果物を画面に出す構成が no valid artifacts found で落ちる真因（preflight skip した run も success だが artifact 無し）と、artifact 実在確認＋直近成功へのフォールバックで画面を殺さない直し方。常駐プロセスの世代確認と実ブラウザ描画までの検証手順つき。
AI エージェントに本番 DB の migration を任せる（破壊的 SQL を構造的に実行できないランナー）
本番 DDL だけ毎回人が SQL エディタに貼っている状態を解消する手順。禁止語 grep ではなく allowlist 文法でパースして許可構文だけ実行するランナーを1本作り、そのパスだけを許可する。成功判定に「期待カラムの実在確認」を必須化して沈黙 failure を潰す。TLS のプライベート CA、マネージド DB 標準の event trigger、履歴基準の「未適用」誤読という3つの落とし穴の回避込み。
提案キューを溜まるだけのゴミ箱にしない — 夜間の自動トリアージ
AIが出した提案を溜める仕組みだけ作ると必ず腐る。Web検索で裏取りし安いLLMがverdict/adoptを返し、done/rejected/TODO起票まで無人で回す設計。unclearは捨てずN回で打ち切る規則、無料枠を焼かない既定値、PowerShellのBOM/文字化けの罠まで。
AIエージェントが突然死する時の切り分け — アプリのバグかOSの資源枯渇か
exit 3221226505 の原因をイベントログとコミット率で5分で確定させる手順と、直し方を非エンジニアに1クリックで渡す型
GUI拡張の「他の環境には出るのに、ここには出ない」を設定探しから始めない
GUI拡張の機能欠落は設定ではなく版の不一致。稼働中の版をプロセスパスで確定し、別ウィンドウで新版をA/B（信頼無効化が必須）してスクショ目視まで自分でやってから、再読み込みを同意付きで渡す手順
AI開発ノウハウをチーム共通ハブへ投稿する型
セッション中に得た AI コーディングのルール・失敗パターンを、Drive の追記専用 inbox フォルダに定型フォーマットで投稿し、管理者が正本へ統合する仕組み。各人のローカルにルールが散らばるのを防ぐ。機密値の書き方も規定。
自分が管理していない上流ファイルを差し込みで維持する型 — 死んだパッチを検知して retired に移す
上流が更新し続けるスクリプトに自分の修正を当て続ける仕組み。find/marker/replace の4状態エンジン、anchor-missing に専用 exit code を与える警報設計、差し込みの連鎖、死んだ差し込みの retired 化。テストが足りない値を注入していて壊れたコードが緑だった実害と、その塞ぎ方まで。
内容で行を特定する書き戻しが、ある日から永久に一致しなくなる
スプレッドシートを正本にした業務アプリで「登録できるのに反映されない」が起きる典型。正規化のtrimとsliceの順序で保存値の往復が非冪等になり、全行走査で0件ヒットになる。本番ログからの追い方、ハッシュを変えずに直す方法、重複行事故を防ぐ固定値テストまで。
「直したのに直らない」— 同じ画面に書き込む経路が2本あるのを見落とす
利用者の不具合を直したのに直らない時の定番原因。同じ表示に書き込むコードが複数あり片方しか直していない、レイアウト版数を片方の経路だけが見ている、記録の成否を確認せず「別の場所を見ろ」と案内する、の3類型と、固定文言からの逆引き・共有ヘルパーへの集約・実データ読み戻しでの検証手順。
放置された open PR を安全に棚卸しする（マージすると退行する PR の見抜き方）
CI が緑でも、後から覆された結論を含む PR をマージすると仕様が巻き戻る。使い捨て worktree で残差分ゼロ判定・陳腐度の数値化・退行検知を行い、マージ/クローズを機械的に振り分ける手順。read-back とクローズ根拠コメントのテンプレ付き。
二重定義を片方へ寄せる挙動不変リファクタを、AI委譲で安全に終わらせる
同じ表が直書きと導出で2箇所にある状態を片方へ寄せる時、テストが緑でも終わっていない。着手前に実データのJSONを保存して機械比較する型と、手写しfixtureが順序違いで偽failを出す罠、導出に変えた後の縮退の決め方まで。
追加したテストが本当にその不具合を捕まえるかを対照群で確かめる
テストが緑でも、直す前のコードに当てても緑なことがある。直した箇所を1つずつ無効化して赤くなるか確かめる手順。置換が当たらず素通りする罠（CRLF）と、期待文字列が実装を通らない経路で出力に混入する罠（例外メッセージのコマンドライン全文）の2つを潰す雛形つき。
同期で巻き戻る設定を「固定時刻の貼り直し」で守ろうとして失敗する — 状態の検出で駆動する収束に変える
配布物の同期で上書きされる設定にパッチを当て続けたい時、同期の直後の時刻に貼り直しジョブを置くと失敗する。上書き側がN時間ガードで発火するため壁時計時刻が毎日漂うから。時刻でなく「当たっているか」で駆動する収束への作り替え方、no-opを無音・exit0にする理由、本番を触らず対照群で検定する手順、cmdのexit=行が消える罠まで。
「1台だけそのサイトが開けない」を30分で確定させる — IPv4専用サイト × IPv6回線
Cookie削除もシークレットも効かないERR_CONNECTION_TIMED_OUTを、サーバ側の無罪を実測で証明してから端末側を読み取り専用コマンドだけで確定させる手順。リモート接続や会議を切らずに原因を一意に決める。
コードから事実検証済みマニュアルを作る段階分けパイプライン
抽出→検証→読者層適応→文体統一を別モデル・別チェックに分離し、ハルシネーションとプレースホルダー化を防ぎながら安価にマニュアルを生成する手順
外部連携の値を内部フィールドで検証して誤診しない手順
チャネル連携・在庫/価格同期で「送った値が外にどう出ているか」を内部APIのフィールドで確認すると誤診する。派生値/参考値の混同、チャネル単位の係数、レスポンスの無言切り捨てという3つの罠と、消費者向けエンドポイント→全件突合→ブラウザ実描画という潰し方。
定期実行が「手動なら動く」まま何週間も止まっているのを見抜いて直す
GitHub Actions の schedule だけが 403 で全滅しても手動実行は成功し続けるため気付けない。--event=schedule での生存判定、actions:read の付与、直した後に露出する次の層の潰し方、死活監視の仕組み化までを手順化する。
審査待ちキューに同じ主題が積み上がるのを「出す前」に止める
取り下げAPIが無い投稿先に、並行セッションが同じ主題を重複投稿するのを投稿直前のしきい値ゲートで止める。しきい値は勘で置かず既存ログの再生で決める手順まで含む。
AI に実装を委譲している間に main が動く — 着手前のPR確認を信用しない
コーディングエージェントへの委譲中に他者が同じファイルを main へ入れる。CIが1本も走らない/mergeable UNKNOWN は「ベースが古い」合図。push直前のfetch+rebaseと、rebase後の全体テスト再実行までを型にする
成功しているのに『スキップ』と出るバグの潰し方(ディスパッチャの戻り値規約)
ボタン一覧→コマンド関数をディスパッチする型のツールで、状態フラグと明細配列に同じキー名を使うと空配列がtruthyで常に成立し、成功しても『スキップ』表示になる。原因特定の順序・修正・文言そのものをテストする退行防止まで
offset ページングで外部APIを読むと、取得中に中身が変わって静かに壊れる
ゲートウェイが毎回全文を取り直して offset で切る構成は、取得中に元データが変わると連結が壊れる。rawLength の一貫性検査と丸ごと取り直しで直す手順と、対照群で検定できるテストの書き方（try の中で assert を書かない・先頭が共通の fixture を避ける）まで。
承認を取る設計書は「ひと目でわかる版」1枚を安いAIに下書きさせて先に出す
技術者向けの要求定義・設計書を、スマホで1分で読める1ページに変換して承認の往復を減らす。下書きは安価なLLM、監督AIは禁止語・タグ・375px描画の機械チェックのみ
マージ中の git checkout HEAD が無関係なファイルを巻き戻す事故の回避
conflict解消中はHEADがマージ前コミットを指すため、退避目的のgit checkout HEAD -- <path>が相手側の自動マージ結果ごと消す。CIで発覚するまで気づけない罠と回避策
WSL/Codex導入がBIOSで止まる原因切り分け
wsl --installが失敗/停止したとき、ネットワーク起因・管理者権限不足・BIOS仮想化無効のどれかを切り分ける診断コマンドと自動化エージェントとしての対処方針
既存の Claude Code 環境に「学び台帳・Decision Record・母数照合・HANDOFF」を後付けする手順
CLAUDE.md とセッション終了手順を既に持つ環境へ、同じ学びを3回数えて仕組み化する台帳・前提が変わったら見直す意思決定記録・母数照合の完了条件・実行役への HANDOFF テンプレを、既存体系を置き換えずに差分導入する手順。
「数字が変わらない」— 定期出力が止まった時に最初に疑う場所を間違えない
定期レポートが更新されない・エラーログは空・手動実行は成功。この組み合わせは「起動していない」のサイン。診断順序（トリガー登録→手動実行→実装）と、二度と沈黙させない実装パターン（キャッシュ鮮度警告・stderr保存・finally解放）
機能を封鎖したら相乗りの検証も死ぬ — 未検証のゼロを画面から追い出す
危険な機能を後から封鎖すると、同じフラグにぶら下がっていた検証処理が道連れで死に、ツールは未検証のゼロを『確認した結果ゼロ』の顔で出し続ける。実例では1週間、12件ぶんの嘘の警報を出していた。フラグ参照の仕分け方、未確認を空集合で表現しない持ち方、原因バケツの合計を不変条件にする数え方、0/1/2 の終了コード設計、修正前後を本番データで並べる検証手順、委譲実装の受け入れ基準まで。
設定ドリフト照合器が「毎朝ずっと赤」になるのを止める（照合対象外の値の扱いとguardの当て方）
決定台帳と本番設定を毎日照合する仕組みは、APIに現れない値をパス欄に説明文で書いた瞬間に永久MISSINGへ落ち、本物のドリフトが埋もれる。照合対象外を第3状態(null=DOC)に分ける設計、値を巻き込まず書式だけ直す手順、旧データでfailさせてから当てるguardの検定順を示す。
ページングAPIで「全件取れたつもり」が4%だった — 静かな取りこぼしの検出法
limit を無視して常に20件返すAPIに対し offset を要求limit分進めていたため6,902件中280件しか取れていなかった。テストもCIも緑だった理由と、本番の意地悪さを再現するモックの書き方。
CI が全部 green なのに auto-merge されない PR を原因から特定して自動マージに乗せる
GitHub の auto-merge が効かない原因は権限ではなく fork であることが多い。切り分けコマンド、ワークフローの5条件の読み方、正しい提出経路、ラベル忘れが成功に見える落とし穴、GraphQL と REST の2系統を実測付きで示す
並走するAIセッションが同じ目的を二重着手する事故を止める
複数のAIコーディングセッションを同時に走らせると、同じ引き継ぎを読んで同じファイルを書き潰し、レート制限のあるAPIのクレジットを食い合って両方が429になる。着手前の検知3点セット（mtime／実行中プロセス／git status）と、衝突時に実装を譲る基準、譲った側が仕上げるべき仕事、検証ツールに必ず要る4点（分母・窓の手前・exit code・ページキャッシュ）。
MCP サーバーを npm 公開せずに GitHub 直接指定（npx github:）で配布する
npm publish が 2FA/権限で止まった時に、LP・README・init・テストの導線を github: 指定へ寄せ、push 漏れとキャッシュに騙されない検証まで含めた手順
squash マージ済みのブランチ / worktree を安全に消す判定手順
用済みの作業ブランチや git worktree を、未取り込みの作業を失わずに消すための判定手順。squash マージは祖先関係を切るため git branch --merged / --contains / origin/main..HEAD はすべて「未マージ」と誤報する。さらにローカルの origin/main ref が古いと内容 diff でも答えを間違える。この2つの誤りを潰し、2点diffと3点diffの切り分け・同一題名コミットによる決定打・削除後の read-back まで含めて確定させる。AI エージェントに投げる際の注意（調査と削除を混ぜない）付き。
連携が「権限不足」に見えて実は「身元違い」のとき — 両側のアカウントを先に実測する
デプロイサービスとGitホスティングの連携が繋がらない時、資源側の権限をいじり続けて往復を溶かす失敗を止める。要求側が外部で名乗る名前と資源の所有者を実測で突き合わせる手順、詰まった時に目的へ戻る代替、環境変数のスナップショット順序など併発する罠まで。
委譲した実装を「本番で起動される環境」で受け入れ検証する
AIに実装を委譲するとテストは緑で返るが、それは委譲先の環境での緑でしかない。WSLとネイティブなど実行環境が2つあると片方でだけ通るコードが生まれ、本番へ配線した日から静かに失敗する。本番の起動経路で受け入れ検証する型と、環境差で死ぬ定番3つ、破壊的ツールの追加ゲート4つ。
スプレッドシート集計業務をNext.js+Supabaseアプリへ段階移行する設計指示書
運用中のSheets業務を止めずにWebアプリ(DB正)へ段階移行。双方向同期のエコーループ根絶・移行6原則・コード先行/スキーマ後追いリリース・プレースホルダ列の水増し防止・worktree隔離まで実戦知見を型化。
fork PR しか出せない AI エージェントに「マージまで」を完了条件にさせない
push権限のないアカウントで動くAIエージェントが、CI全greenでもマージできずタスクを永久に引き継ぎ続ける滞留の診断3コマンドと、完了条件の立て方・リポジトリ側の恒久策2案。
安いLLMにコードをファイル単位で生成させて安全に書き出す（区切りマーカー＋許可リスト＋検収）
コーディングエージェントが動かない環境で、DeepSeek等のチャットAPIに複数ファイルの完全内容を出させ、許可リスト付きsplitterで書き出し、テスト・diff・致命パターンで検収する型。ルーティング上書きやコピー癖などの失敗表つき
共有端末アプリの担当者別状態バグ防止
GAS/Sheetsで共有端末アプリを作る時、担当者名を一意キーに含め忘れて全員の状態が連動してしまうバグの原因と直し方
Windows の .cmd に日本語コメントを書くと REM 断片が命令として実行される（ASCII only で防ぐ・判定はコンソール行数）
タスクスケジューラ用の .cmd/.bat に日本語 REM があると cmd.exe が行の断片を命令として実行する。chcp を先頭に移しても直らない。ASCII only にし、非 ASCII 数とコンソール出力行数の2判定で機械確認する手順とテンプレート。
GAS Webアプリ 原因不明の失敗 切り分けチェックリスト
手動実行は成功するのにWebアプリ経由だけ失敗するGASの謎エラーを、サーバー最適化より先に別端末テスト→キャッシュ確認の順で切り分ける手順
サーバーレスに新secretを足さずローカルCLI+定期タスクで外部API連携を補完する
Vercel等に新規tokenを増やしたくない時、開発機の認証済みCLI(gh等)+OS定期タスクで冪等な差分同期にする設計パターン。throwawayレコードでの安全なE2E検証法とWindows PowerShellラッパーの文字化け/パースエラー回避も含む。
「名前でフォルダを探して無ければ作る」処理が自分の重複を掴み続ける問題を潰す
自動化が保存したファイルが現場のフォルダに入らず「同じ名前のフォルダが2つある」状態になる。真因は探索の深さでも起点でもなく「ヒットで即return する順序」。候補を全部集めてスコアで選ぶ形へ直す手順と、再発を縛るテストの書き方をまとめた指示書。