elixir-handbook
What an agent needs to know about an Elixir codebase, in one place. The
agents say what to run and when (a cycle, a closing point, a review);
the toolchain command does it, and this skill says how to read the results
and write the code.
When it applies
- Projects: only a project whose folder name (the basename of the
repository root) is listed in
projects or printed by
minime-config projects elixir (the optional projects.toml of the
minime configuration). Anywhere else, say that no
handbook covers the project and ask how to build and test it.
- Tools: only those in
tools, and only those the project uses. A
project built with another toolchain (rebar3, erlang.mk, Nix) is reported,
never forced into mix. A check the project does not configure (no
credo or dialyxir dependency) is skipped by toolchain check, never
added: no new dependency, no new .credo.exs, no new alias.
toolchain.yaml and the toolchain command
toolchain.yaml, at the project root (versioned on Claude Code, never on
Copilot: see workflow-files), tells toolchain
how this project runs its commands: the container wrapper (exec, for
example [docker, exec, app]), extra environment, and any command the
project replaces. toolchain show prints what will run. When the file is
missing, toolchain uses plain mix on the host; kent writes the file from
the shopping list, never another agent.
| Need |
Command |
| compile, warnings as errors |
toolchain build |
| one test |
toolchain test test/foo/bar_test.exs:42 |
| a list of test files |
toolchain test <file> <file> |
| the tests that include the files of a commit |
toolchain test --commit (HEAD) |
| the tests that include some files |
toolchain test --related <file>… |
| the tests related to the branch, architecture tests included |
toolchain test --branch |
| the static checks on the branch's files |
toolchain check (--fix formats first) |
Pass --agent <your name> so the output reaches the activity log. A test
file includes a module when it is its mirrored test (lib/a/b.ex →
test/a/b_test.exs; in an umbrella, apps/<app>/lib/… →
apps/<app>/test/…) or names the module. There is no command for the full
suite: the CI runs it.
- Never interrupt a run: an interrupted BEAM can hang on its BREAK menu
inside the container and block everything. Long runs (
toolchain test --branch, toolchain check with dialyzer) go in the background; wait for
them.
- Never fetch dependencies or install anything (
mix deps.get, a PLT
download) without the user's approval.
Reading the static checks
toolchain check runs, on the .ex and .exs files the branch changed:
mix format --check-formatted, mix credo --strict, then mix dialyzer on
the whole program (minutes the first time, while it builds the PLT). Keep
only dialyzer's warnings on lines the branch changed (git-read diff -U0 {base}...HEAD -- <file>); leave the others. A finding fixed without
changing behaviour (formatting, a Credo rule, a typespec) is a fix of the
closing point, committed as the agent's own instructions say; a fix that
would change behaviour is a new TDD cycle, starting with a red.
Testing
- ExUnit:
async: true unless the test touches shared state (the
database without a sandbox, a named process, the application env).
Helpers shared by several test modules live in test/support/ (compiled
in the test env through elixirc_paths), never in a test file.
- Property-based tests: StreamData,
use ExUnitProperties, property "…" do check all x <- generator do … end end. Generators shared by several
tests live in one generator module under test/support/, as the project's
single DSL for building domain values; the scenario's parameters stay
explicit at the call site. Adding stream_data to mix.exs is the user's
decision.
- Doubles: only of a component whose boundary is an interface, which in
Elixir is a behaviour. Prefer Hammox to Mox when the project has it:
it checks every call and return value against the callback's typespecs,
which is the contract test between the double and the real
implementation. With plain Mox, write the contract test yourself: an
ExUnit.CaseTemplate (or a shared describe macro) holding the
behaviour's tests, run once against the real module and once against the
double's expectations. Inject the implementation through the application
env or a function argument, never by redefining modules.
- Architecture tests (ford's fitness functions) live in
test/architecture/; toolchain test --branch always includes them.
Durations and benchmarks (martin)
toolchain test --durations <paths> adds --slowest 1000: ExUnit prints
the tests, slowest first. A slow setup is usually a setup that should be
setup_all, or a service started per test.
- A benchmark is a plain script under
benchmarks/ in the project, run with
toolchain bench <file> (mix run <file>). It defines the old version as
a module of its own (<Module>.Old, copied from the file at HEAD) and
times both with :timer.tc/1 (Benchee when the project has it) on inputs
of growing size (for example 10, 100, 1000, 10000), printing one line per
size and version. Growing ratios between sizes show the complexity; equal
ratios with a constant gap show a constant factor. It is committed as
benchmark(<scope>): … and dropped by linus squash.
Style rules
The user's own rules: the team does not share them, so they live here and not
in the project's .credo.exs. Never add them to the project's configuration.
- Scope: only the code you write or change in the current cycle; the rest
of the project keeps its style, even in a module you touch.
- A green stays the minimum the failing test needs, even when it breaks a
rule: the rules are applied in the refactor phase, the body naming
each rule (
elixir-style: <rule id>). On Copilot, one refactor commit per
rule applied; on Claude Code martin applies them in the unit's code
refactor (refactor(<scope>)), and unclebob-pair in its cycle's. In
review, a rule the unit's code breaks is a finding that cites the rule id.
- A rule never justifies a change of behaviour. If following it would change
what the code does, leave the code as is and say so in the refactor
commit's body.
Rules
with-max-three-clauses: a with has at most three clauses
Every clause of the with head counts, pattern <- expr and x = expr
alike; the else block does not count.
# Avoid: four clauses
with {:ok, user} <- authenticate(params),
cart = Cart.for(user),
{:ok, cart} <- Cart.validate(cart),
{:ok, order} <- Orders.create(cart, params) do
{:ok, order}
end
Extract the related steps into private functions whose names say what they
do, each with its own short with, and compose them in the outer one:
with {:ok, user} <- authenticate(params),
{:ok, order} <- place_order(user, params) do
{:ok, order}
end
defp place_order(user, params) do
with {:ok, cart} <- Cart.validate(Cart.for(user)),
{:ok, order} <- Orders.create(cart, params) do
{:ok, order}
end
end
- Why: a long
with mixes several steps at one level of abstraction and
hides which ones belong together; named steps say it, and each can be read
and tested on its own.
- Keep the behaviour. An extracted function returns every non-matching
value unchanged, so the outer
with and its else see exactly what they
saw before. When the original else tells failures apart, keep their
shapes; never wrap or rename an error while extracting.
- Group steps by meaning, not by count: extract the steps that together form
one action a name can describe, never an arbitrary cut after the third
clause.
- Extracted functions are private (
defp): a refactor adds no public
function.
1---2name: elixir-handbook3description: How to work on an Elixir project in this workflow - toolchain.yaml and the toolchain command (build, the tests to run, the static checks), the testing libraries (ExUnit, StreamData, Mox and Hammox for contract tests), the test layout, and the user's personal style rules. Load it whenever you build, test, check, write or review Elixir code in a project listed in `projects`.4projects: []5tools:6 - mix7 - mix test8 - mix format9 - mix credo10 - mix dialyzer11metadata:12 source: https://skillmd.com/skills/korsmakolnikov/elixir-handbook13---1415# elixir-handbook1617What an agent needs to know about an Elixir codebase, in one place. The18agents say **what** to run and **when** (a cycle, a closing point, a review);19the `toolchain` command does it, and this skill says how to read the results20and write the code.2122## When it applies2324* **Projects**: only a project whose folder name (the basename of the25 repository root) is listed in `projects` or printed by26 `minime-config projects elixir` (the optional `projects.toml` of the27 minime configuration). Anywhere else, say that no28 handbook covers the project and ask how to build and test it.29* **Tools**: only those in `tools`, and only those the project uses. A30 project built with another toolchain (rebar3, erlang.mk, Nix) is reported,31 never forced into `mix`. A check the project does not configure (no32 `credo` or `dialyxir` dependency) is skipped by `toolchain check`, never33 added: no new dependency, no new `.credo.exs`, no new alias.3435## toolchain.yaml and the toolchain command3637`toolchain.yaml`, at the project root (versioned on Claude Code, never on38Copilot: see `workflow-files`), tells `toolchain`39how this project runs its commands: the container wrapper (`exec`, for40example `[docker, exec, app]`), extra environment, and any command the41project replaces. `toolchain show` prints what will run. When the file is42missing, `toolchain` uses plain `mix` on the host; kent writes the file from43the shopping list, never another agent.4445| Need | Command |46|---|---|47| compile, warnings as errors | `toolchain build` |48| one test | `toolchain test test/foo/bar_test.exs:42` |49| a list of test files | `toolchain test <file> <file>` |50| the tests that include the files of a commit | `toolchain test --commit` (HEAD) |51| the tests that include some files | `toolchain test --related <file>…` |52| the tests related to the branch, architecture tests included | `toolchain test --branch` |53| the static checks on the branch's files | `toolchain check` (`--fix` formats first) |5455Pass `--agent <your name>` so the output reaches the activity log. A test56file includes a module when it is its mirrored test (`lib/a/b.ex` →57`test/a/b_test.exs`; in an umbrella, `apps/<app>/lib/…` →58`apps/<app>/test/…`) or names the module. There is no command for the full59suite: the CI runs it.6061* **Never interrupt** a run: an interrupted BEAM can hang on its BREAK menu62 inside the container and block everything. Long runs (`toolchain test63 --branch`, `toolchain check` with dialyzer) go in the background; wait for64 them.65* Never fetch dependencies or install anything (`mix deps.get`, a PLT66 download) without the user's approval.6768## Reading the static checks6970`toolchain check` runs, on the `.ex` and `.exs` files the branch changed:71`mix format --check-formatted`, `mix credo --strict`, then `mix dialyzer` on72the whole program (minutes the first time, while it builds the PLT). Keep73only dialyzer's warnings on lines the branch changed (`git-read diff -U074{base}...HEAD -- <file>`); leave the others. A finding fixed without75changing behaviour (formatting, a Credo rule, a typespec) is a fix of the76closing point, committed as the agent's own instructions say; a fix that77would change behaviour is a new TDD cycle, starting with a red.7879## Testing8081* **ExUnit**: `async: true` unless the test touches shared state (the82 database without a sandbox, a named process, the application env).83 Helpers shared by several test modules live in `test/support/` (compiled84 in the test env through `elixirc_paths`), never in a test file.85* **Property-based tests**: StreamData, `use ExUnitProperties`, `property86 "…" do check all x <- generator do … end end`. Generators shared by several87 tests live in one generator module under `test/support/`, as the project's88 single DSL for building domain values; the scenario's parameters stay89 explicit at the call site. Adding `stream_data` to `mix.exs` is the user's90 decision.91* **Doubles**: only of a component whose boundary is an interface, which in92 Elixir is a behaviour. Prefer **Hammox** to Mox when the project has it:93 it checks every call and return value against the callback's typespecs,94 which is the contract test between the double and the real95 implementation. With plain Mox, write the contract test yourself: an96 `ExUnit.CaseTemplate` (or a shared `describe` macro) holding the97 behaviour's tests, run once against the real module and once against the98 double's expectations. Inject the implementation through the application99 env or a function argument, never by redefining modules.100* **Architecture tests** (ford's fitness functions) live in101 `test/architecture/`; `toolchain test --branch` always includes them.102103## Durations and benchmarks (martin)104105* `toolchain test --durations <paths>` adds `--slowest 1000`: ExUnit prints106 the tests, slowest first. A slow setup is usually a `setup` that should be107 `setup_all`, or a service started per test.108* A benchmark is a plain script under `benchmarks/` in the project, run with109 `toolchain bench <file>` (`mix run <file>`). It defines the old version as110 a module of its own (`<Module>.Old`, copied from the file at `HEAD`) and111 times both with `:timer.tc/1` (Benchee when the project has it) on inputs112 of growing size (for example 10, 100, 1000, 10000), printing one line per113 size and version. Growing ratios between sizes show the complexity; equal114 ratios with a constant gap show a constant factor. It is committed as115 `benchmark(<scope>): …` and dropped by `linus squash`.116117## Style rules118119The user's own rules: the team does not share them, so they live here and not120in the project's `.credo.exs`. Never add them to the project's configuration.121122* **Scope**: only the code you write or change in the current cycle; the rest123 of the project keeps its style, even in a module you touch.124* A green stays the minimum the failing test needs, even when it breaks a125 rule: the rules are applied in the **refactor** phase, the body naming126 each rule (`elixir-style: <rule id>`). On Copilot, one refactor commit per127 rule applied; on Claude Code martin applies them in the unit's code128 refactor (`refactor(<scope>)`), and unclebob-pair in its cycle's. In129 review, a rule the unit's code breaks is a finding that cites the rule id.130* A rule never justifies a change of behaviour. If following it would change131 what the code does, leave the code as is and say so in the refactor132 commit's body.133134### Rules135136#### `with-max-three-clauses`: a `with` has at most three clauses137138Every clause of the `with` head counts, `pattern <- expr` and `x = expr`139alike; the `else` block does not count.140141```elixir142# Avoid: four clauses143with {:ok, user} <- authenticate(params),144 cart = Cart.for(user),145 {:ok, cart} <- Cart.validate(cart),146 {:ok, order} <- Orders.create(cart, params) do147 {:ok, order}148end149```150151Extract the related steps into private functions whose names say what they152do, each with its own short `with`, and compose them in the outer one:153154```elixir155with {:ok, user} <- authenticate(params),156 {:ok, order} <- place_order(user, params) do157 {:ok, order}158end159160defp place_order(user, params) do161 with {:ok, cart} <- Cart.validate(Cart.for(user)),162 {:ok, order} <- Orders.create(cart, params) do163 {:ok, order}164 end165end166```167168* **Why**: a long `with` mixes several steps at one level of abstraction and169 hides which ones belong together; named steps say it, and each can be read170 and tested on its own.171* **Keep the behaviour.** An extracted function returns every non-matching172 value unchanged, so the outer `with` and its `else` see exactly what they173 saw before. When the original `else` tells failures apart, keep their174 shapes; never wrap or rename an error while extracting.175* Group steps by meaning, not by count: extract the steps that together form176 one action a name can describe, never an arbitrary cut after the third177 clause.178* Extracted functions are private (`defp`): a refactor adds no public179 function.