【Antigravity連載⑦】決められたタイミングで処理を自動実行する「Hooks」とは何か

Hooksの実行タイミングは時刻ではなく作業の節目

まず、Hooksの実行タイミングを明確化しておきます。Hooksが動くのは、毎朝9時や毎週月曜日といった時刻ではなく、エージェントがツールを実行する直前など、処理の中で特定のイベントが発生したときです。

時間で起動するScheduled TasksとHooksは異なる機能

Antigravityでは、時間を基準にエージェントへのメッセージ送信を予約するScheduled tasksという機能があります。Hooksとの役割分担を整理すると、定期的な時刻に処理を開始したい場合はScheduled tasks、作業中の特定の段階で処理を動かしたい場合はHooksという使い分けになります。

例えば、毎朝プロジェクトの状態を確認する処理と、エージェントが指定したファイル編集ツールを実行した後にチェックする処理は、どちらも自動化ですが、起点が異なります。Hooksを考えるときは、何を自動化するかに加えて、どの操作の前後で動かす必要があるかを考えることが重要です。

なぜHooksが必要なのか？

コードを修正するだけであれば、エージェントに依頼することで作業を進められます。ただ、実際の開発では、修正そのものに加えて、編集後のチェックや操作前の確認も必要になります。Hooksが役立つのは、こうした付随する処理を、エージェントの操作と結び付けて実行したい場面です。

例えば、コードの編集後に毎回同じチェックを実行する場合を考えます。Rulesにチェックの方針を書いたり、Skillsに確認手順をまとめたりする方法がありますが、Hooksでは指定した編集ツールの実行後にチェックスクリプトを呼び出す、といった実行条件を設定できます。方針や手順をエージェントに伝えることに加えて、処理を動かすタイミングも定義できる点が特徴になっています。

操作を実行する前に、独自の判定を挟みたい場合にも使えます。PreToolUse（後述）では、実行予定のツール名や引数をスクリプトで受け取り、その内容に応じて実行を拒否したり、利用者への確認を求めたりできます。例えば、コマンドの内容を確認し、定めた条件に当てはまる場合には実行前の確認を求める、といった構成です。

つまりHooksは、エージェントに任せる作業に対して、必要なチェックや判定を組み込むための機能です。ただし、チェックスクリプトを実行することと、見つかった問題を修正することは別です。導入する際は、どの操作をきっかけに何を実行し、その結果をどう扱うかまで決めておくと、Hooksを使う目的が明確になります。

SkillsやRulesとの役割分担

過去記事でこれまで説明してきた通り、Antigravityのカスタマイズには、SkillsやRulesもあります。これらの機能は明確に役割が異なりますが、覚える機能が増えてくると分かりにくくなるため、改めてそれぞれが担当する役割を整理します。

Skillsは、特定の作業に必要な手順や知識を再利用可能な形にまとめる仕組みです。中心となるSKILL.mdに指示を記述し、必要に応じてスクリプトや参考資料も組み合わせます。エージェントは利用可能なSkillの名前と説明を確認し、作業に関連するものの詳細を読み込みます。

※Skillsの詳細は以下の記事をご参考ください。

• 【Antigravity連載②】AIエージェントを自分仕様に育てる「Skills」とは？
• 【Antigravity連載③】Skillsを実際に作ってみよう！作成方法をステップごとに解説

Rulesは、エージェントが従う方針や制約を文章で定義する仕組みです。プロジェクトのコーディング規約や回答のスタイルなどを設定でき、常に適用する方法のほか、対象ファイルやモデルの判断に応じて適用する方法があります。

※Rulesの詳細は以下の記事をご参考ください。

• 【Antigravity連載④】RulesとSkillsは何が違う？

これに対してHooksは、実行サイクル上のイベントと、動かすコマンドを結び付けます。設計上の使い分けとしては、守ってほしい方針をRulesに、作業の進め方をSkillsに、所定のタイミングで実行するチェックをHooksに持たせると整理できます。

例えば、コードの品質基準をRulesで共有し、レビュー手順をSkillsにまとめ、変更後の機械的なチェックをHooksで実行する構成です。三つを組み合わせることで、方針、手順、実行する処理をそれぞれ明示できます。

Hooksを実行できる五つのタイミング

Hooksには、次の5つのイベントがあります。これらのイベントは、後述する設定ファイル(hooks.json)に対して、特定のパラメーター(固定の文字列)として指定します。

このうち、最初に理解しておきたいのがPreToolUseとPostToolUseです。前者は操作を実行する前の判定、後者は実行後のチェックや記録に対応します。対象にするツールはmatcherで指定でき、コマンド実行やファイル編集など、必要な操作に絞ってHooksを動かせます。

