once、async、asyncRewake など、フックの動きを変える隠し気味の設定があるこの記事は、Claude Code のソースコードを読んだら、公式ドキュメントに書かれていない設定がいろいろ見つかった、という内容です。
率直に言うと、こういう“中身を覗いた人だけが知っている小技集”は、かなりワクワクします。AIツールって、見た目はシンプルでも、裏側には結構な仕掛けが隠れているんですよね。
元記事の筆者 André Figueira は、Claude Code のソースコードから、hooks、Skills、agents に関する undocumented な挙動を掘り出しています。しかも「こう使うと面白いですよ」だけでなく、実際にコピペできる例まで示しているのが親切です。
ただし最初に大事な注意点があります。
これは @anthropic-ai/claude-code@2.1.87 時点の話 で、未文書化機能は今後のアップデートで変わるかもしれません。ここはかなり重要です。便利でも、永遠に安定しているとは限らない。こういう“内部仕様っぽいもの”は、便利さと脆さがセットだと思ったほうがいいです。
まず一番インパクトが大きいのが hooks です。
一般に hook というと、「何かの前後でちょっと処理を足すもの」くらいの理解で十分ですが、Claude Code の hooks はそれよりずっと強いです。
元記事によると、hooks は JSON を stdin で受け取るだけでなく、stdout に JSON を返して Claude Code の動作をリアルタイムで変えられる そうです。つまり、ただ監視するだけでなく、実行内容そのものに介入できます。
たとえば PreToolUse hook では、こんなことができます。
updatedInput で、実行直前のコマンドを書き換えるpermissionDecision で、許可・拒否を強制するpermissionDecisionReason で、その理由をUIに表示するadditionalContext で、会話コンテキストに情報を足すこれ、かなり強いです。
要するに、Claude Code の行動を外側からルールベースで制御できるわけです。AIに「勝手にやらないで」と言うだけではなく、実際にシステム側で安全策を実装できるのは大きいと思います。
記事では、git push を見つけたら自動で --dry-run を付ける hook の例が紹介されています。
Claude には本物の push をしているように見えて、実際にはテスト実行に差し替えられるわけです。
これ、地味ですがかなり実用的です。
「AIが勝手に危ない操作をしたら怖い」という不安に対して、かなり現実的なブレーキになります。
SessionStart hook では、次のようなことができます。
記事では、package.json や .env、tsconfig.json を監視しつつ、現在のブランチ名や未コミットの変更数を Claude に教える例が出ています。
これはかなり“気が利く”使い方です。人間でも、今どのブランチで何を触っているかを毎回説明するのは面倒ですからね。Claude に最初から状況を渡せるのは、地味だけど効きます。
ls、cat、pwd みたいな安全なコマンドを、毎回プロンプトなしで許可する例もあります。
これも便利ですが、同時に「許可判定を自前で持てる」という点が本質だと思います。
記事の言い方を借りると、自分で permission classifier を作っている ようなものです。
AIエージェントにとって許可判断はかなり大事なので、ここをシェルスクリプトで細かく制御できるのは、なかなか面白い設計です。
この記事の面白いところは、hooks のイベントだけでなく、フック設定に使える隠れフィールド まで拾っている点です。
元記事によると、ドキュメントにあるのは主に type、command、matcher、timeout、if、statusMessage ですが、実際にはさらに次のようなものがあるそうです。
once: trueasync: trueasyncRewake: trueonce: true一度だけ実行して、その後は自動で外れる設定です。
初回セットアップに向いています。たとえば .env.example から .env を作る処理を一度だけ走らせる、というのはかなり自然です。
async: trueバックグラウンドで実行して、Claude を待たせない設定です。
監査ログを取るだけ、集計するだけ、みたいな処理にはぴったりです。
個人的には、こういう“重くないけど常時やりたい処理”に使うのが一番気持ちいいと思います。
asyncRewake: trueこれが一番おもしろいです。
通常は非同期で走るけれど、終了コード 2 のときだけモデルを起こしてブロックする、という動きになります。
つまり、
という、かなり賢い設計です。
たとえばファイル保存後に secret をスキャンして、password や api_key のような文字列が見つかったら止める、という使い方ができます。
これ、実際に欲しい人は多そうです。
「毎回厳しく止めるとうるさい。でも危険なときは止めたい」。ソフトウェアの制御って、だいたいこの悩みとの戦いですからね。
次に Skills です。
ドキュメントでも基本的な項目は案内されていますが、ソースコードを見ると、もっと自由度があります。
元記事で挙がっている隠れフィールドはたとえばこんな感じです。
modelefforthooksagentdisable-model-invocationshellmodel で skill ごとに使うモデルを変えられるこれ、かなり実用的です。
軽い lint やチェックは haiku、重い設計レビューは opus、という使い分けができます。
「全部同じモデルでやる」よりも、タスクごとにコストと性能のバランスを変えるほうが自然です。
AI利用って、使い始めるとつい“全部強いモデルで”になりがちですが、現実には速度もコストも大事なので、この切り替えはありがたいと思います。
effort で思考の深さを調整するlow / medium / high / max のような値で、内部の reasoning depth に相当するものを調整できるとされています。
ざっくり言えば、どれくらい真剣に考えるかの強度 を変えられるイメージです。
これは面白い一方で、かなり内部実装寄りでもあります。
便利ではあるけれど、外から見て“本当に何が変わっているのか”は分かりにくい。なので、私はここは「効いたらラッキー」より「使い分けのノブが増えた」くらいに見たほうがよさそうだと思います。
ここも強いです。
たとえば TypeScript 専用の skill を作って、その skill が動いている間だけ typecheck や lint を有効にする、という設計ができます。
要するに、Skill 自体が“処理のまとまり”であり、さらにその中で独自ルールを持てる。
かなりモジュールっぽいです。AIエージェントというより、小さな自動化パッケージ に近い感覚ですね。
agent で別エージェントに委譲できるSkill から別の agent を呼べるのも面白いです。
たとえば security review を専門の agent に渡す、みたいな設計ができます。
これは“役割分担”がしやすくなるという意味で重要です。
AIに全部やらせると雑になりやすいですが、専門エージェントに分けると整理しやすい。
ソフトウェア設計の基本である「責務の分離」が、ここでもそのまま効いています。
元記事の後半では、.claude/agents/ に置く Custom agents の話も出てきます。
ここで驚きなのは、memory フィールドです。
これは agent に永続的な記憶を持たせる仕組みで、次のようなスコープがあるとされています。
user - 全プロジェクト共通で永続project - プロジェクト単位で永続local - gitignore されるローカル専用もし本当にこれが意図どおりに使えるなら、かなり強力です。
毎回「このプロジェクトではこういうルールだったっけ？」を説明しなくても、agent がある程度覚えていてくれるわけですから。
これは便利な反面、少し怖くもあります。
記憶があるということは、設定ミスや古い知識が残る可能性もあるからです。人間のチームでも「前のルールが残ってて混乱した」はよくありますよね。AIでも同じことが起きそうです。
この記事を読んで一番感じるのは、Claude Code は単なる「コードを書くAI」ではなく、かなり細かく制御できる実行環境 になっている、ということです。
特に重要なのは次の3点だと思います。
安全性を自前で強化できる
危険なコマンドを防ぐ、secret を検出する、監査ログを残すなど。
文脈を自動注入できる
ブランチ情報、変更数、監視ファイルなど、毎回説明しなくて済む。
用途ごとに振る舞いを分けられる
軽い作業は cheap & fast、重い作業は deep & powerful、という切り分けができる。
個人的には、こういう機能は「AIを賢くする」というより、AIをチームに組み込むための現実的な道具 だと思います。
AI単体の性能より、周辺の制御が使いやすいかどうかで、生産性はかなり変わるはずです。
元記事はかなりテンション高めに「こんなこともできる！」と紹介していますが、私はここで少し冷静さも必要だと思います。
asyncRewake のような挙動は便利だが、運用を理解していないと混乱しやすいつまり、これは“裏技集”であると同時に、“運用設計の話”でもあるんです。
個人利用なら遊びやすいですが、チームで使うなら設定の共有方法や責任範囲をちゃんと決めたほうがいいと思います。
この元記事は、Claude Code のソースコードを読み解いて、公式ドキュメントでは見えない hooks / Skills / agents の拡張性を暴いた記事です。
特に面白いのは、単なる設定追加ではなく、コマンドの書き換え、許可判定の自動化、セッション文脈の注入、永続メモリ まで扱えることです。
AIツールって、つい「モデルが賢いかどうか」ばかり見がちですが、実際の使い勝手を決めるのは、こういう周辺機能だったりします。
この記事は、そのことをかなりはっきり示していて、技術好きとしてはかなり楽しい内容でした。