---
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.
- Name permanent artifacts by product capability, not development history.
- 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 (STATE, CONTEXT, PLAN 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`.