CLAUDE.md に書いたのに守られないルールを、Claude Code の Hooks で守らせる（Laravel / Windows 編）

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "php artisan migrate:fresh" } ← これを見て判断する
  ~~~~~
}

Unsupported operating system [MINGW64_NT-10.0-26200]. Laravel Sail supports macOS, Linux, and Windows (WSL2).

# Claude Code hooks 共通ヘルパー（Windows PowerShell 5.1 / PowerShell 7 両対応）

$ErrorActionPreference = 'Stop'

# 日本語の入出力が化けないように、標準入出力を UTF-8 にそろえる
[Console]::InputEncoding  = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

# stdin で渡される JSON を読み取る
function Read-HookInput {
    $raw = [Console]::In.ReadToEnd()
    if ([string]::IsNullOrWhiteSpace($raw)) { return $null }
    return $raw | ConvertFrom-Json
}

# hook の中で例外が起きたら「止める」側に倒す（exit 2）。
# 例外のまま終わると exit 1 になり、ガードが黙って素通りになってしまうため
function Stop-OnHookError($err) {
    [Console]::Error.WriteLine("hook の実行に失敗したため、安全のため操作を止めました: $err")
    exit 2
}

# プロジェクトのルート（Claude Code が環境変数で渡してくれる）
function Get-ProjectDir {
    if ($env:CLAUDE_PROJECT_DIR) { return $env:CLAUDE_PROJECT_DIR }
    return (Resolve-Path "$PSScriptRoot\..\..").Path
}

# ツールの実行を止める。理由は Claude に返り、Claude はそれを読んで方針を変える
function Deny-Tool([string]$reason) {
    Write-HookJson @{
        hookSpecificOutput = @{
            hookEventName            = 'PreToolUse'
            permissionDecision       = 'deny'
            permissionDecisionReason = $reason
        }
    }
    exit 0
}

# 許可ルールがあっても、必ず人間に確認させる
function Ask-User([string]$reason) {
    Write-HookJson @{
        hookSpecificOutput = @{
            hookEventName            = 'PreToolUse'
            permissionDecision       = 'ask'
            permissionDecisionReason = $reason
        }
    }
    exit 0
}

# PostToolUse / Stop で「まだ終わりじゃない」と Claude に差し戻す
function Block-WithReason([string]$reason) {
    Write-HookJson @{ decision = 'block'; reason = $reason }
    exit 0
}

function Write-HookJson($obj) {
    [Console]::Out.Write(($obj | ConvertTo-Json -Depth 5 -Compress))
}

# Windows のパスを、コンテナ内（/var/www/html）のパスに変換する
function ConvertTo-ContainerPath([string]$path) {
    $root = (Get-ProjectDir).TrimEnd('\', '/')
    $rel = $path.Substring($root.Length).TrimStart('\', '/') -replace '\\', '/'
    return $rel
}

# git や docker を、プロジェクトのルートで実行する。
# PowerShell 5.1 は外部コマンドの stderr 出力を例外扱いすることがあるので、ここだけ Continue に戻す
function Invoke-Native([string]$exe, [string[]]$arguments) {
    $ErrorActionPreference = 'Continue'
    Push-Location (Get-ProjectDir)
    try {
        # 色付けの制御文字は Claude に渡しても読みにくいだけなので取り除く
        $ansi = [char]27 + '\[[0-9;]*m'
        $out = & $exe @arguments 2>&1 | ForEach-Object { "$_" -replace $ansi, '' }
        return [pscustomobject]@{ ExitCode = $LASTEXITCODE; Output = ($out -join "`n") ; Lines = @($out) }
    } finally {
        Pop-Location
    }
}

# Sail のコンテナ内でコマンドを実行する（sail スクリプトは Git Bash では動かないので compose を直接呼ぶ）
function Invoke-Sail([string[]]$arguments) {
    return Invoke-Native 'docker' (@('compose', 'exec', '-T', 'laravel.test') + $arguments)
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell", ← Windows では PowerShell ツールも使われるので両方
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File",
                     "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-bash.ps1"] ← プロジェクトの場所は自動で埋まる
          }
        ]
      }
      ~~~~~

# PreToolUse(Bash|PowerShell)：危険なコマンドを止める／人に確認させる
. "$PSScriptRoot\lib.ps1"
trap { Stop-OnHookError $_ }

$hook = Read-HookInput
$command = [string]$hook.tool_input.command
if (-not $command) { exit 0 }

