.cursorignore完全ガイド：設定方法と「効かない」トラブル解決

.cursorignoreとは？何をブロックできるのか

.cursorignoreの役割とブロック対象

室谷代表取締役

まず大前提として、.cursorignore はプロジェクトルートに置く設定ファイルで、中身は .gitignore と同じ構文なんですよね。で、何をブロックするかというと、Tab 補完、Agent、Inline Edit、@mentions といったAI機能と、インデックスの両方を遮断する。

テキトー教師.AI認定講師

そこがポイントですよね。最初に触る人は「.gitignore と同じ感覚でいいんでしょ？」って思うんですけど、実は .cursorignore の方が影響範囲が広い。

.gitignore はあくまでインデックスだけに効くので、.env を .gitignore に入れても Agent が読めちゃうケースがある。

室谷代表取締役

そうそう。だからセキュリティ的にちゃんと止めたいなら .cursorignore を使えと。

公式ドキュメントにも「.cursorignore は Tab, Agent, Inline Edit, @mentions のコードアクセスをブロックする」って書いてあります。

.cursorindexingignoreとの使い分け

室谷代表取締役

じゃあ、インデックスだけブロックしたい場合どうするかというと、.cursorindexingignore っていう別のファイルがあるんですよ。

テキトー教師.AI認定講師

現場でよく聞かれるのが「.cursorignore で全部止めると、逆に大きな生成ファイルが参照できなくて困る」って相談ですね。そういうときは .cursorindexingignore を使うと、インデックスからは除外されるけど、Agent とかからは普通に参照できる。

室谷代表取締役

使い分けの基準としては、単純に「検索結果に表示させたくないだけ」なら .cursorindexingignore、本当にAIに触らせたくないなら .cursorignore。たとえば .env や鍵ファイルは絶対に .cursorignore に入れるべき。

なぜ.cursorignoreが必要なのか（セキュリティとパフォーマンス）

テキトー教師.AI認定講師

セキュリティ面が大きいですよね。実際に .env を .cursorignore に入れてなかったら、Agent が普通に API キーを読み上げちゃった、みたいな報告もコミュニティでありましたし。

室谷代表取締役

あとはパフォーマンス。大規模なモノレポとかで docs/ やビルド成果物をインデックス対象にすると、検索が遅くなって精度も落ちる。

無視すべきファイルを切っておくだけで、Tab 補完の反応速度が体感で変わります。

テキトー教師.AI認定講師

コストの観点でも、余計なファイルを読み込まないことで処理が軽くなる。ROI で考えると、設定に5分かけても十分ペイする話ですね。

.cursorignoreの書き方：.gitignoreと同じ構文で設定

基本的なパターンと例

室谷代表取締役

.cursorignoreの書き方は.gitignoreとまったく同じです。ファイル名、拡張子、ディレクトリを一行ずつ書くだけ。

Git使ってる人ならすぐ慣れますよ。

テキトー教師.AI認定講師

そうですね。具体的には config.json で特定ファイル、*.log で拡張子一括、dist/ でディレクトリ全体、という指定が基本です。

室谷代表取締役

現場では無視リストを最小限に抑えたほうがAIの精度が上がるんですよね。不必要にたくさん指定しすぎると、必要なファイルまで隠れてしまう。

テキトー教師.AI認定講師

それ、よく聞きます。最初は手厚く書きがちですが、本当に必要なものだけに絞るのがコツです。

ネストしたディレクトリと否定パターン

室谷代表取締役

**/logs みたいに二重アスタリスクを使えば、ネストしたディレクトリにもマッチします。否定パターンは !src のように先頭にエクスクラメーション。

テキトー教師.AI認定講師

