Elixir Phoenix Guide for Claude Code
Version: 2.3.0 | Changelog
An essential development guide for Claude Code that ensures idiomatic Elixir and Phoenix LiveView code. This plugin includes enforced skills, context-aware hooks, automated code quality analysis, and agent documentation that actively guide and validate your Elixir development workflow.
v2.3.0 Released! Expanded domains — security enforcement hooks, deployment gotchas, Phoenix Channels, telemetry/observability, and JSON API skills. See CHANGELOG.md for details.
What's Included
Skills (19 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
- otp-essentials - OTP patterns: GenServer, Supervisor, Task, Agent, DynamicSupervisor, Registry, ETS
- oban-essentials - Background jobs: workers, queues, idempotency, unique jobs, cron, testing with Oban.Testing
- code-quality - Automated code quality detection: duplication, complexity, unused functions
- phoenix-liveview-auth - LiveView authentication: on_mount, current_scope, import conflicts, session handling
- ecto-changeset-patterns - Advanced changesets: separate per operation, cast_assoc pitfalls, composition
- phoenix-auth-customization - Extending phx.gen.auth: custom fields, migrations, fixture updates
- phoenix-pubsub-patterns - Real-time updates: subscriptions, broadcasting from contexts, topic naming
- phoenix-authorization-patterns - Access control: server-side authz, ownership, policy modules, scoped queries
- ecto-nested-associations - Nested data: cast_assoc, cast_embed, Ecto.Multi, cascades, FK indexes
- security-essentials - Security enforcement: atom exhaustion, SQL injection, XSS, open redirects, timing attacks
- deployment-gotchas - Deployment pitfalls: runtime.exs, release migrations, PHX_HOST, health checks, secrets
- phoenix-channels-essentials - Channels: socket auth, topic authorization, Presence, handle_in patterns
- telemetry-essentials - Observability: structured logging, :telemetry, Ecto events, LiveDashboard, metrics
- phoenix-json-api - JSON APIs: :api pipeline, FallbackController, pagination, versioning, Bearer auth
Each skill includes a RULES section with 6-11 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 (27 rules in settings.json)
Context-aware enforcement rules that adapt to your project stack:
SessionStart (runs once per session):
- project-detection - Parses
mix.exs to detect Phoenix version, LiveView, Ecto adapter, Oban — hooks adapt behavior based on results
Blocking (exit 2 - prevents action):
- missing-impl - Blocks callbacks without @impl true (skips in API-only projects) — with fix suggestion
- hardcoded-paths - Blocks hardcoded file paths — with Application.get_env fix
- hardcoded-sizes - Blocks hardcoded file size limits — with config migration fix
- static-paths-validator - Blocks file references not in static_paths()
- deprecated-components - Blocks deprecated Phoenix components — context-aware: warns on @current_user in Phoenix 1.8+ projects
- dangerous-operations - Blocks mix ecto.reset, git push --force, MIX_ENV=prod
- atom-from-user-input - Blocks String.to_atom/1 — atom table exhaustion risk
- unparameterized-sql-fragment - Blocks string interpolation in Ecto fragment — SQL injection
- unsafe-redirect - Blocks redirect to user-controlled URLs — open redirect risk
j-morgan6