【Antigravity】Google Antigravity の設定カオスを防ぐ！ルール・スキルをセルフメンテナンスする「自動監査カスタムスキル」の構築と配布

作成日: 2026/07/12, 更新日: 2026/07/12

AI コーディングアシスタント（Google Antigravity 等）を使ううちに、設定ファイルが増えすぎて管理できなくなるカオス問題が発生します。
本記事では、AI エージェント自身に設定をレビューさせ、自動で最適化・修正させるカスタムスキル（antigravity-audit）の構築とポータブルな設計方法を紹介します。

Overview / 概要
AIエージェント開発環境の「設定カオス」問題とは？
自動監査カスタムスキル antigravity-audit の設計
1. 主要な機能
2. 🔄 監査処理の全体フロー
🔍 antigravity-audit がチェックする具体的な監査観点
1. 1. 静的検証（プログラムによる自動チェック）
2. 2. AI 定性的レビューと構成チューニング提案（エージェントによる評価）
🌐 Selenium による「外部の最新ドキュメント・ルール」の自動取得と監査
1. 動作プロセス
📊 実際に生成される監査レポート例
🛠️ 強力な「自動修復 (Auto-fix)」機能の仕組み
🔄 開発時の導入と運用フロー
🔗 GitHub リポジトリ
まとめ

【Antigravity】Google Antigravity の設定カオスを防ぐ！ルール・スキルをセルフメンテナンスする「自動監査カスタムスキル」の構築と配布

Overview / 概要

AIコーディングアシスタント（Google Antigravity や Claude Code 等）を使ううちに、設定ファイルやカスタムスキルが増えすぎて管理できなくなる「設定カオス問題」が発生します。本記事では、AIエージェント自身にルールやスキルをレビューさせ、自動で重複の検出や最適化・修正を行わせるセルフメンテナンス用のカスタムスキル antigravity-audit の構築方法と、ポータブルな設計パターンを紹介します。

AIエージェント開発環境の「設定カオス」問題とは？

AIコーディングアシスタントの導入が進むと、プロジェクト個別、あるいはグローバルなユーザーディレクトリ配下に、AIに対する挙動指示（RULES.md や AGENTS.md などのルール設定）や、特定の開発タスクを自動化する「カスタムスキル（SKILL.md や補助スクリプト）」が急速に蓄積されていきます。

これにより、以下のような課題（カオス）が発生しがちです：
1. 不要なルールの放置 : すでに完了した古い仕様や、不要になった指示が残り、コンテキスト窓を無駄に圧迫する。
2. スキルの破損やデッドリンク : 補助スクリプトのパスが変わったり、依存関係が崩れて実行できないスキルが放置される。
3. 多言語ドキュメントの同期ズレ : 日英バイリンガルで運用している場合、片方のドキュメントだけが更新され、もう片方が古いままになる。

これらの管理を人間が手動で行うのは非常に面倒です。そこで、 「AIエージェントの設定の監査は、AIエージェント自身に行わせる」 というアプローチが極めて有効になります。

自動監査カスタムスキル `antigravity-audit` の設計

今回構築した antigravity-audit スキルは、指定されたワークスペース（ .agents/ またはグローバル設定ディレクトリ）を自動でスキャンし、ルールやスキルの整合性、重複、破損状況を自動で診断してマークダウン形式のレポートを生成し、さらには一部の不整合を自動修復します。

主要な機能

ワークスペースの言語の動的判定 :
スキャン先の主要ドキュメント（ SKILL.md , README.md 等）から日本語と英語の文字比率を自動検出し、判定結果に基づいてレポートの言語（日本語/英語）を動的に切り替えます。これにより、多言語チームの環境であってもシームレスに動作します。
スキルの整合性診断 :
各カスタムスキルの SKILL.md の YAML フロントマッターに必須項目（ name , description ）が存在するか、補助スクリプトへの実行パスが破損していないかを診断します。
ルール定義の重複排除と監査 :
同一のグローバルルールが複数箇所でバッティングしていないかをチェックし、最適化の提案を行います。

🔄 監査処理の全体フロー

本スキルが起動してから監査レポートを出力し、修正を適用するまでの大きな処理の流れは以下の通りです。

