大学生のころ月10万の副業から始めて、掛け持ちで月60万まで伸ばした。会社都合で解雇されて一時期ゼロになったけれど、半年でClaude Codeの自律環境を整えて今は月商120万。その経験で一番強く思うのは「同じミスを口頭で直し続けるのは時間の浪費だ」ということです。

なぜこの仕組みが効くのか

口頭指摘が効かない本当の理由

Claude Codeに「! ハンドオフで && を使わないで」と言い聞かせても直りませんでした。2026年7月16日までに5回以上指摘しています。毎回「わかりました」と返ってくる。でも次のセッションでは同じコマンドが出てきます。

これは Claude の怠慢ではなく、アーキテクチャの問題です。

Claude Codeのセッションは会話ごとに独立しています。前のセッションで「これはダメ」と教えた内容は、次のセッション起動時点では存在しない。CLAUDE.md に書けば常時注入されるとはいえ、あの量のルールを読んでいる中で一行の注意書きが確実に機能するかというと、実際のコード出力を見ればわかります——機能しませんでした。

口頭指摘で直らない理由はシンプルです。指摘はコンテキストに乗り、コンテキストはセッションと共に消える。

ブロッキングコマンド連鎖で何が起きるか

Claude Codeの ! コマンドはシェルを起動してコマンドを実行します。このとき --auth オプション付きのサーバー起動など、プロセスを占有するブロッキング系のコマンドを && で連鎖させると、最初のコマンドが完了を返さないまま待機状態に入り、後続のコマンドは永遠に実行されません。セッション全体が固まります。

正しいのは &（バックグラウンド実行）を使って次のコマンドに制御を渡すことです。&& は「前のコマンドが正常終了したら次を実行」という逐次実行なので、ブロッキングプロセスの後では絶対に機能しない。

# 壊れる型（セッションが固まる）
! npx wrangler dev --local &amp;&amp; open http://localhost:8787

# 正しい型（バックグラウンドで起動してから次へ）
! npx wrangler dev --local & sleep 2 && open http://localhost:8787

この差は小さく見えて、デバッグコストは巨大です。固まったと気づくまで数分待つ、強制終了する、再度試みる——これが毎回発生していました。

「作業」ではなく「環境」を変える

口頭で5回直してもらえなかった。ならば物理的に不可能にするしかない。

Claude Codeには Stop hook という機能があります。Claude が応答を返す直前に任意のシェルスクリプトを実行できます。そのスクリプトが exit 2 を返すと、Claude の応答はユーザーに届く前にブロックされ、エラーメッセージが表示されます。

これはルールではありません。コードです。コードは次のセッションになっても消えない。セッションをまたいでも消えない。Claude がどれだけ「ハンドオフコマンドです」というラベルを付けようとも、&& が含まれていれば物理的に通過できません。

問題を「指摘→修正」の繰り返しから「環境設計」に変えた瞬間、同じ失敗は二度と起きなくなりました。

これが個人開発で自動化を積み上げるときの基本思想です。自分が再現性のある手順を踏んでいるなら、それをコードにする。Claudeが繰り返すミスがあるなら、そのミスを物理的に封じる環境を作る。

読者のあなたも同じ経験をしているはずです。「前にも言ったのに」「わかったと言ったのに」「なぜまた同じことを」——その感覚は正しい。問題はコミュニケーションではなく、設計です。

全体の流れ

システム構成の概要

Stop hook は Claude Code の設定ファイル（.claude/settings.json または ~/.claude/settings.json）に登録します。Claude が応答を生成し終えたタイミングで、登録したスクリプトが起動します。スクリプトには JSON でトランスクリプトのパスが渡されます。

今回の bang_handoff_amp_guard.sh は46行のスクリプトです。やることは一つ——最後の assistant メッセージを読んで、! で始まる行に && が含まれていたらブロックする。

Claude が応答を生成
        │
        ▼
Stop hook が起動
stdin に JSON（transcript_path を含む）が渡される
        │
        ▼
transcript_path を取り出す
        │
        ├── パス無し / ファイル無し → exit 0（フェイルオープン・通過）
        │
        ▼
transcript JSONL を Python でパース
全 assistant メッセージを収集
        │
        ▼
最後の assistant メッセージだけ取り出す
        │
        ▼