ここで、ファイルの変更を確認したいなら、変更に使われるツールを対象にする必要があります。すべてのツールを対象にすると、ファイルを読むだけの操作でもチェックを実行する構成になります。まずは何の操作をきっかけにしたいのかを決め、その操作に対応するツール名を設定するのが分かりやすいでしょう。

また、モデルの呼び出し完了と、作業全体の終了は異なります。PostInvocationはモデルの呼び出しごとに発生するため、最終的な作業終了に結び付けたい処理とは分けて考える必要があります。

設定はhooks.jsonに記述する

Hooksの設定ファイルはhooks.jsonです。プロジェクト内の.agents/や、ユーザー共通の~/.gemini/config/といったカスタマイズ用ディレクトリに配置します。

設定の基本は、Hooksの名前、実行するイベント、対象ツール、実行コマンドの組み合わせです。以下は、ファイルの作成・編集後に、用意したチェックスクリプトを呼び出す構成例です。

matcherには、ファイルを新規作成するツールと、既存ファイルを編集する二つのツールを指定しています。commandのパスは例示なので、実際に用意したスクリプトのパスに置き換えてください。timeoutは処理の制限時間で、単位は秒です。

ここで押さえておきたいのは、設定ファイルにチェック内容そのものが書かれているわけではない点です。何を調べ、結果をどう記録するかは、呼び出すスクリプト側に実装します。Hooksは、その処理を実行するタイミングを担当します。

また、HooksとスクリプトはJSONで情報を受け渡します。スクリプトは標準入力から情報を受け取り、標準出力に所定のJSONを返す形式に合わせて作成します。既存のチェックコマンドを組み込む場合も、その出力をそのまま返す構成でよいかを確認する必要があります。

Hooksの3つの活用方法

ファイル変更後の品質チェック

一つ目は、ファイル変更後の品質チェックです。先ほどの構成例のように、編集後のイベントにチェック処理を接続できます。例えば、コードの書き方を検査するリンターを実行する用途です。

この場合、運用設計としては、チェックを動かすことと、結果を確認して修正することを分けて考えるとよいでしょう。チェックスクリプトを呼び出しただけで、指摘事項への対応まで設計できたことにはなりません。何を検査し、問題があった場合に誰がどう確認するかまで決めておくと、目的が明確になります。

ツール実行前の判定処理

二つ目は、ツール実行前の判定です。PreToolUseでは、実行予定のツール名や引数を受け取り、実行を許可する、拒否する、利用者に確認するといった判断を返せます。独自の条件で対象操作を判定する処理を組み込めるため、実行前に確認を挟みたい場面で利用できます。

確認方法には違いがあり、askは既存の常時許可設定を尊重します。一方、force_askは保存済みの許可にかかわらず確認を求めます。毎回確認させる設計にしたい場合、この違いは押さえておく必要があります。

処理終了時の記録

三つ目は、処理終了時の記録です。Stopでは終了理由や、バックグラウンド処理まで終了しているかを示す情報を受け取れます。これらを使い、終了時の状態を記録するスクリプトを組み込む構成が考えられます。

ただし、終了イベントが発生したことだけで、依頼した作業の成功を判断する設計にはできません。終了理由にはエラーやステップ数の上限到達も含まれます。また、fullyIdleがfalseなら、バックグラウンドの処理はまだ動いています。完了通知などに応用する場合は、こうした情報を判定に含める必要があります。

チームで利用するならプラグインで管理するのがおすすめ

Hooksは、Pluginsの構成要素としてまとめることもできます。Pluginsには、Rules、Skills、MCPサーバーの設定、Hooksを一つのパッケージに含められます。プロジェクト単位で配置する方法と、ユーザー共通の場所に配置する方法があります。

チームで利用する構成を考えるなら、品質基準を記したRules、確認手順をまとめたSkills、チェックを呼び出すHooksを一緒に管理する方法が候補になります。ただし、Hooksの設定には実行するコマンドが含まれるため、設定ファイルだけでなく、呼び出し先のスクリプトも確認対象に含める運用が適切だと思います。

導入時は、特定のプロジェクトで一つのチェックから始めると、設定の目的を説明しやすくなります。対象の操作、実行する処理、結果の確認方法を決めてから、共通化する範囲を検討する進め方です。

Hooksの価値は、作業の節目に必要な処理を、設定として明示できる点にあります。Antigravityにどのような作業を任せるかを考える際には、その前後にどのような確認を組み込むかも、合わせて設計してみてください。