sequenceDiagram autonumber actor Developer as 開発者 participant Audit as audit.py participant Selenium as Selenium (Headless) participant Spec as 公式仕様書 (Web) participant Agent as AIエージェント (LLM) participant Patch as apply_patch.py Developer->>Audit: スキルの起動 (python3 scripts/audit.py) rect rgb(240, 248, 255) note right of Audit: 自己更新フェーズ Audit->>Selenium: 仕様書のスクレイピング指示 Selenium->>Spec: 最新仕様 (Antigravity 2.x) の取得 Spec-->>Selenium: レンダリングデータ Selenium-->>Audit: 最新仕様データ (Markdown/JSON) note right of Audit: ローカル定義と比較し、必要に応じて自己更新して再起動 end rect rgb(245, 245, 245) note right of Audit: 解析・判定フェーズ Audit->>Audit: 対象ディレクトリ (.agents/) のスキャン Audit->>Audit: 日本語/英語の文字比率からレポート言語を判定 end rect rgb(255, 245, 238) note right of Audit: 静的検証 & AI定性分析 Audit->>Audit: プログラムによる「静的検証」の実行 (JSON/YAML, Sidecar, MCP等) Audit-->>Agent: スキャン結果と設定ファイルの中身を提示 Agent->>Agent: 「AI定性的レビュー」の実行 (フック変換, 委譲, 重複等の分析) Agent-->>Audit: 定性チューニング提案データ end Audit-->>Developer: 最終監査レポート出力 (audit_report.md) Developer->>Developer: レポート内容の確認と修正案の承認 Developer->>Patch: パッチ適用の実行 (python3 apply_patch.py --patch [file]) Patch-->>Developer: 各ファイルへ安全に修正適用完了

①自己更新フェーズ (Self-Update Check) :
起動時、外部の最新仕様書と同期を取るため、Selenium を介してヘッドレスで公式ドキュメントをスクレイピングし、差分があればスキル本体を自動更新・再起動します。
②解析・判定フェーズ (Workspace Scan & Language Detection) :
対象フォルダ（グローバルおよびプロジェクト配下の .agents/ ）を巡回し、ドキュメント内の文字比率からレポートの出力言語を決定します。
③静的検証 & AI定性分析 (Verification & LLM Analysis) :
スキーマ適合性や配置ルール、MCP/Sidecar 設定などのプログラム検証を走らせた後、その結果と設定ファイルをエージェント（LLM）に渡し、「チューニング提案チェックリスト」に基づく定性的な改善案（フックへの移行やサブエージェント委譲設計など）を生成します。
④レポート出力とパッチ適用 (Report & Patch Application) :
自動生成された Markdown レポート（ audit_report.md ）を開発者が確認し、修正提案に合意した後に apply_patch.py コマンドで安全に環境へパッチを適用します。

🔍 `antigravity-audit` がチェックする具体的な監査観点

本監査スキルは、AI開発環境の劣化を防ぐため、プログラムによる「静的検証」と、LLM（エージェント）による「定性的な動的レビュー」のハイブリッド方式で評価を実施します。

1. 静的検証（プログラムによる自動チェック）

audit.py および検証モジュールを用いて、以下の項目をプログラムで自動的に検証します。

評価項目	観点の詳細・チェック内容	目的
スキーマ適合性	`SKILL.md` の YAML フロントマッターの有無、JSONの文法および必須項目の適合性を検証。	システムによるスキルの正しい解析とロードを保証するため。
ルール記述ルール	ルールファイル（ `rules/*.md` ）のフロントマッターにおける `description` が150文字以内であるかを検証。	ルール一覧表示時の視認性を維持するため。
物理的重複の検出	同一ファイルがグローバル（ `~/.gemini/config/` ）とローカル（ `.agents/` ）で重複して配置されていないかを検証。	コンテキスト競合の防止および無駄なファイルの削減。
Sidecar 有効化チェック ⚡	`sidecar.json` 存在時に、 `config.json` の `sidecars.<id>.enabled` が `false` （無効）になっていないかを検証。	有効化漏れによるバックグラウンドタスクの未実行を防止するため。
Plugin 配置チェック ⚡	プラグイン配置先が公式サポートの `.agents/plugins/` または `_agents/plugins/` であるかを検証。	プラグインロードエラーを防止するため。
MCP スキーマチェック ⚡	`mcp_config.json` のリモート設定で `serverUrl` （非推奨の `url` ではない）が正しく使われているかを検証。	MCP サーバーとの通信エラーを防止するため。
Hook AgentStop 出力検証 ⚡	`hooks.json` の `AgentStop` イベント時、出力 JSON に `decision` フィールド（ `"continue"` 等）が含まれるか検証。	フック処理による制御フローの意図しない切断を防止するため。
brain 履歴の自動分析 ⚡	直近のセッションログを自動スキャンし、エラー履歴から構成改善の推奨警告（AUD-08〜10）を検出。	頻発する不具合やワークフローのボトルネックを自動で改善するため。

