Claude Code
ターミナルで動く AI コーディング支援ツール Claude Code の実践記事です。導入手順、CLAUDE.md の設計、サブエージェント、フック、CI 連携、詰まりやすいエラーの解決まで扱います。自動化やヘッドレス運用の記事も揃えています。
日本語フォルダ名を守るはずのフックが、一度も止めてくれませんでした — Python の stdin が cp932 で読んでいた話
「経理」「議事録」などの日本語フォルダを守る PreToolUse フックが、Python の stdin 既定が cp932 の環境では素通りします。再現の手順と 3 行の直し方、確認用の 1 コマンドを書き残します。
onFailure を block にしても、jq が無い環境では公式例の rm -rf ブロックは素通りしました
PreToolUse の門番フックは、落ちたときに通すのか止めるのか。公式例を jq の無い環境で走らせると exit 0 で素通りしました。終了コード10通りの実測、直し方、settings.json を走査して素通りを洗い出すスクリプトをまとめます。
Grep の先頭250行は、一致した183ファイルのうち42ファイルしか見ていませんでした
記事リポジトリで「hook」を探したところ、一致は1,312行・183ファイル。ripgrep・git grep・grep の速さは11〜35 msで差がなく、効いたのは出力の量と順番でした。先頭250行の取りこぼしを事前に見積もるスクリプトと、探索の順番を実測値つきでまとめます。
「cd して git add して commit」の承認が毎回出る — 設定の抜けではなく、仕様だと分かるまでにたどった道
cd /path && git add && git commit のような複合コマンドで、許可ルールを入れても承認が繰り返し出る。公式の権限ドキュメントと GitHub の報告を突き合わせると、cd と git の組み合わせは設計上プロンプトが出ると分かりました。原因の切り分け順と、手数を減らす4つの直し方を並べます。
SPM に移したら、起動した瞬間にアプリが落ちるようになりました — dyld の一行を Claude Code と読み解いた記録
CocoaPods から Swift Package Manager へ移した直後、ビルドは通るのに起動した瞬間に落ちました。dyld の一行から原因を切り分け、直し方と確認コマンドまでをまとめます。
「コミットは私がします」と書いたのに git log に一行増えていた朝、指示を強めるのをやめました
Claude Code に「コミットしないで」と頼んだのにコミットされたとき、まず git reset --soft で戻し、permissions.deny と PreToolUse hook の二層で物理的に止める手順です。deny ルールが素通しする git -c の形と、hook の試し方を書き残します。
安定版の Claude Code には、二度の既定モデル交代がまだ届いていません
安定版を追う Claude Code は、今朝の時点で最新版から 6 リリース・10 日ぶん後ろにいました。版番号の引き算に頼らず、実在するリリースだけを数えて「届いていない変更」を見出し付きで一覧にする小さなスクリプトを、標準ライブラリだけで組みます。
既定の Opus が 5.5 に変わった週、別名のまま残していた3箇所を数えました
Claude Code 2.1.280 で Opus 5.5 が既定になり、Pro の既定モデルも Sonnet から Opus へ変わりました。設定を触る前に確かめた3点（別名の解決先・/effort の引き継ぎ・キャッシュ読み $0.20 の見込み）を、手元で使った確認スクリプトと一緒に書き残します。
消えたことになっている作業ツリーの棚卸しと、隔離の任せどころ
サブエージェントに任せた隔離作業ツリーが畳まれずに残っていました。git 2.34.1 で実測した remove の可否、消しても残るブランチ、1 ツリーあたり 12 MB の差から、棚卸しの手順と隔離の任せどころをお伝えします。
Pro を払っているのに Console に請求が立っていたとき、私が最初に見た一行
サブスクリプションと API の従量は別会計で、Claude Code はそのどちらでも動きます。どちらが選ばれているかを決めるのは優先順位で、ログインはその最下段です。status の読み方と、無人実行だけが別の答えを返す理由を書き残します。
巡回タスクが朝まで返らなかった原因は、WebFetch の待ち時間に上限がなかったことでした
Claude Code v2.1.268 で WebFetch に 300 秒の期限が付きました。応答を閉じないサーバーに当たると無人実行がどこで止まるのか、CLAUDE_CODE_WEBFETCH_DEADLINE_MS の 0 がなぜ「待たない」ではないのかを、手元で再現できる形で整理します。
inferenceGatewayHeaders はいまも動きます。10月7日の正午に、既定値へ落ちます
9月10日から出始めた管理設定の非推奨警告を、私は表記ゆれの整理だと受け取っていました。期限を過ぎた旧名は無視されるのではなく、fail-closed な値か既定値に落ちます。旧新の対応と、設定を1本のスクリプトで棚卸しする手順を書き残します。
「Not signed in to the Cloud gateway」で全リクエストが止まる朝に、設定より先に版を見ます
Claude Code 2.1.265 でゲートウェイ・プロキシ構成が全リクエスト失敗した回帰を入口に、認証の入力面を一枚に並べて「設定と版のどちらが変わったか」を数秒で切り分ける小さな手順をまとめます。
plugin.json を1枚置くと、スキルの棚がまとめて外せる単位になります
スキルを用途ごとに色分けしたら、毎日使う一群は全体の5パーセントしかありませんでした。.claude-plugin/plugin.json を1枚置いてフォルダをプラグインに変え、その日に使わない棚をグループごと外せるようにするまでの手順と、途中で二度つまずいた読み込みの規則を書き残します。
スキルを数えたら42本ありました。うち4本は中身が『移動しました』だけでした
Claude Code v2.1.261 で入った /skill-doctor を入り口に、自分のスキル棚を実際に数えてみました。毎ターン乗るのは説明の1行だけという構造と、名前の重複を素朴な awk で探すと別のスキルまで拾ってしまう落とし穴を、手元で動かした小さなスクリプトとともに書き残します。
拒否ルールが見ていたのはファイル名で、そこへ届く経路ではありませんでした
deny に書いた 1 行が、同じファイルへ届く別の書き方を素通りさせていました。経路を機械的に並べて、版を上げた日に効きを確かめる小さな検査表の作り方をお伝えします。
~/.claude.json の巻き戻しは v2.1.259 で直りました。消えた設定は自分で戻します
同時に走らせたセッションが ~/.claude.json を互いに巻き戻す不具合が v2.1.259 で修正されました。消えた信頼設定と MCP を洗い出して戻すまでを、キー集合の差分を取る小さなスクリプトとあわせて書き残します。
Claude Code に project.pbxproj だけは直接触らせていません
Xcode のプロジェクトファイルは、開けなくなる壊れ方より開けてしまう壊れ方のほうが高くつきました。直接編集をやめてスクリプト経由に寄せるまでに測ったことと、いま引いている線を書き残します。
ログのタイムゾーンを表示で寄せるか、記録で固定するか
AdMob とストアのレポートと手元のログで一日の切れ目がずれていました。表示側に寄せる方法と記録側を固定する方法を、実際に往復して選び直した判断の記録です。
モデル切り替えの記録と歯止めを、フック2本で作る
PreModelSwitch と PostModelSwitch を使い、無人実行中のモデル切り替えを記録するフックと、約束していない切り替えだけを止めるフックをゼロから作ります。実測値つきの手順です。
heredoc のクォートを1つ落とすと、ログに書いた金額や日付が別物になります
未クォートの heredoc は本文の変数とバックティックを実行します。実測した4通りの書き換わり方、3種類のクォート記法の比較、プレースホルダと sed で値を安全に埋める手順、既存スクリプトを棚卸しする検出コードまでをまとめました。
MCPサーバが十数個を超えてから、起動直後の一覧を信用しなくなりました
起動直後に「接続できません」と並ぶサーバのうち、こちらから手を打てるものは一部だけです。応答なし・起動失敗・プロトコル拒否を分けて返すプローブを実装し、14台構成で逐次22.03秒が並列5.09秒まで縮むところ、待ち時間を詰めると健全なサーバが失敗に化けるところを実測で残しました。
同じ告知が『+25%』とも『17%減』とも読める — 9月14日に変わる Claude Code の週次上限を検算する
8月29日の告知で Claude Code の週次上限は9月14日から恒久的に+25%へ変わります。『+25%』と『17%減』が同時に成り立つ理由を指数化で検算し、/usage とステータスラインで自分への影響を確かめる手順をまとめました。
無音で半分になっていた定期実行と、欠落を捕まえる突き合わせ
1日2回動いているはずのバッチが、実際には1回しか起動していませんでした。エラーは1件も出ていません。期待起動回数と実行記録を突き合わせて、無音の欠落を検出する仕組みを作ります。
thinking を切ったまま effort xhigh を指定した設定が、いま黙って high で走っています
thinking を無効にしたまま effort を xhigh や max にすると 400 が返ります。この失敗が黙って high に落ちる挙動へ変わったため、送信前に組み合わせを判定する小さなプリフライトを用意しました。
名前に混ざった見えない文字を、プラグインを入れる前に洗い出す小さなスクリプト
プラグインやスキルの名前に不可視文字や制御文字が混ざっていても、ターミナルの一覧では見分けがつきません。実際に6つの紛らわしい名前を並べて ls の出力を比べ、導入前に走らせる点検スクリプトと、その点検が拾えない範囲までを整理しました。
検証スクリプトの出力を、そのまま hook から返してはいけません
hook に足した検査は正しく動いていたのに、会話のほうが先に容量を使い果たしていました。833ファイルで58バイトの検査と42KBの検査を実測で並べ、出力が会話に届く経路と、予算を機械的に守らせるラッパーの書き方をまとめます。
使うモデルだけを /model に並べる modelPicker の設定と、置き換えで消える行
Claude Code v2.1.242 で入った modelPicker で、/model のピッカーに自分の行を並べる方法をまとめました。追加と置き換えの違い、プロジェクト設定では読まれない理由、availableModels と重ねたときに選択肢が狭まる境目までを扱います。
リポジトリに置いた allow を信じるか、環境側の信頼登録に寄せるか
使い捨ての実行環境で Claude Code を非対話で走らせると、リポジトリ内の permissions.allow が信頼待ちのまま落ちます。何が落ちて何が残るのかを 2.1.246 で確かめ、許可設定の置き場所を決め、起動前に検出するプリフライトを用意します。
キャッシュのTTLを1時間に延ばすかは、離席の長さではなく戻る場所で決めています
Claude Code v2.1.242 で promptCacheTtl と subagentPromptCacheTtl が追加されました。1時間キャッシュが効く条件は離席時間ではなく、同じ作業ディレクトリと同じ git 状態へ戻るかどうかです。判断の順番と、効いているかを確かめる手順を書き残します。
settings.json のキー名を1文字間違えても、Claude Code は何も言わずに無視します
キー名を書き間違えた settings.json と正しい settings.json で claude doctor の出力を比べたところ、差分はゼロでした。何が検証され何が素通りするかを5通りで測り、書き間違いを自分で落とす検査を用意します。
空白ひとつで、80件の検査が0件になる — 一括処理を任せる前に置くガード
空白を含むフォルダ名の下で走らせた検査ループが、80件のうち1件も開いていませんでした。断片が実在パスに化ける仕組みを実測で切り分け、削除を伴うバッチに置く件数アサーションまで書き残します。
同じスキルを二か所に置いていたら、片方だけ中身が痩せていました
同名のスキルが二つのスコープに存在していました。SKILL.md は sha256 まで一致しているのに、片方には本文が名指ししているファイルが入っていません。66本を走査して欠落2件に絞るまでに検出器を三度書き直した記録です。
長い処理を別セッションに任せて待つ — 通知が届かなかったときのための完了マーカー
Claude Code の notify_when_idle で別セッションの完了通知を受け取る手順と、通知が落ちても待ち続けないための完了マーカーの最小実装。3つの状態切り分けを実行結果つきで解説します。
Claude Code の headersHelper に移したら、プロジェクト配下のカタログだけ認証が通らなくなりました
自前のプラグインカタログを headersHelper へ移す途中で、ユーザースコープでは動くヘルパーがプロジェクト配下だけ落ちました。原因は認証情報の非継承です。動くヘルパー2種と実測した実行コスト、無人実行での注意点をまとめました。
ANTHROPIC_MODEL を消さないまま ANTHROPIC_DEFAULT_MODEL を足しても、始まるモデルは変わりません
v2.1.236 で追加された ANTHROPIC_DEFAULT_MODEL は ANTHROPIC_MODEL の後継ではありません。二つの効き方の違いと、モデル指定の散らばりを一覧する Python スクリプトをまとめました。
Claude Code の read deny が許可フォルダの内側まで届いていなかった話
秘密ファイルとソースが同じツリーに同居する個人開発環境で、permissions.deny の Read ルールが実際にどのファイルまで届いているかを数え直した記録です。棚卸し用のスクリプトつき。
Claude Code で「今後確認しない」を押した範囲を棚卸しする
確認ダイアログで「今後確認しない」を選んだあと、自分が何を許可したのかを説明できるでしょうか。手元の設定を数えるスクリプトと、最小から足していく権限の組み立て方をまとめました。
起動しただけで1万トークン消えるスキルを、大きさではなく到達率で切り分ける
自分用の運用スキルが、呼び出しただけで約1万トークンを消費していました。節ごとにトークンを測り、最大の節ほど切り出してはいけない理由と、到達率で分けたときの実測値を、監査スクリプトつきでまとめます。
一度キャッシュに載った500ページは、直しても消えません
修正をデプロイしたのに壊れたページが出続けたことがあります。原因はコードではなくエッジキャッシュでした。ステータスコードだけを見る保存判定が、200で返る壊れたHTMLを通していたのです。本文の完全性で保存可否を決めるガードの実装と、運用で調整した誤検知の線引きを、実際に踏んだ経緯とともに書きました。