Elixir Phoenix Guide for Claude Code

Version: 1.3.0 | Changelog

An essential development guide for Claude Code that ensures idiomatic Elixir and Phoenix LiveView code. This plugin includes enforced skills, hooks, and agent documentation that actively guide and validate your Elixir development workflow.

v1.3.0 Released! New testing-essentials skill added — proactive testing guidance for all _test.exs files. All existing skills now point to it. See CHANGELOG.md for details.

What's Included

Skills (5 essential files)

Consolidated domain expertise with enforced patterns:

• elixir-essentials - Core Elixir patterns: pattern matching, pipes, with statements, error handling
• phoenix-liveview-essentials - Complete LiveView guide: lifecycle, events, rendering phases, state management
• ecto-essentials - Database operations: schemas, changesets, queries, migrations, associations
• phoenix-uploads - File uploads and static file serving workflow
• testing-essentials - Testing patterns: DataCase/ConnCase setup, fixtures, LiveView tests, TDD workflow

Each skill includes a RULES section with 7-8 non-negotiable patterns that must be followed.

Note on auto_suggest metadata: Skills include auto_suggest: true and file_patterns metadata for future Claude Code enhancements. These fields are not currently active in the Claude Code runtime but are included for forward compatibility.

Hooks (10 shell commands in settings.json)

Active enforcement rules that catch anti-patterns in real-time:

Blocking (exit 2 - prevents action):

• missing-impl - Blocks callbacks without @impl true
• hardcoded-paths - Blocks hardcoded file paths
• hardcoded-sizes - Blocks hardcoded file size limits
• static-paths-validator - Blocks file references not in static_paths()
• deprecated-components - Blocks deprecated Phoenix components (.flash_group, form_for, live_redirect) 1 Warnings (exit 1 - shows warning, allows action):
• nested-if-else - Warns about nested if/else, suggests pattern matching
• inefficient-enum - Warns about multiple Enum operations
• string-concatenation - Warns about string concatenation in loops
• auto-upload-warning - Warns when auto_upload: true is detected

Agent Documentation (4 files)

Detailed reference material for complex tasks:

• project-structure.md - Directory layout and context boundaries
• liveview-checklist.md - Step-by-step LiveView development checklist
• ecto-conventions.md - Comprehensive Ecto patterns and best practices
• testing-guide.md - Testing patterns for contexts, LiveViews, and schemas

Project Template

• CLAUDE.md.template - Project-specific instructions template

Installation

Note: Official marketplace publication is in progress. Once available, installation will be even simpler through the official Claude Code marketplace.

Installing for the First Time

In a Claude Code session, use the interactive plugin manager:

# Step 1: Add the marketplace (first time only)
/plugin marketplace add j-morgan6/elixir-phoenix-guide

# Step 2: Open the interactive plugin manager
/plugin

# This opens an interactive menu where you can:
# - Select the elixir-phoenix-guide marketplace
# - Install the elixir-phoenix-guide plugin
# - Choose scope (user = all projects, project = current only)
# - Verify you have version 1.3.0 or higher

Updating to Latest Version

If you already have the plugin installed:

# Open the interactive plugin manager
/plugin

# Select "Marketplaces" → "elixir-phoenix-guide" → "Update"
# Then update the plugin from the menu
# Verify version shows 1.3.0 or higher

Latest Updates (v1.3.0):

• New testing-essentials skill for all _test.exs files
• All 4 existing skills now point to testing-essentials for test files
• testing-guide.md refactored as a deep reference companion to the skill

See CHANGELOG.md for full release notes and version history.

Usage

Once installed, Claude Code will automatically:

1. Load skills based on code context - providing intelligent suggestions for Elixir patterns
2. Enforce hooks in real-time - catching anti-patterns as you write code
3. Reference agent docs when needed - accessing detailed information for complex tasks
4. Follow CLAUDE.md (if present) - respecting project-specific conventions

Example Interactions

Before (without optimization):