否定パターンは最初に戸惑う人が多いポイントです。例えば public/* ですべて除外したあと !public/index.html で一部だけ戻せますが、さらに深い階層のファイルは戻せないという制約があります。

室谷代表取締役

親ディレクトリごと除外すると、その中の個別ファイルは復活できない。パフォーマンスの都合だそうですけど、地味にハマる。

テキトー教師.AI認定講師

その場合は public/assets/* にして !public/assets/style.css と明示的に指定する必要があります。.gitignoreと同じ挙動ですね。

コメントの書き方

室谷代表取締役

コメントは # で始めます。これも .gitignore そのまま。

設定ファイルに説明を書いておくとチームで共有するときに役立ちます。

テキトー教師.AI認定講師

# Build directories みたいにセクション分けするのがおすすめです。あと末尾のスペースが意図せずパターンの一部にならないよう注意が必要。

室谷代表取締役

細かいですが、バックスラッシュでエスケープできるので、どうしてもスペースを含めたいときは \ を付けます。でも普通は使いませんね。

テキトー教師.AI認定講師

実際には、コメントを活用して「なぜこのファイルを無視するのか」を書いておくと、後から見た人が迷いません。

環境変数（.env）を確実に無視する方法

.cursorignoreで.envを指定する

室谷代表取締役

.envファイルって、.gitignoreに入れてるだけだとCursorのAgentとかTab補完で読まれちゃうんですよね。これは知っておいたほうがいい。

テキトー教師.AI認定講師

たしかに。現場で「.gitignoreに入れてるのに.envの中身が提案に出てきた」って話、よく聞きます。

.gitignoreはインデックスにしか効かないんですよ。

室谷代表取締役

.cursorignoreで明示的に.envと.env.*を書いておくのが正解。例えばこんな感じです。

.env
.env.*

テキトー教師.AI認定講師

それでAgentやTab、インライン編集からブロックされます。ただ…

グローバル設定で全プロジェクトに適用

室谷代表取締役

毎回プロジェクトに.cursorignoreを置くのは面倒。USの開発現場だと、グローバル設定で一括指定してるチームが多いですよ。

テキトー教師.AI認定講師

ありますね。Cursorの設定から、VS Code設定のGeneral > Global Cursor Ignore Listにパターンを追加するんです。

室谷代表取締役

そこに **/.env と **/.env.* を書いておけば、開くプロジェクト全部で効く。時給換算すると、設定にかける5分で何時間分もの漏洩リスクが減る計算です。

テキトー教師.AI認定講師

最初にグローバルで設定しておけば、新規プロジェクトでも.envをうっかり送信しちゃう心配がなくなりますね。

ターミナル経由の回避策と注意点

室谷代表取締役

ただ、ここで落とし穴があって。.cursorignoreはAgentのターミナル経由の操作まではブロックできないんですよ。

テキトー教師.AI認定講師

そう、ドキュメントにも「ターミナルとMCPツールは.cursorignoreの対象外」って書いてあります。Agentが cat .env を実行しようとすることもある。

室谷代表取締役

だから、ターミナルコマンドの許可は「毎回確認」にしておくのが鉄則。特にcatやecho、Get-Content系は許可リストに入れない。

テキトー教師.AI認定講師

環境変数を完全に守るなら、.cursorignoreとターミナルの承認設定の組み合わせが必須です。この二段構えで初めて安全と言えますね。

.cursorignoreが効かない！よくあるトラブルと解決策

ファイルのルート配置を確認

テキトー教師.AI認定講師

まず最初にハマるのが、ファイルの設置場所ですね。.cursorignoreはプロジェクトのルートディレクトリに置かないと認識されません。

室谷代表取締役

そうなんですよ。サブフォルダに置いて「効かない」ってなるパターン、結構見かけます。

ルート直下、.gitignoreと同じ階層に置くのが基本です。

テキトー教師.AI認定講師

現場でよく聞くのは「.gitignoreと同じ場所に置いたのに効かない」という相談。実はスペルミスとかも多いんですよね。

.cursorignore、頭にドットがついてるのを忘れて「cursorignore」って名付けてしまう人も。

室谷代表取締役

それはあるあるですね。ファイル名の確認、まずはそこからです。

再インデックスが必要なケース

室谷代表取締役

もう一つ、設定後にインデックスが更新されていないパターン。.cursorignoreを追加したあと、Cursorがすぐに反映するとは限らないんですよ。

テキトー教師.AI認定講師

たしかに。特にすでにプロジェクトのインデックスができていると、新しいルールを認識するまでに時間がかかったり、再インデックスが必要だったりします。

室谷代表取締役

あとは.cursorindexingignoreとの混同ですね。インデックスだけブロックしたいならそっちを使うんですが、.cursorignoreはインデックスとAI機能の両方をブロックする。

効かないと思ったら、どっちを使うべきか見直す必要があります。

テキトー教師.AI認定講師

公式のドキュメントでも、.cursorignoreはAgentやTab、インライン編集からのアクセスをブロックするって明確に書かれてますね。再インデックスをトリガーするには、Cursorを再起動するか、コマンドパレットからインデックスを再構築するのが確実です。

ファイルが開かれていると効かない？

室谷代表取締役

