---
alwaysApply: true
---

# Code Quality

## Principles

- Functions do one thing. If it needs a section comment, extract that section.
- No magic values — extract numbers, strings, and config to named constants.
- Handle errors at the boundary. Don't catch and re-throw without adding context.
- No premature abstractions. Three similar lines > a helper used once.
- Don't add features or "improve" things beyond what was asked.
- No dead code or commented-out blocks. Git has history.
- Composition over inheritance.

## Naming

- **Files**: PascalCase for components/classes (`UserProfile.tsx`), kebab-case for utilities/directories (`date-utils.ts`)
- **Booleans**: `is`, `has`, `should`, `can` prefix — `isLoading`, `hasPermission`
- **Functions**: verb-first — `getUser`, `validateEmail`, `handleSubmit`
- **Handlers/callbacks**: `handle*` internally, `on*` as props — `handleClick` / `onClick`
- **Factories**: `create*` — `createUser`. **Converters**: `to*` — `toJSON`. **Predicates**: `is*`/`has*`
- **Constants**: `SCREAMING_SNAKE` — `MAX_RETRIES`, `API_BASE_URL`
- **Enums**: PascalCase members — `Status.Active`
- **Abbreviations**: only universally known (`id`, `url`, `api`, `db`, `config`, `auth`). Acronyms as words: `userId` not `userID`

## Comments

- **WHY**, never WHAT. If the code needs a "what" comment, rename instead.
- Comment: non-obvious decisions, workarounds with issue links, regex patterns, perf tricks
- Don't comment: obvious code, self-explanatory function names, section dividers, type info the language provides
- No commented-out code — delete it. No journal comments — git blame does this.
- API docs (JSDoc, docstrings) at module boundaries only, not every internal function

## Code Markers

| Marker | Use |
|---|---|
| `TODO(author): desc (#issue)` | Planned work |
| `FIXME(author): desc (#issue)` | Known bugs |
| `HACK(author): desc (#issue)` | Ugly workarounds (explain the proper fix) |
| `NOTE: desc` | Non-obvious context for future readers |

Must have an owner + issue link. Don't commit TODOs you can do now. Never use `XXX`, `TEMP`, `REMOVEME`.

## File Organization

- **Imports**: builtins → external → internal → relative → types. Blank line between groups.
- **Exports**: named over default. Export at declaration site. One component/class per file.
- **Functions**: public first, then private helpers in call order. Top-to-bottom reads as a story.