Code style

• Comments: only for the non-obvious — a hidden constraint, a subtle invariant, a workaround for a specific bug, behavior that would surprise a reader. If removing the comment wouldn't confuse a future reader, don't write it; well-named identifiers and straightforward code don't need one. Before writing one — or when trimming an existing one for length — check whether it says anything beyond what the identifier names or the next few lines of code already show. A guard called alreadyNudged/hasRun returning early on its own .done/.called flag needs no comment restating "skip if already done"; explaining reasoning any engineer already has by default (a DB leak of plaintext credentials is bad) doesn't count as non-obvious either — both are a restatement, just dressed differently, and a shorter restatement is still a restatement. When a comment is warranted: one line, glued to the specific line it explains — not a paragraph block sitting above several lines. If a comment would cover multiple following lines, split it into one short comment per line instead. Reserve multi-line comments for a single genuinely complex decision, not a summary of a block.
• Never silence an ESLint (or other linter) warning with a disable comment — restructure the code so the rule is satisfied for real. In particular, react-hooks/set-state-in-effect almost always means the state belongs elsewhere: derive it at render time instead of mirroring a value into state, batch a dependent setState into the same event handler that triggers the change instead of a separate effect watching for it, or key a child component by the prop that should reset it. A useRef used only to dodge a stale-closure warning is the same problem — fix the data flow (pass the current value explicitly, or fold the trigger into the effect's own dependency array) rather than patching around it with a ref.
• Centralize a shared type or config value (e.g. into a project's central types file, mirroring existing patterns such as a const-object-plus-derived-type pair) only once a second module actually imports it. A type or value used by exactly one file — a React Context's value shape, a single route's helper — belongs next to its sole consumer, not preemptively centralized. Don't export anything with no consumer outside its own file; add the keyword when a real second consumer shows up, not in case one might.
• Before wrapping a custom route, hook, or helper around a third-party/vendor library, check whether the library already exposes that capability directly — a built-in endpoint, a client method, a plugin hook. Bridging only earns its keep when the vendor's own surface genuinely doesn't cover the need (e.g. it isn't typed for your framework, or real app-specific logic has to sit on top of it).
• SCSS: nest BEM elements/modifiers under their block with &__element/&--modifier (matching every existing partial), not flat top-level .block__element { } selectors.

Migrations

• Never edit a migration file once it's shipped — check whether its content already matches dev/prod before touching it. The migration runner tracks what's applied by filename, not content, so editing an already-applied migration is invisible everywhere it already ran and silently changes schema only in fresh environments that haven't run it yet. Any further change, however small, goes in a new migration file.
• Any migration that mutates existing rows (UPDATE/DELETE/backfill INSERT, not schema-only DDL) must log how many rows it actually affected — per statement if it loops over multiple targets, plus a total. migrate.ts only prints ✓ <name> on success, which means "the transaction committed," not "it did what you expected" — a WHERE/FROM clause that silently matches zero rows still reports success. Use Kysely's executeTakeFirst() result's numUpdatedRows/numDeletedRows (or a manual counter for raw sql statements) and console.log it inside up().

Commit messages

• Subject line: 50 characters is the target, 72 is the hard limit — count it before committing. Applies to every commit in this repo (human or AI-authored), not just version-bump commits.
• Subject line only — no body/description text below it, even to explain a non-obvious "why." If that context is worth keeping, put it in the PR/MR description instead.
• Never append a Claude-Session: (or any AI-attribution) link or footer to a commit message — omit it entirely, even if a default template suggests otherwise. This overrides that default for this repo.

Branch names

• Format: <type>/<short-kebab-description> (e.g. fix/silent-tool-rejections, feat/repo-memories). type is one of the Conventional Commits types already used in this repo's commit subjects: feat, fix, chore, refactor, docs, style, perf, test.