これ、結構誤解されてるポイントなんですが、.cursorignoreに追加しても、そのファイルがエディタで開かれているとコンテキストとして使われることがあるんですよ。

テキトー教師.AI認定講師

そうなんです。古いフォーラムの投稿でも報告されていて、.cursorignoreでブロックしても、開いているファイルはチャットの自動コンテキストとして追加されてしまう。

完全に遮断したい場合は、ファイルを閉じてから操作する必要があります。

室谷代表取締役

つまり、セキュリティ的に厳密にやりたいなら、機密ファイルは開いたままにしない、という運用ルールが必要ですね。あと最近のバージョンでは改善されているはずですが、古い情報に惑わされないように。

テキトー教師.AI認定講師

そうですね。今は.cursorignoreがTab補完やインライン編集もブロックするようになっているので、以前よりはマシですが、完全に「見えない」わけではないという認識は持っておいた方がいいでしょう。

.gitignoreとの優先順位の誤解

室谷代表取締役

最後にこれ、.gitignoreと.cursorignoreの関係ですね。.gitignoreに書いたから大丈夫、と思ってると危険です。

テキトー教師.AI認定講師

実際、.gitignoreはインデックスにしか適用されないんですよ。Agentがファイルを読んだり、Tab補完が効いたりするのを防ぐには.cursorignoreが必要です。

室谷代表取締役

この誤解で.envが漏れるケース、結構あるみたいです。フォーラムでも「.gitignoreに.envがあるのにAgentが読める」って報告が上がってますからね。

テキトー教師.AI認定講師

解決策としては、機密ファイルは.cursorignoreにも明示的に追加する。もしくはグローバルな無視リストに.envや.pemを登録しておくと、プロジェクトごとに書かなくて済みます。

設定はVS Codeの設定から「Global Cursor Ignore List」で行けます。

.gitignoreと.cursorignoreの使い分けと連携

.gitignoreはインデックスにのみ適用

室谷代表取締役

これ、結構な割合の人が勘違いしてるんですよね。.gitignore 書いておけば AI も勝手に避けてくれると思ってる。

テキトー教師.AI認定講師

たしかに。でも実際は .gitignore ってインデックスにしか効かないんですよ。

エージェントが Read file で読もうとしたら普通に読めちゃう。

室谷代表取締役

そう。で、.gitignore に書いた .env がエージェントから丸見えになるって報告がフォーラムで何件も上がってて。

結構危ない。

テキトー教師.AI認定講師

じゃあ「.gitignore だけ書いて安心」はダメで、ちゃんと .cursorignore を使う必要があると。

.cursorignoreはAI機能もブロック

テキトー教師.AI認定講師

.cursorignore は一歩進んで、AI 機能全般からファイルをブロックします。ドキュメントにも「Agent, Tab, Inline Edit, @ mentions」からアクセスできなくなると。

室谷代表取締役

コードで言うと、.cursorignore に書いたファイルはタブ補完の候補にも出てこないし、エージェントが参照しようとしてもアウト。ただしターミナル経由の cat とかは止められない。

テキトー教師.AI認定講師

そこは知っておかないと。.cursorignore をすり抜けてターミナルで読もうとするケースもあって、実際に「echo .env ってコマンドを提案された」って報告があります。

室谷代表取締役

だから「Ask Every Time」を有効にして、ターミナル実行は都度承認する運用にするのが現実的です。

両方を併用するベストプラクティス

室谷代表取締役

で、結局どう使い分けるか。.gitignore は Git 管理から外すためのもの。

.cursorignore は AI から隠すためのもの。両方書いておくのが基本です。

テキトー教師.AI認定講師

特に .env や鍵ファイルは .cursorignore に必ず追加。グローバル設定で「**/.env」を指定しておけばプロジェクトごとに書かなくて済みます。

室谷代表取締役

US の現場だと「Global Ignore Files」に .env* と *.pem を最初に突っ込むのが定番ですね。MYUUU でもチームの全員にそれを強制してます。

テキトー教師.AI認定講師

あと、インデックスだけ除外したい大きな生成ファイルは .cursorindexingignore を使う。そっちは AI 機能からは読めるけど検索結果には出てこない。

パフォーマンス最適化：大規模プロジェクトで無視すべきファイル

node_modulesやdistを無視する理由

室谷代表取締役

大規模プロジェクトだと、最初にnode_modulesやdistを.cursorignoreに入れるだけでインデックス時間が劇的に変わります。シリコンバレーのチームだと、これをやってないと「なんでAIの応答遅いんだ」って話になるんですよね。

