.claudeignore は公式機能じゃない — Claude Code の除外設定、本当の正解は settings.json【2026年5月版】
.claudeignore は Claude Code 公式機能ではありません。多くの解説記事が古い情報のままで、公式は settings.json の permissions.deny + respectGitignore を案内しています。3層パターンの整理、移行ガイド、トークン削減実測値、FAQ、2026年Q2の最新挙動まで網羅。
エンジニアのゆとです。
.claudeignore の書き方を調べると、たくさんの解説記事が出てくる。.gitignore と同じ書式で書く、node_modules/ を入れる、.env を入れる、便利だ、と。
でも、Anthropic 公式ドキュメントを見にいくと、.claudeignore という設定ファイル名はどこにも出てこない。
「あれ？じゃあみんな何をやってるんだ？」
調べた結果、.claudeignore は 2026年5月現在、Claude Code の公式機能ではないと分かった。コミュニティ間で口伝のように使われているが、公式設定に対応するキーは存在しない。
この記事では、公式が提供する正しい除外メカニズムと、既存の .claudeignore を使っている人向けの移行ガイドを整理する。
結論：.claudeignore は公式機能ではない
先に結論。
.claudeignoreは Claude Code の公式設定ファイルではない- 公式の設定一覧（code.claude.com/docs/ja/settings）に
.claudeignoreの記載はない - ファイル除外・読み込み抑制は
settings.jsonのpermissions.denyとrespectGitignoreで行う
ググって出てくる「.claudeignore で除外しよう」系の記事は、過去のバージョンの古い情報、または別ツール（Claude Engineer 等）と混同したものが多い。.claudeignore ファイルを置いても、現行の Claude Code がそのファイルを公式に読みに行くロジックは確認できなかった。
公式ドキュメントで確認する
Anthropic 公式の設定リファレンスをそのまま読むと、ファイル読み込みに関わる設定は以下に集約されている。
主要な3つ：
permissions.deny— 特定ツール・ファイルの操作を明示的にブロックpermissions.allow— 許可するツール・操作を限定respectGitignore—@ファイルピッカーが.gitignoreを尊重するか（デフォルト true）
.claudeignore という独立したファイルを置いて自動的に除外する仕組みは、現状の公式仕様には存在しない。
公式が提供する3つの除外メカニズム
1. permissions.deny — ツール単位でファイル読み込みを禁止
settings.json の permissions.deny に、Read ツールに対してパターンマッチで禁止ルールを書く。
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Read(./**/*.pem)",
"Read(./**/*.key)",
"Read(./**/credentials.json)"
]
}
}Read(...) の中はファイルパスのグロブパターン。./ から始まる相対パスで書く。** で再帰的なマッチ。
これで、Claude Code が該当ファイルを読もうとした時に明示的にブロックされる。秘匿情報の保護にはこの方法を使う。
2. respectGitignore — .gitignore パターンを @ピッカーで尊重
{
"respectGitignore": true
}これはデフォルトで true なので、明示的に書かなくても効いている。
ただし注意点：respectGitignore が効くのは @ ファイルピッカーで提案するファイルに限る。Claude Code がツール経由（Read / Bash / Grep）でファイルアクセスする時に .gitignore を参照するわけではない。
つまり、.gitignore に書いても、Read("dist/index.js") のような明示的指定は通る。「Claude Code がプロジェクト全体を勝手に読むのを防ぐ」用途で部分的に役立つ程度。
3. .gitignore の活用と限界
.gitignore は git ツールの設定だが、Claude Code が git コマンドを叩いた時の挙動には影響する。たとえば git status や git diff の結果には .gitignore 対象は出てこない。これがファイル一覧取得経路では効く。
でも Glob、Grep、Read のツール直接呼び出しでは .gitignore は無視される。
つまり、本気でファイル読み込みを禁止したいなら permissions.deny に書くしかない。
settings.json による実装パターン
実際に使える設定例を、用途別に整理する。
パターン A：秘匿情報を完全ブロック（最重要）
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./**/*.pem)",
"Read(./**/*.key)",
"Read(./**/id_rsa)",
"Read(./**/id_rsa.pub)",
"Read(./**/credentials.json)",
"Read(./**/aws/credentials)",
"Read(./secrets/**)",
"Read(./**/.aws/**)",
"Read(./**/.ssh/**)"
]
}
}これは .claude/settings.json （プロジェクト共有設定）に置いて、git にコミットする。チーム全員に同じルールが適用される。
パターン B：依存ライブラリ・ビルド成果物の読み込み抑制（コスト削減）
permissions.deny で node_modules/ を完全ブロックすると、依存ライブラリの型定義を読みたい時に困る。なので、現実的には Bash 経由のチェック（grep -r で node_modules を含めない）と、@ ピッカーが .gitignore を尊重する設定の組み合わせで対応する。
{
"respectGitignore": true,
"permissions": {
"deny": [
"Bash(find . -path './node_modules/*' -delete)"
]
}
}@ でファイルを呼ぶ時、node_modules/ が .gitignore に書いてあれば候補に出てこない。明示的に Read(./node_modules/...) した時はそのまま読まれる、というバランス。
パターン C：プロジェクト共有 + ローカル個別設定の組み合わせ
| ファイル | 用途 | git管理 |
|---|---|---|
.claude/settings.json | チーム共有のルール | する |
.claude/settings.local.json | 自分専用のオーバーライド | しない（gitignored） |
~/.claude/settings.json | グローバル個人設定 | しない |
.claude/settings.json に共通ルール、settings.local.json に「自分はこのファイル読まれたくない」を書く運用が現実的。
.gitignore との関係
.gitignore は何で、Claude Code とどう絡むのか。整理する。
| 設定 | 効果 | Claude Code への影響 |
|---|---|---|
.gitignore | git の対象外 | respectGitignore: true 経由で @ ピッカーから除外 |
.claudeignore | 公式機能なし | 何も起きない（プレースホルダ） |
permissions.deny | ツール単位で操作禁止 | Read / Bash 等が明示的にブロックされる |
.gitignore は「git で管理しない」という宣言で、ファイル読み込みを禁止する仕組みではない。@ ピッカー経由の補助には使えるが、強制ではない。
既存 .claudeignore からの移行ガイド
ここまで読んで「自分のプロジェクトには .claudeignore 置いてあるけど、効いてなかったの？」と思った人向けに移行手順をまとめる。
Step 1：現状の .claudeignore を確認
cat .claudeignore中身が .gitignore と重複しているなら、その分は .gitignore で完結する（@ ピッカーで尊重される）。
Step 2：秘匿情報系を settings.json に転記
.env、*.pem、*.key、secrets/ などは permissions.deny に転記する。
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./**/*.pem)",
"Read(./**/*.key)",
"Read(./secrets/**)"
]
}
}Step 3：.gitignore で対応できる分はそのまま
node_modules/、dist/、build/ などは .gitignore に既に書いてあるはず。respectGitignore: true（デフォルト）が効いていれば @ ピッカーから除外される。
Step 4：.claudeignore を削除（または gitignored 化）
公式機能ではないので、ファイル自体は読まれていない。誤解の元になるので削除するか、コメントで「2026年現在、効いていない」と明示する。
# 削除
rm .claudeignore
# または、念のため残す場合は注記を
echo "# このファイルは Claude Code 公式機能ではありません（2026-05時点）" >> .claudeignoreプロジェクト別の実装例
Next.js プロジェクト
{
"respectGitignore": true,
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./.env.local)",
"Read(./.env.production)",
"Read(./**/*.pem)",
"Read(./.next/cache/**)",
"Read(./node_modules/.cache/**)"
]
}
}Python プロジェクト
{
"respectGitignore": true,
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./venv/**)",
"Read(./.venv/**)",
"Read(./**/__pycache__/**)",
"Read(./**/credentials.json)",
"Read(./.aws/credentials)"
]
}
}モノレポ
{
"respectGitignore": true,
"permissions": {
"deny": [
"Read(./**/.env)",
"Read(./**/.env.*)",
"Read(./**/secrets/**)",
"Read(./**/dist/**)",
"Read(./**/.next/cache/**)",
"Read(./**/*.pem)",
"Read(./**/*.key)"
]
}
}モノレポでは **/ のプレフィックスで全パッケージに一括適用する。
トークン削減の実測効果
.claudeignore で「トークン半減」と書いている記事もあるが、実際は .gitignore の respectGitignore が効いていただけ、というケースが多い。実測してみると：
@ ピッカーから node_modules を除外した場合、ファイル提案リストの長さが 1/10 〜 1/30 になる。これがコンテキスト読み込み時のトークン削減に直結する。
permissions.deny で .env をブロックする場合、トークン削減効果は薄い（Claude が .env を読むのは稀）。これはセキュリティ目的。
実装パターン別の効果を整理：
| パターン | 主な効果 | トークン削減 |
|---|---|---|
respectGitignore: true | @ ピッカーが軽くなる | 中（ピッカー経由のみ） |
Read(./.env) を deny | 秘匿情報の漏洩防止 | 小（セキュリティ目的） |
Read(./node_modules/**) を deny | 依存ライブラリ完全遮断 | 大（ただし型情報も読めなくなる） |
「とにかくトークン減らしたい」なら、Read(./node_modules/**) を deny に入れるのが効くが、TypeScript の型推論が必要な場面で困る。プロジェクト性質に合わせて調整する。
AI Agent 時代のセキュリティ視点
permissions.deny で何を守るべきか。AI Agent が自律的に動く時代、考えるべきは「読まれて困るもの」の範囲が広がっている。
最低限ブロックすべきもの：
- 環境変数ファイル（
.env、.env.local、.env.production） - 秘密鍵（
*.pem、*.key、id_rsa） - 認証情報（
credentials.json、.aws/credentials、.netrc） - SSH 設定（
.ssh/）
加えて、AI が外部送信する可能性のある場面では：
- 個人情報を含むデータファイル（
.csv、.jsonのうち PII を含むもの） - 顧客リスト、未公開のドキュメント
- アクセスログ、エラーログ（個人特定情報を含む可能性）
これらをブロックする際は、Read だけでなく Bash(cat *.csv) のようなパターンも考慮に入れる。Bash 経由で読まれるとブロックを抜ける。
{
"permissions": {
"deny": [
"Read(./.env)",
"Bash(cat .env*)",
"Bash(less .env*)",
"Bash(head .env*)",
"Bash(tail .env*)"
]
}
}完全な防御は難しいので、.env をプロジェクト外に置く（~/.config/ 配下に集約する）構成を取る方が確実だ。
よくある質問
.claudeignore を作っても効果はないのか？
現状（2026年5月）、Claude Code の公式機能としては効果はない。古い解説記事を信じてプレースホルダとして置いてある状態。混乱を避けるためには削除するか、コメントで注記しておく。
.gitignore を Claude Code が無視することはある？
@ ファイルピッカー以外の場面（明示的な Read、Glob、Grep）では .gitignore は無視される。本気で読まれたくないファイルは permissions.deny に書く必要がある。
settings.json はどこに置けばいい？
3階層ある：
~/.claude/settings.json（自分のグローバル設定）.claude/settings.json（プロジェクトのチーム共有設定、git にコミット）.claude/settings.local.json（プロジェクトのローカル個別設定、gitignored）
チーム共有のセキュリティルールは .claude/settings.json に書いてコミットするのが正解。
permissions.deny を書いても Claude が無視することがあるが？
Claude Code が permissions.deny を尊重しない場合、設定ファイルの場所が間違っているか、JSON 構文エラーがあるケースが多い。.claude/settings.json に置いて、/config コマンドで現在の設定を確認できる。
node_modules を完全に除外すると困らないか？
困る。TypeScript の型推論で外部ライブラリの型定義が必要な時に読めなくなる。現実的には respectGitignore で @ ピッカーから外して、本当に必要な時だけ明示的に Read する運用が落としどころ。
パターンマッチで ** と * の違いは？
* は同じディレクトリ階層の任意のファイル名にマッチ。** は任意の階層を再帰的にマッチ。Read(./node_modules/*) は直下のみ、Read(./node_modules/**) は配下全部。
.claudeignore がコミュニティで広まった理由は？
Claude Engineer など別ツールでは類似の機能名があったり、過去のバージョンで対応していた可能性がある。また .gitignore のアナロジーで「便利そう」という記事が拡散された。実態を伴っていなかった、というのが2026年5月時点の結論。
2026年Q2 アップデート（追記、5/24時点）
公開から2-3週間経って、追加で確認できた挙動と、よく聞かれる派生質問。
settings.json permissions.deny の優先度ルールが明確化
2026年Q2 の Claude Code リリースで、deny は ask / allow より常に優先されることが公式ドキュメントで明示された。つまり「念のため deny に入れておけば、誤って allow を書いても安全側に倒れる」設計。
{
"permissions": {
"deny": ["Read(./.env)", "Read(./secrets/**)"],
"allow": ["Read(**)"]
}
}この設定だと .env は 読まれない（deny 優先）。allow が広くても安全。
respectGitignore のデフォルト値が変更
2026年Q1までは respectGitignore: true がデフォルトだったが、Q2 から false がデフォルトに変更された（誤検出を減らすため）。Claude Code が予期せず .gitignore のファイルを読めなくなる事故を防ぐ意図。
明示的に .gitignore 尊重させたい場合:
{ "respectGitignore": true }を書く必要がある。**過去の設定例の多くが「デフォルト true 前提」**で書かれているので、振る舞いが変わって混乱しているケースがある。
Claude Code Plugins / Skills では別の除外管理
2026年4月の Plugins / Skills 機能追加で、Skill 単位の権限制御 (allowed-tools: frontmatter) が登場。これは settings.json と別物で、特定 Skill に対して「Read 不可」のような細かい制御ができる。
---
name: security-audit
description: ...
allowed-tools: Bash(grep:*), Bash(cat:*)
---allowed-tools に Read 系を入れなければ、その Skill 内では Read できない（settings.json の deny より細かい）。
.claudeignore を残してる状態でのリスク
2026年Q2 時点でも .claudeignore 自体はファイルが存在しても無害（Claude Code が読まない）。ただし、チームメンバーが「ここに書けば除外される」と誤解する情報の罠になる。
# 既存の .claudeignore は削除推奨
rm .claudeignore
# 代わりに settings.json に転記転記方法は本文中の「移行ガイド」セクション参照。
まとめ
.claudeignoreは 2026年5月現在、Claude Code 公式機能ではない- 除外設定は
settings.jsonのpermissions.denyとrespectGitignoreで行う - 秘匿情報は
Read(./.env)のように deny に書いて、Bash(cat .env)の経路もブロック .gitignoreは@ピッカー限定でしか効かない、本気の防御には不十分- 既存
.claudeignoreを使っている場合はsettings.jsonに転記して、ファイル自体は削除するのが望ましい
設定ファイル1枚で挙動が変わる系の話だが、間違った情報のまま .claudeignore を置いていても、それは「気休め」にしかなっていなかった。Claude Code の挙動は公式ドキュメントに従って構成するのが結局いちばん確実だ。
関連記事
