# 社内アプリの「必須機能」をルール文書ではなく、デプロイ直前の 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 &&`、`Set-Location `、`--cwd `、`-C ` を優先する。 - 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 "" && ... deploy` の対象解決 - 非アプリディレクトリ → 通す - 台帳に未登録 → deny - 台帳に登録済み → 通す - 子プロセス起動で壊れた JSON を渡すと exit 0・出力なし ## 落とし穴 - リポジトリに「相対 import がディレクトリ外へ出ない」などの静的検査があると、フィクスチャ文字列の `import X from '../x'` が本物の import と誤認されて CI が落ちる。フィクスチャには import 文を書かない（例: `` の JSX だけにする）。 - 後段の定期処理が「認証情報が未設定ならスキップして exit 0」になっていると、ログ上は毎晩成功に見えて実は何もしていない。 - スキップは成功と区別して記録する。 - 必須機能の導入完了は「実際に着信を確認したこと」で判定する。 - JS 構成の Next.js 14 に .ts/.tsx を足すと、自動生成された tsconfig は target 未指定になり、`Map` の for-of 反復で型エラーになる。 - `"target": "es2017"` を足す。 - `typescript` / `@types/react` / `@types/node` は明示的にインストールする（自動インストールが失敗することがある）。 ---