mirror of https://github.com/ryan4yin/nix-config.git synced 2026-03-24 10:21:43 +01:00

Files

Ryan Yin f5444150ef feat: agents

2026-03-21 20:54:40 +08:00

5.8 KiB

Raw Blame History

AGENTS.md - Guidelines for AI Coding Agents

This file defines the default operating guide for AI agents working in this Nix Flake repository. Keep changes minimal, verifiable, and safe for multi-host deployments.

Scope and Repository Model

This repository manages:

NixOS hosts (desktop + servers)
macOS hosts via nix-darwin
Home Manager profiles shared across platforms
Remote deployments via colmena

High-level layout:

.
├── flake.nix                    # Flake entry; outputs composed in ./outputs
├── Justfile                     # Primary command entrypoint (uses nushell)
├── outputs/
│   ├── default.nix
│   ├── x86_64-linux/
│   ├── aarch64-linux/
│   └── aarch64-darwin/
├── modules/                     # NixOS + darwin modules
├── home/                        # Home Manager modules
├── hosts/                       # Host-specific config
├── vars/                        # Shared variables
├── lib/                         # Helper functions
├── agents/                      # Reusable cross-project agent files and installer
└── secrets/                     # Agenix secret definitions

Ground Rules for Agents

Prefer just tasks over ad-hoc commands when an equivalent task exists.
Make the smallest reasonable change; avoid drive-by refactors.
Do not commit secrets, generated credentials, or private keys.
Preserve platform guards ([linux], [macos]) and host naming conventions.
Run formatting and evaluation checks for touched areas before finishing.

Quick Start Workflow (Recommended)

Inspect context:

just --list
rg -n "<symbol-or-option>" modules home hosts outputs

Implement the change.
Format:

just fmt

Validate:

just test

If deployment behavior changed, provide the exact just command the user should run (do not run remote deploys unless explicitly requested).

Canonical Commands

Core quality loop

just fmt                    # format Nix files
just test                   # run eval tests: nix eval .#evalTests ...
nix flake check             # run flake checks + pre-commit style checks

Dependency/input updates

just up                     # update all inputs and commit lock file
just upp <input>            # update one input and commit lock file
just up-nix                 # update nixpkgs-related inputs

Local deploy commands

just local                  # deploy config for current hostname
just local debug            # same with verbose/debug mode
just niri                   # deploy "<hostname>-niri" on Linux
just niri debug             # debug mode

Remote deploy commands (colmena)

just col <tag>              # deploy nodes matching tag
just lab                    # deploy all kubevirt nodes
just k3s-prod               # deploy k3s production nodes
just k3s-test               # deploy k3s test nodes

Useful direct commands

nix eval .#evalTests --show-trace --print-build-logs --verbose
nix build .#nixosConfigurations.<host>.config.system.build.toplevel
nixos-rebuild switch --flake .#<hostname>

Test Structure and Expectations

Eval tests live under:

outputs/x86_64-linux/tests/
outputs/aarch64-linux/tests/
outputs/aarch64-darwin/tests/

Typical test pair:

expr.nix
expected.nix

Agent expectations:

If logic changes affect shared modules, run just test.
If only docs/comments changed, tests may be skipped, but say so explicitly.
If tests cannot run, report why and include the exact failing command.

Formatting and Style

Formatting tools

Nix: nixfmt (RFC style, width 100)
Non-Nix: prettier (see .prettierrc.yaml)
Spelling: typos (see .typos.toml)

Nix style conventions

Files use kebab-case.nix.
Prefer inherit (...) for attribute imports.
Prefer lib.mkIf, lib.optional, lib.optionals for conditional config.
Use lib.mkDefault for defaults and lib.mkForce only when necessary.
Keep module options documented with description.

Module pattern:

{ lib, config, ... }:
{
  options.myFeature = {
    enable = lib.mkEnableOption "my feature";
  };

  config = lib.mkIf config.myFeature.enable {
    # ...
  };
}

Platform Notes

Justfile uses nu (set shell := ["nu", "-c"]).
Some tasks exist only on Linux or macOS via [linux] / [macos] guards.
just local has different implementations per platform:
- Linux: nixos-switch
- macOS: darwin-build + darwin-switch

Secrets and Safety

Secrets are managed with agenix and an external private secrets repo.
Never inline secret values in Nix files, tests, or docs.
Do not run broad remote deploy commands unless requested.
Prefer build/eval validation first, deploy second.

Change Review Checklist (for agents)

Before finishing, verify:

Change is scoped to requested behavior.
just fmt applied (or not needed, stated explicitly).
just test run for config changes (or limitation explained).
No secrets or machine-specific artifacts added.
User-facing summary includes what changed and what was validated.

Common Pitfalls

Editing host-specific files when the change belongs in shared module layers (modules/ or home/).
Forgetting to update both Linux and darwin paths when touching shared abstractions.
Running deployment commands to validate syntax when nix eval/nix build would be safer.
Introducing hardcoded usernames/paths instead of using myvars and existing abstractions.

5.8 KiB Raw Blame History