# 1. DB を消すコマンドは、どんな許可設定でも通さない
$migrateHint = 'マイグレーションを試したいときは、新しいマイグレーションを追加して php artisan migrate を使ってください。'
$destructive = @(
    @{ pattern = 'migrate:(fresh|reset|refresh)'; why = 'DB のテーブルがすべて削除・再作成されます'; hint = $migrateHint },
    @{ pattern = 'db:wipe'; why = 'DB のテーブルがすべて削除されます'; hint = $migrateHint },
    @{ pattern = 'git\s+push\b.*\s(--force|-f)(\s|$)'; why = 'リモートの履歴を上書きします'; hint = '' },
    @{ pattern = 'git\s+reset\s+--hard'; why = 'コミットしていない変更が消えます'; hint = '' }
)
foreach ($rule in $destructive) {
    if ($command -match $rule.pattern) {
        # 「ダメ」だけでなく、代わりにどうすればいいかを返すと、Claude が自分で方針を変えてくれる
        Deny-Tool ("このコマンドはプロジェクトのルールで禁止されています（{0}）。" -f $rule.why + $rule.hint +
            "どうしても必要な場合は、実行せずにユーザーへ理由を説明して依頼してください。")
    }
}

# 2. 共有ブランチに影響する操作は、許可設定があっても必ず人に確認させる
if ($command -match 'git\s+(push|merge)\b' -or $command -match 'gh\s+pr\s+merge') {
    Ask-User 'push / merge は人間の確認が必要なルールです。'
}

exit 0

# PreToolUse(Edit|Write)：コミット済みのマイグレーションと .env を書き換えさせない
. "$PSScriptRoot\lib.ps1"
trap { Stop-OnHookError $_ }

$hook = Read-HookInput
$path = [string]$hook.tool_input.file_path
if (-not $path) { exit 0 }

# Windows では \ 区切りで届くので、比較用に / にそろえる
$normalized = $path -replace '\\', '/'
$rel = ConvertTo-ContainerPath $path

# .env 系（.env.example だけは OK）
if ($normalized -match '/\.env(\.[^/]+)?$' -and $normalized -notmatch '/\.env\.example$') {
    Deny-Tool '.env は編集禁止です。必要な設定値はユーザーに伝えて、手で設定してもらってください。'
}

# マイグレーション：git にコミット済み = どこかの環境で実行済み、とみなして編集を禁止する
if ($rel -match '^database/migrations/.+\.php$' -and (Test-Path -LiteralPath $path)) {
    $tracked = (Invoke-Native 'git' @('ls-files', '--error-unmatch', '--', $rel)).ExitCode -eq 0
    if ($tracked) {
        Deny-Tool ("{0} はコミット済みのマイグレーションなので編集できません。" -f $rel +
            "テーブル定義を変えたいときは、php artisan make:migration で新しいマイグレーションを追加してください。")
    }
}

exit 0

# PreToolUse(Bash|PowerShell)：git commit のときだけ、秘密情報が混ざっていないか確かめる
. "$PSScriptRoot\lib.ps1"
trap { Stop-OnHookError $_ }

$hook = Read-HookInput
$command = [string]$hook.tool_input.command
if ($command -notmatch 'git\s+commit\b') { exit 0 }

$files = (Invoke-Native 'git' @('diff', '--cached', '--name-only')).Lines
$diff = (Invoke-Native 'git' @('diff', '--cached', '-U0')).Output

# .env そのものがステージされていないか
$envFiles = $files | Where-Object { $_ -match '(^|/)\.env(\.|$)' -and $_ -notmatch '\.env\.example$' }
if ($envFiles) {
    Deny-Tool ("{0} がステージされています。git restore --staged で外してからコミットしてください。" -f ($envFiles -join ', '))
}

# 追加行（+ で始まる行）だけを見る
$added = ($diff -split "`n" | Where-Object { $_ -match '^\+' -and $_ -notmatch '^\+\+\+' }) -join "`n"
$secrets = @(
    @{ pattern = 'AKIA[0-9A-Z]{16}'; name = 'AWS アクセスキー' },
    @{ pattern = 'sk-[A-Za-z0-9_-]{20,}'; name = 'API キー（sk-）' },
    @{ pattern = 'base64:[A-Za-z0-9+/=]{40,}'; name = 'APP_KEY' },
    @{ pattern = '-----BEGIN [A-Z ]*PRIVATE KEY-----'; name = '秘密鍵' }
)
foreach ($s in $secrets) {
    if ($added -match $s.pattern) {
        Deny-Tool ("コミット対象に {0} らしき文字列が含まれています。.env に移して、コードからは env() / config() で参照してください。" -f $s.name)
    }
}

exit 0

# PostToolUse(Edit|Write)：PHP を編集したら Pint で整形する
# ※ PHPStan はここでは回さない（1回 60 秒前後かかるため）。stop-gate.ps1 でまとめて回す
. "$PSScriptRoot\lib.ps1"
trap { Stop-OnHookError $_ }

