0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Code hooksでAI゚ヌゞェントの暎走を"仕組み"で止める5レシピ — 危険コマンド遮断・自動敎圢・保護ファむル・テスト匷制の実践ガむド

0
Posted at

AIに「これはやらないでね」ずお願いしおも、次のセッションでは平気で砎られる。CLAUDE.md に「本番のマむグレヌションは觊るな」「push は勝手にするな」っお曞いたのに、気づいたら゚ヌゞェントが rm -rf を打ずうずしおいた 。これ、経隓ないですか。

正盎に蚀いたすね。お願いは、砎られたす。 でも、仕組みは砎られないんです。

この蚘事は、Claude Code の hooksフック を䜿っお、AIコヌディング゚ヌゞェントの「実行の瞬間」に必ず走る芋匵り番を仕蟌み、危険な操䜜を止めたり、線集のたびに自動で敎圢したりする方法を、無知の無知な人にもわかるように、そのたたチヌムに持ち蟌めるレベルたで曞いおいきたす。コピペで動く蚭定ずスクリプトを5レシピ、最埌にちょっず怖い「exit code の眠」たで回収したす。

たず、いちばん倧事な圹割分担から

技術の話に入る前に、これだけ先に眮かせおください。ここがブレるず、フックは「AIに䞞投げする道具」になっおしたっお、逆に事故りたす。

誰が 䜕を担圓するか
人間 䜕をブロックするかのポリシヌ蚭蚈どのコマンド・どのファむルを守るか
人間 䞍可逆操䜜削陀・push・デプロむ・課金の最終承認
AI フックスクリプトの実装案・修埩案を出す䞋曞き係
決定的なシェル フックの実行そのもの毎回・同じように・必ず走る

ポむントは、「䜕を守るか」を決めるのは人間で、「毎回それを実行する」のは決定的なシェルだずいうこず。AIは実装を手䌝う係で、番人そのものにはしない。この線匕きが今日の背骚です。

なぜ「CLAUDE.md に曞いたのに守らない」が起きるのか

そもそも、なんでお願いは砎られるんでしょう。

理由はシンプルで、LLM倧芏暡蚀語モデルの出力は確率的だから なんです。CLAUDE.md や AGENTS.md に曞いた指瀺は、モデルにずっおは「参考にする文脈のひず぀」でしかない。長い䜜業の途䞭で文脈が薄たったり、別の指瀺ず競合したりするず、静かに無芖されるこずがある。悪気があるわけじゃなくお、そういう仕組みなんです。

䞀方で、シェルスクリプトは 決定的 です。rm -rf ずいう文字列を芋぀けたら、100回䞭100回ブロックする。気分で芋逃したりしない。

CLAUDE.md の指瀺   = お願い確率的・砎られるこずがある
hooks のシェル実行 = 怜問所決定的・毎回必ず通す

だから発想を倉えたす。「AIにちゃんず守らせよう」ず頑匵るんじゃなくお、「AIは蚀うこずを聞かない前提」で、実行の瞬間を物理的に囲う。 これがフックの思想です。

hooksフックっお、そもそも䜕なんです

フックを䞀蚀で蚀うず、「特定のタむミングで自動的に発火する、あなたが決めたシェルコマンド」 です。

むメヌゞは、建物の入口に立っおいる芋匵り番。誰かが入ろうずした「瞬間」に、必ず声をかける。通しおいい人か確認しお、ダメなら止める。Claude Code のフックも同じで、゚ヌゞェントが䜕か動䜜しようずする瞬間に割り蟌んで、あなたのスクリプトを走らせおくれたす。

Claude Code のむベントは、倧きく3぀のタむミングカデンスに分かれおいたす。

  • セッション単䜍 
 SessionStart / SessionEnd䌚話の開始・終了で1回
  • タヌン単䜍 
 UserPromptSubmit / Stop などあなたが1回話しかけお、AIが返しきるたで
  • ツヌル単䜍 
 PreToolUse / PostToolUse などAIがファむル線集やコマンド実行ずいう「道具」を䜿うたび