テキトー教師.AI認定講師

たしかに。初めて触る人がやりがちなのが、全部インデックスさせようとすることです。

でもnode_modulesなんて数千ファイルあって、コード補完の邪魔になるだけなんですよ。

室谷代表取締役

MYUUUの現場でも、最初に無視リストを整備するかどうかで、時給換算すると毎月数時間の差が出ます。待ち時間がコストですからね。

テキトー教師.AI認定講師

最初に設定しておくべきはnode_modules、dist、.next、outあたりですね。これらはビルド成果物なので、AIに見せても意味がないどころか、むしろノイズになります。

生成ファイルとソースファイルの区別

テキトー教師.AI認定講師

ソースファイルと生成ファイルをごっちゃにすると、AIが混乱するケースが多いんです。たとえば*.min.jsや*.generated.*を無視しないと、コンパイル後のコードを参照して変な提案をしてきます。

室谷代表取締役

そこはちゃんと区別したほうがいいですね。CIで生成されるカバレッジレポートやキャッシュも同様です。

coverage/や.nyc_output/は確実に無視すべきです。

テキトー教師.AI認定講師

具体的には、.min.css、、coverage/あたりは必須です。あとログファイルも。

現場では「こんなのまでインデックスしてたのか」と驚く人が多いです。

室谷代表取締役

プロジェクトが大きくなればなるほど、無視リストも拡張していく必要がありますね。数が増えすぎると今度はメンテが大変になるので、グローバルなignoreとプロジェクト固有のignoreを使い分けるのが現実的です。

モノレポでの戦略

室谷代表取締役

モノレポ構成だと、各パッケージに個別に.cursorignoreを置くか、ルートにまとめて書くかで迷うんですよね。Anthropicの設計思想に近いんですが、パッケージ単位で独立性が高いなら階層的に管理した方が効率がいい。

テキトー教師.AI認定講師

モノレポでルートにだけ.cursorignoreを置くと、サブパッケージ固有の生成ファイルを除外しきれないことがあります。そういう時はCursorの設定で「Hierarchical Cursor Ignore」をオンにすると、親ディレクトリの.cursorignoreを子が自動で継承するんですよ。

室谷代表取締役

うちでも、フロントエンドとバックエンドで無視すべきファイルが違うので、ルートに共通のパターン、各ディレクトリに個別の.cursorignoreを置くようにしてます。これでインデックス対象が半分以下になりました。

テキトー教師.AI認定講師

ただ、この設定はCursor 3.11より前だとFeatures > Editorにありましたが、最新版ではIndexing > Ignore Filesに移動してるので、場所がわからずハマる人もいるようです。

階層的な.cursorignoreの活用

テキトー教師.AI認定講師

階層ignoreを使うと、親でnode_modulesを無視しつつ、子で特定の生成ファイルだけ無視を解除する、みたいな細かい制御ができるんです。ただし、否定パターン（!）の制限には注意が必要で、親ディレクトリを*で全部除外した子は再includeできません。

室谷代表取締役

その制限は.gitignoreと同じですね。どこで線を引くかが設計のポイントです。

あと、全プロジェクト共通で.envなどを無視したい場合は、VS Code設定の「Global Cursor Ignore List」にパターンを追加する方が現実的です。

テキトー教師.AI認定講師

