Developing Elixir

Expert guidance for building robust, scalable Elixir/Phoenix applications.

Quick Start

For immediate help, identify your task type and consult the relevant reference:

Working On	Reference File	Key Topics
Controllers, routing, plugs, channels	phoenix-framework	MVC patterns, authentication, WebSockets
LiveView components, forms	liveview	Real-time UI, hooks, streams
Schemas, queries, migrations	ecto-database	Associations, changesets, transactions
Safe migrations, schema changes	safe-ecto-migrations	Concurrent indexes, zero-downtime DDL
GenServer, Supervisor, processes	otp-patterns	Fault tolerance, state management
Domain modeling, value objects	functional-modeling	Parse-don't-validate, DDD
GraphQL schemas, resolvers	graphql-absinthe	Subscriptions, dataloader
ExUnit tests, TDD workflow	testing-exunit	Test organization, assertions

TDD Phase Awareness

All guidance in this skill is phase-aware. Identify your current phase:

RED Phase (Writing Failing Tests)

• Write the smallest test that captures intent
• Use hard-coded values directly in tests
• Skip edge cases and parameterization initially
• Focus on what behavior the test demands

GREEN Phase (Making Tests Pass)

• RESIST over-engineering at all costs
• Start with pure functions and simple data structures
• Recommend primitives and maps before structs
• Defer abstractions, smart constructors, and validations
• Focus only on making the current test pass

REFACTOR Phase (Improving Design)

• NOW apply proper patterns and abstractions
• Extract value objects from primitives
• Add comprehensive error handling
• Introduce OTP patterns if genuinely needed
• Improve test structure and coverage

Cross-Cutting Principles

These principles apply across all Elixir development:

Functional-First Approach

1. Prefer pure functions over stateful processes
2. Use explicit state passing through function parameters
3. Only introduce OTP patterns when tests require them
4. Push side effects to system boundaries

Progressive Abstraction

1. Start with primitives and maps
2. Introduce structs when structure is genuinely needed
3. Add type specs when interfaces stabilize
4. Extract domain modules when concepts are proven

Parse, Don't Validate

• Transform unstructured data into guaranteed-valid types at boundaries
• Once data is parsed, it's always valid throughout the system
• Prefer constructors that return {:ok, value} | {:error, reason}

Error Handling Philosophy

• Use tagged tuples consistently: {:ok, result} or {:error, reason}
• Implement proper error types for domain-specific errors
• Never expose internal implementation details in errors

Examples

Creating a Phoenix context with Ecto:

User: "I need to add a checkout feature for orders"
→ Consult ecto-database.md for schema design, phoenix-framework.md for controller

Implementing real-time updates:

User: "Show live order status updates to the customer"
→ Consult liveview.md for socket state and PubSub patterns

Refactoring to proper domain model:

User: "This order calculation has grown complex with many edge cases"
→ Identify TDD phase (likely REFACTOR), consult functional-modeling.md

Adding background job processing:

User: "Process order confirmations asynchronously"
→ Consult otp-patterns.md for process decisions, phoenix-framework.md for Oban

Writing a database migration:

User: "I need to add an index to the posts table"
→ Consult safe-ecto-migrations.md for concurrent index creation

Anti-Patterns to Avoid

Premature OTP

• GenServer for data that could be function arguments
• Supervisors for processes that don't need restart strategies
• ETS tables for small, static datasets
• Message passing when direct function calls suffice

Premature Abstraction

• Creating types for single-use values
• Building generic solutions for specific problems
• Introducing abstractions without duplication
• Modeling future requirements

Testing Anti-Patterns

• Writing multiple assertions before any pass
• Creating elaborate test fixtures prematurely
• Testing implementation details
• Adding error case tests too early

Reference File IDs

For programmatic access (e.g., parallel reviews), use these identifiers:

phoenix-framework · liveview · ecto-database · safe-ecto-migrations · otp-patterns · functional-modeling · graphql-absinthe · testing-exunit