行ごとにコードフェンス（```）・バッククォートを除去
        │
        ▼
正規表現チェック: ^!\s かつ && を含む行があるか
        │
        ├── ある  → stderr にエラー出力 → exit 2（ブロック）
        └── ない  → exit 0（通過・Claude の応答がユーザーへ届く）

実コードの構成と各パートの意図

スクリプト全体を3つのブロックに分けて見ていきます。

ブロック1: トランスクリプトパスの取得とフェイルオープン

input=$(cat)
tpath=$(printf '%s' "$input" | /usr/bin/python3 -c \
  "import sys,json;print(json.load(sys.stdin).get('transcript_path',''))" 2>/dev/null)
[ -n "$tpath" ] && [ -f "$tpath" ] || exit 0

Stop hook の stdin には Claude Code から JSON が流れてきます。transcript_path キーにトランスクリプトファイルの絶対パスが入っています。Python でそれを取り出し、パスが空またはファイルが存在しない場合は exit 0 で素通りします。

これがフェイルオープン設計です。スクリプトが何らかの理由でトランスクリプトを読めなくても、Claude の応答は通過します。誤ブロックによる作業停止は、&& による固まりより遥かにコストが高い。だから「読めなければ黙って通す」を原則にしています。

ブロック2: トランスクリプトのパースと最後のメッセージ抽出

msgs = []
try:
    for line in open(sys.argv[1], encoding="utf-8"):
        line = line.strip()
        if not line:
            continue
        try:
            o = json.loads(line)
        except Exception:
            continue
        if o.get("type") == "assistant" or o.get("role") == "assistant":
            m = o.get("message", o)
            c = m.get("content")
            if isinstance(c, list):
                for b in c:
                    if isinstance(b, dict) and b.get("type") == "text":
                        msgs.append(b.get("text", ""))
            elif isinstance(c, str):
                msgs.append(c)
except Exception:
    pass
last = msgs[-1] if msgs else ""

Claude Code のトランスクリプトは JSONL 形式です（1行1JSONオブジェクト）。各行を json.loads() でパースし、type または role が "assistant" のエントリを拾います。content はリスト形式（複数ブロック）と文字列形式の両方があるので両パターンを処理しています。

全 assistant メッセージを msgs リストに積み、最後の一つだけ last に取り出します。過去の会話履歴は関係ない——今回の応答だけを検査します。

ブロック3: 検出パターンと出力

bt = chr(96)  # backtick をコード内で直接書かない
for ln in last.splitlines():
    s = ln.strip().strip(bt).strip()   # コードフェンス/バッククォート除去
    if re.match(r'^!\s', s) and '&&' in s:
        print(s)
        break

echo "🚫 ! ハンドオフに && を使った(本人が5回以上指摘済)。Claude Codeの ! セッションでは \
&& でブロッキング系(--auth等)を連鎖すると固まって通らない。\
>> && を単一 & に直して出し直せ <<。該当行: ${bad}" >&2
exit 2

検出ロジックは2段階です。

まず各行からコードフェンス（バッククォート）を剥がします。Claude はコードブロックの中にコマンドを書くことがあります。``` で囲まれていても、その中身が実際のコマンドである場合は検出対象にする必要があります。ここで bt = chr(96) というトリックが出てきます——スクリプト自体がシェルから eval されることがあるため、スクリプト内にバッククォートを直接書くと自己パースエラーが発生します。chr(96) でバッククォートの文字を動的に生成して回避しています。

剥がした後、正規表現 ^!\s で行の先頭が ! （感嘆符＋スペース）であることを確認し、さらに && が含まれているかをチェックします。両方が true のとき、その行を stdout に print して Python スクリプトを終了します。

bash 側でその出力を bad 変数に受け取り、空でなければ exit 2。空であれば exit 0。

エラーメッセージには「本人が5回以上指摘済(2026-07-16)」という記述がそのまま入っています。これは将来の自分（または Claude）へのコンテキストです。なぜこのスクリプトが存在するのか、なぜこれがルールなのかを、コード内のコメントとエラーメッセージで自己説明させています。

設定ファイルへの登録

Stop hook は ~/.claude/settings.json の hooks セクションに登録します。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/bang_handoff_amp_guard.sh"
          }
        ]
      }
    ]
  }
}

Stop イベントは Claude が応答を完成させた直後に発火します。matcher を空文字にすることで全ての応答に対して実行されます。特定のプロジェクトだけに適用したい場合はプロジェクトの .claude/settings.json に書きます。グローバルに適用したいなら ~/.claude/settings.json です。このスクリプトは ~/.claude/hooks/ に置いてグローバル登録しています——&& 問題はプロジェクト横断で発生するからです。