2. AI 定性的レビューと構成チューニング提案（エージェントによる評価）

静的検証の実行後、AIエージェントがファイル群を読み込んで精査し、以下のチューニング観点から改善案を提案します。

評価項目	観点の詳細・チェック内容	目的
Hook（フック）への変換	フォーマット検証やビルド実行など、コマンド実行前後で自動化すべき処理についてフック（ `hooks.json` ）への移行を提案。	手動実行の漏れを防ぎ、開発プロセスを完全に自動化するため。
グローバル/ローカル最適配置	汎用指示はグローバル設定へ、プロジェクト特有の仕様はローカル（ `.agents/` ）へ配置するアセットの最適化を提案。	トークン消費（コンテキストサイズ）の最適化と再利用性の向上のため。
Sidecar（サイドカー）化	定期実行する Cron ジョブや常時バックグラウンド監視タスクを `sidecar.json` を用いてプロセス分離することを提案。	メインセッションの同期実行時間を短縮し、エージェントの処理を軽量化するため。
サブエージェント委譲	コード全走査や重いテスト実行など、コンテキスト窓を大きく消費する重い処理についてサブエージェントへの非同期委譲を提案。	親コンテキスト（65,536トークン制限）の圧迫を防ぎ、並行処理を可能にするため。
Plugin（プラグイン）化	関連するルール、スキル、MCP、Hooks を1つの名前空間付きプラグイン（ `plugin.json` ）としてパッケージングすることを提案。	設定アセットのメンテナンス性向上と配布・管理を容易にするため。
Permission（権限）の最小化	ワイルドカード（ `*` ）による無制限な実行許可を避け、必要最小限の狭いスコープ（コマンドプレフィックスやサブディレクトリ）へ制限。	安全なサンドボックス環境を維持し、予期せぬ破壊的コマンドの実行を防ぐため。
論理的重複の検出と統合	ファイル名が異なる場合でも、実質的な規約や手順が類似している「論理的な重複」を検出し、グローバル共通ルール等へのマージを提案。	指示の矛盾を排除し、コンテキストサイズを削減するため。
Failsafe Hook 導入	`--no-verify` コミットや設定ファイルの直接改変をフックで検知・ブロックする仕組みの導入を提案。	開発ルールやセキュリティ規制の意図しない迂回を防止するため。
メモリ整合性検証	`task.md` などの Markdown メモリと状態管理キャッシュ（JSON等）の整合性を検証。	エージェントのステータス認識の不一致を防ぐため。
フックコスト評価	タイムアウト設定や登録フック数が過剰でないかを評価し、レスポンス遅延やトークン消費を抑える軽量化を提案。	開発者の待ち時間を最小限に抑え、開発体験（DX）を最適化するため。
ルールとスキルの追加	ワークスペース内の技術スタックや外部API利用特性に合わせ、品質や安全性を担保するために新設すべきルール・スキルを提案。	プロジェクト固有のバグを未然に防ぎ、開発生産性を高めるため。

🌐 Selenium による「外部の最新ドキュメント・ルール」の自動取得と監査

AIエージェントのルール監査において、もう一つの重要なポイントが 「ルールそのものの鮮度管理」 です。
AWSやGCPなどのクラウドサービス、あるいは使用しているAIツール（Antigravity やライブラリ等）の公式仕様は日々アップデートされます。ローカルに保存したルール（ RULES.md ）が古い仕様に基づいていると、AIエージェントは非推奨の古いコマンドや設定を生成し続けてしまいます。

そこで antigravity-audit は、 Selenium（ヘッドレスブラウザ）を用いて外部の公式リファレンスや仕様書ページを自動巡回・スクレイピングし、最新のルール定義を自動取得してローカルに同期する機能を備えています。

動作プロセス

動的なドキュメント取得 : ヘッドレスの Chrome を Selenium で制御し、API認証等がない公開リファレンスサイトや最新のリリースノートを自動巡回して最新のマークダウン/JSONデータを取得します。
差分検知と警告 : 取得した最新リファレンスと、ローカルのルール定義（例： port_allocation.md のポート一覧や、各種コマンドの仕様）をパースして比較します。
ルール更新の自動提案 : 古い API 仕様や非推奨になったコマンドの記述があれば、監査レポートを通じてユーザーに警告し、自動置換可能な箇所はパッチファイルを作成します。

これにより、AI開発環境そのものを「世の中の最新仕様」と同期した状態に自動で維持することが可能になります。