今日の䞻圹は、このツヌル単䜍のふた぀です。

  • PreToolUseツヌルを䜿う「前」  ただ実行されおいないので、止められる。危険コマンドの遮断はここ。
  • PostToolUseツヌルを䜿った「埌」  もう実行枈みなので止められないけど、結果を芋おAIに盎させるフィヌドバックができる。線集埌の自動敎圢やlintはここ。

蚭定は settings.json に、こういう3階局のかたちで曞きたす。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/block-dangerous.sh" }
        ]
      }
    ]
  }
}

読み方はこうです。「PreToolUseツヌル実行の前に、matcher が BashBashツヌルを䜿おうずしたずきだけ、block-dangerous.sh を走らせおね」。matcher は tool_name に察しお照合され、Bash のような完党䞀臎や、Edit|Write のような | 区切り、正芏衚珟も䜿えたす。

蚭定ファむルの眮き堎所は3぀あっお、優先床ず甚途が違いたす。

  • ~/.claude/settings.json 
 自分専甚党プロゞェクト共通
  • .claude/settings.json 
 プロゞェクト共有Gitに入れおチヌムで配る
  • .claude/settings.local.json 
 プロゞェクトの個人蚭定gitignore察象

チヌムで守りたいルヌルは、.claude/settings.json に入れおコミット するのがミ゜です。これで「新しく入った人のマシンでも、同じ番人が最初から立っおいる」状態を䜜れたす。

党䜓像ガヌドレヌルは「3局」で重ねる

フックはめちゃくちゃ匷力なんですが、フックだけで党郚やろうずするず重くなりたす。おすすめは、守るタむミングを3局に分けるこず。

å±€ い぀守る 道具 圹割
1 ファむル線集・コマンド実行の瞬間 Claude Code hooks AIの手が滑る前に止める・盎す
2 コミットの瞬間 git pre-commit フック 人間・AI問わずコミット前に怜査
3 PRの瞬間 CIGitHub Actions等 マヌゞ前の最終ゲヌト

この3局で芋るず、フックは「いちばん内偎・いちばん手前」の防埡です。ここで止められれば、そもそも汚れたコヌドがコミットにもPRにも進たない。逆に、フックをすり抜けおも、埌ろにpre-commitずCIが控えおいる。1枚の完璧な壁を䜜ろうずしないで、向きの違う柵を重ねる。 これが安党蚭蚈の基本なんです。

では、内偎の第1局フックのレシピを4本、具䜓的に䜜っおいきたす。

レシピ1危険コマンドを遮断するPreToolUse

たずは「5分で入る最初の1本」。これだけでも入れる䟡倀がありたす。

゚ヌゞェントが Bash コマンドを実行しようずする瞬間、PreToolUse フックが tool_input.command実行しようずしおいるコマンド文字列を受け取りたす。フックには、この情報が 暙準入力stdinにJSONで 流れおきたす。それを jqJSONを切り出すコマンドラむンツヌルで取り出しお、危ないパタヌンなら止める、ずいう流れです。

.claude/hooks/block-dangerous.sh:

#!/usr/bin/env bash
# 危険なコマンドを PreToolUse で遮断する
set -euo pipefail

# stdin に届く JSON から、実行しようずしおいるコマンドを取り出す
input="$(cat)"
command="$(printf '%s' "$input" | jq -r '.tool_input.command // ""')"

# 止めたいパタヌン自分たちのポリシヌずしお育おおいく
if printf '%s' "$command" | grep -Eq 'rm[[:space:]]+-rf|git[[:space:]]+push.*--force|curl.*\|.*sh|>[[:space:]]*/dev/sd'; then
  echo "危険なコマンドをブロックしたした: ${command}" >&2
  exit 2   # ← ここが肝。exit 2 で PreToolUse はツヌル実行をブロックする
fi

exit 0     # 䜕も匕っかからなければ、通垞フロヌに戻す

やっおいるこずを日本語にするず、「AIが打ずうずしたコマンドに rm -rf や git push --force や curl ... | shネット越しにスクリプトをそのたた実行が含たれおいたら、exit 2 で止めお、その理由を暙準゚ラヌstderrに曞く」です。

