Elixir and OTP skill for Claude Code

Done well means: processes exist only to model runtime concerns (state, concurrency, fault isolation), every process sits under a supervisor with a restart strategy that matches its failure semantics, no GenServer is a global bottleneck, and mix compile --warnings-as-errors, mix format --check-formatted, mix credo --strict, and mix test pass.

Ground rules

• Do not use processes to organize code. Modules and functions organize code; processes organize runtime state and failure. A GenServer wrapping pure logic is a serialization bottleneck.
• Let it crash, but only below a supervisor and only for unexpected errors. Expected failures (invalid input, not found) return {:error, reason}.
• Pattern match on the happy path; use with for multi-step pipelines that can fail.
• Never spawn unlinked, unsupervised processes in application code. Use Task.Supervisor or a supervised child.
• Keep GenServer callbacks fast. Slow work (HTTP, heavy compute) goes to a Task, with the result sent back as a message.

Do I need a process?

Need	Use
Pure transformation	Plain functions
One-off async work, result needed	Task.async + Task.await (linked to caller)
Many concurrent jobs, bounded	Task.async_stream(enum, fun, max_concurrency: n, timeout: ms)
Fire-and-forget work that must not crash caller	Task.Supervisor.start_child
Mutable state with serialized updates	GenServer
Read-heavy shared data (cache, config)	ETS table (read_concurrency: true) owned by a GenServer, or :persistent_term for rarely-changing data
One process per entity (game, session, device)	DynamicSupervisor + Registry via-tuple names
Periodic job	GenServer with Process.send_after/3, or Oban for persistent jobs
Durable background jobs	Oban (Postgres-backed), not GenServers

GenServer template

defmodule MyApp.RateCounter do
  use GenServer
  require Logger

  # Client API: the only functions other modules call
  def start_link(opts) do
    name = Keyword.get(opts, :name, __MODULE__)
    GenServer.start_link(__MODULE__, opts, name: name)
  end

  def hit(server \\ __MODULE__, key), do: GenServer.cast(server, {:hit, key})
  def count(server \\ __MODULE__, key), do: GenServer.call(server, {:count, key})

  # Callbacks
  @impl true
  def init(opts) do
    interval = Keyword.get(opts, :reset_ms, 60_000)
    {:ok, %{counts: %{}, interval: interval}, {:continue, :schedule}}   # keep init fast
  end

  @impl true
  def handle_continue(:schedule, state) do
    Process.send_after(self(), :reset, state.interval)
    {:noreply, state}
  end

  @impl true
  def handle_cast({:hit, key}, state),
    do: {:noreply, update_in(state.counts[key], &((&1 || 0) + 1))}

  @impl true
  def handle_call({:count, key}, _from, state),
    do: {:reply, Map.get(state.counts, key, 0), state}

  @impl true
  def handle_info(:reset, state) do
    Process.send_after(self(), :reset, state.interval)
    {:noreply, %{state | counts: %{}}}
  end

  def handle_info(msg, state) do                      # never let unknown messages pile up
    Logger.warning("unexpected message: #{inspect(msg)}")
    {:noreply, state}
  end
end

• call when the caller needs a reply or backpressure; cast only when losing the message on crash is acceptable. Default call timeout is 5000 ms.
• Expensive startup goes in handle_continue, so start_link returns quickly and the supervisor is not blocked.
• Put @impl true on every callback so typos become compile warnings.
• Keep the state small; large binaries in state are copied on every :sys.get_state and inspected in crash logs.

Supervision

defmodule MyApp.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      MyApp.Repo,
      {Phoenix.PubSub, name: MyApp.PubSub},
      {Registry, keys: :unique, name: MyApp.GameRegistry},
      {DynamicSupervisor, name: MyApp.GameSupervisor, strategy: :one_for_one},
      {Task.Supervisor, name: MyApp.TaskSup},
      MyApp.RateCounter,
      MyAppWeb.Endpoint                         # last: start serving once deps are up
    ]
    Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
  end
