Home › Nix › Nix flakes AGENTS.md

Nix flakes AGENTS.md

AGENTS.md for projects using Nix flakes: dev shells, pinned nixpkgs, packages, formatting, and flake checks.

AGENTS.mdNix

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Nix flakes

## Commands
- Enter the dev environment: `nix develop` (or `direnv allow` with `use flake`). Run tools from inside it.
- Build: `nix build .#<package>` · Checks: `nix flake check` · Format: `nix fmt` (configured formatter, e.g. `nixfmt`)
- Update inputs only when asked: `nix flake update <input>`; commit `flake.lock` changes separately.

## Rules
- All inputs are pinned in `flake.lock`. Never use channels or `<nixpkgs>` lookup paths in new code; get packages from the flake's `nixpkgs` input.
- Support the systems the project lists (use `nixpkgs.lib.genAttrs` or `flake-utils`/`flake-parts` as already used). Don't hard-code `x86_64-linux` unless the flake does.
- Dev shells: add tools to `devShells.<system>.default` (`pkgs.mkShell { packages = [ ... ]; }`) instead of telling users to install them globally. Keep shell hooks minimal.
- Packages use the right builder for the language (`buildGoModule`, `rustPlatform.buildRustPackage`, `buildNpmPackage`, `python3Packages.buildPythonApplication`) with fixed-output hashes. When a hash changes, use `lib.fakeHash`, build, and copy the hash from the error.
- Use `lib` functions and `inherit` to keep expressions readable; split large flakes into `nix/*.nix` files.
- NixOS/home-manager modules expose `options` with types and descriptions and use `lib.mkIf cfg.enable`.
- Never put secrets in Nix expressions (they end up world-readable in `/nix/store`); use sops-nix/agenix.

## Done
`nix flake check` and `nix build` succeed, and `nix fmt` leaves no diff.