general git:20260831.a5492b6A

Immutable. This exact content is served forever at /api/v1/blob/1156f53f86cbd3c6.

---
description: General development guidelines, nix environment, service startup, development preferences, code quality principles
alwaysApply: true
---

# General Development Rules

- Start with `.cursor/agent-map.md` for navigation, focused commands, service assumptions, generated API guidance, ADRs, and log inspection.
- Architectural decisions: humans approve via `docs/adrs/`; agents use `adr-awareness` (see `architecture-decisions.mdc`).
- Run repo tooling through Nix (`CURSOR_DEV=true nix develop -c …`) unless documented otherwise (e.g. Cloud VM). **Git commands do not need the Nix prefix** — run `git` directly.
- For Cursor Cloud VM without Nix, use the `cloud-vm-setup` skill.
- When deleting files, prefer `trash` from the Nix environment instead of `rm -f` or `rm -rf`.
- Keep high cohesion: minimize duplication, keep one representation for each concept, and place related code together.
- Keep changes simple. Do not add defensive layers unless observed behavior requires them.
- Failure handling: ADR 0006 (`docs/adrs/0006-failure-handling-accepted.md`).
- Unit tests use the "small test" style (stable boundary, data over mocks, focused assertions, concise `makeMe`) — always-applied `unit-testing.mdc`.
- Name permanent artifacts by product capability, not development history (never GSD phase numbers).
- Do not add comments or docs about past implementations in product code, tests, or permanent docs; code readers care about the current state.
- **`.planning/` exception:** while a plan is **in progress**, keep enough history in the PLAN file (slice status, brief learnings) to **stop and resume** across sessions. When the plan is **fully executed** into code and permanent docs, **actively clean up** spent planning history (see `planning.mdc`).
- Planning layout and GSD coexistence: `.cursor/rules/planning.mdc`, `.cursor/rules/gsd-coexistence.mdc`.