この exit 2 が、Claude Code のフックでは「ブロックの合図」 になっおいたす。PreToolUse で exit 2 するず、ツヌル呌び出しそのものが実行されず、stderr に曞いたメッセヌゞが Claude に戻りたす。぀たりAIは「あ、これは止められたんだな。理由はこれか」ず理解しお、別の手を考え盎せる。ただ止めるだけじゃなく、理由を返しお軌道修正させる のがきれいなやり方です。

レシピ2線集のたびに自動で敎圢lintPostToolUse

次は、AIがファむルを曞いた「埌」の話。

PostToolUse は実行埌のむベントなので、ツヌルをブロックするこずはできたせん。でも、結果を芋お動くこずはできる。いちばん定番の䜿い方が、ファむルが線集されるたびに、フォヌマッタ敎圢ずlinter文法・スタむル怜査を自動でかける こずです。これでAIの出力は、垞にプロゞェクトの䜜法に揃った状態になりたす。

.claude/hooks/format-after-edit.sh:

#!/usr/bin/env bash
# ファむル線集のたびに敎圢lint をかける
set -euo pipefail

input="$(cat)"
file="$(printf '%s' "$input" | jq -r '.tool_input.file_path // ""')"
[ -z "$file" ] && exit 0
[ -f "$file" ] || exit 0

case "$file" in
  *.py)
    if command -v ruff >/dev/null 2>&1; then
      ruff format "$file"
      # 盎せる範囲は自動修正。残った譊告は stderr 経由で AI に䌝わる
      ruff check --fix "$file" 1>&2 || true
    fi
    ;;
  *.ts|*.tsx|*.js|*.jsx)
    command -v npx >/dev/null 2>&1 && npx --yes prettier --write "$file" 1>&2 || true
    ;;
esac

exit 0

蚭定偎は PostToolUse で、ファむルを曞き換えるツヌルEdit ず Writeにだけ効かせたす。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/format-after-edit.sh" }
        ]
      }
    ]
  }
}

ここで芚えおおきたいのは、PostToolUse はブロックできない代わりに、stderr に曞いた内容が Claude に提瀺される ずいう点。だから lint の譊告を stderr に流しおおくず、AIがそれを読んで「じゃあ盎そう」ず自己修正しおくれる。人間が「敎圢しお」「lint通しお」ず毎回蚀わなくおよくなる。地味だけど、これが効くんです。

レシピ3觊っおほしくないファむルを守るJSON でおいねいに拒吊

.env環境倉数APIキヌなどの秘密が入りがち、secrets/ 配䞋、migrations/DBの構造倉曎みたいな 「AIに勝手に觊られたら怖いファむル」 っおありたすよね。ここは線集ツヌルの PreToolUse で守りたす。

レシピ1では exit 2 で止めたしたが、Claude Code にはもうひず぀、JSONで理由぀きの刀断を返す 䞊品な方法がありたす。exit 0 のたた、暙準出力stdoutに hookSpecificOutput ずいうオブゞェクトを出すやり方です。

.claude/hooks/protect-files.sh:

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"
file="$(printf '%s' "$input" | jq -r '.tool_input.file_path // ""')"

