[FEATURE] Allow project-level rules to override user-level rules

Resolved 💬 6 comments Opened Dec 14, 2025 by Isoceth Closed Mar 14, 2026

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:

  1. 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.
  1. 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

  1. I have ~/.claude/rules/testing-workflow.md with instructions like:
  • "Always run the full test suite before committing"
  • "Ensure new features have corresponding test coverage"
  • "Don't commit if tests are failing"
  1. I clone an external repository to contribute a bug fix
  2. That project has a broken test suite (common in older OSS projects) — tests fail due to outdated dependencies, missing fixtures, or flaky CI
  3. My global workflow rules now actively block progress: Claude keeps trying to run tests, they fail, and it refuses to commit the fix
  4. I create .claude/rules/testing-workflow.md in the external project stating "Tests are known-broken; commit working code without running the test suite"
  5. Current behaviour: Both rule files load; Claude receives contradictory instructions ("always run tests" vs "don't run tests") and must interpret which takes precedence
  6. Desired behaviour: Project-level testing-workflow.md overrides user-level testing-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.

View original on GitHub ↗

This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