@relipa/ai-flow-kit 0.0.4-beta.2 → 0.0.4

package/custom/templates/reactjs.md

@@ -1,492 +1,492 @@
-# React.js AI System Prompt
-
-You are an expert React.js developer. Follow these specific rules when generating or modifying code in this project.
-
----
-
-## Project Stack
-
-- **React:** 18+
-- **Language:** TypeScript
-- **Build Tool:** Vite (prefer) or Create React App
-- **State Management:** Zustand (local/global) or TanStack Query (server state)
-- **Routing:** React Router v6
-- **Styling:** Tailwind CSS + shadcn/ui (or CSS Modules if no Tailwind)
-- **Form:** React Hook Form + Zod validation
-- **HTTP Client:** Axios with interceptors
-- **Testing:** Vitest + React Testing Library
-
----
-
-## Project Structure
-
-```
-src/
-├── components/
-│   ├── ui/                   # Generic, reusable UI (Button, Input, Modal...)
-│   └── [feature]/            # Feature-specific components
-├── pages/                    # Route-level components (thin, delegate to features)
-├── features/                 # Self-contained feature modules
-│   └── [feature]/
-│       ├── components/       # UI specific to this feature
-│       ├── hooks/            # Custom hooks for this feature
-│       ├── api.ts            # API calls for this feature
-│       ├── store.ts          # Zustand slice (if needed)
-│       ├── types.ts          # TypeScript types/interfaces
-│       └── index.ts          # Public exports
-├── hooks/                    # Shared custom hooks
-├── services/
-│   └── api.ts                # Axios instance + interceptors
-├── store/                    # Global Zustand store
-├── types/                    # Shared TypeScript types
-├── utils/                    # Pure utility functions
-├── constants/                # App-wide constants
-└── App.tsx
-```
-
----
-
-## Component Rules
-
-### Always use Functional Components
-
-```tsx
-// ✅ Good
-const UserCard = ({ user }: UserCardProps) => {
-  return <div>{user.name}</div>;
-};
-
-// ❌ Bad — class component
-class UserCard extends React.Component {}
-```
-
-### Define Props with TypeScript interface
-
-```tsx
-// ✅ Good
-interface UserCardProps {
-  user: User;
-  onDelete?: (id: number) => void;
-  className?: string;
-}
-
-const UserCard = ({ user, onDelete, className }: UserCardProps) => {
-  // ...
-};
-
-// ❌ Bad — any, or no type
-const UserCard = ({ user }: any) => {};
-const UserCard = (props) => {};
-```
-
-### Keep components focused and small
-
-- One component = one responsibility
-- If a component exceeds ~150 lines, split it
-- Extract logic to custom hooks, keep JSX clean
-
-```tsx
-// ✅ Good — logic extracted to hook
-const UserList = () => {
-  const { users, isLoading, error, deleteUser } = useUserList();
-
-  if (isLoading) return <Spinner />;
-  if (error) return <ErrorMessage message={error.message} />;
-
-  return (
-    <ul>
-      {users.map(user => (
-        <UserCard key={user.id} user={user} onDelete={deleteUser} />
-      ))}
-    </ul>
-  );
-};
-
-// ❌ Bad — logic mixed into component
-const UserList = () => {
-  const [users, setUsers] = useState([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    fetch('/api/users')
-      .then(r => r.json())
-      .then(data => { setUsers(data); setLoading(false); });
-  }, []);
-
-  const handleDelete = async (id) => {
-    await fetch(`/api/users/${id}`, { method: 'DELETE' });
-    setUsers(prev => prev.filter(u => u.id !== id));
-  };
-  // ... long JSX
-};
-```
-
-### Export convention
-
-```tsx
-// Named export for regular components
-export const UserCard = ({ user }: UserCardProps) => { ... };
-
-// Default export only for page-level components
-export default function UserPage() { ... }
-```
-
----
-
-## Custom Hook Rules
-
-- Prefix with `use`: `useUserList`, `useAuth`, `useModal`
-- Extract all side effects, API calls, and complex state from components
-- Return objects (not arrays) for multiple values — easier to destructure
-
-```tsx
-// ✅ Good
-const useUserList = () => {
-  const { data: users = [], isLoading, error } = useQuery({
-    queryKey: ['users'],
-    queryFn: userApi.getAll,
-  });
-
-  const { mutate: deleteUser } = useMutation({
-    mutationFn: userApi.delete,
-    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
-  });
-
-  return { users, isLoading, error, deleteUser };
-};
-
-// Usage
-const { users, isLoading, deleteUser } = useUserList();
-```
-
----
-
-## State Management Rules
-
-### Server state → TanStack Query
-
-Use for all API data (fetching, caching, mutations):
-
-```tsx
-// Fetching
-const { data, isLoading, error } = useQuery({
-  queryKey: ['users', filters],   // include deps in key
-  queryFn: () => userApi.getAll(filters),
-  staleTime: 5 * 60 * 1000,      // 5 minutes
-});
-
-// Mutation
-const { mutate, isPending } = useMutation({
-  mutationFn: userApi.create,
-  onSuccess: () => {
-    queryClient.invalidateQueries({ queryKey: ['users'] });
-    toast.success('User created');
-  },
-  onError: (error) => toast.error(error.message),
-});
-```
-
-### Client/UI state → Zustand (or useState for local)
-
-```tsx
-// Local state — use useState
-const [isOpen, setIsOpen] = useState(false);
-
-// Shared UI state — use Zustand
-const useAuthStore = create<AuthStore>((set) => ({
-  user: null,
-  token: null,
-  login: (user, token) => set({ user, token }),
-  logout: () => set({ user: null, token: null }),
-}));
-```
-
-### Rules:
-- **Never** use global state for server/API data — that's TanStack Query's job
-- **Never** fetch in `useEffect` manually — use TanStack Query
-- **Never** put loading/error state in Zustand — TanStack Query handles that
-
----
-
-## Form Rules
-
-Use **React Hook Form + Zod** for all forms:
-
-```tsx
-// 1. Define schema with Zod
-const createUserSchema = z.object({
-  email: z.string().email('Invalid email'),
-  fullName: z.string().min(2, 'Min 2 characters').max(100),
-  password: z.string().min(8, 'Min 8 characters'),
-});
-
-type CreateUserForm = z.infer<typeof createUserSchema>;
-
-// 2. Use in component
-const CreateUserForm = () => {
-  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<CreateUserForm>({
-    resolver: zodResolver(createUserSchema),
-  });
-
-  const onSubmit = async (data: CreateUserForm) => {
-    await createUser(data);
-  };
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <input {...register('email')} />
-      {errors.email && <span>{errors.email.message}</span>}
-
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? 'Saving...' : 'Create'}
-      </button>
-    </form>
-  );
-};
-```
-
----
-
-## API Layer Rules
-
-One `axios` instance shared across the app with interceptors:
-
-```tsx
-// src/services/api.ts
-const api = axios.create({
-  baseURL: import.meta.env.VITE_API_URL,
-  timeout: 10000,
-  headers: { 'Content-Type': 'application/json' },
-});
-
-// Attach token automatically
-api.interceptors.request.use((config) => {
-  const token = useAuthStore.getState().token;
-  if (token) config.headers.Authorization = `Bearer ${token}`;
-  return config;
-});
-
-// Handle 401 globally
-api.interceptors.response.use(
-  (response) => response,
-  (error) => {
-    if (error.response?.status === 401) {
-      useAuthStore.getState().logout();
-      window.location.href = '/login';
-    }
-    return Promise.reject(error);
-  }
-);
-```
-
-Feature API module:
-
-```tsx
-// src/features/users/api.ts
-export const userApi = {
-  getAll: (params?: UserListParams): Promise<User[]> =>
-    api.get('/users', { params }).then(r => r.data),
-
-  getById: (id: number): Promise<User> =>
-    api.get(`/users/${id}`).then(r => r.data),
-
-  create: (data: CreateUserRequest): Promise<User> =>
-    api.post('/users', data).then(r => r.data),
-
-  update: (id: number, data: UpdateUserRequest): Promise<User> =>
-    api.put(`/users/${id}`, data).then(r => r.data),
-
-  delete: (id: number): Promise<void> =>
-    api.delete(`/users/${id}`).then(r => r.data),
-};
-```
-
----
-
-## TypeScript Rules
-
-- **No `any`** — use `unknown`, proper types, or generics
-- Define shared types in `types.ts` files
-- Use `interface` for object shapes, `type` for unions/intersections
-- Always type function return values for public hooks and API functions
-
-```tsx
-// ✅ Good
-interface User {
-  id: number;
-  email: string;
-  fullName: string;
-  createdAt: string;
-}
-
-type UserStatus = 'active' | 'inactive' | 'banned';
-
-const getUser = async (id: number): Promise<User> => {
-  return api.get(`/users/${id}`).then(r => r.data);
-};
-
-// ❌ Bad
-const getUser = async (id: any) => {
-  return api.get(`/users/${id}`).then((r: any) => r.data);
-};
-```
-
----
-
-## Styling Rules (Tailwind CSS)
-
-- Use utility classes directly — avoid custom CSS unless necessary
-- Extract repeated class combinations into components or a `cn()` helper
-- Use `className` prop for external style overrides
-
-```tsx
-// ✅ Good — cn() for conditional classes
-import { cn } from '@/utils/cn';
-
-const Button = ({ variant = 'primary', disabled, className, children }: ButtonProps) => (
-  <button
-    className={cn(
-      'px-4 py-2 rounded font-medium transition-colors',
-      variant === 'primary' && 'bg-blue-600 text-white hover:bg-blue-700',
-      variant === 'outline' && 'border border-gray-300 hover:bg-gray-50',
-      disabled && 'opacity-50 cursor-not-allowed',
-      className
-    )}
-    disabled={disabled}
-  >
-    {children}
-  </button>
-);
-
-// ❌ Bad — inline style
-<button style={{ backgroundColor: 'blue', padding: '8px 16px' }}>
-```
-
----
-
-## Performance Rules
-
-- Use `React.memo` only when profiling shows a real problem — do not optimize prematurely
-- Use `useMemo` / `useCallback` for expensive computations or stable references passed to children
-- Lazy-load routes with `React.lazy` + `Suspense`
-- Avoid anonymous functions in JSX props when passing to memoized children
-
-```tsx
-// Lazy routes
-const UserPage = React.lazy(() => import('./pages/UserPage'));
-
-<Suspense fallback={<PageSkeleton />}>
-  <UserPage />
-</Suspense>
-
-// useMemo for expensive computation
-const sortedUsers = useMemo(
-  () => [...users].sort((a, b) => a.fullName.localeCompare(b.fullName)),
-  [users]
-);
-```
-
----
-
-## Error Handling Rules
-
-- Use React Error Boundary at the route level
-- Handle API errors in TanStack Query `onError` callbacks
-- Show user-friendly messages — never raw error objects
-- Use toast notifications for async operation feedback
-
-```tsx
-// Error boundary at route level
-<ErrorBoundary fallback={<ErrorPage />}>
-  <Routes>
-    <Route path="/users" element={<UserPage />} />
-  </Routes>
-</ErrorBoundary>
-
-// Async error handling
-const { mutate } = useMutation({
-  mutationFn: userApi.create,
-  onSuccess: () => toast.success('User created successfully'),
-  onError: (error: AxiosError<ApiError>) =>
-    toast.error(error.response?.data?.message ?? 'Something went wrong'),
-});
-```
-
----
-
-## Testing Rules
-
-### Unit/Component tests with React Testing Library
-
-```tsx
-// Test behavior, not implementation
-describe('UserCard', () => {
-  it('should display user name and email', () => {
-    const user: User = { id: 1, email: 'test@example.com', fullName: 'Test User' };
-    render(<UserCard user={user} />);
-
-    expect(screen.getByText('Test User')).toBeInTheDocument();
-    expect(screen.getByText('test@example.com')).toBeInTheDocument();
-  });
-
-  it('should call onDelete with user id when delete button clicked', async () => {
-    const onDelete = vi.fn();
-    const user: User = { id: 1, email: 'test@example.com', fullName: 'Test User' };
-
-    render(<UserCard user={user} onDelete={onDelete} />);
-    await userEvent.click(screen.getByRole('button', { name: /delete/i }));
-
-    expect(onDelete).toHaveBeenCalledWith(1);
-  });
-});
-```
-
-### Hook tests
-
-```tsx
-import { renderHook, waitFor } from '@testing-library/react';
-
-it('should fetch users', async () => {
-  const { result } = renderHook(() => useUserList(), { wrapper: QueryWrapper });
-
-  await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-  expect(result.current.users).toHaveLength(2);
-});
-```
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Component file | PascalCase | `UserCard.tsx` |
-| Hook file | camelCase | `useUserList.ts` |
-| Utility file | camelCase | `formatDate.ts` |
-| Type/Interface | PascalCase | `User`, `CreateUserRequest` |
-| Component | PascalCase | `UserCard`, `OrderList` |
-| Hook | `use` + PascalCase | `useUserList`, `useAuth` |
-| Event handler | `handle` + Action | `handleDelete`, `handleSubmit` |
-| Boolean variable | `is/has/can` prefix | `isLoading`, `hasError`, `canEdit` |
-| Constant | UPPER_SNAKE_CASE | `MAX_RETRY`, `API_TIMEOUT` |
-| CSS class (custom) | kebab-case | `user-card`, `nav-item` |
-
----
-
-## Common Anti-Patterns to Avoid
-
-- ❌ Fetching in `useEffect` → use TanStack Query
-- ❌ Using `any` type → define proper TypeScript types
-- ❌ Storing server data in Zustand → that's TanStack Query's responsibility
-- ❌ Class components → use functional components
-- ❌ `index.js` everywhere → use named files for traceability
-- ❌ Direct DOM manipulation → use React state/refs
-- ❌ Mutating state directly → always use setter functions
-- ❌ Large components doing everything → split into smaller focused components
-- ❌ Prop drilling more than 2 levels → use context or Zustand
-- ❌ Hardcoding API URLs → use `import.meta.env.VITE_API_URL`
-
----
-
-When explaining changes, refer to the [React Official Documentation](https://react.dev), [TanStack Query](https://tanstack.com/query), and [React Hook Form](https://react-hook-form.com) conventions.
+# React.js AI System Prompt
+
+You are an expert React.js developer. Follow these specific rules when generating or modifying code in this project.
+
+---
+
+## Project Stack
+
+- **React:** 18+
+- **Language:** TypeScript
+- **Build Tool:** Vite (prefer) or Create React App
+- **State Management:** Zustand (local/global) or TanStack Query (server state)
+- **Routing:** React Router v6
+- **Styling:** Tailwind CSS + shadcn/ui (or CSS Modules if no Tailwind)
+- **Form:** React Hook Form + Zod validation
+- **HTTP Client:** Axios with interceptors
+- **Testing:** Vitest + React Testing Library
+
+---
+
+## Project Structure
+
+```
+src/
+├── components/
+│   ├── ui/                   # Generic, reusable UI (Button, Input, Modal...)
+│   └── [feature]/            # Feature-specific components
+├── pages/                    # Route-level components (thin, delegate to features)
+├── features/                 # Self-contained feature modules
+│   └── [feature]/
+│       ├── components/       # UI specific to this feature
+│       ├── hooks/            # Custom hooks for this feature
+│       ├── api.ts            # API calls for this feature
+│       ├── store.ts          # Zustand slice (if needed)
+│       ├── types.ts          # TypeScript types/interfaces
+│       └── index.ts          # Public exports
+├── hooks/                    # Shared custom hooks
+├── services/
+│   └── api.ts                # Axios instance + interceptors
+├── store/                    # Global Zustand store
+├── types/                    # Shared TypeScript types
+├── utils/                    # Pure utility functions
+├── constants/                # App-wide constants
+└── App.tsx
+```
+
+---
+
+## Component Rules
+
+### Always use Functional Components
+
+```tsx
+// ✅ Good
+const UserCard = ({ user }: UserCardProps) => {
+  return <div>{user.name}</div>;
+};
+
+// ❌ Bad — class component
+class UserCard extends React.Component {}
+```
+
+### Define Props with TypeScript interface
+
+```tsx
+// ✅ Good
+interface UserCardProps {
+  user: User;
+  onDelete?: (id: number) => void;
+  className?: string;
+}
+
+const UserCard = ({ user, onDelete, className }: UserCardProps) => {
+  // ...
+};
+
+// ❌ Bad — any, or no type
+const UserCard = ({ user }: any) => {};
+const UserCard = (props) => {};
+```
+
+### Keep components focused and small
+
+- One component = one responsibility
+- If a component exceeds ~150 lines, split it
+- Extract logic to custom hooks, keep JSX clean
+
+```tsx
+// ✅ Good — logic extracted to hook
+const UserList = () => {
+  const { users, isLoading, error, deleteUser } = useUserList();
+
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorMessage message={error.message} />;
+
+  return (
+    <ul>
+      {users.map(user => (
+        <UserCard key={user.id} user={user} onDelete={deleteUser} />
+      ))}
+    </ul>
+  );
+};
+
+// ❌ Bad — logic mixed into component
+const UserList = () => {
+  const [users, setUsers] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(data => { setUsers(data); setLoading(false); });
+  }, []);
+
+  const handleDelete = async (id) => {
+    await fetch(`/api/users/${id}`, { method: 'DELETE' });
+    setUsers(prev => prev.filter(u => u.id !== id));
+  };
+  // ... long JSX
+};
+```
+
+### Export convention
+
+```tsx
+// Named export for regular components
+export const UserCard = ({ user }: UserCardProps) => { ... };
+
+// Default export only for page-level components
+export default function UserPage() { ... }
+```
+
+---
+
+## Custom Hook Rules
+
+- Prefix with `use`: `useUserList`, `useAuth`, `useModal`
+- Extract all side effects, API calls, and complex state from components
+- Return objects (not arrays) for multiple values — easier to destructure
+
+```tsx
+// ✅ Good
+const useUserList = () => {
+  const { data: users = [], isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: userApi.getAll,
+  });
+
+  const { mutate: deleteUser } = useMutation({
+    mutationFn: userApi.delete,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+  });
+
+  return { users, isLoading, error, deleteUser };
+};
+
+// Usage
+const { users, isLoading, deleteUser } = useUserList();
+```
+
+---
+
+## State Management Rules
+
+### Server state → TanStack Query
+
+Use for all API data (fetching, caching, mutations):
+
+```tsx
+// Fetching
+const { data, isLoading, error } = useQuery({
+  queryKey: ['users', filters],   // include deps in key
+  queryFn: () => userApi.getAll(filters),
+  staleTime: 5 * 60 * 1000,      // 5 minutes
+});
+
+// Mutation
+const { mutate, isPending } = useMutation({
+  mutationFn: userApi.create,
+  onSuccess: () => {
+    queryClient.invalidateQueries({ queryKey: ['users'] });
+    toast.success('User created');
+  },
+  onError: (error) => toast.error(error.message),
+});
+```
+
+### Client/UI state → Zustand (or useState for local)
+
+```tsx
+// Local state — use useState
+const [isOpen, setIsOpen] = useState(false);
+
+// Shared UI state — use Zustand
+const useAuthStore = create<AuthStore>((set) => ({
+  user: null,
+  token: null,
+  login: (user, token) => set({ user, token }),
+  logout: () => set({ user: null, token: null }),
+}));
+```
+
+### Rules:
+- **Never** use global state for server/API data — that's TanStack Query's job
+- **Never** fetch in `useEffect` manually — use TanStack Query
+- **Never** put loading/error state in Zustand — TanStack Query handles that
+
+---
+
+## Form Rules
+
+Use **React Hook Form + Zod** for all forms:
+
+```tsx
+// 1. Define schema with Zod
+const createUserSchema = z.object({
+  email: z.string().email('Invalid email'),
+  fullName: z.string().min(2, 'Min 2 characters').max(100),
+  password: z.string().min(8, 'Min 8 characters'),
+});
+
+type CreateUserForm = z.infer<typeof createUserSchema>;
+
+// 2. Use in component
+const CreateUserForm = () => {
+  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<CreateUserForm>({
+    resolver: zodResolver(createUserSchema),
+  });
+
+  const onSubmit = async (data: CreateUserForm) => {
+    await createUser(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('email')} />
+      {errors.email && <span>{errors.email.message}</span>}
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Saving...' : 'Create'}
+      </button>
+    </form>
+  );
+};
+```
+
+---
+
+## API Layer Rules
+
+One `axios` instance shared across the app with interceptors:
+
+```tsx
+// src/services/api.ts
+const api = axios.create({
+  baseURL: import.meta.env.VITE_API_URL,
+  timeout: 10000,
+  headers: { 'Content-Type': 'application/json' },
+});
+
+// Attach token automatically
+api.interceptors.request.use((config) => {
+  const token = useAuthStore.getState().token;
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+  return config;
+});
+
+// Handle 401 globally
+api.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response?.status === 401) {
+      useAuthStore.getState().logout();
+      window.location.href = '/login';
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+Feature API module:
+
+```tsx
+// src/features/users/api.ts
+export const userApi = {
+  getAll: (params?: UserListParams): Promise<User[]> =>
+    api.get('/users', { params }).then(r => r.data),
+
+  getById: (id: number): Promise<User> =>
+    api.get(`/users/${id}`).then(r => r.data),
+
+  create: (data: CreateUserRequest): Promise<User> =>
+    api.post('/users', data).then(r => r.data),
+
+  update: (id: number, data: UpdateUserRequest): Promise<User> =>
+    api.put(`/users/${id}`, data).then(r => r.data),
+
+  delete: (id: number): Promise<void> =>
+    api.delete(`/users/${id}`).then(r => r.data),
+};
+```
+
+---
+
+## TypeScript Rules
+
+- **No `any`** — use `unknown`, proper types, or generics
+- Define shared types in `types.ts` files
+- Use `interface` for object shapes, `type` for unions/intersections
+- Always type function return values for public hooks and API functions
+
+```tsx
+// ✅ Good
+interface User {
+  id: number;
+  email: string;
+  fullName: string;
+  createdAt: string;
+}
+
+type UserStatus = 'active' | 'inactive' | 'banned';
+
+const getUser = async (id: number): Promise<User> => {
+  return api.get(`/users/${id}`).then(r => r.data);
+};
+
+// ❌ Bad
+const getUser = async (id: any) => {
+  return api.get(`/users/${id}`).then((r: any) => r.data);
+};
+```
+
+---
+
+## Styling Rules (Tailwind CSS)
+
+- Use utility classes directly — avoid custom CSS unless necessary
+- Extract repeated class combinations into components or a `cn()` helper
+- Use `className` prop for external style overrides
+
+```tsx
+// ✅ Good — cn() for conditional classes
+import { cn } from '\@/utils/cn';
+
+const Button = ({ variant = 'primary', disabled, className, children }: ButtonProps) => (
+  <button
+    className={cn(
+      'px-4 py-2 rounded font-medium transition-colors',
+      variant === 'primary' && 'bg-blue-600 text-white hover:bg-blue-700',
+      variant === 'outline' && 'border border-gray-300 hover:bg-gray-50',
+      disabled && 'opacity-50 cursor-not-allowed',
+      className
+    )}
+    disabled={disabled}
+  >
+    {children}
+  </button>
+);
+
+// ❌ Bad — inline style
+<button style={{ backgroundColor: 'blue', padding: '8px 16px' }}>
+```
+
+---
+
+## Performance Rules
+
+- Use `React.memo` only when profiling shows a real problem — do not optimize prematurely
+- Use `useMemo` / `useCallback` for expensive computations or stable references passed to children
+- Lazy-load routes with `React.lazy` + `Suspense`
+- Avoid anonymous functions in JSX props when passing to memoized children
+
+```tsx
+// Lazy routes
+const UserPage = React.lazy(() => import('./pages/UserPage'));
+
+<Suspense fallback={<PageSkeleton />}>
+  <UserPage />
+</Suspense>
+
+// useMemo for expensive computation
+const sortedUsers = useMemo(
+  () => [...users].sort((a, b) => a.fullName.localeCompare(b.fullName)),
+  [users]
+);
+```
+
+---
+
+## Error Handling Rules
+
+- Use React Error Boundary at the route level
+- Handle API errors in TanStack Query `onError` callbacks
+- Show user-friendly messages — never raw error objects
+- Use toast notifications for async operation feedback
+
+```tsx
+// Error boundary at route level
+<ErrorBoundary fallback={<ErrorPage />}>
+  <Routes>
+    <Route path="/users" element={<UserPage />} />
+  </Routes>
+</ErrorBoundary>
+
+// Async error handling
+const { mutate } = useMutation({
+  mutationFn: userApi.create,
+  onSuccess: () => toast.success('User created successfully'),
+  onError: (error: AxiosError<ApiError>) =>
+    toast.error(error.response?.data?.message ?? 'Something went wrong'),
+});
+```
+
+---
+
+## Testing Rules
+
+### Unit/Component tests with React Testing Library
+
+```tsx
+// Test behavior, not implementation
+describe('UserCard', () => {
+  it('should display user name and email', () => {
+    const user: User = { id: 1, email: 'test\@example.com', fullName: 'Test User' };
+    render(<UserCard user={user} />);
+
+    expect(screen.getByText('Test User')).toBeInTheDocument();
+    expect(screen.getByText('test\@example.com')).toBeInTheDocument();
+  });
+
+  it('should call onDelete with user id when delete button clicked', async () => {
+    const onDelete = vi.fn();
+    const user: User = { id: 1, email: 'test\@example.com', fullName: 'Test User' };
+
+    render(<UserCard user={user} onDelete={onDelete} />);
+    await userEvent.click(screen.getByRole('button', { name: /delete/i }));
+
+    expect(onDelete).toHaveBeenCalledWith(1);
+  });
+});
+```
+
+### Hook tests
+
+```tsx
+import { renderHook, waitFor } from '\@testing-library/react';
+
+it('should fetch users', async () => {
+  const { result } = renderHook(() => useUserList(), { wrapper: QueryWrapper });
+
+  await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+  expect(result.current.users).toHaveLength(2);
+});
+```
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Component file | PascalCase | `UserCard.tsx` |
+| Hook file | camelCase | `useUserList.ts` |
+| Utility file | camelCase | `formatDate.ts` |
+| Type/Interface | PascalCase | `User`, `CreateUserRequest` |
+| Component | PascalCase | `UserCard`, `OrderList` |
+| Hook | `use` + PascalCase | `useUserList`, `useAuth` |
+| Event handler | `handle` + Action | `handleDelete`, `handleSubmit` |
+| Boolean variable | `is/has/can` prefix | `isLoading`, `hasError`, `canEdit` |
+| Constant | UPPER_SNAKE_CASE | `MAX_RETRY`, `API_TIMEOUT` |
+| CSS class (custom) | kebab-case | `user-card`, `nav-item` |
+
+---
+
+## Common Anti-Patterns to Avoid
+
+- ❌ Fetching in `useEffect` → use TanStack Query
+- ❌ Using `any` type → define proper TypeScript types
+- ❌ Storing server data in Zustand → that's TanStack Query's responsibility
+- ❌ Class components → use functional components
+- ❌ `index.js` everywhere → use named files for traceability
+- ❌ Direct DOM manipulation → use React state/refs
+- ❌ Mutating state directly → always use setter functions
+- ❌ Large components doing everything → split into smaller focused components
+- ❌ Prop drilling more than 2 levels → use context or Zustand
+- ❌ Hardcoding API URLs → use `import.meta.env.VITE_API_URL`
+
+---
+
+When explaining changes, refer to the [React Official Documentation](https://react.dev), [TanStack Query](https://tanstack.com/query), and [React Hook Form](https://react-hook-form.com) conventions.