スクリプトには実行権限が必要です。

chmod +x ~/.claude/hooks/bang_handoff_amp_guard.sh

これで設定は完了です。次のセッション以降、&& を含む ! ハンドオフコマンドを出力しようとした瞬間に Claude の応答がブロックされ、stderr にエラーメッセージが表示されます。Claude は応答を出し直す（&& を & に直す）しかなくなります。

口頭で5回指摘し続けた問題が、46行のスクリプトで物理的に消えました。

なぜその書き方でなければならないか

前章でスクリプト全体の構造と3ブロックの役割を見ました。ここでは「動くだけ」ではなく「壊れにくく動く」ために施した設計判断を掘り下げます。実際に詰まって後から気づいたものばかりです。

stdin を変数に一度受ける理由

input=$(cat)
tpath=$(printf '%s' "$input" | /usr/bin/python3 -c "..." 2>/dev/null)

最初の行で cat を変数 input に入れています。Stop hook の JSON は標準入力から来るので、cat を Python に直接パイプすれば1行で済みます。それをしない理由は「stdin は一度しか読めない」からです。

パイプでそのまま渡すと stdin を消費し切ります。デバッグ時に同じ入力を別の Python 呼び出しにも渡したい、あるいはスクリプトを拡張して複数の値を取り出したい——そういう場面で詰みます。input=$(cat) で先に全部受け取り、printf '%s' "$input" で何度でも再利用できる形にする。これがシェルスクリプトで stdin を扱う安全な型です。

`/usr/bin/python3` とフルパスで書く理由

