CLAUDE.md for Elixir: 13 Rules That Make AI Write Idiomatic, OTP-Aware Elixir

This is an OTP application. Model concurrent behavior with:
- GenServer for stateful processes
- Supervisor for fault tolerance and restart strategies
- Task for one-off concurrent work
- Agent for simple shared state (prefer GenServer for anything non-trivial)

Do NOT model concurrency with shared mutable state, mutexes, or global variables.
The process is the unit of concurrency and isolation.

Use pattern matching in function heads for branching:

  def process(%{status: :active} = user), do: ...
  def process(%{status: :inactive} = user), do: ...
  def process(%{status: status}), do: {:error, "unknown status: #{status}"}

Not:
  def process(user) do
    cond do
      user.status == :active -> ...
      user.status == :inactive -> ...
    end
  end

Reserve `case` for local branching within a function. Reserve `cond` for boolean expressions without a matching value.

Pipe rules:
- Use `|>` when transforming data through 3+ steps
- Each pipe step should be a single operation (avoid anonymous functions in pipes unless necessary)
- The first argument of every piped function must be the data being transformed
- Don't pipe into `IO.inspect/2` in production code — use Logger
- Break long pipes into named intermediate values when readability suffers

Avoid:
  result = transform(filter(validate(data)))  # nest style

Prefer:
  result = data
    |> validate()
    |> filter()
    |> transform()

Use `with` for sequential operations where any step can fail:

  with {:ok, user} <- fetch_user(id),
       {:ok, account} <- fetch_account(user),
       {:ok, _} <- charge(account, amount) do
    {:ok, "charged"}
  else
    {:error, :not_found} -> {:error, "user not found"}
    {:error, reason} -> {:error, reason}
  end

Not nested case/if chains.
Return `{:ok, value}` and `{:error, reason}` tuples from all functions that can fail.

Supervision strategy:
- Use `:one_for_one` for independent workers
- Use `:one_for_all` when workers have shared state that becomes inconsistent on crash
- Use `:rest_for_one` when workers have ordered dependencies
- Start supervised processes in application.ex or a dedicated Supervisor module
- Do NOT rescue exceptions in GenServer callbacks to avoid crashes — let it crash, let the supervisor restart

The supervisor IS the error handler. Writing defensive rescue clauses in worker processes fights the design.

Database access: Ecto only.
- All data validation in changesets: `cast`, `validate_required`, `validate_format`
- Queries built with Ecto.Query DSL — no raw SQL except for complex queries using `fragment/1`
- No `Repo.get!` in business logic — use `Repo.get` and handle nil explicitly
- Preload associations explicitly: `Repo.preload(user, [:posts])` — no lazy loading
- Use `Repo.transaction` for operations that must be atomic
- Schema changesets are the single validation point — not controllers or context functions

Organize with Phoenix contexts (even outside Phoenix):
- One context module per domain: `Accounts`, `Payments`, `Inventory`
- Context functions are the public API: `Accounts.get_user(id)`, `Accounts.create_user(attrs)`
- Schema modules are private to contexts — not called directly from controllers or other contexts
- No cross-context direct schema access — only through the owning context's API

This is the Phoenix 1.3+ architecture. Do not use the older one-schema-one-controller pattern.

Atom discipline:
- Never convert user-provided strings to atoms with `String.to_atom/1`
  (atoms are not garbage collected — unlimited creation = memory leak / DoS vector)
- Use `String.to_existing_atom/1` when converting known strings to atoms
- Module names, function names, map keys in your own code: atoms are fine
- JSON parsing: use string keys by default, not atom keys (Jason default is correct)

Process communication:
- Use `GenServer.call/3` for synchronous requests (returns a value)
- Use `GenServer.cast/2` for asynchronous fire-and-forget (no return)
- Use `send/2` + `receive` only for ad-hoc message passing not managed by OTP
- Always set timeouts on `call`: `GenServer.call(pid, msg, 5_000)`
- Handle unexpected messages in `handle_info/2` — don't let them accumulate in the mailbox

Never use `Process.sleep/1` for coordination — use `GenServer.call` or `Task.async/await`.

Testing:
- All tests: `use ExUnit.Case, async: true` unless they share global state (database)
- Database tests: use `Ecto.Adapters.SQL.Sandbox` for transaction isolation
- Test setup: `setup` blocks, not module attributes
- Use `assert {:ok, _} = MyModule.function(args)` — match on the structure
- Factory: ExMachina for test data, not hand-built maps
- No `Process.sleep` in tests — use `assert_receive` with a timeout for async assertions
- Mock external services with `Mox` — define behaviors and verify expectations

Observability:
- Use `:telemetry` for emitting metrics from library/application code
- Use `Logger.metadata/1` to attach context to log entries: `Logger.metadata(user_id: id, request_id: req_id)`
- Log levels: debug (verbose dev), info (normal ops), warning (degraded), error (failure)
- No bare `IO.puts` or `IO.inspect` in production code — use Logger
- Attach telemetry handlers in application startup, not inline

Domain data:
- Define structs for all domain entities: `defstruct [:id, :name, :email]`
- Use `@enforce_keys` for required fields: `@enforce_keys [:id, :name]`
- Structs provide compile-time key checking — bare maps do not
- Use `%User{}` not `%{id: ..., name: ...}` when the shape is known
- Typespec every public function: `@spec create_user(attrs :: map()) :: {:ok, User.t()} | {:error, Ecto.Changeset.t()}`

Deployment:
- Use `mix release` for production deployments — not `mix run`
- Config: `config/runtime.exs` for runtime configuration (env vars read at startup)
  `config/config.exs` for compile-time only
- Never hardcode secrets — use `System.fetch_env!/1` in `config/runtime.exs`
- Health checks: implement a simple HTTP endpoint, not a Mix task that shells out
- Migrations: always run with `--no-start` in CI: `mix ecto.migrate --no-start`

# Elixir Project — AI Coding Rules

## Architecture
OTP application. GenServer + Supervisor for concurrency. Let it crash — supervisors handle recovery.
Contexts for domain boundaries. Schema modules private to their context.

## Patterns
Function head dispatch over cond/case at function level.
with for sequential fallible operations — {:ok, val} / {:error, reason} tuples everywhere.
Pipe operator for 3+ step data transforms.

## Ecto
Changesets for all validation. Explicit preloads. Repo.get not Repo.get!.
Raw SQL only via fragment/1. Transactions for atomic operations.

## Atoms
Never String.to_atom/1 on user input. String.to_existing_atom/1 for known strings only.

## Testing
async: true where possible. Ecto.Adapters.SQL.Sandbox for DB tests.
Mox for external service mocks. assert_receive for async. No Process.sleep in tests.

## Observability
Logger with metadata. Telemetry for metrics. No IO.puts/IO.inspect in production.

## Deployment
mix release. runtime.exs for env vars. System.fetch_env!/1 for secrets.