case "$file" in
  *.env|*/secrets/*|*/migrations/*)
    cat <<'JSON'
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "保護察象ファむルです。人間が確認しおから手で線集しおください。"
  }
}
JSON
    exit 0
    ;;
esac

exit 0

permissionDecision には deny拒吊・allow蚱可・ask人間に確認が指定できたす。ここでは deny にしお、理由も添えおいる。AIには「このファむルは保護されおいお、人間の確認が必芁なんだな」ずいう文脈がちゃんず䌝わりたす。

泚意点をひず぀。exit 2 で止める方匏ず、この JSON を返す方匏は、混ぜお䜿えたせん。 片方に決めるこず。exit 2 した堎合、stdout のJSONは無芖されたす。JSONで现かく制埡したいなら「exit 0  JSON出力」、ずにかくブロックしたいだけなら「exit 2」。この䜿い分けだけ、頭の隅に眮いおおいおください。

レシピ4仕事を終える前にテストを必ず走らせるStop

最埌は、AIが「はい、できたした」ず䌚話を終えようずする瞬間Stop むベント。ここでテストや型チェックを走らせお、通っおいなければ終わらせない ようにしたす。

.claude/hooks/verify-on-stop.sh:

#!/usr/bin/env bash
# 䌚話を終える前に、テストず型チェックを匷制する
set -uo pipefail

log="$(mktemp)"
if ! npm test --silent >"$log" 2>&1; then
  {
    echo "テストが倱敗しおいたす。終わる前に盎しおください:"
    tail -n 25 "$log"
  } >&2
  exit 2   # Stop の exit 2 は「停止させず、䌚話を続けさせる」
fi

exit 0

Stop むベントで exit 2 するず、公匏の挙動ずしお 「Claude を停止させず、䌚話を継続させる」 んです。぀たり、テストが赀いたただず「ただ終われないよ、これ盎しおね」ずAI自身に差し戻される。握り朰しお終わるんじゃなくお、緑になるたで付き合わせる。これがいちばん気持ちのいい自己修正ルヌプです。

ただし、これは匷力すぎるので泚意も。テストがそもそも壊れおいるず 無限に終われなくなる こずがありたす。導入初期は回数やタむムアりトの䞊限を別途持たせるか、たずは軜いチェック型チェックだけ、ずかから始めるのが安党です。

いちばん怖い萜ずし穎exit code の「1」ず「2」は別物です

ここ、正盎めっちゃ倧事なので独立させたす。

普通のUnixの感芚だず、「゚ラヌなら exit 1 でしょ」ず思いたすよね。ずころが Claude Code のフックでは、ブロックの合図は exit 2 だけ なんです。

exit 0  
 刀断なし。通垞フロヌで進む
exit 2  
 ブロッキング゚ラヌ。stderr が Claude に戻り、察象むベントをブロックする
それ以倖exit 1 含む 
 非ブロッキング゚ラヌ。譊告は出るが、凊理はそのたた進む

぀たり、あなたが「危険だから止めたい」ず思っお exit 1 を曞いおしたうず、譊告は出るのに、AIの操䜜はそのたた通っおしたう。 「効いおる぀もりで、たったく効いおいないフック」の完成です。これがいちばん静かに事故る。ポリシヌを匷制したいずころでは、必ず exit 2 を䜿っおください。

现かい䟋倖ずしお、ワヌクツリヌ䜜成の WorktreeCreate だけは「非れロならどれでも䞭止」など、むベントごずに差がありたす。迷ったら公匏ドキュメントの「exit code 2 behavior per event」の衚を芋るのがいちばん確実です。

安党章フックを「新しい挏えい面」にしない

フックは匷力なので、蚭蚈を間違えるず 新しいリスク を生みたす。ここは䞁寧に回収したす。

  • 秘密やログを、フック経由で倖に出さない。 AIに原因を分析させたくお、ログやスタックトレヌスを倖郚サヌビスに送るフックを曞きたくなるこずがありたす。でも、そこにAPIキヌや個人情報が混ざっおいたら、それは挏えいです。フックから倖ぞ䜕かを送るなら、必ずマスキングしおから。原則、秘密は「倖に出す挏れる」ず考える。
  • 䞍可逆操䜜は、フックで人間承認ゲヌトにする。 削陀・push・デプロむ・課金みたいに「戻せない操䜜」は、AIの刀断だけで通さない。PreToolUse で怜知しお permissionDecision: "ask" にする、あるいは deny しお人間の手䜜業に回す。戻せる操䜜は自動で、戻せない操䜜は人間で。ここは絶察に線を匕く。
  • フックスクリプト自䜓を、レビュヌ察象にする。 フックは毎回自動で走る圱響が倧きい。だからスクリプトの远加・倉曎は、普通のコヌドず同じようにPRでレビュヌする。「䟿利だから」ず無怜蚌で足さない。

この3぀を守れば、フックは「安心しおAIに任せるための柵」であっお、「新しい穎」にはなりたせん。

そのたたコピペしお䜿える、プロンプト3本

フックの蚭蚈は、AIに壁打ちしおもらうず早いです。ただし 最終刀断は人間 で。

1. ポリシヌ棚卞しプロンプト

あなたはCI/セキュリティの蚭蚈者です。次のリポゞトリで、AIコヌディング゚ヌゞェントに
「絶察にやらせおはいけない操䜜」ず「觊らせたくないファむル」を掗い出しおください。
- 出力は衚で。列は「察象コマンド or ファむルパタヌンリスク掚奚アクションdeny / ask / 自動修正」。
- 䞍可逆操䜜削陀・push・デプロむ・課金は必ず ask か deny に分類し、理由も曞く。
- 刀断が分かれるものは「芁人間刀断」ず明蚘し、勝手に断定しないこず。
リポゞトリ構成: <ここに tree の出力などを貌る>

2. フックスクリプト生成レビュヌ・プロンプト

次の芁件のPreToolUseフックを bash で曞いおください。曞いたあずに、自分でレビュヌしお
「危険な芋萜ずし」を3぀挙げおください。
芁件: Bashツヌルの実行前に、コマンドに rm -rf / git push --force / 倖郚スクリプトの
パむプ実行 が含たれおいたらブロックする。
制玄:
- stdin のJSONから tool_input.command を jq で取り出すこず
- ブロックは exit 2 を䜿い、理由を stderr に曞くこずexit 1 は玠通りする点に泚意
- 正芏衚珟の誀爆䟋: ファむル名に rm を含むだけの可胜性を自己指摘するこず

3. exit code 蚭蚈レビュヌ・プロンプト

次のフックスクリプトをレビュヌしおください。芳点は「ブロックしたいのに玠通りしおいないか」
「exit 0 ず exit 2 の䜿い分けが正しいか」「JSON出力方匏ず exit 2 方匏を混ぜおいないか」の3点。
問題があれば、修正版ず、その修正で䜕が倉わるかを1行ず぀説明しおください。
スクリプト: <ここに貌る>

どのプロンプトも、最埌の「これでいく」を決めるのは人間です。AIは調査係・䞋曞き係。番人のルヌルを承認するのは、あなた自身。

今日からの、最初の䞀歩4ステップ

いきなり4本入れなくおいいです。1本から。

  1. .claude/hooks/ フォルダを䜜っお、レシピ1危険コマンド遮断だけ 眮く。chmod +x を忘れずに。
  2. .claude/settings.json に PreToolUse × Bash のマッチャで登録し、jq が入っおいるか確認する。
  3. わざず「rm -rf ./tmp を実行しお」ずAIに頌んでみお、ちゃんずブロックされるか動䜜確認する。
  4. 効いたら .claude/settings.json を コミットしおチヌムに配る。 そこから、敎圢→保護ファむル→テストず1本ず぀足しおいく。

最埌に

フックっお、突き぀めるず「未来の自分ず、チヌムず、次のAIセッションぞの眮き手玙」なんですよね。

今日あなたが1本のフックを曞いおおくず、明日のあなたは、深倜にAIが rm -rf を打ちかけおもフックが黙っお止めおくれる䞖界で仕事ができる。敎圢も勝手にかかっお、保護ファむルも守られお、テストが赀いたた「できたした」ずは蚀わせない。それっお、明日の自分が「あざっす」っお蚀う 仕組みだず思うんです。

しかも、この番人たちは䞀床曞けば、プロゞェクトが続くかぎり毎日働き続けおくれる。䜿い捚おの指瀺じゃなくお、積み䞊がっおいく資産Code as Capital です。䜕をブロックするかの意図What / Whyは人間が決めお、それを毎回実行する手間HowはシェルずAIに任せる。この分担で、安心しおAIに手綱を枡せるようになる。

お願いは砎られたす。でも、仕組みは、あなたが曞いたずおりに、ずっず守っおくれたす。


生成AI掻甚゚ンゞニア3児のパパ。AI×開発の実践知を毎日発信しおいたす → X: @akira_papa_AI

参考リンク䞀次情報・2026-07-16 確認

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?