claudeignore を設定せずに、node_modules・dist・.env をそのまま読ませていませんか？不要ファイルを除外するだけで、コンテキスト消費と回答ノイズを同時に減らせます。実際の削減幅は構成次第ですが、サンプル検証では 20〜40% 程度の軽量化が狙えます。
この記事では、.claudeignore の書き方を起点に、プロジェクト別テンプレート、.gitignore との使い分け、よくある失敗までを一気に整理します。※本記事は 2026年3月3日（JST）時点で確認した情報をベースにしています。現行仕様は更新される可能性があるため、最終確認は公式ドキュメントを参照してください（Claude Code settings）。
.claudeignoreとは？なぜ必要なのか
.claudeignore は、AIに読み込ませる必要がないファイルを除外するための設定ファイルです。特に巨大な依存ディレクトリや生成物を除外すると、次の効果が出やすくなります。
- 不要な文脈が減り、指示に対する回答の焦点が合いやすい
- セッションのコンテキスト枠を本当に必要なコードへ使える
- 機密情報を含むファイルを読み取り対象から外しやすい
なお、環境によっては .claudeignore ではなく、.claude/settings.json の permissions.deny が優先される運用もあります。後半で併用パターンを解説します。
.claudeignoreの基本的な書き方（.gitignore形式）
基本は .gitignore に近いパターン指定です。まずは次の最小セットから始めると安全です。
node_modules/
dist/
build/
coverage/
.env
*.log
.DS_Storeパターン指定のルール
node_modules/: ディレクトリ単位で除外*.log: 拡張子で一括除外.env: 機密情報を含む単一ファイルを除外
最初に入れるべき最小セット
最初から大量に除外すると必要ファイルまで読まれなくなるため、node_modules・生成物・ログ・機密ファイルの4系統から始めるのが実務では安定します。
除外すべきファイル・ディレクトリの具体例
| 対象 | 代表パターン | 除外理由 |
|---|---|---|
| 依存ライブラリ | node_modules/, .venv/ | 容量が大きく、解析価値が低い |
| ビルド成果物 | dist/, build/, out/ | 生成物は再現可能でノイズになりやすい |
| テスト生成物 | coverage/, *.lcov | 要約指示時に不要情報を増やす |
| ログ・キャッシュ | *.log, .cache/ | 時系列ノイズで回答精度を下げやすい |
| 機密ファイル | .env, *.pem | 漏えいリスク低減 |
除外方針を決めるときは、先に1-11「コンテキスト管理術」の「必要ファイルだけ読む」原則を合わせて確認しておくと、運用がぶれません。
プロジェクト種別ごとのテンプレート（React/Python/WordPress等）
ここではそのまま貼り付けて使えるテンプレートを示します。必要に応じて追加してください。
React / Next.js
node_modules/
.next/
out/
dist/
coverage/
*.log
.env*Python
.venv/
__pycache__/
.pytest_cache/
.mypy_cache/
htmlcov/
*.pyc
.env*WordPress（テーマ/プラグイン開発）
wp-content/cache/
wp-content/uploads/
node_modules/
dist/
vendor/
*.log
.envプロジェクトルールを文書化するときは、2-1「CLAUDE.md書き方ガイド」で「何を読む/読まないか」を明示しておくと、チーム運用時の再現性が上がります。
.claudeignore設定前後のコンテキスト消費量を比較
削減率はリポジトリ構成で変わるため、次の3指標で比較するのが実務向きです。
- 読み取り対象ファイル数
- 読み取り対象の総サイズ
- 同じ依頼文での応答の一貫性（主観評価で可）
| 指標 | 設定前 | 設定後 | 差分 |
|---|---|---|---|
| 対象ファイル数 | 5,420 | 3,180 | -41.3% |
| 対象サイズ | 1.8GB | 1.1GB | -38.9% |
| 回答の手戻り | 多い | 少ない | 改善 |
上記はサンプル構成での比較例です。実運用では、同一プロンプトで3回程度試し、差分を見てから除外ルールを固定してください。
.gitignoreとの違いと併用のコツ
.gitignore は Git 追跡対象を制御する設定、.claudeignore（または同等設定）は AI の読み取り対象を制御する設定です。目的が違うため、同じ内容に見えても分けて管理する方が安全です。
| 項目 | .gitignore | .claudeignore / permissions.deny |
|---|---|---|
| 主目的 | コミット対象の制御 | AI読み取り対象の制御 |
| 影響範囲 | Git運用 | AIセッション品質と安全性 |
| 設計のコツ | 差分管理を優先 | 文脈最適化と機密保護を優先 |
現行環境で .claudeignore が効かない場合は、.claude/settings.json に移すと安定します。
{
"permissions": {
"deny": [
"Read(node_modules/**)",
"Read(dist/**)",
"Read(.env)",
"Read(coverage/**)"
]
}
}複数ブランチを同時に扱う場合は、除外設定の同期漏れが起こりやすくなります。実務では2-12「worktreeで並列開発」の手順と一緒に管理すると事故を減らせます。
よくある設定ミスとトラブルシューティング
除外したはずのファイルをまだ読む
- パターンが浅い（例:
node_modules/だけでネストを取りこぼす） - 設定ファイルの場所が違う
- セッション再開時に古い文脈が残っている
対処: パターンを見直し、設定保存後にセッションを切り替えて再評価します。
除外しすぎて必要ファイルまで読まれない
src/など実コードまで除外してしまう- ワイルドカード指定が広すぎる
対処: まず機密・生成物だけを除外し、最小構成に戻してから段階的に追加します。
最後に、設定後は「同じ依頼文で回答の安定度が上がったか」を必ず確認してください。導入の次ステップとして、コンテキスト設計の全体像は1-11「コンテキスト管理術」、運用ルールの文書化は2-1「CLAUDE.md書き方ガイド」を続けて読むと定着しやすくなります。
コメント