[FEATURE] Allow project-level rules to override user-level rules
Problem Statement
Currently, user-level rules (~/.claude/rules/) and project-level rules (.claude/rules/) are additive — both are loaded and combined in context. There's no mechanism for a project to say "ignore the global rule about X".
This creates friction when working on external repositories or projects with different conventions. For example:
- My global rules specify behavioural expectations like "always run tests before committing" or "ensure test coverage for new features"
- When contributing to an external repo with broken, outdated, or non-existent tests, those global instructions actively hinder progress
- Path frontmatter doesn't help here — these are process rules, not language-specific tooling rules
The workaround of structuring rules to be minimal at user-level defeats the purpose of having sensible global defaults.
Proposed Solution
Allow project-level rule files to explicitly override or disable specific user-level rules. Two possible approaches:
- Override by filename convention: If a project rule has the same filename as a user rule (e.g., both have
testing-workflow.md), the project version takes precedence rather than both being loaded.
- Explicit override frontmatter: Add frontmatter syntax to project rules:
``yaml`
---
overrides: "~/.claude/rules/testing-workflow.md"
---
`
Or to disable without replacement:
yaml``
---
disables: ["testing-workflow.md", "coding-standards.md"]
---
Option 1 is simpler and follows the principle of least surprise. Option 2 is more explicit but more verbose.
Alternative Solutions
Current workarounds considered:
- Path exclusions in user rules — Doesn't apply; these are behavioural rules, not path-specific tooling
- Minimal user rules — Defeats the purpose of having sensible global defaults
- Manual override convention — Adding "if project contradicts, follow project" to global rules; relies on LLM interpretation rather than system behaviour
Priority
Medium - Impacting my workflow
Feature Category
Configuration/Settings
Use Case Example
- I have
~/.claude/rules/testing-workflow.mdwith instructions like:
- "Always run the full test suite before committing"
- "Ensure new features have corresponding test coverage"
- "Don't commit if tests are failing"
- I clone an external repository to contribute a bug fix
- That project has a broken test suite (common in older OSS projects) — tests fail due to outdated dependencies, missing fixtures, or flaky CI
- My global workflow rules now actively block progress: Claude keeps trying to run tests, they fail, and it refuses to commit the fix
- I create
.claude/rules/testing-workflow.mdin the external project stating "Tests are known-broken; commit working code without running the test suite" - Current behaviour: Both rule files load; Claude receives contradictory instructions ("always run tests" vs "don't run tests") and must interpret which takes precedence
- Desired behaviour: Project-level
testing-workflow.mdoverrides user-leveltesting-workflow.md; Claude follows the project-specific guidance unambiguously
This isn't about different tooling for different languages — path matching handles that. This is about behavioural/process rules that should apply globally by default but need explicit exemption for specific projects.
Additional Context
This follows a common pattern in configuration systems (e.g., .gitconfig with include.path, ESLint's overrides, VS Code's workspace vs user settings). The expectation that more-specific config can override less-specific config is well-established.
This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