clean-code

name	clean-code
description	Clean Code rules for TypeScript, React, and Next.js. Apply when writing, refactoring, or reviewing code - naming, small functions, no any, early returns, typed errors, plus tech-specific rules for React 19, Next.js 15/16, Zustand v5, TanStack Query v5.
argument-hint	[feature/file]

Clean Code Rules

Follow these rules as much as possible whenever you write, refactor, or review code. They are guidelines, not a workflow: apply them inline, in every edit. When a rule conflicts with the existing codebase style, match the codebase and mention the tension.

If a target (feature, file, directory) is given as argument, read that code and bring it in line with these rules, then verify with the project's build/lint/test commands.

Core rules

Naming

• Names reveal intent: currentDate, not d; doubleValue(value), not fn(x).
• Booleans read as predicates: isLoading, hasAccess, canEdit.
• Functions are verbs (fetchUser), values are nouns (userProfile).
• No abbreviations except universally known ones (id, url, api).

Functions & components

• Single responsibility: one thing per function/component. If describing it needs "and", split it.
• Functions < 20 lines, components < 150 lines as a soft ceiling.
• Early returns over nested if/else; max ~2 levels of nesting.
• Prefer pure functions; push side effects to the edges.
• Extract complex conditions into named booleans or predicates.

DRY & simplicity

• Rule of 3: abstract on the third repetition, not the first.
• KISS: readable beats clever. Prefer the boring solution.
• Delete dead code and commented-out code; git remembers.
• No magic numbers/strings: use named constants.

TypeScript

• Never any: use unknown + narrowing, generics, or discriminated unions.
• satisfies to validate without widening; as const satisfies for literal maps.
• Discriminated unions for state ({ status: 'loading' } | { status: 'success'; data: T } | ...) with exhaustive switch (never check in default).
• Utility types over hand-rolled shapes: Partial for patches, Pick/Omit for DTOs, Record for dictionaries.
• Branded types when mixing primitives is dangerous (UserId vs ProductId).
• Derive types from values (ReturnType, typeof, schema inference) rather than duplicating them.

Error handling

• Typed error classes (AppError with code/statusCode) or a Result<T, E> type; never swallow errors silently.
• Fail fast: validate inputs at the boundary, throw/return early.
• No console.log left in committed code; use the project's logger.

Control flow & data

• Immutability by default: const, spread/toSorted/toReversed over mutation.
• Prefer map/filter/reduce chains when they stay readable; a plain loop when they don't.
• Handle the error/empty/loading cases first, happy path last and unindented.

File organization

• One component per file; feature-based folders (features/auth/{components,hooks,utils}).
• Import order: external → internal absolute (@/) → relative → import type last.
• Colocate tests next to the code they test.

Tech-specific rules

When the code you're touching uses one of these, load the matching reference and follow it:

Reference	Load when touching
references/general-clean-code.md	Full TypeScript detail: branded types, template literal types, Result, tsconfig strictness
references/react-clean-code.md	React components/hooks: React 19 (use, useActionState, useOptimistic, ref-as-prop, no manual memo), Suspense, error boundaries
references/nextjs-clean-code.md	Next.js App Router: Server Components, Server Actions, caching, async params (15+)
references/zustand-best-practices.md	Zustand stores: v5 syntax, slices, selectors, middleware
references/tanstack-query-best-practices.md	Data fetching: query key factories, useSuspenseQuery, mutations, invalidation — and any useEffect-based fetching to migrate

Anti-patterns — always fix on sight

Anti-pattern	Fix
any	unknown, generics, discriminated unions
useEffect for data fetching	TanStack Query (or Server Components)
useState for server data	TanStack Query
Props drilling 3+ levels	Composition, Zustand, or Context
Manual useMemo/useCallback/memo everywhere	React Compiler (React 19) — remove unless measured
forwardRef	ref as prop (React 19)
Deep nesting	Early returns
Magic numbers	Named constants
Commented-out code	Delete it

Verification

After applying rules to existing code, run the project's typecheck/build and tests (and lint if configured). Never leave the codebase in a broken state to satisfy a style rule.