code-quality

name	code-quality
description	Always-applicable code quality rules for React/Next.js/TypeScript work in this repo. Triggers on ANY code authoring or review — component creation, refactoring, FSD slice placement, Next.js caching decisions, TS strictness, naming, a11y. Reference matching `rules/<prefix>-*.md` when violating or unsure.
license	MIT
metadata	{"author":"recipio","version":"0.1.0"}

Code Quality

Tier-2 (on-demand) detail for the always-on self-check block in CLAUDE.md (section "코드 작성 자가체크"). The inline block is the trigger; this folder holds the elaboration.

When to apply

Every code-authoring or code-reviewing task in the repo. The inline self-check fires first; if a rule is violated, unclear, or about to be violated, read the specific rules/<prefix>-<topic>.md file.

Rule prefixes

Prefix	Topic
size-	Component and function size limits
fsd-	Feature-Sliced Design layer placement
policy-	Human-error blockers (URL / env / keys / etc.)
nextjs-	Next.js cache, static/dynamic, server/client
react-	React Compiler-era memoization and effect hygiene
ts-	TypeScript strictness
naming-	High-payoff naming conventions
a11y-	Accessibility minimum bar

Quick reference

Size

• Component size limits — 100/150 hard, SRP signals
• Function complexity — 30 lines + branch / nesting / verb-pair / await flags
• Rule of three — extract on 3rd occurrence, not 2nd (premature abstraction prevention)

FSD

• 4-layer placement — shared / widget / _components/ / page
• Widget vs page-local — single-page → _components/, multi-page → widget/
• Entity vs feature boundary — mutations live in features

Policy (human-error blockers)

• URL and query strings — new URL / URLSearchParams
• TanStack Query keys — [domain, sub, ...ids] tuple
• Env via shared/config — no direct process.env
• Storage keys — constants module
• Z-index tokens — semantic names, no magic numbers
• Dates and numbers — single library, Intl.NumberFormat
• Nullish coalescing — ?? for defaults; || only for actual falsy semantics

Next.js

• Cache and revalidation — mutation → revalidate*; Request Memoization
• Dynamic vs static — static is default; recognize triggers
• Server vs client boundary — 'use client' at the lowest point; initialData

React (Compiler era)

• Compiler memoization — three legitimate useCallback cases
• Effect / state diet — derived computed, events handled, effects only for external sync

TypeScript

• any and as — any banned; as justified with a comment
• Non-null and union — no !; discriminated unions
• Discriminated unions at API boundary — translate correlated optionals into a union once at the seam
• Typed mapper extraction — inline literals hide dead fields; extract with explicit return type
• Type imports — avoid dist paths — derive from public hook via ReturnType, don't reach into pkg/dist/...

Naming

• Booleans, handlers, hooks — is/has/can/should, on*/handle*, use*
• Function verbs — get / fetch / load

A11y

• Interactive elements — native button, cursor-pointer, aria-label

File template

Every rule file uses this four-section shape:

• Symptom — what fails when the rule isn't followed
• Recommended pattern — short code example
• Anti-pattern — short code example
• Heuristic — when and how to self-check