Claude Code
ターミナルで動く AI コーディング支援ツール Claude Code の実践記事です。導入手順、CLAUDE.md の設計、サブエージェント、フック、CI 連携、詰まりやすいエラーの解決まで扱います。自動化やヘッドレス運用の記事も揃えています。
調べ物タスクの WebFetch キャッシュ TTL を、自分の使い方に合わせて選ぶ
Claude Code の WebFetch には URL キャッシュの TTL 設定があります。同じページを何度も取りに行く調べ物タスクで、取得回数と情報の鮮度がどう入れ替わるのかを、観測用の小さなサーバと計算スクリプトで確かめながら決めていきます。
フォーク既定のサブエージェントで、レビュー役だけは名前で呼ぶという線引き
サブエージェントのフォークが既定になり、親の会話をそのまま引き継ぐようになりました。作業は継承させ、判定は継承させない。その境界をリポジトリに宣言し、ずれを機械的に見つけるまでの設計です。
ビルドがメモリを食い尽くしたときの止まり方は、cgroup と ulimit で別物でした
Claude Code v2.1.233 で Bash ツールに memory cgroup 対応が入りました。上限を仮想アドレス空間に置く ulimit -v と、実メモリに置く cgroup では、止まり方も、そもそも止められるかどうかも変わります。Linux 上で実際に確かめた記録です。
Todo ツールが既定オフになった Claude Code で、多段作業の進捗をどう追うか
Claude Code v2.1.233 以降、新しいモデルでは TodoWrite と Task 系ツールが既定で読み込まれません。環境変数で戻す前に確かめるべき3つの分岐と、チェックリストの代わりに置いた作業台帳の実装、並列実行で台帳が壊れた境界の実測結果をまとめます。
Claude Code を動かしたまま席を離れるなら、Remote Control を先に入れておく
長い作業を任せて席を離れると、最初の確認プロンプトで止まったまま時間だけが過ぎます。手元のマシンで動いている Claude Code をスマホやブラウザから触れるようにする Remote Control の始め方と、使う前に知っておきたい制約をまとめました。
生成物1ファイルが手書きコード70本より重いので、Claude Code に読ませる範囲を決め直しました
運用中のリポジトリを対象に、どの領域が文脈をどれだけ食うかを数え直しました。生成物の除外・探索パターンの選び方・settings.json での固定まで、実際に決めた運用ルールとその根拠をまとめます。
課金ユーザーに広告が出る不具合を、判定の一元化で止めるまで
広告除去を購入した方に広告が出てしまう不具合の原因は、フラグの不足ではなく判定の分散でした。Claude Codeで広告SDKの呼び出し口を棚卸しし、単一の純粋な判定関数へ畳み込むまでの実装記録です。期限判定を端末時計に預けない工夫や、消し忘れを構造で防ぐ設計も紹介します。
同じ rm -rf が、10箇所では戻せて5箇所では戻せませんでした — auto モード既定化の前に可逆性を測る
8月14日に auto モードが Pro / Max / Team の既定になりました。止まる境界は「取り消せない・破壊的・環境の外」ですが、可逆性は操作の名前ではなく実行時点の状態で決まりました。復旧不能バイトを数えるプローブと、15対象の実測をまとめます。
一時的な401が長期トークンを置き換える — ヘッドレス実行の資格情報に「出所」を持たせる
共有した資格情報ファイルは、たった一度の一時的な401で長期トークンを失うことがあります。24並列の実行に401を1回だけ注入して被害範囲を実測し、資格情報に出所フィールドを持たせるガードと隔離のコストを比較、24マイクロ秒で現在地を確定する起動時カナリアまで検証しました。
同じコミットから作った zip なのに SHA-256 が変わる — プラグイン配布のピン留めを壊さない正規化
HTTPS 経由の zip からプラグインを導入できるようになり、SHA-256 のピン留めも選べるようになりました。同一内容の zip を2回作って測ったところ、22,669 バイト中 50 バイトだけが異なりハッシュが毎回変わりました。原因の測定と、20回連続で同一ハッシュになる正規化手順をまとめます。
権限モードを変えても止まらない書き込み — サブエージェント用 PreToolUse ゲートを150通りで測る
ワークフローのサブエージェントによるファイル編集は、セッションの権限モードに関わらず自動承認されます。残る境界である agent_id / agent_type ベースの PreToolUse フックを150通りのペイロードで測り、素通りしていた54件の内訳と、フェイルクローズへ寄せた実装を共有します。
呼んだはずのスキルが何も返さない — 起動前に名前の解決順序を確定させる
端末の組み込みコマンドと同名のスキルは、非対話セッションで呼び出しが解決されないことがあります。実効名の表を起動前に作る preflight を書いて走らせ、検査器自身が取りこぼしていた2件までを実測で洗い出した記録です。
秘密を渡さず、リクエストだけ通す — サンドボックス資格情報マスキングの差し替えが効く境界
Claude Code のサンドボックス資格情報マスキングは、センチネル値を読ませて送信時に実値へ差し替える設計です。差し替えが効く認証方式と効かない方式、ボディに載せたときの長さのずれ、そしてチャンク分割転送で置換そのものが空振りする境界を、最小プロキシを自作して実測しました。
ファイルシステムの分離をネットワークと別に締める — 触ったパスを採り、書き込み面から絞る
Claude Code v2.1.216 でファイルシステムの分離をネットワークと切り離して指定できるようになりました。締める前にジョブが触ったパスを strace で採取し、読み取り面と書き込み面を分けて測った実務メモ。同じジョブを3回走らせたときのパス集合の安定率と、接頭辞に畳んだときの安定率の差まで実測しています。
存在チェックが通っても書けない — 無人実行の前提を能力プローブで測る
ディレクトリが存在することと、そこへ書けることは別の問題です。無人で走るClaude Codeのセッションが静かに止まる原因を実測し、存在チェックの代わりに実際の読み書きを試す能力プローブ方式のプリフライトを設計しました。書けるのに消せない場所、静的な手掛かりが健全と答える落とし穴、シェル側の穴まで扱います。
予算上限で止まった実行の再開設計 — 停止点36通りを総当たりして分かったこと
ヘッドレス実行が予算上限で止まると、成功でも失敗でもない第三の終了が生まれます。停止点36通りを総当たりして再開の健全性と総支出を測った実験から、原子的な書き込みとインデックス優先の再開、上限をバッチ全体でなく最小の再開単位に掛ける設計へ至った記録です。
作業ルートを途中で足したとき、無視規則と deny はどこまで届くのか — DirectoryAdded で境界を測り直す
セッション途中で作業ルートを追加すると、無視規則も deny パターンもそのままでは新しいルートに届きません。git check-ignore と照合器の比較で境界を実測し、DirectoryAdded から呼ぶ差分監査スクリプトの実行結果まで記録しました。
MCPサーバーは繋がっているのに、ツールが0件で返る — 無人実行の権限劣化をツール表の差分で止める
資格情報が抜けてもMCPのハンドシェイクは成功し、tools/list は空配列を返します。例外が飛ばないまま実行が完走する構造と、期待ツール表との差分で無人実行を止めるpreflightの実装を、実測値つきで記録しました。
許可リストに書いた環境変数は誰の環境で展開されるのか — Managed MCP の実効ポリシーを指紋で確かめる
Managed MCP の allowlist・denylist に書いた環境変数参照の解決元が、起動時環境と managed-settings の env に変わりました。同じ設定ファイルが環境ごとに別のポリシーになる仕組みを手元で再現し、実効ポリシーを指紋で突き合わせる起動前チェックを組みました。
strictAllowlist で Claude Code サンドボックスの外向き通信を締める
Claude Code v2.1.219 の sandbox.network.strictAllowlist で自動化の外向き通信を締めた実践メモ。接続先を洗い出すスクリプト、失敗までの時間で拒否とDNSと回線を切り分ける実測、そして観測スクリプト自身が壊れていた三つの欠陥と修正版まで。
コミット済みのシンボリックリンクが worktree の外を指す — AI に並列作業を預ける前のリポジトリ点検
Claude Code 2.1.212 で、コミット済みのシンボリックリンクを worktree 作成時に辿ってリポジトリ外へ書きうる不具合が修正されました。パッチが塞いだのは辿りの側です。危険なリンクがコミットされている側を点検する監査スクリプトと、隔離の手順をまとめました。
auto モードの設定が、いつの間にか自分でも思い出せなくなっていた — 既定へ戻す claude auto-mode reset の使いどころ
夜間の自動運用を続けるうちに、auto モードの設定を少しずつ触り足していました。ある朝の違和感で、自分が何を変えたのか思い出せないことに気づきます。既定へ戻す claude auto-mode reset を基点にして設定を組み直した、個人開発の片付けの記録です。
headless の Claude Code を止めたのに、ビルドだけが生き残っていた — exit 143 を前提に停止処理を設計する
headless モードの Claude Code が Bash 実行中に SIGTERM を受けると、コマンドのプロセスツリーが孤児化していました。2.1.212 の修正で挙動は exit 143 に変わります。この契約を前提に、監督スクリプトと後片づけを設計し直す手順をまとめます。
プランモードを「読むだけ」と信じていた — 前提を機構で確かめ直す
Claude Code 2.1.212 で、プランモードがファイルを変更する Bash を許可プロンプトも canUseTool も通さず実行していた不具合が修正されました。前提が崩れていた期間に何が起きうるのか、手元で確かめる方法と、モード名に安全性を預けない設計をまとめます。
/fork と /subtask の使い分け — 分岐は手元から切り離し、委譲はセッションに残す
Claude Code 2.1.212 で /fork は会話をバックグラウンドセッションへ複製する挙動に変わり、従来のセッション内サブエージェントは /subtask へ移りました。2つの使い分けと、分岐を増やす前に決めておきたい上限の話です。
宣言したMCPサーバーが一覧から消えていた — 名前空間をベンダーと共有する前提で設定を組み直す
MCPサーバー名がベンダーに予約され、自分の .mcp.json の宣言が黙って無効になる。無人実行で気づけないこの欠落を、宣言と実体を突き合わせる preflight と接頭辞規約で落とす設計をまとめました。
承認したのは、私が読んだ文字列ではなかった — 確認プロンプトの中継を細工文字で検証する
チャットへ中継した確認プロンプトに双方向上書き文字やゼロ幅文字を混ぜて通す実験をしました。NFKC正規化では検知率が0%だった理由、日本語コミットメッセージを止めてしまった素朴な規則の失敗、見せる文字列と照合する文字列を分けて細工を全件止める実装までを記録します。
夜間に回した並列サブエージェントの記録が、追えなくなった — --forward-subagent-text で増えたログを絞り直す
サブエージェントのテキストと思考を stream-json へ流せるようになった一方で、無人実行のログ量は跳ね上がります。実測値をもとに、事後解析に効く記録だけを残す3層の保存方針と相関IDの設計をまとめました。
テーブルが「… 2,847 more rows」で切れていた朝 — 描画上限とトークン計上を切り離して、ツール出力を設計し直す
Claude Code 2.1.209 で 200 行超の markdown テーブルは先頭 200 行＋残り件数の表示になりました。省略されるのは描画だけで、モデルは全行を受け取ります。この差を測り、ツール出力を集約型へ組み替える設計をまとめます。
許可ルールを積み上げたセッションが毎ターン重くなる — ルールセットの棚卸しと、安全性を保ったまま数を減らす設計
deny/ask ルールを増やすほど毎ターン遅くなる問題が 2.1.209 で修正されました。ただしルール設計そのものの負債は残ります。棚卸しスクリプト・被覆検出・ターン時間の実測手順と、列挙型から接頭辞型へ移す設計をまとめます。
夜間セッションの常駐メモリが朝には数GB — 蓄積の四つの出どころと、RSS を刻んで切り分ける
夜間に回した Claude Code のプロセスを朝に見ると、常駐メモリが数GBまで膨らんでいました。2.1.209 で塞がれた四つの蓄積源と、自分の構成に残る分を RSS の傾きで切り分ける方法、しきい値で畳む運用までを個人開発の目線で整理します。
Claude Code の描画をプレーンテキストに切り替える — screen reader mode の三経路と、ログとして残すときの実寸
夜間に回した Claude Code のログを翌朝開いたら、同じ行が何十回も積み重なっていました。screen reader mode の三つの有効化経路と、ANSI 制御シーケンスを含んだログの実寸を測るスクリプト、描画を素にすると何が失われるかまでを、個人開発の運用目線で整理します。
無人実行のログを読める形に保つ — axScreenReader のプレーンテキスト描画を計測して常用に切り替える
Claude Code の出力をログへ落とすと、制御列と再描画で膨らみ後から追えなくなります。axScreenReader のプレーンテキスト描画を3経路で有効化し、同一タスクを計測して常用へ切り替えるまでの実装と判断を記録します。
Dynamic Workflows の規模と effort を、勘ではなく手元の台帳で決める
Dynamic Workflows の一般提供で /config の workflow size と effort が自分の手に渡りました。large を選び続けて費用だけが伸びた1週間の記録から、OpenTelemetry のコンソール出力を台帳化し、タスク型ごとに size と effort を割り当てるまでを実装込みで整理します。
無人実行で auto モードの確認要求を止めずに捌く — permission-prompt-tool で deny-by-default に応える
auto モードの事前確認は、手元で作業しているときは頼もしい味方ですが、深夜の無人実行では「確認待ち」で朝まで止まる原因になります。permission-prompt-tool で確認要求を受け止め、deny-by-default で自動判定して台帳に残す構成を、動くコードつきでまとめました。
型は付いたのに、安全にはならなかった — JS→TS 移行で Claude Code に任せた範囲と任せなかった範囲
tsc が緑でも any は静かに漏れます。型カバレッジで移行の実態を測り、Claude Code に任せて速い作業と人が決めるべき判断を線引きし、悪化を止める CI ゲートまでを実装付きで整理した運用メモです。
push先がいつの間にか一つ増えていた — /commit-push-pr が origin 以外のリモートへも押し始めた変更に、許可リストで蓋をする
7月14日の更新で /commit-push-pr が origin に加えて設定済みの push リモートへも自動で押すようになりました。便利な一方、ミラーやバックアップ用の第二リモートを持つ環境では、意図しない push が静かに増えます。どのリモートへ押し得るかを棚卸しし、許可リスト外の push を pre-push フックで止め、無人実行でも安全に回す設計を実装込みで整理しました。
空の変数と rm -rf の夜 — Claude Code auto モードの事前確認に助けられた片付けの記録
空になった変数のせいで rm -rf が広範囲に化けかけた夜の記録です。set -u が空文字を素通りさせる理由を手元のシェルで検証し、ドライランを既定にした掃除スクリプトの実行結果まで残しました。
設定したはずのMCPタイムアウトが効かず、毎回きっかり60秒で切れていた — request_timeout_ms をサーバー単位で取り戻す
長めのMCPツール呼び出しが、設定した待ち時間を無視してきっかり60秒で切れていました。原因は .mcp.json のサーバー単位 request_timeout_ms が読まれず既定へ落ちていたこと。修正後の正しい置き方と、値をツールの性質から逆算する設計、切れ際を自分で確かめる手順を実装込みで整理しました。
PreCompact と SessionEnd で長時間セッションの決定事項を引き継ぐ
自動コンパクションで消えるのは会話ではなく「なぜそう決めたか」です。PreCompact / SessionEnd / SessionStart の3フックで決定ログを外部ファイルへ退避し、次のセッションへ確実に手渡す実装を、動くコードと実測値つきで解説します。