---
description: How Cursor rules in this repository must be written and maintained.
globs: [".cursor/rules/**/*.mdc"]
alwaysApply: true
---

# Rule authoring — {{PROJECT_NAME}}

## Context
Rules are version-controlled contracts for AI assistants. Poor rules waste context and silently steer every edit.

## Constraints
- One focused concern per file; split broad topics instead of one mega-rule
- Every rule MUST have a clear `description` in frontmatter (one sentence)
- Prefer `alwaysApply: false` with **narrow** `globs` for domain rules — reserve `alwaysApply: true` for meta and safety
- `globs` must be as specific as possible — never `["**/*"]` unless tooling requires it
- Code samples in rules MUST be valid for this project (Dart/Flutter/YAML as appropriate)
- Deprecated guidance is removed, not left commented out
- Each substantive rule includes **Context** (why), **Constraints** (must/must not), and where helpful **Patterns** / **Anti-patterns**

## Anti-patterns
- Domain rules (testing, l10n, a feature) with `alwaysApply: true` — burns context
- Rules with no concrete examples when the topic is code-facing
- Stale feature rules after modules are removed — run `tool/cursor_audit.sh` periodically
