28 lines
1.8 KiB
Markdown
28 lines
1.8 KiB
Markdown
# Devil's Advocate Review — Project Conventions
|
|
|
|
## Critical rules (must never be violated)
|
|
|
|
- **Never update `system.stateVersion`** — it must remain at the original installation version. NixOS upgrades are done by updating the `channel` file, not `stateVersion`.
|
|
- **Never modify `secrets.yaml` directly** — these are SOPS-encrypted. Changes must be made via `nix-shell -p sops --run 'sops <file>'`.
|
|
- **No plaintext secrets in Nix files** — passwords, API keys, tokens, and private keys must use `sops.secrets`, never hardcoded strings.
|
|
|
|
## Architecture rules
|
|
|
|
- **Explicit module imports only** — no wildcard or directory-level imports. Each module must be imported by its explicit path.
|
|
- **Host structure** — each host in `hosts/<name>/` must have `configuration.nix` and `hardware-configuration.nix`. Symlinks `fleet.nix` and `utils/` point to root level.
|
|
- **Shared modules** go in `utils/modules/`, not duplicated across hosts.
|
|
- **Custom packages** in `utils/pkgs/` must include an `update.sh` script for automated version updates.
|
|
|
|
## Code style
|
|
|
|
- **Two-space indentation** in all Nix files.
|
|
- **Lower kebab-case** for file and directory naming.
|
|
- **Conventional Commits** format: `fix:`, `feat:`, `chore:`, with optional scope by host (e.g., `fix(mail):`).
|
|
- No "Generated with Claude Code" or "Co-Authored-By: Claude" footers in commits.
|
|
|
|
## Common review checks
|
|
|
|
- New network services must have corresponding `networking.firewall.allowedTCPPorts` or `allowedUDPPorts` entries.
|
|
- New `sops.secrets.<name>` references must have a corresponding entry in the host's `secrets.yaml` (or the relevant module's `secrets.yaml`).
|
|
- Changes to `utils/` affect all hosts — verify cross-host compatibility.
|
|
- Package modifications should be testable with a direct `nix-build`, not just `test-configuration`.
|