Elixir has a sharper gap between working code and idiomatic code than most languages. AI assistants can write Elixir that compiles and passes tests — but misses the OTP patterns, function head dispatch, supervision trees, and pipe conventions that experienced Elixir developers use as a matter of course.

The result: code that works in dev, breaks under load, and doesn't behave like the Elixir ecosystem expects.

A CLAUDE.md at your project root closes this gap. Here are the 13 rules with the highest impact.

Rule 1: OTP first — processes, not objects

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.…