end

Strategy	When a child dies	Use when
:one_for_one	Restart that child only	Children independent (default)
:rest_for_one	Restart it and children started after it	Later children depend on earlier ones
:one_for_all	Restart all	Children share state that must stay consistent

restart:	Meaning
:permanent	Always restart (default for GenServer)
:transient	Restart only on abnormal exit (per-entity workers that finish)
:temporary	Never restart (Tasks, one-shot jobs)

• Default intensity is 3 restarts in 5 seconds; exceeding it kills the supervisor and escalates. A crash loop at boot means a bad dependency or config, not a reason to raise max_restarts.
• Order children so dependencies start first; the supervisor shuts down in reverse.
• Start per-entity processes with names through the Registry:

def start_game(id) do
  DynamicSupervisor.start_child(MyApp.GameSupervisor, {MyApp.Game, id: id})
end

# in MyApp.Game
def start_link(opts), do: GenServer.start_link(__MODULE__, opts, name: via(opts[:id]))
defp via(id), do: {:via, Registry, {MyApp.GameRegistry, id}}

Bounded concurrency

urls
|> Task.async_stream(&fetch/1, max_concurrency: 10, timeout: 15_000, on_timeout: :kill_task)
|> Enum.reduce({[], []}, fn
  {:ok, {:ok, body}}, {ok, err} -> {[body | ok], err}
  {:ok, {:error, reason}}, {ok, err} -> {ok, [reason | err]}
  {:exit, reason}, {ok, err} -> {ok, [reason | err]}
end)

Task.async_stream defaults max_concurrency to the scheduler count; set it explicitly for I/O. Use Task.Supervisor.async_stream_nolink when a crashing item must not take down the caller.

Phoenix structure (1.7+)

• Contexts (MyApp.Accounts, MyApp.Billing) are the public API to the domain; controllers and LiveViews call contexts, never Repo directly.
• Ecto changesets validate and cast at the boundary; one changeset function per use case (registration_changeset, email_changeset).
• Verified routes ~p"/users/#{user}" catch broken links at compile time.
• LiveView: assign only what the template renders; use streams (stream/3) for large lists; subscribe to PubSub in mount only if connected?(socket).
• Wrap multi-step writes in Ecto.Multi and Repo.transaction.
• Preload associations explicitly (Repo.preload / preload: in queries); Ecto never lazy-loads, so missing preloads raise Ecto.Association.NotLoaded errors in templates.

Debugging live systems

:observer.start()                                   # GUI: process tree, memory, ETS
Process.info(pid, [:message_queue_len, :memory, :current_function])
:sys.get_state(MyApp.RateCounter)
:recon.proc_count(:message_queue_len, 5)           # with the :recon dependency

A growing message_queue_len means the process cannot keep up: shard it (one process per key via Registry/PartitionSupervisor), move reads to ETS, or apply backpressure with call.

Gotchas

• GenServer.call to yourself from inside a callback deadlocks (times out after 5 s).
• Large binaries (>64 bytes) are reference-counted; a long-lived process that touches many of them can hold memory until it garbage collects. Hibernate or restructure.
• Atoms are never garbage collected: never String.to_atom/1 on user input; use String.to_existing_atom/1.
• Task.async must be awaited by the same process; unawaited tasks send messages that pile up in the caller’s mailbox.
• ExUnit async: true with a shared named process causes flaky tests; start per-test instances with start_supervised!({MyServer, name: nil}) and pass the pid.
• Catch-all handle_info clauses that silently drop messages hide bugs; log them.

Verification

mix compile --warnings-as-errors
mix format --check-formatted
mix credo --strict
mix test --warnings-as-errors
mix dialyzer            # if dialyxir is configured

For OTP changes also: kill the process in iex (Process.exit(pid, :kill)) and confirm the supervisor restarts it and dependents recover.