Exclude Irrelevant CLAUDE.md Files in Monorepos
In a large monorepo, Claude picks up CLAUDE.md files from ancestor directories as it walks up the tree — which means you might get instructions from other teams' packages that have nothing to do with what you're working on. The claudeMdExcludes setting lets you block specific files by path or glob.
Add it to .claude/settings.local.json so the exclusion stays on your machine and doesn't affect teammates:
{
"claudeMdExcludes": [
"**/monorepo/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}
Patterns match against absolute file paths using glob syntax. You can configure claudeMdExcludes at any settings level — user, project, local, or managed policy — and arrays merge across levels.
One important exception: managed policy CLAUDE.md files (deployed by IT at the system level) cannot be excluded. That's intentional — org-wide instructions always apply regardless of individual settings.
A typical monorepo setup might look like this:
{
"claudeMdExcludes": [
"**/packages/legacy-app/CLAUDE.md",
"**/packages/mobile/.claude/rules/**",
"**/packages/infra/CLAUDE.md"
]
}
You can also use this in team project settings to prevent future CLAUDE.md files in certain paths from automatically loading.
Stop other teams' instructions from polluting your Claude Code context in a monorepo.
Log in to leave a comment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.