DEV Community

Zac
Zac

Posted on

What to put in .claudeignore (and why most people skip it)

#claudecode #ai #programming #webdev

.claudeignore works like .gitignore. Files listed in it don't get loaded into Claude Code's context. Most projects don't have one.

They should.

Why it matters

Claude Code doesn't know which files are useful for your task. Given a project root, it tries to load the whole thing. Build artifacts, lockfiles, test fixtures, and generated code all compete for context budget alongside the files that actually matter.

On a medium-sized project, that's often 20-30% waste. Here's what I found when I scanned mine:

--- Top files (token hogs) ---
10.4k   package-lock.json
 6.6k   multi-agent-templates.md  (generated, not edited)
 6.3k   agent-prompt-playbook.md  (reference doc)
 4.2k   dist/bundle.js
 3.1k   .next/build-manifest.json
Enter fullscreen mode Exit fullscreen mode

That's 30k tokens that had no reason to be there. Adding three lines to .claudeignore dropped total usage from 82% to around 58% of Cursor's default window.

What to ignore

Lockfiles first — they're huge, machine-generated, and Claude doesn't need them:

package-lock.json
yarn.lock
pnpm-lock.yaml
Gemfile.lock
poetry.lock
composer.lock
Enter fullscreen mode Exit fullscreen mode

Build output next:

dist/
build/
.next/
out/
*.min.js
*.min.css
Enter fullscreen mode Exit fullscreen mode

Then generated files, test fixtures, and snapshots:

*.generated.ts
*.pb.go
__snapshots__/
cypress/fixtures/
Enter fullscreen mode Exit fullscreen mode

Binary assets (Claude can't read them anyway):

*.png
*.jpg
*.pdf
*.mp4
Enter fullscreen mode Exit fullscreen mode

Situational — ignore if you're not actively working on them:

migrations/
vendor/
docs/api-reference/
CHANGELOG.md
Enter fullscreen mode Exit fullscreen mode

What NOT to ignore

.claudeignore is for noise, not for hiding your project from itself. Don't add:

  • Source files you're actively working on
  • Config files (.eslintrc, tsconfig.json) — Claude reads these to understand your conventions
  • CLAUDE.md or AGENTS.md — those are your instructions to Claude
  • Tests for code you're currently changing

Finding your own noise

I wrote a script that scans your project and shows token usage per file, compared to each model's context limit. One run and you know exactly what to add to .claudeignore:

python3 context-scanner.py .
Enter fullscreen mode Exit fullscreen mode

Free, ~60 lines: builtbyzac.com/tools.html

Fifteen minutes with .claudeignore is usually worth it. The files eating your context are almost always files you'd never think to check.

If you want to read more about managing AI agent context, task decomposition, and multi-agent patterns, I put it in a 40-page playbook: payhip.com/b/6rRkT ($29).

Top comments (0)