$hook = Read-HookInput
$path = [string]$hook.tool_input.file_path
if ($path -notmatch '\.php$') { exit 0 }

# 整形は黙ってやる（Claude に伝える必要はない）
Invoke-Sail @('vendor/bin/pint', '--quiet', (ConvertTo-ContainerPath $path)) | Out-Null

exit 0

# Stop：PHPStan とテストが通るまで、「終わりました」と言わせない
. "$PSScriptRoot\lib.ps1"
trap { Stop-OnHookError $_ }

$hook = Read-HookInput

# hook で差し戻された続きの作業なら、二重に止めない（無限ループ防止）
if ($hook.stop_hook_active) { exit 0 }

# 変更のあったファイル（未コミット＋新規）を集める
$changed = (Invoke-Native 'git' @('status', '--porcelain', '--untracked-files=all', '--', 'app', 'routes', 'database', 'tests', 'config')).Lines |
    Where-Object { $_ } |
    ForEach-Object { ($_.Substring(3) -split ' -> ')[-1].Trim('"') }

# PHP に変更がなければ（雑談や調査だけなら）何もしない
if (-not $changed) { exit 0 }

# 1. 静的解析：変更した app/ 配下のファイルだけ
$appFiles = @($changed | Where-Object { $_ -match '^app/.+\.php$' })
if ($appFiles.Count -gt 0) {
    $result = Invoke-Sail (@('vendor/bin/phpstan', 'analyse', '--no-progress', '--error-format=raw', '--memory-limit=1G') + $appFiles)
    if ($result.ExitCode -ne 0) {
        $errors = ($result.Lines | Where-Object { $_ -match '\.php:\d+:' }) -join "`n"
        if (-not $errors) { $errors = $result.Output.Trim() }
        Block-WithReason ("PHPStan でエラーが出ています。修正してから終了してください。`n" + $errors)
    }
}

# 2. テスト
$result = Invoke-Sail @('php', 'artisan', 'test', '--compact')
if ($result.ExitCode -ne 0) {
    # 出力が長いと Claude のコンテキストを圧迫するので、末尾だけ渡す
    $tail = ($result.Lines | Select-Object -Last 40) -join "`n"
    Block-WithReason ("テストが失敗しています。原因を調べて直してから終了してください。`n" + $tail)
}

exit 0

型宣言は不要とのことでしたが、保存時に PHPStan のフックが
「戻り値の型がない」とエラーにしたため、`: int` を付けました。

{
  "matcher": "Edit|Write",
  "hooks": [
    {
      "type": "prompt",
      "if": "Edit(tests/**)", ← tests/ 配下を編集するときだけ判定する
      "continueOnBlock": true, ← 止めた理由を Claude に返して、作業を続けさせる
      "prompt": "あなたは Laravel プロジェクトのコードレビュアーです。以下は、AI がテストファイルに加えようとしている変更です。\n\n$ARGUMENTS\n\n次の基準で判定してください。\n- テストを削除する、スキップする（markTestSkipped 等）、アサーションを削除・緩める（具体的な値の検証をやめる、期待値を実際の出力に合わせて意味のない値にする等）など、テストがバグを見つける力を下げる変更なら ok: false。reason は「テストを弱める変更なので、実行せずにユーザーへ理由を説明して判断を仰いでください」とする。\n- 仕様変更に合わせて期待値を正しく書き換える、テストを追加する、読みやすくするなど、バグを見つける力を保つ・高める変更なら ok: true。"
    }
  ]
}

削除はまだ実行していません。このプロジェクトのフックが編集をブロックしたためです。
……進め方は次の3つから選べます。
1. そのまま削除する
2. 不安定な原因を調べて直す
3. 別の形で検証を残す

[powershell.exe guard-bash.ps1] exit=1 ← 構文エラーで exit 1

> powershell.exe -NoProfile -ExecutionPolicy Bypass -File .claude\hooks\tests\run-tests.ps1
OK  bash-migrate-fresh         expect=deny   actual=deny     630ms
OK  powershell-push            expect=ask    actual=ask      509ms
OK  bash-force-push            expect=deny   actual=deny     522ms
OK  bash-migrate               expect=allow  actual=allow    470ms
OK  edit-committed-migration   expect=deny   actual=deny     735ms
OK  write-new-migration        expect=allow  actual=allow    495ms
OK  edit-env                   expect=deny   actual=deny     441ms
OK  edit-env-example           expect=allow  actual=allow    439ms
OK  broken-json                expect=error  actual=error    447ms ← 壊れた入力で止まるか
すべて OK

[INFO] Slow PostToolUse hooks: 132530ms for Edit (2 hooks)