RFC: Add support for path-scoped agent rules (`.claude/rules`)

[headinbeds]

Code of Conduct

• I agree to follow this project's Code of Conduct

AI Policy

• I agree to follow this project's AI Policy, or I agree that AI was not used while creating this issue.

Is your feature request related to a problem? Please describe.

Today all selected rules load every session, whether or not they are relevant. That costs more than tokens: when I edit a LiveView template, having Ecto, JSON:API, and migration rules in context dilutes the model's attention and spends budget on code I am not touching. It gets worse the more dependencies a project has. Path-scoping shows each rule only when it matters: the .heex rule appears when I open a .heex file. It beats link:, which removes the bloat but also removes the rule.

Describe the solution you'd like

Add a usage_rules output target that writes path-scoped rule files: rules an agent loads only when it touches matching files, not on every session. The first format is Claude Code's .claude/rules/*.md (a paths: glob in frontmatter, loaded lazily on matching files). Cursor has the same idea with globs:

List which sub-rules to scope and to what paths. General rules stay always-on in AGENTS.md; only topical sub-rules get scoped.

rules: [
  {"phoenix:html", paths: ["lib/**/*.heex"]}
]

Globs match the project's own layout, so the project is the source of truth (a package could ship a coarse default). Syntax and naming are left open for you.

Describe alternatives you've considered

No response

Additional context

Questions

1. Does this fit the scope of usage_rules, or is runtime-loading out of bounds for a sync tool?
2. Model "scope" tool-neutrally (also emit Cursor globs:), or Claude-only to start?
3. Glob defaults consumer-only, or allow coarse package defaults too?

[zachdaniel]

🤔 I can't think of a way for us to actually make this happen. The only thing would be supporting scoped CLAUDE.md/AGENTS.md files per usage_rules file. But usage_rules itself doesn't decide when they are loaded etc. We just are copying text from one file to another.

Have you looked into the skills building options in this library? That can allow you to build skills out of dependencies usage rules which the agent can call when it needs to.