Usage Rules Cheatsheet

Sync Usage Rules to CLAUDE.md

# Sync all usage rules from dependencies
mix claude.install

# This embeds usage rules between markers in CLAUDE.md
# Rules are pulled from deps/*/usage-rules.md files

In .claude.exs

%{
  subagents: [
    %{
      name: "database-expert",
      description: "For database and Ecto work",
      prompt: "You are a database specialist...",
      # Include specific usage rules
      usage_rules: ["ash", "ash_postgres", "ecto"]
    },
    %{
      name: "phoenix-specialist", 
      description: "For Phoenix web development",
      prompt: "You are a Phoenix expert...",
      # Multiple usage rules
      usage_rules: ["phoenix", "ash_phoenix", "phoenix_live_view"]
    }
  ]
}

Available Usage Rule Keys

# Core Elixir
"usage_rules:elixir"  # Elixir patterns and conventions
"usage_rules:otp"     # OTP/GenServer patterns

# Common packages (if installed)
"ash"                 # Ash framework
"ash_phoenix"         # Ash Phoenix integration  
"ash_postgres"        # PostgreSQL data layer
"igniter"            # Code generation
"ecto"               # Database wrapper
"phoenix"            # Web framework
"phoenix_live_view"  # LiveView

1. Dependencies Provide Rules

deps/
  ash/
    usage-rules.md      # Ash framework rules
  ash_phoenix/
    usage-rules.md      # Phoenix integration rules
  igniter/
    usage-rules.md      # Code generation rules

2. Mix Task Syncs to CLAUDE.md

mix claude.install
# Reads deps/*/usage-rules.md
# Updates CLAUDE.md between markers
# Preserves custom content outside markers

3. Subagents Get Targeted Rules

# Only specified rules are included
usage_rules: ["ash", "ecto"]  

# Rules embedded in agent's system prompt
# Agent sees only relevant framework docs

Distribute CLAUDE.md Files Across Directories

# In .claude.exs
%{
  nested_memories: %{
    "lib/my_app_web" => ["phoenix", "ash_phoenix"],
    "lib/my_app/accounts" => ["ash"]
  }
}

Creates Context-Specific Files

lib/my_app_web/CLAUDE.md      # Phoenix and Ash Phoenix rules
lib/my_app/accounts/CLAUDE.md  # Ash framework rules

Benefits

• Context-aware guidance per directory
• Reduced cognitive load for Claude
• Better organization of domain rules

Auto-Generated Section

<!-- usage-rules-start -->
<!-- usage-rules-header -->
# Usage Rules
**IMPORTANT**: Consult these usage rules...
<!-- usage-rules-header-end -->

<!-- package-start -->
## package usage
[package usage rules](deps/package/usage-rules.md)
<!-- package-end -->

<!-- usage-rules-end -->

Manual Content (Preserved)

# Custom Instructions
Your custom content here...

<!-- usage-rules-start -->
[Auto-generated rules]
<!-- usage-rules-end -->

# More Custom Content
Additional instructions...

Minimal Subagent

%{
  name: "formatter",
  description: "Format and style code",
  prompt: "Focus on code formatting",
  # No usage_rules - gets general Elixir rules only
}

Framework-Specific Agent

%{
  name: "ash-resource-builder",
  description: "Create and modify Ash resources",
  prompt: "You are an Ash framework expert",
  usage_rules: ["ash", "ash_postgres", "ash_phoenix"]
}

Multi-Framework Agent

%{
  name: "full-stack-developer",
  description: "Full-stack Elixir development",  
  prompt: "You handle all aspects of Elixir apps",
  usage_rules: [
    "ash",           # Resources
    "ash_phoenix",   # Web layer
    "ash_postgres",  # Database
    "phoenix",       # Framework
    "ecto",          # Queries
    "igniter"        # Generation
  ]
}

Keep Rules Focused

# ✅ Good: Specific to task
usage_rules: ["phoenix", "phoenix_live_view"]

# ❌ Bad: Everything included  
usage_rules: ["ash", "ecto", "phoenix", "oban", "req", ...]

Match Rules to Agent Purpose

# Testing agent → testing frameworks
usage_rules: ["ex_unit", "mimic", "mox"]

# API agent → HTTP and JSON libs
usage_rules: ["req", "jason", "phoenix"]

# Database agent → data layers
usage_rules: ["ecto", "ash_postgres"]

Update After Adding Dependencies

# After adding new deps
mix deps.get
mix claude.install  # Syncs new usage rules