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 --inline usage_rules:all --link-to-folder deps

This command:

  • Gathers usage rules from all dependencies that provide them
  • Adds them inline to your CLAUDE.md file
  • Creates links to the source files in deps/
  • Ensures Claude Code always has access to current best practices

In Your CLAUDE.md

After installation, your CLAUDE.md will contain sections like:

## 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:elixir usage
# Elixir Core Usage Rules

## Pattern Matching
- Use pattern matching over conditional logic when possible
- Prefer to match on function heads instead of using `if`/`else`
...

Claude Code reads this file at the start of every session, ensuring it follows these guidelines.

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