社内アプリの「必須機能」をルール文書ではなく、デプロイ直前の hook で強制する（Claude Code）

何が起きるか（よくある失敗）

「社内アプリには必ず〇〇を入れる」（例: 不具合・要望フォーム、利用規約リンク、エラー通知）を、CLAUDE.md などのルール文書に書くだけで運用している。

• ルール文書が長くなると、該当節が毎回は読まれない（自動ロードされない別ファイルにあることも多い）。
• その結果、新しいアプリが作られ、何度も改修・本番デプロイされても、必須機能が一度も入らないまま運用される。
• 必須機能に「後段の処理」（例: 投稿 → Issue 化 → 対応完了時に投稿者へ通知）がある場合、後段の対象アプリ一覧がコードにハードコードされていると、新アプリは機能を入れても後段に乗らない。

対策の型

「本番反映コマンドの直前」に機械的に点検し、満たさなければ止める。

1. PreToolUse hook（matcher: Bash|PowerShell）を1本作る

• 発火条件: コマンドが本番反映系に一致したとき。
  • 例: vercel deploy / vercel --prod / vercel/dist/vc.js deploy / clasp push / clasp deploy / netlify deploy / wrangler deploy / firebase deploy / npm run deploy
• 対象ディレクトリの解決:
  • hook 入力の cwd を基本にする。
  • コマンド先頭の cd <dir> &&、Set-Location <dir>、--cwd <dir>、-C <dir> を優先する。
  • Windows の Git Bash 形式 /d/foo は D:/foo に読み替える（読み替えないと別ドライブを見て素通りする）。
  • そこから親へ辿り、package.json / appsscript.json / .clasp.json がある最初のディレクトリをプロジェクトルートにする。
• 種別判定:
  • package.json の依存に next があれば Next.js、appsscript.json か .clasp.json があれば GAS。
  • それ以外は対象外として通す。
• 搭載判定: 必須機能の目印（コンポーネント名・関数名などの固有文字列）を、ソースディレクトリから grep する。
  • node_modules、.next、.git、dist、build、out は除外する。
  • 走査は最大2000ファイルまでとし、上限に達したら通す（遅延防止）。
• 未搭載なら permissionDecision: "deny" を返す。理由文には次を入れる。
  • 導入コマンド
  • 導入後の検証方法
  • 除外の方法
• 例外・JSON パース失敗は必ず通す（fail-open）。hook のバグで全デプロイを止めないため。

2. 除外の逃げ道を「理由つきファイル」にする

• リポジトリ直下に .feature-exempt のようなファイルを置き、中身が空でなければ通す。空なら除外扱いにしない。
• 理由が残るので、後から監査できる。人の確認を取ってから置く運用にする。

3. 後段の対象一覧をハードコードから台帳ファイルへ

• apps.json（アプリ名 → リポジトリ）を新設し、後段処理の対応表にマージする。
• 同じ hook で「機能はあるが台帳に未登録」も deny する。
  • 例: Next.js なら API ルートに焼き込まれた APP_NAME を読み、台帳を引く。
• これで「入れたのに後段（通知・完了報告）が動かない」状態を本番に出さない。
• 台帳の配布反映を待てないときのために、環境変数でも登録扱いにできる口を用意しておく。

4. 全PCへの配布

• hook 登録スクリプトと、セットアップ時の点検項目（settings.json に hook 名が含まれるか）の両方に追加する。
• 片方だけだと、配布漏れが検知されない。

テスト（node:test）

最低限、次を一時ディレクトリのフィクスチャで確かめる。

• 未搭載 → deny
• 搭載済み → 通す
• GAS の未搭載 → deny
• 理由ありの除外ファイル → 通す
• 空の除外ファイル → deny
• 非デプロイコマンド → 通す
• cd "<dir>" && ... deploy の対象解決
• 非アプリディレクトリ → 通す
• 台帳に未登録 → deny
• 台帳に登録済み → 通す
• 子プロセス起動で壊れた JSON を渡すと exit 0・出力なし

落とし穴

• リポジトリに「相対 import がディレクトリ外へ出ない」などの静的検査があると、フィクスチャ文字列の import X from '../x' が本物の import と誤認されて CI が落ちる。フィクスチャには import 文を書かない（例: <FeatureWidget /> の JSX だけにする）。
• 後段の定期処理が「認証情報が未設定ならスキップして exit 0」になっていると、ログ上は毎晩成功に見えて実は何もしていない。
  • スキップは成功と区別して記録する。
  • 必須機能の導入完了は「実際に着信を確認したこと」で判定する。
• JS 構成の Next.js 14 に .ts/.tsx を足すと、自動生成された tsconfig は target 未指定になり、Map の for-of 反復で型エラーになる。
  • "target": "es2017" を足す。
  • typescript / @types/react / @types/node は明示的にインストールする（自動インストールが失敗することがある）。