Configuration Patterns

Hard Guardrails

MUST USE

MUST NOT USE

Symlink Warning

Nix and Home-manager use symlinks by design:

• ~/.config/* → /nix/store/...-home-manager-files/...
• ~/.nix-profile → /nix/var/nix/profiles/...

If symlinks are unacceptable:

• For project configs: Use actual files, not symlinks
• For user dotfiles: Consider chezmoi instead of Home-manager
• For Nix itself: No alternative - Nix fundamentally uses symlinks

Responsibility Matrix

Validation Commands

# Validate configuration policies
conftest test . --policy .claude/policies/configuration.rego

# Check for forbidden files
ls .tool-versions .mise.toml .asdfrc 2>/dev/null && echo "VIOLATION!" || echo "OK"

# Verify direnv integration
grep -q "use flake" .envrc && echo "OK" || echo "VIOLATION: .envrc missing 'use flake'"

# Verify lock files exist
[[ -f flake.lock && -f pixi.lock ]] && echo "OK" || echo "VIOLATION: Missing lock files"

# Verify Home-manager module structure
find modules/ -name "*.nix" -exec grep -L "lib\|mkDefault\|mkOption" {} \;

When to Consider Alternatives

chezmoi (Dotfile Management)

Consider When:

• Users need portable dotfiles across non-Nix systems
• Template-heavy per-user configuration is needed
• 1Password/pass secret integration required

Do NOT Use For:

• Project configuration (use flake.nix)
• Development shells (use devshell)
• Package management (use Nix/Pixi)

mise (Runtime Version Manager)

Consider When:

• Non-Nix users need quick onboarding
• Runtime version switching during active development
• CI environments without Nix available

Do NOT Use For:

• ROS2 packages (no RoboStack equivalent)
• Reproducible builds (less rigorous than Nix)
• Primary development workflow

Decision Tree

Need to manage configuration?
├── Project-level packages → Nix (flake.nix) or Pixi (pixi.toml)
├── Project-level shells → Nix devshell
├── User-level dotfiles?
│   ├── Nix system available → Home-manager
│   └── Portable/non-Nix → chezmoi
├── Runtime version switching?
│   ├── Reproducibility critical → Nix + pixi environments
│   └── Quick switching needed → mise (fallback only)
└── Remote development → DevPod with .devcontainer/

Module Patterns

Home-manager Module Template

# modules/common/example.nix
{ config, lib, pkgs, ... }:
let
  inherit (lib) mkDefault mkOption types;
in
{
  options.example = {
    enable = mkOption {
      type = types.bool;
      default = true;
      description = "Enable example configuration";
    };
  };

  config = lib.mkIf config.example.enable {
    # Configuration here
  };
}

direnv stdlib Extensions

# In modules/common/direnv.nix → programs.direnv.stdlib

# Enhanced use_flake with pixi integration
use_flake_pixi() {
  use flake
  if [[ -f pixi.toml ]]; then
    eval "$(pixi shell-hook)"
  fi
}

# ROS2 workspace layout
layout_ros2() {
  export ROS_DOMAIN_ID=${ROS_DOMAIN_ID:-0}
  if [[ -f install/local_setup.bash ]]; then
    source install/local_setup.bash
  fi
}

DevContainer Requirements

{
  "name": "project-name",
  "features": {
    "ghcr.io/devcontainers/features/nix:1": {
      "extraNixConfig": "experimental-features = nix-command flakes"
    }
  },
  "mounts": [
    "source=nix-store,target=/nix,type=volume"
  ],
  "postCreateCommand": "direnv allow && nix develop"
}

Enforcement Integration

Pre-commit Hook

# .pre-commit-config.yaml