グローバルignoreはデフォルトでは空なので、自分で/.envや/*.pemを追加しておくと、プロジェクトごとに書かずに済みます。ただし、ターミナル経由だとこの制限をすり抜けられるので、そこはAgentツールの設定でAsk Every Timeをオンにするなど対策が必要です。

室谷代表取締役

結局、パフォーマンス最適化の鍵は「何を無視するか」より「どう運用するか」です。最初から完璧を目指さず、プロジェクトの成長に合わせて.cursorignoreを育てていくのが現実的な戦略だと思います。

セキュリティ強化：.cursorignoreで守るべき機密ファイル

環境変数ファイル以外に注意すべきもの

室谷代表取締役

.env は当然として、実際に守るべきはもっと多いんですよね。USのスタートアップだと .env.staging や .env.production もまとめて弾いてます。

テキトー教師.AI認定講師

たしかに。.env だけ書いて満足してる人、結構見かけます。

でも .env.local とか .env.* のパターンでまとめて指定しないと漏れるリスクがあります。

室谷代表取締役

あと credentials.json や secrets.json も。GCPやAWSのクレデンシャルがバレたら洒落にならない。

テキトー教師.AI認定講師

そうそう。そこはグローバルな ignore リストで共通設定しておくと安全です。

キーファイルや証明書

テキトー教師.AI認定講師

次に気になるのが鍵ファイルですね。*.pem, *.key, id_rsa あたりは .cursorignore に追加しておいた方がいい。

室谷代表取締役

証明書も *.cert, *.p12 は必須。ROIで考えると、一度設定すればずっと守られるんでコスパいいです。

テキトー教師.AI認定講師

現場でよく聞くのは「鍵ファイルを.gitignoreに入れてたから安心」って声。でも .gitignore は Cursor のAI機能には効かないんですよ。

.cursorignore に書かないと意味がない。

室谷代表取締役

その点は知っておかないと痛い目見ますね。MYUUUでも最初は .gitignore だけで済ませてたけど、すぐに .cursorignore に移行しました。

個人設定ファイル（.localなど）

テキトー教師.AI認定講師

もう一つ盲点なのが .zshrc.local や .gitconfig.local みたいな個人設定ファイル。中にAPIキーとか書いてあることが多い。

室谷代表取締役

そう。.local サフィックスはマシン固有の設定の定番パターン。

**/*.local で一括 ignore するのが手っ取り早い。

テキトー教師.AI認定講師

ただ .env.local はデフォルトで無視されるけど、そうでない.localファイルは自分で指定が必要。グローバル設定に追加しておくといいですよ。

室谷代表取締役

わかってますね。VS Codeの設定から Global Cursor Ignore List に **/*.local を追加すれば、プロジェクトごとに書かなくて済む。

セキュリティの限界と補完策

テキトー教師.AI認定講師

ここまで聞くと .cursorignore に全部書けば完璧に思えますけど、実際はそうじゃないんです。

室谷代表取締役

そう。公式ドキュメントにも書いてありますが、ターミナル経由のコマンドは .cursorignore をすり抜けます。

Agentが cat .env を実行できちゃう。

テキトー教師.AI認定講師

そこが一番怖いところですね。いくら .cursorignore でブロックしても、Agentがシェル経由で読み取るのを止められない。

室谷代表取締役

だからこそ、Agentのターミナル実行に「毎回確認」をかける設定と併用するのが現実解。承認必須にしておけば、少なくともユーザーが目視で止められます。

よくある質問

Q1. .cursorignore で正規表現は使えますか？

テキトー教師.AI認定講師

使えないんですよ。.gitignore と同様にグロブパターンだけです。

初めて触る人は「*.log」とかで指定するんだな、と覚えてください。

室谷代表取締役

そう。ただ、** でディレクトリ階層をまたげるので、実務ではそれで十分なケースが多いです。

Q2. ファイル単位で無視を解除（否定）できますか？

テキトー教師.AI認定講師

できます。先頭に「!」を付けるとそのパターンを無視しなくなります。

たとえば「!important.log」と書けば、それだけは処理対象に戻る、と。

室谷代表取締役

ただし否定のワイルドカードの効き方に癖があるので、一度テストしてみることをおすすめします。

Q3. .cursorignore はチームで共有すべき？個人の設定でいい？

室谷代表取締役

チームでプロジェクトのルートに置けば自動で共有されます。個人の隠しファイルとして使いたいならグローバル設定もできますが、私はリポジトリに含めるのが安全だと思います。

テキトー教師.AI認定講師

そうですね。チーム全員が同じ除外設定を持てるので、node_modules のような巨大ファイルを全員がスキップできます。

Q4. .cursorignore と cursor の設定画面（settings.json）の違いは？

テキトー教師.AI認定講師

設定画面では「Files: Exclude」という項目があって、エクスプローラーの表示を隠せます。.cursorignore は Cursor の AI 機能が読み取るファイルを制限します。

つまり、見えなくするか、AI に渡さないかの違いです。

室谷代表取締役

両方設定しておくと、セキュリティとパフォーマンスの両面で効果的です。MYUUU の現場では両方やっています。

Q5. プロジェクトが大きくなると .cursorignore の記述が増えて管理が大変です。何か良い方法は？

テキトー教師.AI認定講師

.gitignore をベースにして、そこに追記する形が楽です。.gitignore をコピーして、さらに必要なら足す。

重複しても問題ないので、まずは .gitignore の中身をそのまま流用するのが現実的です。

室谷代表取締役

海外のスタートアップでは、**/build, **/dist のようにテンプレート化して、プロジェクトの初期化時に自動生成する仕組みを入れてますね。