Elixir Phoenix Guide for Claude Code
Version: 2.3.1 | 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.1 Released! Corrected LiveView assigns and test setup guidance based on community feedback. 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
Warnings (exit 1 - shows warning with fix suggestion):
- nested-if-else - Warns with case/multi-clause function fix
- inefficient-enum - Warns with for comprehension/reduce fix
- string-concatenation - Warns with IO list/Enum.join fix
- auto-upload-warning - Warns when auto_upload: true is detected (skips in API-only projects)
- debug-statements - Warns on IO.inspect, dbg(), IO.puts outside test files
- migration-safety - Checks for missing FK indexes, on_delete strategies, unsafe column operations
- raw-html-warning - Warns on raw/1 usage — XSS risk from unescaped HTML
- sensitive-logging - Warns on password/token/secret/api_key in Logger calls
- timing-unsafe-compare - Warns on == with tokens/secrets — suggests Plug.Crypto.secure_compare/2