📊 実際に生成される監査レポート例

以下は、実際に自動生成される Markdown 形式の監査レポートの例です。

# 🛡️ Antigravity Environment Audit Report

> [!NOTE]
> スキャン実行時刻: 2026-07-12 19:40:00 (JST)
> 判定された主要言語: 日本語 (ja)

## 📈 診断サマリー

| 監査対象カテゴリ | チェック数 | 検出された問題 | 自動修復ステータス |
| :--- | :---: | :---: | :---: |
| グローバルルール (AGENTS.md) | 12 | 1 | 🛠️ 自動修復済み |
| プロジェクトルール (RULES.md) | 8 | 0 | ✅ 異常なし |
| カスタムスキル (skills/) | 15 | 2 | ⚠️ ユーザー要確認 |

---

## 🚨 検出された詳細アラート

### 1. グローバル設定の重複ルール
- **ファイル**: `~/.gemini/config/AGENTS.md`
- **ステータス**: `⚠️ Warning`
- **検出内容**: 「Chromeの自動操作禁止」に関するルール定義が、ローカルプロジェクトの `.agents/RULES.md` の定義と完全に重複しています。
- **対応アクション**: コンテキスト削減のため、グローバル設定側から該当する重複ルールセクションを自動削除しました。 (**自動修復完了**)

### 2. カスタムスキルのフロントマッター欠損
- **ファイル**: `skills/aws-deploy/SKILL.md`
- **ステータス**: `❌ Error`
- **検出内容**: システムローダーに必要な YAML フロントマッターの `description` フィールドが不足しています。
- **対応アクション**: 手動で `skills/aws-deploy/SKILL.md` を開き、適切な説明文をフロントマッターに追記してください。

### 3. スキル補助スクリプトの実行パス破損
- **ファイル**: `skills/house-keeping/SKILL.md`
- **ステータス**: `❌ Error`
- **検出内容**: `SKILL.md` 内で参照されているヘルパースクリプト `scripts/cleanup.sh` が存在しないか、実行権限がありません。
- **対応アクション**: ファイルが実際に存在するか、また `chmod +x` が実行されているかを確認してください。

🛠️ 強力な「自動修復 (Auto-fix)」機能の仕組み

本スキルは単に問題をレポートするだけでなく、安全に修復可能な不整合に対しては自動的にパッチを適用します。

YAMLフロントマッターの自動補正 :
SKILL.md に frontmatter 記法が欠けている場合、AIエージェントはファイル内の内容を読み取って自動的にタイトルと説明文（ name と description ）を推定し、ファイルの最上部にフロントマッターを自動挿入します。
重複ルールのマージとクリーンアップ :
ローカルプロジェクトのルールとグローバルルールで全く同じ指示が重複している場合、優先度の低いグローバルルール側をコメントアウト、またはセクションごとクリーンアップし、トークン消費の無駄を防ぎます。

🔄 開発時の導入と運用フロー

この自動監査スキルは、以下のように日常の開発フローに組み込んで運用することをお勧めします。

週次・月次での定期的な見直し（推奨） :
開発環境のルールやスキルは日々増大するため、 「週に一回」または「月に一回」の定期メンテナンス日 を設け、自動監査スクリプトを定期実行させて環境の棚卸しとクリーンアップを行います。これにより、開発時のコミット体験（DX）を妨げることなく、環境を常に最適に維持できます。
CI/CD パイプラインへの組み込み :
GitHub Actions などの CI/CD 環境で PR 作成時やマージ時に自動実行させ、ルールファイルやスキルファイルの破損がないかチェックさせます（ローカルでの Git コミット速度を落とさずに整合性を担保できます）。
手動での明示的チェック :
AIエージェントとの開発セッションを開始する際、最初のプロンプトとして以下のように指示して手動実行させます。
> 「自動監査スキルを実行して、現在のカスタムスキルとルールの状態をスキャンし、破損や不要な重複があれば修正してください。」

🔗 GitHub リポジトリ

本記事で紹介した自動監査スキルの構成テンプレートおよびブログのソースコードは、以下の GitHub リポジトリで公開しています。

👉 kanji-shinohara/web-gcp-us-firebase-moderniser-repo

まとめ

AIコーディングエージェントを最大限に活用し続けるためには、開発環境自体も常にクリーンで最適化された状態に保つ必要があります。AI自身にセルフメンテナンスを依頼するカスタムスキルを導入することで、設定カオスから解放され、より本質的な開発作業に集中できるようになります。