def process(user) do
  if user.status == :active do
    if user.role == :admin do
      :allowed
    else
      :denied
    end
  else
    :inactive
  end
end

After (with hooks and skills):

• Hook warns about nested if/else
• Skill suggests pattern matching
• Claude generates:

def process(%{status: :active, role: :admin}), do: :allowed
def process(%{status: :active}), do: :denied
def process(_), do: :inactive

Testing the Setup

1. Open a Phoenix/Elixir project in Claude Code
2. Ask Claude to create a LiveView
3. Observe:
   • Skills guide idiomatic implementation
   • Hooks catch anti-patterns (missing @impl, hardcoded values)
   • Agent docs provide detailed checklists

What This Optimizes

Code Quality

• Blocks callbacks without @impl true (prevents compilation)
• Blocks hardcoded file paths and sizes (prevents runtime issues)
• Warns about nested if/else (suggests pattern matching)
• Warns about inefficient Enum chains (suggests for comprehensions)
• Warns about string concatenation in loops (suggests IO lists)

Developer Experience

• Proactive guidance on Elixir idioms
• Real-time feedback on code quality
• Detailed checklists for complex features
• Consistent conventions across projects
• Reduced iterations and corrections

Learning

• Clear explanations of "why" not just "what"
• Links to relevant patterns and best practices
• Progressive disclosure of complexity
• Examples of idiomatic vs non-idiomatic code

Why This Exists

This plugin was created to ensure Claude Code consistently produces idiomatic Elixir and Phoenix code by making best practices impossible to ignore, not just available. It combines enforced patterns, real-time validation, and comprehensive guidance for all Elixir development work.

Project-Specific Setup

For project-specific instructions, you can create a CLAUDE.md file in your project root with:

• Your app name and description
• Project-specific contexts
• Custom commands and workflows
• Team conventions

This file will be automatically loaded by Claude Code when working in your project.

File Structure

elixir-phoenix-guide/
├── README.md                          # This file
├── skills/                            # Elixir expertise (5 essential skills)
│   ├── elixir-essentials/SKILL.md
│   ├── phoenix-liveview-essentials/SKILL.md
│   ├── ecto-essentials/SKILL.md
│   ├── phoenix-uploads/SKILL.md
│   └── testing-essentials/SKILL.md
├── hooks-settings.json                # Hook configuration
└── agents/                            # Reference documentation
    ├── project-structure.md
    ├── liveview-checklist.md
    ├── ecto-conventions.md
    └── testing-guide.md

Requirements

• Claude Code CLI installed
• Elixir 1.15+ projects
• Phoenix 1.7+ (for LiveView features)

Customization

After installation via the plugin manager, all configuration files are installed to ~/.claude/:

• Skills: ~/.claude/skills/
• Hooks: ~/.claude/settings.json
• Agent docs: ~/.claude/agents/

You can customize these files directly. Changes take effect after restarting Claude Code.

Adding Custom Skills

Create new directories with SKILL.md files in ~/.claude/skills/

Modifying Existing Rules

Edit any skill or hook file - changes take effect on next Claude Code restart

Checking Your Version

In a Claude Code session:

/plugin

# Or check version in the plugin list
# Navigate to your installed plugins and verify version 1.3.0 or higher

Uninstall

In a Claude Code session:

/plugin

# Navigate to installed plugins
# Select elixir-phoenix-guide and choose "Uninstall"

Contributing

Contributions welcome! Areas for improvement:

• Additional Elixir patterns and anti-patterns
• More Phoenix-specific hooks
• OTP and GenServer guidance
• Testing patterns and best practices
• Real-world examples and case studies

License

MIT

Acknowledgments

Inspired by the Optimizing Claude Code article by Steven Mays.

Related Resources

• Claude Code Documentation
• Elixir Style Guide
• Phoenix Framework
• Credo (Static Analysis)

---

Note: This configuration applies globally to all Elixir projects. For project-specific customizations, use the CLAUDE.md.template in your project root.