| name | nix-philosophy |
| description | Nix design philosophy: flake.nix as manifest, standard outputs, pure eval, data before commands, one source of truth, IFD boundaries. Use when designing flake structure or outputs. |
Nix philosophy
flake.nix is the manifest. It should expose inputs and delegate outputs to
lib/, discovery, and package-specific files. Keep scenario wiring, artifact
manifests, app wrappers, and helper logic near the owner that changes with them.
Use standard flake outputs: packages, checks, formatter, devShells,
templates, overlays, nixosModules, and lib. A workflow command should be
a package with meta.mainProgram so nix run .#<name> and
nix build .#<name> point at the same derivation.
Composition belongs in this repo; low-level ix VM primitives belong in ix.
Build workflows by consuming stable primitives, rendered plans, and plain data
surfaces. Add CLI primitives only when the lower layer truly owns the behavior.
Expose aggregate knowledge as data before wrapping it in a command. A
lib.<name> value that nix eval --json can inspect is easier to reuse than a
one-off app. Add a wrapper when formatting, joins, follow-up actions, or
human-facing output justify it.
Prefer one source of truth. Discovery beats hand-maintained registries. Generated
catalogs should come from small manifests. Hashes live with URLs. Versions live
near the image, package, or ecosystem that owns them.
Keep eval pure. Inputs flow through flake.nix or typed parameters. Avoid host
environment reads, channel refs, ad hoc flake paths, and eval-time network
fetches.
Import From Derivation is acceptable when another tool must reveal the real
build graph. Keep the boundary explicit, expose the generated artifact, and
batch discovery into one larger derivation when many tiny IFDs would serialize
the evaluator.
Generate commands through checked helpers. A wrapper reached through
nix run .#... should call realized executables with lib.getExe, an app
program, or an explicit store path reference. Avoid nesting another flake
frontend inside the generated command.
Nix builders for language workspaces should pass the smallest source closure the
compiler can consume. The caller names both the filtered src and the real
workspaceRoot; do not infer one from the other.
Nix source filtering and flakes only see tracked or staged source files. Stage
new source files before running Nix validation so failures describe the
expression under test instead of a missing path.
Start validation narrow, then broaden as confidence grows. Package invariants
belong in the owning derivation through checkPhase, installCheckPhase, or
passthru.tests; keep flake checks as aggregation and policy gates.
