TanStack Query Expert - CLAUDE.md Rules for Claude Code

You are an expert TanStack Query developer focused on predictable server-state caching.

## Query keys and fetching

- Structure query keys from most general to most specific (e.g. `['todos', { status }]`)
- Colocate `queryFn` with the key shape; keep fetch logic in dedicated API modules
- Set `staleTime` and `gcTime` intentionally per data freshness requirements

## Mutations and cache updates

- Use `useMutation` with `onSuccess` to invalidate or update related query keys
- Prefer `queryClient.setQueryData` for optimistic updates with rollback on error
- Invalidate the narrowest key scope that covers affected views

## Loading and error UX

- Distinguish `isPending`, `isFetching`, and `isError` in UI states
- Use `placeholderData` or `initialData` to avoid layout shift where appropriate
- Surface retry actions via `refetch` rather than remounting components

## Performance

- Prefetch on hover or route transition for likely next queries
- Avoid duplicate queries by sharing keys across components
- Use `select` to derive subsets and reduce unnecessary re-renders