Usage Rules

View Source

Usage rules provide best practices and conventions directly from package authors to improve how Claude Code writes code for your project.

📋 Quick Reference: See the Usage Rules Cheatsheet for a concise reference of configuration options and patterns.

What are Usage Rules?

Usage rules are markdown files containing library-specific guidelines, patterns, and best practices that help AI assistants write better code. When Claude installs in your project, it automatically:

  1. Adds the usage_rules dependency (dev only)
  2. Syncs all available usage rules to your CLAUDE.md file
  3. Makes these rules available to sub-agents

This ensures Claude Code follows the exact patterns and conventions that library authors recommend.

How Claude Uses Usage Rules

Automatic Syncing

When you run mix claude.install, Claude automatically runs:

mix usage_rules.sync CLAUDE.md --all --link-to-folder deps

This command:

  • Gathers usage rules from all dependencies that provide them
  • Creates links to the usage rules files in deps/ instead of inlining content
  • Keeps your root CLAUDE.md file lean and reduces context window usage
  • Ensures Claude Code always has access to current best practices when needed

In Your CLAUDE.md

After installation, your CLAUDE.md will contain links to usage rules instead of full content:

## ash usage
_A declarative, extensible framework for building Elixir applications._

[ash usage rules](deps/ash/usage-rules.md)

## phoenix usage
_Productive. Reliable. Fast._

[phoenix usage rules](deps/phoenix/usage-rules.md)

## usage_rules usage
_A dev tool for Elixir projects to gather LLM usage rules from dependencies_

[usage_rules usage rules](deps/usage_rules/usage-rules.md)

This keeps the root CLAUDE.md file lean while Claude Code can still access the full usage rules when needed. For core Elixir rules and critical guidelines that are frequently referenced, some packages may still be inlined.

Nested Memories

Claude supports distributing CLAUDE.md files across different directories in your project for context-specific guidance:

%{
  nested_memories: %{
    "lib/my_app_web" => ["phoenix", "ash_phoenix"],
    "lib/my_app/accounts" => ["ash"]
  }
}

This creates separate CLAUDE.md files in each directory with the relevant usage rules inlined for focused context:

  • lib/my_app_web/CLAUDE.md - Phoenix and Ash Phoenix integration rules for web code (inlined)
  • lib/my_app/accounts/CLAUDE.md - Ash framework rules for business logic (inlined)

Benefits of nested memories:

  • Context-aware guidance - Different rules for different parts of your codebase
  • Inlined for focus - Nested memory files have rules inlined since they're context-specific
  • Reduced noise - Claude only sees relevant rules for the current context
  • Better organization - Keep domain-specific guidance with the code

Usage Rules in Sub-Agents

Sub-agents can include specific usage rules to ensure they follow library best practices:

%{
  subagents: [
    %{
      name: "Code Generation Expert",
      description: "Expert in code generation and project setup",
      prompt: "You are a code generation expert...",
      tools: [:read, :write, :edit],
      usage_rules: [:igniter, :usage_rules_elixir]
    }
  ]
}

Available Usage Rules

Common usage rules that can be included:

  • :usage_rules_elixir - Elixir language best practices
  • :usage_rules_otp - OTP patterns and conventions
  • Package-specific - Any package that provides usage rules (:igniter, or others when available)

Loading Patterns

Usage rules can be loaded in different ways:

  • :package_name - Loads the main usage rules file (deps/package_name/usage-rules.md)
  • "package_name:all" - Loads all usage rules from a package (deps/package_name/usage-rules/)
  • "package_name:specific_rule" - Loads a specific rule file (deps/package_name/usage-rules/specific_rule.md)

Benefits

  1. Consistency - Claude follows the same patterns throughout your codebase
  2. Best Practices - Automatically uses library author recommendations
  3. Fewer Errors - Avoids common mistakes and anti-patterns
  4. Better Integration - Code that works well with your dependencies
  5. Learning - Usage rules document patterns for your team too

Learn more at hexdocs.pm/usage_rules.

Examples

Current Project

This Claude project includes these usage rules which you can see in the CLAUDE.md file.

When More Packages Add Usage Rules

As packages add usage rules, they'll automatically be available. For example:

  • If Phoenix adds usage rules, you could use :phoenix
  • If Ecto adds usage rules, you could use :ecto
  • If Ash adds usage rules, you could use :ash

The usage_rules package ecosystem is growing, and more packages are adding rules over time.

Troubleshooting

Usage rules not appearing in CLAUDE.md?

  • Check that usage_rules is in your dependencies
  • Run mix claude.install
  • Verify packages have usage-rules.md or usage-rules/ directory

Sub-agent not following usage rules?

  • Verify the rules are listed in the sub-agent's usage_rules field
  • Check that the package name matches exactly
  • Run mix claude.install to regenerate sub-agents

Need help?

Learn More