「.env.example が見つからないと言われた」「dist/ の中のビルド成果物を確認してほしいのに、Claude Code が『そんなファイルはありません』と返してくる」——この壁にぶつかったとき、最初は Claude Code 側のバグかと思ってしまうかもしれません。私も最初は何度か検索コマンドを打ち直していました。
種を明かすと、これはバグではなく仕様です。Claude Code の Glob と Grep ツールは、デフォルトで .gitignore の内容を尊重するように作られています。理由を理解した上で、必要なときだけ「見える状態」にする方法を持っておくと、無駄な往復が一気に減ります。
なぜ .gitignore のファイルは検索結果に出てこないのでしょうか
Claude Code の Glob ツールは内部的に fd、Grep ツールは ripgrep の動作モデルに近いものを使っています。両方とも、デフォルトの挙動として 「Git が無視するファイルは検索結果から外す」 という親切設計になっているのです。
これは普段の開発体験には合っています。node_modules/ の中身が grep にヒットしてノイズだらけになる経験は、誰しも一度はあるはずです。Claude Code が大規模なリポジトリでも素早く応答できるのは、この前提のおかげでもあります。
しかし、状況によってはこの「親切」が裏目に出ます。具体的には次のようなケースです。
.env.exampleを確認したい（.env*が.gitignoreに書かれている場合）- ビルド済みの
dist/、build/、.next/の中身を読み取りたい coverage/や__snapshots__/のテストレポートを参照したい- 自分で
.gitignoreに追加した検証用フォルダを Claude に見せたい
つまり「Git では追跡したくないけれど、いま手元のセッションでは Claude Code に見てほしい」というシーンが、実は思ったよりも多いということです。
一見「バグ」に見える3つの典型シーン
私の経験上、この挙動で詰まる場面は3パターンに集約されます。
シーン1: .env.example が無いと言われる
User: .env.example の内容を教えて
Claude Code: [Globでcheck] そのパスにファイルは見つかりませんでした
実際にはリポジトリ直下に存在しているのに、.env* を .gitignore に書いている場合は引っかかりません。
シーン2: ビルド成果物のサイズや構成を見せたい
dist/index.js を見て最終バンドルがどうなっているか相談したいときに、Claude Code は「dist/ ディレクトリは存在しません」と返してきます。これも .gitignore 経由の除外です。
シーン3: ローカルで生成したログやスクリーンショットを見せたい
screenshots/, logs/, .cache/ などをデバッグの相談に使いたいケースでは、Claude Code が見えていないために的外れな提案を返してくることがあります。
解決策その1: Read ツールでパスを直接渡すのが最短です
3つの突破口がありますが、私が一番よく使うのは 「Claude Code に絶対パスを直接読ませる」 方法です。Claude Code の Read ツールは Glob や Grep と違って .gitignore を見ません。パスさえ確定していれば、即座に内容を取得できます。
具体的には、Claude にこう伝えるだけで十分です。
.env.example の内容を Read ツールで直接読んで。パスは ./project-root/.env.example。
または、自分でパスを cat してプロンプトに貼り付ける形でも構いません。
# シェルから内容を確認しつつ、必要な部分だけ Claude に渡す
cat .env.example | head -50「探させる」のではなく「位置を教える」ことで、.gitignore の壁を回避できます。これが Claude Code の検索系ツールと読み取りツールの最大の違いを活かす方法です。
検索しないと位置が分からないファイルの場合は、自分のシェルで先に位置を特定してから渡す流れが現実的です。
# 通常の find は .gitignore を無視しない
find . -name ".env.example" -not -path "*/node_modules/*"
# git に登録されていないファイルだけを表示
git ls-files --others --exclude-standard解決策その2: Bash ツール経由で --no-ignore フラグを使う
検索を Claude Code 側にやらせたい場合は、Bash ツールから ripgrep または fd を --no-ignore 付きで呼ぶのが確実です。
# .gitignore を無視して全ファイル検索（ripgrep）
rg --no-ignore "DATABASE_URL" .
# 隠しファイルやドットフォルダも含める場合
rg --no-ignore --hidden "API_KEY" .
# ファイル名検索（fd）
fd --no-ignore --hidden "\.env" .rg も fd もデフォルトで .gitignore を読みます。--no-ignore を付けると Git の世界から離脱した「素の検索」になります。--hidden を併用すると .next/ のような先頭がドットのフォルダもスキャン対象になります。
ただし注意点があります。node_modules/ 以下まで全文検索すると、応答時間が極端に長くなることがあります。私は次のようにスコープを絞って使っています。
# 「dist と coverage だけは見たいけど node_modules は除外」
rg --no-ignore --hidden \
--glob '!node_modules/**' \
--glob '!.git/**' \
"TODO" .--glob を組み合わせて自分でフィルタを書くのが、結果として一番速いです。Claude Code が遅く感じるときは、検索範囲が広すぎることがほとんどです。
Bash ツール周りのトラブルシューティングについては、Claude Code の Bash ツール実行エラー解決ガイドもあわせて参照してください。
解決策その3: .gitignore 自体を一時的に書き換える（最終手段）
どうしても Claude Code 側の標準ツール（Glob/Grep）にファイルを認識させたい場合は、.gitignore を編集する方法もあります。ただしこれは推奨度が低いやり方です。理由は、リポジトリ全体の挙動が変わるため、コミット時に意図しないファイルを追跡してしまうリスクがあるからです。
それでも使うなら、ローカル限定で完結する .git/info/exclude を逆手に取る やり方が安全です。.gitignore には書かず、.git/info/exclude に追記したルールはそのリポジトリのローカル限定です。
しかし「除外を解除したい」のが目的の場合は、もっと簡単な方法があります。.gitignore の特定行に ! プレフィックスを付けて、例外的に追跡対象に戻すのです。
# .gitignore の例
.env*
# Claude Code に見せたいので例外扱い
!.env.example
この変更をコミットする前提なら、.env.example は通常通り Glob/Grep に乗ってきます。ローカル作業中だけ無視を解除したい場合は、ファイルを編集後にコミットしないでセッションを続ければ十分です。
ちなみに .gitignore の挙動が思った通りにならないときは、git check-ignore -v <パス> で「どのルールがどのファイルを無視しているか」を1行で確認できます。これを覚えておくと診断がぐっと楽になります。
私が普段使っている運用パターン
毎回コマンドを思い出すのは大変なので、私は次のような運用に落ち着きました。読者の方の参考になれば嬉しいです。
- 見たいファイルのパスが分かっている場合:
Readツールに直接渡す。これが90%のケースをカバーします - 検索が必要だが範囲を絞れる場合:
Bashからrg --no-ignore --hidden --glob '!node_modules/**'で実行 - 頻繁に見せたいファイル（
.env.example等）:.gitignoreに!で例外を入れてコミットする - デバッグ用の一時ファイル: そもそも
.gitignore対象外のフォルダ（tmp/を.gitignoreに書かないなど）に置く
設定ファイル全般の挙動については、Claude Code settings.json 完全ガイドで permissions や env フィールドの細かい設定項目を確認できます。環境変数が読まれない問題でつまずいた経験がある方は、ANTHROPIC_API_KEY が効かないときの診断手順も役に立つかもしれません。
「ファイルが見つからない」と言われたら、まずは .gitignore を疑う。これだけで、ツール越しのやり取りで失う時間がかなり減ります。今日のうちに、自分のリポジトリで git check-ignore -v .env.example を一度試してみてください。仕組みが腹落ちすると、Claude Code の応答もずっと予測しやすくなります。