個人開発で続けている壁紙アプリの配信用画像を抱えたリポジトリで、エージェントに読ませる範囲を絞ろうとしたときのことです。.antigravityignore に assets/ と書き、そのすぐ下に !assets/keep.png と足しました。1枚だけは読ませたかったからです。
結果は、意図の半分だけ通りました。assets/ 配下は静かになった一方で、keep.png も一緒に消えていたのです。書き方の問題だとは思わず、しばらくキャッシュを疑って時間を溶かしました。いま思えば、ファイルは私が書いたとおりに動いていて、私の思ったとおりに動いていなかっただけでした。
.antigravityignore は .gitignore と同じ書式の除外ファイルです。そして gitignore 形式には、読んだだけでは気づきにくい規則がいくつもあります。手元で1件ずつ判定を取ってみたところ、「書いたのに効かない」も「思ったより効きすぎる」も、原因はだいたい4か所に集まっていました。
最初にお伝えしたいのは、書式の4か所を直す前に「このファイルに何を任せているか」を一度確かめていただきたい、ということです。ノイズを減らす道具と、秘密を守る道具は別物です。
そもそも .antigravityignore は何を止めるのか(2026年11月時点)
2026年11月時点の公式ドキュメントを一通り確認したところ、.antigravityignore の名前が出てくるのは、CLI v1.1.16 の changelog にある「@ のファイルパス補完に .antigravityignore に書いたファイルが出ていた不具合を修正」という1件でした。書式の仕様ページや、エージェントの読み取りツールがどこまでこのファイルに従うかの説明は、私には見つけられませんでした。
一方で、読み取りを確実に止める仕組みは公式に明記されています。並べると次のとおりです。
| 仕組み | 公式ドキュメントでの位置づけ | 向いている用途 |
|---|---|---|
.antigravityignore | CLI の @ 補完が従う(v1.1.16 の修正)。読み取りの遮断としての説明は確認できず | 生成物・画像・ロックファイルなど、文脈に混ぜたくないノイズ |
.gitignore + Strict mode | Strict mode の説明に「Respect .gitignore」とあり、無視対象のファイルへのアクセスを防ぐ | リポジトリにもエージェントにも入れたくないもの |
Permissions の deny(例: read_file(secrets/)) | 統一パーミッションで Deny > Ask > Allow の順に評価され、Deny は即座にブロック | API キー・.env・顧客データなど、読まれたら困るもの |
ですから線引きは一つです。減らしたいものは .antigravityignore に、守りたいものは deny に。 除外ファイルの書き損じで秘密が漏れる構造そのものを、最初から作らないようにしています。
Deny ルールの書き方は公式の Permissions ページにあります。CLI の場合は ~/.gemini/antigravity-cli/settings.json に次のように足します(パスはワークスペースのルートからの相対で書けます)。
{
"permissions": {
"deny": [
"read_file(.env)",
"read_file(secrets/)"
]
}
}ここから先の4か所は、ノイズ除けとしての .antigravityignore を思いどおりに効かせるための話です。
目視をやめて、判定器に聞く
確かめ方から共有します。パターンが当たっているかを目で追うのは、行数が増えた時点で破綻します。
書式が gitignore 系ですから、手元の git をパターンの判定器として借りるのが手っ取り早い方法です。検証用の空ディレクトリに実際のパス構造だけを再現し、ルールを書いた状態で当たり外れを見ます。
mkdir -p /tmp/ignore-lab && cd /tmp/ignore-lab && git init -q .
mkdir -p assets/thumbs/ja
touch assets/a.png assets/keep.png assets/thumbs/b.png assets/thumbs/ja/c.png
printf 'assets/\n!assets/keep.png\n' > .gitignore
# 除外されずに「読まれる側」に残るファイルを列挙する
git ls-files -o --exclude-standardgit ls-files -o --exclude-standard は、除外されなかったファイルだけを並べます。「何が消えたか」ではなく「何が残っているか」を見るほうが、除外しすぎに気づきやすいという理由でこちらを使っています。
ひとつ注意があります。git check-ignore -v は否定行(! で始まる行)に一致したときもその行を表示し、終了コードが 0 になります。私はこれを「除外された」と読み違えて、最初の切り分けを一度やり直しました。可否を機械的に判定したいときは -v ではなく -q を使い、終了コード 1 を「除外されていない」と読みます。
git check-ignore -v assets/keep.png # → .gitignore:2:!assets/keep.png (終了コード 0)
git check-ignore -q assets/keep.png; echo $? # → 1(=除外されていない)以下の実測は git 2.34.1 の判定器で取ったものです。書式は共通ですが実装が完全に同一である保証まではありませんので、最後は Antigravity 側の実挙動でも一度確認しておくと安心です。
1. 親ディレクトリごと除外すると、! は届かない
冒頭でつまずいたのがこれでした。ディレクトリ自体を除外対象にすると、その中身は走査されなくなります。走査されないものは、あとから ! で呼び戻せません。
同じ「1枚だけ残す」を、書き方を変えて試した結果です。
| 書き方 | 読まれる側に残ったファイル |
|---|---|
assets/ + !assets/keep.png | なし(keep.png も除外された) |
assets/** + !assets/keep.png | assets/keep.png |
assets/** + !assets/thumbs/** | なし |
assets/** + !assets/thumbs/ + !assets/thumbs/** | assets/thumbs/b.png、assets/thumbs/ja/c.png |
3行目が興味深いところです。!assets/thumbs/** だけでは1件も戻ってきません。assets/** が assets/thumbs というディレクトリそのものにも当たっているため、その下へ降りる前に打ち切られるからです。ディレクトリを先に呼び戻し(!assets/thumbs/)、そのうえで中身を呼び戻す(!assets/thumbs/**)という2行が要ります。
「ディレクトリ単位で消して、一部だけ例外にする」という直感的な書き方が、ちょうど成立しない形になっている、と覚えておくのが早いと思います。
行の順序も効きます。!assets/keep.png を assets/** より前に書いた場合、keep.png は戻ってきませんでした。最後に一致した行が勝つ仕組みですので、例外は必ず除外の後ろに置きます。
2. スラッシュの有無で、探し始める場所が変わる
これが「効きすぎ」の主因でした。パターンの途中にスラッシュが含まれるかどうかで、意味がまるで変わります。
| パターン | src/tmp/t.txt | docs/src/tmp/z.txt |
|---|---|---|
tmp/(スラッシュを含まない) | 除外 | 除外 |
src/tmp/(内部にスラッシュ) | 除外 | 除外されず |
スラッシュを含まないパターンは、どの階層にある同名ディレクトリにも当たります。内部にスラッシュを含むパターンは、.antigravityignore を置いた位置から見た相対パスに固定されます。
規模のある場所でどう効くかも測ってみました。2,250 ファイルの Next.js プロジェクトで、content という1行だけを書いた場合です。
| 書いた行 | 除外対象になったファイル数 |
|---|---|
content | 2,133 / 2,250 件(約 95%) |
content/articles/en/、public/content/、*.lock の3行 | 1,032 / 2,250 件 |
content と1語書いただけで、リポジトリのほぼ全体が対象になりました。src/content、docs/content、そして深い階層の同名ディレクトリまで、すべて拾ってしまうためです。エージェントが急に的外れな回答を返し始めたとき、モデルではなく除外ファイルの1行が原因という場合があります。
ちなみに public/content/ の1行は 0 件でした。このリポジトリではビルド時に生成されるパスで、クローン直後には存在しないからです。「書いたのに効いていない」ように見えて、そもそも対象が無いだけということもあります。
3. * はディレクトリの区切りを越えない
assets/*.png のつもりが下の階層に届いていない、というパターンです。
| パターン | assets/a.png | assets/thumbs/b.png | assets/thumbs/ja/c.png |
|---|---|---|---|
assets/*.png | 除外 | 除外されず | 除外されず |
assets/**/*.png | 除外 | 除外 | 除外 |
* は1階層分しか担当しません。任意の深さを含めたいときは ** を挟みます。画像やビルド成果物のように階層が深くなりがちなものほど、この差が効いてきます。
4. 目に見えない文字と、行頭の記号
最後は、ファイルを見ても分からない種類の原因です。実際に測った4件を挙げます。
| 状況 | 結果 |
|---|---|
行末に半角スペースがある(assets/a.png␣) | スペースは切り捨てられ、除外は成立した |
行末スペースをバックスラッシュで保護(assets/a.png\␣) | 除外されず(末尾スペース込みの名前を要求する) |
| 改行コードが CRLF | 除外は成立した |
ファイル名が # で始まる(#temp.txt) | コメント扱いになり除外されず。\#temp.txt で成立 |
末尾スペースと CRLF は、疑わしく見えて実際には無害でした。切り分けの順序としては後回しで構いません。逆に、# や ! で始まる実在のファイル名を書くときは、バックスラッシュでの保護が要ります。
症状から引く切り分け表
4か所を、目の前の症状から逆に引けるように並べ直しました。上の行ほど、私の手元で当たった頻度が高かったものです。
| 症状 | 原因の候補 | 確かめ方 | 直し方 |
|---|---|---|---|
| 例外にしたはずの1ファイルも消えている | 親ディレクトリを dir/ で除外している | git check-ignore -v で一致した行が dir/ になっているか | dir/** に変え、例外を除外の後ろに置く |
| エージェントが急にコードを知らない前提で答える | スラッシュのない1語が全階層に当たっている | 後述の手順で、除外される件数を全体と比べる | 先頭か途中にスラッシュを入れて位置を固定する |
| 浅い階層だけ除外され、深い階層が残る | * が1階層しか担当していない | 深い階層のファイルを1つ選んで -q で判定する | dir/**/*.ext にする |
| 書いた行がまったく効かない | パスの綴り違い、または対象がまだ存在しない | 除外件数が 0 のままか | 実在するパスを find で確かめてから書く |
| 特定のファイル名だけ効かない | 行頭の #・!、保護した末尾スペース | エディタで不可視文字を表示する | 行頭を \#・\! にし、不要な \ を外す |
よくある誤解を3つ
「除外したファイルは、エージェントが絶対に読めない」——公式に確認できたのは @ 補完が従うところまでです。読まれたら困るものは、前述の deny に置きます。
「! を書けば、どこからでも呼び戻せる」——親ディレクトリが除外されていると届きません。git の公式ドキュメント(gitignore)にも「親ディレクトリが除外されているファイルは再び含めることができない」と書かれています。
「check-ignore が行を表示したら除外されている」——否定行に一致した場合も表示され、終了コードは 0 です。可否の判定は -q と終了コードで行います。
公開前に、残っている側を一度数える
書いたルールの棚卸しは、使い捨てのリポジトリで行います。ここで私は一度つまずきました。
最初は作業中のリポジトリでそのまま git -c core.excludesFile=.antigravityignore check-ignore を流していたのですが、数えた件数には .gitignore で除外されていたファイルまで混ざっていました。check-ignore は .gitignore と .git/info/exclude も同時に読むからです。手元で確かめたところ、.gitignore にだけ書いた docs/y.md が「除外される側」に数えられていました。
数えるときは、数えたいルール以外を部屋から出します。 そう決めてからは、次の形にしています。
# 1) 作業中のリポジトリで、全ファイルのパスを書き出す
find . -path ./.git -prune -o -type f -print | sed 's|^\./||' > /tmp/all-paths.txt
# 2) .antigravityignore だけを持つ使い捨てリポジトリを作る
L=$(mktemp -d) && git -C "$L" init -q . && cp .antigravityignore "$L/.gitignore"
# 3) グローバルの除外設定も切って、除外される件数と全体件数を比べる
git -C "$L" -c core.excludesFile=/dev/null check-ignore --no-index --stdin < /tmp/all-paths.txt | wc -l
wc -l < /tmp/all-paths.txtcheck-ignore はパスが実在しなくても判定できますので、使い捨て側にファイルを複製する必要はありません。assets/ のような末尾スラッシュのパターンも、assets/keep.png のように下にパスが続いていればディレクトリとして判定されました。
私はこの2つの数を見て、想定と桁が違えばルールを書き直すようにしています。先ほどの 2,133 件のようなケースは、数えれば一目で分かります。逆に0件のままなら、パスの綴りか、そのパスの存在自体を疑う番です。
次に詰まる一歩
除外がうまく効き始めると、次に気になるのは「秘密をどう扱うか」と「エージェントに何を実行させるか」だと思います。Deny ルールを最初にどこから書き始めるかは、Antigravity の Deny list は、自分のシェル履歴から作り始めますで、実際の履歴を数える手順と一緒にまとめました。
エージェントに丸ごとファイルを渡す場面では、エージェントに .zip を渡す前に、.git を除いて 29 MB を 15 MB にし、秘密情報の警告 28 件を見分けましたが近い話です。除外が効いているのに動作が重い場合は、Workspace Indexing が止まる・完了しない時の診断と修復手順のほうが当たるかもしれません。
書き込みや削除まで任せる段階になると、「読ませない」だけでは足りません。承認を通したあとに何がどこまで実行されるかを止められる形にする話は、消えたのは中身ではなく作業ディレクトリでしたで実際の事故と復旧をたどりながら書いています。
今日いちばんお勧めしたい一歩は、いま開いているプロジェクトで上の手順を走らせ、除外される件数と全体件数を一度書き留めておくことです。数字を持っていると、次に何かがおかしくなったとき、除外ファイルを容疑者リストの上に置けるようになります。
私自身、除外ファイルは書いた時点で満足しがちでした。数えて確かめる習慣が身についたのは、1枚の画像が消えたあの午後のおかげだと感じています。