tpath=$(printf '%s' "$input" | /usr/bin/python3 -c "..." 2>/dev/null)
bad=$(/usr/bin/python3 - "$tpath" <<'PY'

2箇所とも python3 ではなく /usr/bin/python3 です。

Stop hook が起動するシェルは通常のターミナルセッションではありません。~/.zshrc も ~/.bash_profile も読み込まれていないため、$PATH は最小限の状態です。nvm 経由でインストールしたツール類は当然見えない。pyenv や Homebrew の Python も見えません。

python3 というコマンド名だけでは、hook のシェル環境に完全に依存します。macOS のシステム Python は Xcode コマンドラインツールさえ入っていれば必ず /usr/bin/python3 にあります。フルパスで指定することで、環境に左右されない移植性が確保できます。

確認方法は簡単です。

/usr/bin/python3 --version

このコマンドが通れば hook 内でも同じパスが使えます。

ヒアドキュメントのシングルクォートが命綱

bad=$(/usr/bin/python3 - "$tpath" <<'PY'
import sys, json, re
...
if re.match(r'^!\s', s) and '&&' in s:
PY
)

ヒアドキュメントのマーカーを 'PY'（シングルクォートあり）にしています。<<PY（クォートなし）との違いは根本的です。

クォートなし <<PY では、ヒアドキュメント内の $変数 やバッククォートがシェルに展開されます。たとえば正規表現 r'^!\s' の \s がシェルによって s に変換されてしまいます。Python には r'^!s' というパターンが渡される。スペースにマッチするはずの \s が失われ、検出ロジック全体が壊れます。

<<'PY' にするとヒアドキュメント全体がリテラル文字列として扱われます。どんな Python コードをそのまま渡せます。シェルスクリプトに Python を埋め込む場合のシングルクォートは絶対原則です。

`type` と `role` の両方を見る理由

if o.get("type") == "assistant" or o.get("role") == "assistant":

or で2つのフィールドを参照しています。これは Claude Code のトランスクリプト JSONL が、バージョンやセッションの長さによって異なるフォーマットを使っているためです。

古いエントリは role: "assistant" フィールドを持ちます。新しいエントリは type: "assistant" フィールドを使います。一つのトランスクリプトファイルに両方が混在することもあります。長いセッションでは前半が旧フォーマット、後半が新フォーマットという状況が普通に起きます。

type だけ見ていると、role: "assistant" のメッセージが msgs リストに積まれず、最後の assistant メッセージを正しく特定できなくなります。

Claude Code はバージョンアップで内部フォーマットが変わることがあります。特定フィールドだけに依存する実装は、アップデートのたびに壊れる可能性があります。複数フィールドをフォールバックとして見るのが安全な書き方です。

`chr(96)` でバッククォートを間接生成する理由

bt = chr(96)  # backtick をコード内で直接書かない
for ln in last.splitlines():
    s = ln.strip().strip(bt).strip()

ASCII コード96番がバッククォートです。なぜ直接書かないかというと、スクリプトがシェルの heredoc に埋め込まれている以上、将来別のシェルコンテキスト（eval 経由、別スクリプトからの source など）に移植された際にバッククォートが自己パースエラーを引き起こすリスクがあるからです。

chr(96) で実行時に文字を生成すれば、スクリプト本文にバッククォートが一文字も登場しません。加えて、str.strip(bt) を使うことで「コードフェンスで囲まれたコマンド」も正しく処理できます。

Claude がコマンドをインラインバッククォートで囲んで書いた場合——たとえば 「次のコマンドを実行してください: `! npx wrangler dev --local && open http://localhost:8787` 」 のような出力——でも、バッククォートを剥がした後に正規表現でチェックするので検出漏れになりません。

私が詰まった話

完成した46行は整然として見えますが、動く前には4回詰まりました。それぞれ「症状→原因→直し方」で書きます。

詰まり1: grep で書いたら検出率ゼロだった

最初の実装

一番シンプルに考えて、こう書きました。

if grep -qE '^\! .* &&' "$tpath"; then
    echo "🚫 && を使わないでください" >&2
    exit 2
fi

ターミナルで手動テストすると動く。Claude に && 入りのコマンドを実際に出力させてみると——通過する。ブロックされない。

原因

トランスクリプトは JSONL です。各行が1つの JSON オブジェクトで、実際のテキストは "text" フィールドの値として JSON エンコードされています。ファイルをそのまま grep すると、デコード前の生バイト列を見ることになります。

JSON の中では ! が ! になっていることがあります。&& は && に変換されていることもあります。改行は \n のリテラル2文字（バックスラッシュとn）として格納されています。grep のパターン ^\! .* && は1行のテキストにマッチしようとしますが、JSONL の1行は JSON オブジェクト全体です。中身の改行は \n という2文字として格納されているので、実際のコマンド行は grep には「1行」として見えません。

直し方

Python で JSON をパースして、text フィールドを取り出してから正規表現をかける。デコード済みの実テキストを見る限り、JSON エスケープの問題は発生しません。grep でトランスクリプトを直接スキャンする実装は根本的に誤りです。

詰まり2: フェイルオープンが「常に通過」に化けていた

症状

Stop hook を設定し直し、Claude に && を含む ! コマンドを出力させても、やはりブロックされない。exit 0 で素通りしている。デバッグ用に echo "hook起動" >&2 を先頭に入れると出力される——hook 自体は確かに動いている。なのに exit 2 に到達しない。

原因

2>/dev/null で python3 のエラーを捨てていたため、気づかなかったのです。実際には：

/usr/bin/python3: command not found

というエラーが出ていました。hook のシェルから python3（フルパスなし）を呼んでいたため見つからない。python3 が見つからない → tpath が空文字列になる → [ -n "$tpath" ] || exit 0 でフェイルオープン → 全部通過。という流れです。

フェイルオープン設計が正しい方向性である一方、「誤りを隠してしまう」副作用として現れました。

直し方

まず /usr/bin/python3 --version を hook のシェルで確認します。Hook は launchd や内部プロセスから起動されるため、PATH が通常と違います。確認できたフルパスをそのままスクリプトに書く。デバッグ時は 2>/dev/null を一時的に外して stderr を見ます——エラーが見えるようになるだけで原因特定が劇的に速くなります。

詰まり3: ヒアドキュメントが Pyhon コードを破壊していた

症状

python3 のフルパス問題は直した。でも bad 変数が常に空で、&& を含むコマンドを書いても exit 2 にならない。2>/dev/null を外して stderr を見ると：

  File "<stdin>", line 1
    if re.match(r'^!s', s) and '&&' in s:
                       ^
SyntaxError: invalid syntax

r'^!\s' が r'^!s' になっています。

原因

ヒアドキュメントを <<PY（クォートなし）で書いていました。Python コードの正規表現 r'^!\s' は \s を含みます。bash はクォートなしのヒアドキュメント内でバックスラッシュをエスケープとして処理するため、\s の \ が消えて s だけが残りました。Python 側では r'^!s' という全く別のパターンが渡されます。スペースにマッチするはずの \s が失われ、どの行もマッチしない状態になっていました。

直し方

<<PY を <<'PY' に変える。それだけです。この1文字（'）の差で動作が根本から変わります。Python を埋め込む heredoc には必ずシングルクォートをつけます。他のスクリプトでも同じ問題を踏む可能性があるので、Pythonコード埋め込み用の heredoc はシングルクォート必須と体に覚えさせました。

詰まり4: 特定セッションだけブロックが発動しない

症状

基本的には動いています。ただし、長めのセッション（30往復以上の会話）で Claude が && コマンドを書いても、通過してしまうことがある。短いセッションでは確実にブロックされる。

原因

実際のトランスクリプトを直接覗いて確認しました。

python3 -c "
import json
for l in open('/path/to/transcript.jsonl'):
    l = l.strip()
    if not l: continue
    o = json.loads(l)
    print(list(o.keys())[:4])
"

出力を見ると、セッション序盤のエントリは ['role', 'content', ...] という構造で、後半のエントリは ['type', 'message', ...] という構造になっています。最初の実装では o.get("type") == "assistant" だけを見ていたため、序盤の role: "assistant" エントリが全部スキップされていました。

長いセッションでは type: "assistant" のメッセージが存在しない、あるいは最後のメッセージが role: "assistant" 形式になっていることがあります。そうなると msgs が空になり、last = "" → 何も検出しない → exit 0、という経路をたどります。

直し方

if o.get("type") == "assistant" or o.get("role") == "assistant":

or で両方のフィールドを確認します。Claude Code のバージョンアップでフォーマットが変わっても、どちらかのフィールドが "assistant" を持っていれば拾えます。

4回詰まって、その都度1行か2行足した結果が今の46行です。コードの各行は「なぜここに存在するか」に答えられます。/usr/bin/python3 はフルパスでないと hook 環境で見つからないから。<<'PY' はシングルクォートがないと Python コードが壊れるから。or o.get("role") は旧フォーマットを拾いこぼさないため。フェイルオープンの exit 0 は誤ブロックを防ぐため。

「なぜそう書くか」が言えないコードは、壊れた時に直せません。詰まった記憶がそのまま設計根拠になっています。

共通のデバッグ手順——hook が「なぜか素通りする」と感じたら

Stop hook 系のトラブルはどれも「フェイルオープンが静かに通過させている」パターンに帰着します。まず確認すること3点です。

1. hook 自体が起動しているかを確認する

スクリプトの冒頭に1行追加します。

echo "[DEBUG] hook起動 tpath=${tpath}" >&2

Claude の応答後に stderr にこの行が出なければ、hook 自体が起動していません。設定ファイルのパスが間違っているか、実行権限がついていないかです。

ls -la ~/.claude/hooks/bang_handoff_amp_guard.sh
# → -rwxr-xr-x になっているか確認。rが抜けていたら chmod +x

2. 2>/dev/null を外してエラーを見る

フェイルオープン設計は「静かに通過」するため、内部でエラーが起きていても表面に出ません。一時的に 2>/dev/null を外します。

# 変更前
tpath=$(printf '%s' "$input" | /usr/bin/python3 -c "..." 2>/dev/null)

# デバッグ用（確認後に戻す）
tpath=$(printf '%s' "$input" | /usr/bin/python3 -c "...")

stderr に command not found や SyntaxError が見えたら原因がわかります。確認が終わったら必ず 2>/dev/null を戻してください。

3. トランスクリプトの構造を直接覗く

python3 -c "
import json, sys
for l in open(sys.argv[1]):
    l = l.strip()
    if not l: continue
    o = json.loads(l)
    role = o.get('role') or o.get('type', '?')
    if role == 'assistant':
        print('--- assistant entry keys:', list(o.keys()))
" ~/.claude/projects/.../transcript.jsonl

これで type と role どちらのフィールドが使われているか、content がリストか文字列かを実際のファイルで確認できます。Claude Code のバージョンが変わってフォーマットが変わっていると思ったときも、ここを見れば即座にわかります。

3点確認すれば、「素通りの原因」は必ずどれかに当てはまります。Hook の問題は仕組みを理解していれば難しくありません。詰まるのはいつも「静かに通過している」ことに気づくのが遅いだけです。

つまずきポイント

p2では実際に詰まった4回を掘り下げました。ここでは運用を続ける中でじわじわ出てきた追加の落とし穴を箇条書きで網羅します。「なぜか動かない」「なぜかブロックされない」のデバッグ照合リストとして使ってください。

settings.json の構文エラーで hook がサイレントに無効化される

JSON の末尾カンマ・閉じ括弧の不足・キー名のクォート漏れ。Claude Code は起動時にこれらのパースエラーを目立つ形で通知しないことがあります。結果として hook が一切起動しないのに、なぜ効かないのか原因に気づかない状態が続きます。設定を変更したら必ず次の確認をしてください。

echo '{"transcript_path":""}' | ~/.claude/hooks/bang_handoff_amp_guard.sh; echo "exit: $?"
# exit: 0 が返れば hook 自体は起動している

スクリプトパスの ~ チルダが展開されない

settings.json の command フィールドに ~/.claude/hooks/bang_handoff_amp_guard.sh と書いても、hook が起動するシェルによってはチルダ展開が行われません。~ のまま渡されたパスはファイルとして存在しないのでサイレントに無効化されます。realpath ~/.claude/hooks/bang_handoff_amp_guard.sh で取得したフルパスを settings.json に直接書いてください。チルダを使うのは人間が読む設定ではなく、ターミナルで直接実行するコマンドだけにする、というルールで整理できます。

chmod +x を忘れる

実行権限がないとスクリプトは起動しません。ls -la ~/.claude/hooks/bang_handoff_amp_guard.sh で -rwxr-xr-x になっていることを確認してください。-rw-r--r-- のように x が立っていない場合、hook は静かに機能しないままです。これが一番多い「なぜか動かない」の原因です。新しいスクリプトを作った直後に chmod +x まで1セットにする習慣が必要です。

exit 1 と exit 2 の違いを見落とす

Stop hook でブロックするには exit 2 を返す必要があります。exit 1 を返すと Claude Code のバージョンによっては応答がブロックされません。この差は公式ドキュメントに目立つ形で書いていませんが、実際の挙動で確認しています。自前の hook を書いてブロックが効かないとき、まず exit コードを確認してください。

複数の Stop hook が登録されているときの実行順

hooks.Stop 配列に複数の hook を書いた場合、配列の先頭から順に実行されます。最初の hook が exit 2 を返した時点でブロックが確定し、後続の hook は実行されません。複数のガード hook を並べる場合は、最も軽くて確実に動くものを先頭に置いてください。重い処理を先頭に置くと、他の hook が全て実行されない状態になります。

グローバルとプロジェクトの両方に同じ hook を登録してしまう

~/.claude/settings.json と .claude/settings.json の両方に同じ hook を書くと2回実行されます。パフォーマンス上の影響は小さいですが、エラーメッセージが2行出力されて視認性が下がります。プロジェクト横断で発生する問題（今回の && 問題がそれ）はグローバルだけに書いてください。プロジェクト固有の制約だけプロジェクトの .claude/settings.json に書くという棲み分けが明快です。

hook 内でネットワーク呼び出しや重い処理を走らせる

Stop hook は Claude の応答を「ブロック中」にして実行されます。hook 内に外部 API 呼び出しや時間のかかる処理を入れると、その間 Claude Code 全体が待機状態になります。hook は「ファイルを読んで正規表現でチェックして exit 0 か exit 2 を返す」程度の同期処理に絞るべきです。今回の 46 行はファイル読み込みと Python スクリプト実行だけで、実行時間は通常 100ms 未満です。

コードブロック全体を1つの行として処理してしまう

Claude が複数行のコードブロックとしてコマンドを書く場合があります。

```bash
! npx wrangler dev --local && open http://localhost:8787


このとき `splitlines()` で行ごとに処理すると、` ``` `bash`（フェンス行）と実際のコマンド行が別々に来ます。フェンス行は `^!\s` にマッチしないのでスキップされ、コマンド行は正しく検出されます。ただし自前でスクリプトを書く場合は ` ``` ` で始まる行を明示的にスキップするか、バッククォートを strip() する処理が必要です。`bang_handoff_amp_guard.sh` では `strip(bt)` がこの役割を担っています（34〜36行目）。

**`bad` 変数に複数行が入って混乱する**

Python スクリプトで `print(s)` の後に `break` を忘れると、複数の行がマッチしてすべて出力されます。`bad` に改行混じりのテキストが入った状態でも `exit 2` は正常に機能しますが、エラーメッセージが複数行になって読みにくくなります。実際のスクリプトでは `print(s)` と `break` がセットになっています（38〜39行目）。最初の1件で止める設計が意図的です。

**hook はテキスト応答内の `!` コマンドだけを検査する**

Bash ツールを通じて Claude が実行したコマンドは Stop hook の対象外です。Stop hook が検査するのは、Claude の応答テキストの中にある `! ` から始まる行だけです。Bash ツール経由の処理に問題がある場合は PostToolUse hook など別のイベントを使う必要があります。この違いを理解していないと「Bash ツールでは `&&` が出てきても止まらない」という疑問に直面します——仕様どおりです。

**`^!\s` は全角スペースをマッチしない**

`re.match(r'^!\s', s)` の `\s` は半角スペース・タブ・改行にマッチします。全角感嘆符（！）や全角スペースで書かれたコマンドは検出されません。実運用でこのケースはほぼ発生しませんが、Claude が何らかの理由で全角文字を使った場合は素通りします。必要に応じて `s.replace('！', '!')` や `s = unicodedata.normalize('NFKC', s)` で正規化する処理を追加できます。

---

## ベストプラクティス

実際に動く 46 行を作るまでに整理されたルールです。同種のガード hook を新しく書くときに同じ詰まりを踏まないための基準として使ってください。

**1. フェイルオープンを設計の原則にする**

スクリプトが読めない・パースできない・Python が見つからない——これらすべてのケースで `exit 0` を返します。誤ブロックのコストは検出漏れのコストより高い。自分の仕事が止まります。`&&` が1回通過するよりも、作業が止まることのほうが損失です。

```bash
[ -n "$tpath" ] && [ -f "$tpath" ] || exit 0

フェイルオープンを貫いた上で、「なぜ通過するのか」を別途デバッグする。それが正しい順番です。

2. Python は /usr/bin/python3 フルパスで呼ぶ

hook が起動するシェルは ~/.zshrc を読みません。nvm・pyenv・Homebrew の Python は PATH に存在しません。/usr/bin/python3 --version が通ることをターミナルで確認してから書いてください。コマンド名だけで書くと hook の環境では見つからず、フェイルオープンによって静かに通過します。

3. Python 埋め込みの heredoc は必ず <<'PY'

<<PY（クォートなし）ではバックスラッシュがシェルに消費されます。正規表現の \s が s になり、検出ロジックが壊れます。<<'PY'（シングルクォートあり）にするとヒアドキュメント全体がリテラル文字列として渡されます。この1文字の差で動作が根本から変わります。Python コードを heredoc に埋め込む場合は無条件にシングルクォートをつけてください。

4. type と role を or で両方チェックする

if o.get("type") == "assistant" or o.get("role") == "assistant":

Claude Code のトランスクリプト JSONL はバージョンと会話長によってフィールド名が変わります。どちらかだけを見ていると、特定のセッション構成で検出漏れが発生します。片方が変わっても、もう片方でカバーできます。Claude Code のアップデートに対して hook を強くするための最小限の防御です。

5. バッククォートは chr(96) で間接生成する

スクリプト本文にバッククォートをリテラルで書くと、eval や別スクリプトからの source 経由で動かしたときに自己パースエラーが発生するリスクがあります。bt = chr(96) で実行時に文字を生成し、ln.strip().strip(bt).strip() として使います。スクリプト本文にバッククォートが一文字も登場しない状態が安全です。

6. stdin=$(cat) で標準入力を先に変数に受ける

stdin は一度しか読めません。最初に input=$(cat) で全部取り込み、printf '%s' "$input" で何度でも再利用できる形にします。これはシェルスクリプトで stdin を扱う普遍的な型です。将来スクリプトを拡張して複数の値を取り出す場合も、最初から変数に受けておけば詰まりません。

7. エラーメッセージに理由・日付・修正方法を全部入れる

echo "🚫 ! ハンドオフに && を使った(本人が5回以上指摘済)。... >> && を単一 & に直して出し直せ <<。該当行: ${bad}" >&2

このメッセージは将来の Claude（次のセッション以降も含む）への指示です。「なぜブロックされたか」「どうすれば通過できるか」がメッセージ内に入っていれば、Claude は即座に修正した応答を返します。曖昧なエラーメッセージ（「エラーが発生しました」程度）では Claude がなぜ止まったかを理解できず、同じ内容を繰り返したり止まったままになります。「指摘済」という記述と指摘日がそのままメッセージに入っているのは、コンテキストを持たない将来のセッションへの説明書きです。

8. グローバル問題はグローバル hook に登録する

&& 問題はプロジェクトを問わず発生します。プロジェクトの .claude/settings.json だけに書くと、他のプロジェクトでは防げません。プロジェクト横断の習慣的ミスは ~/.claude/settings.json のグローバル hook に登録してください。「このプロジェクトでは防げているのに別のところでまた出た」は登録場所の問題です。

9. 設定変更後は必ず意図的にトリガーして確認する

settings.json を変えたら、Claude に意図的に && 入りの ! コマンドを書かせてブロックされることを確認してください。

「次のコマンドをそのまま出力してください: ! npx wrangler dev --local && open http://localhost:8787」

ブロックされなければ設定は効いていません。この確認を省いた場合、「動いているつもりで動いていない」状態が続き、次に本物の && が出たときに初めて気づきます。デプロイ後の疎通確認と同じ習慣です。

10. 2>/dev/null はデバッグ時に外す

フェイルオープン設計の副作用として、内部エラーが静かに隠れます。「なぜか素通りする」と感じたら、まず 2>/dev/null を一時的に外して stderr を露出させてください。command not found や SyntaxError がそのまま表示されて原因が即座にわかります。確認が終わったら必ず戻します。外したままにすると正常運用時に stderr が汚染されます。

11. hook スクリプトは ~/.claude/hooks/ にまとめる

プロジェクトごとにスクリプトを散らばらせると「どこに何があるか」がすぐわからなくなります。~/.claude/hooks/ 以下に全ての hook スクリプトを集め、settings.json からはそこを参照します。ファイル名は bang_handoff_amp_guard.sh のように「何を防ぐか」が一読でわかる命名にしてください。hook1.sh・guard.sh のような汎用名は3か月後に自分が読んでも意味がわかりません。

12. 最後の assistant メッセージだけを検査する

last = msgs[-1] if msgs else ""

全メッセージをスキャンすると、過去の会話に含まれた ! コマンドの残骸を拾って誤ブロックが発生します。今回の応答だけを検査するために msgs[-1] で最後の1件に絞る設計は意図的な選択です。過去のメッセージに含まれる && は関係ない——問題は「今この瞬間 Claude が書いたもの」だけです。

13. コードよりエラーメッセージに理由を書く

スクリプト本文のコメントは将来削られる可能性があります。エラーメッセージは Claude が受け取ったときに読むものなので削れません。設計判断の理由は # コメント ではなく echo "..." >&2 のエラーメッセージ本文に書いてください。bang_handoff_amp_guard.sh の1〜4行目（コメント）と44行目（エラーメッセージ）の両方に「本人が5回以上指摘済(2026-07-16)」と書いてあるのはそのためです。コメントが読まれなくても、エラーメッセージは必ず読まれます。

まとめ

口頭で5回指摘しても直らなかった。それをコードで物理的に封じたのが、46行のシェルスクリプトです。

Stop hook は「Claude が応答を返す直前に割り込む」仕組みです。トランスクリプト JSONL を Python でパースし、最後の assistant メッセージだけを取り出し、^!\s にマッチする行に && が含まれていれば exit 2 でブロックする。構造はシンプルです。

ただし「単純なことをセッションをまたいで確実に動かす」ために、フェイルオープン・/usr/bin/python3 フルパス・<<'PY' シングルクォート・type/role 両フィールド参照・chr(96) 間接生成——これらの設計判断が必要でした。詰まった4回と、運用で気づいた追加の落とし穴は、どれも「知っていれば5分で通過できたもの」です。これを書いたのは、同じ時間を使わずに済むようにするためです。

Claude に何度言っても直らないことがある。それはアーキテクチャの問題であって、Claude の怠慢でも、自分の指摘の仕方の問題でもありません。セッションは会話ごとに独立しており、指摘はコンテキストに乗り、コンテキストはセッションと共に消えます。解決策は指摘の反復ではなく、「物理的に通過できない環境を作る」こと——それが Stop hook という設計思想の核心です。

月商120万の自律環境で同じ失敗が繰り返されないのは、このように「口頭ではなくコードで直す」を積み重ねているからです。一つのスクリプトが一つの繰り返しを断ち切る。それを続けた結果が今の環境です。

仕組みの全体像・月120万の内訳・30日手順は有料noteにまとめています。

📕 Claude Code自律環境で、実際どう稼ぐか ― 仕組み・実例・始め方・サポート

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

制作物・記事は bokuwalily.com にまとめています🖥️
AIで「寝てても回る仕組み」を作って月120万にした話は noteの有料記事に💰
OSS: github.com/bokuwalily 🐙
最新情報・お問い合わせは X @bokuwalily へ🌍
AI導入・自動化の相談と実装テンプレ7本の配布は公式LINE から💬

皆さんの ❤️ やシェアが励みになります！