rules builder

# CLAUDE.md

<!-- This file is read by Claude as project-level instructions -->
<!-- Place this file at the root of your project -->

# my-project

> Clean Next.js agent rules with a src-first architecture
> Version: 1.0.0

---

## 🗂️ Project Overview

This is a **Next.js** project using the **App Router**.
Language: **TypeScript** (strict mode)
Styling: **tailwind**

## 📁 Folder Structure

```
my-project
└── src
    ├── app
    │   ├── main
    │   ├── layout.tsx
    │   └── page.tsx
    ├── components
    │   ├── ui
    │   └── common
    │       ├── navbar.tsx
    │       └── footer.tsx
    ├── features
    └── shared
        ├── hooks
        ├── lib
        └── types
```

**Component organization:** feature-based
- Keep type definitions in dedicated `types/` files
- Custom hooks live in `hooks/` directory, prefixed with `use`
- Utility functions in `utils/` — pure functions only, no side effects
- Constants in `constants/` — never inline magic strings or numbers

## ✏️ Naming Conventions

| Entity | Convention | Example |
|--------|-----------|---------|
| Components | `PascalCase` | `UserProfile` |
| Files | `kebab-case` | `user-profile.tsx` |
| Functions | `camelCase` | `getUserData()` |
| Variables | `camelCase` | `userData` |
| Constants | `SCREAMING_SNAKE` | `USER_DATA` |
| CSS Classes | `kebab-case` | `.user-profile` |
| API Routes | `kebab-case` | `/api/user-profile` |
| React Hooks | prefix `use` | `useUserProfile()` |
| Interfaces | prefix `I` | `IUserProps` |

## 🎨 Code Style

```json
{
  "semi": true,
  "singleQuote": false,
  "tabWidth": 2,
  "printWidth": 100,
  "trailingComma": "es5",
  "arrowParens": "always"
}
```

**Rules:**
- Prefer arrow functions over `function` declarations for callbacks
- Use `const` by default, `let` only when reassignment is necessary, never `var`
- Prefer named exports over default exports for better refactoring support
- Use `async/await` over `.then()/.catch()` chains
- Use early returns to reduce nesting depth — avoid deeply nested conditionals
- Max line length: **100** characters
- Indent size: **2** spaces

## ⚛️ Component Guidelines

- **Always use functional components** — class components are not permitted
- Define a props interface for every component: `IComponentNameProps`
- Destructure props in the function signature
- Default to **Server Components** — add `'use client'` directive only when necessary (event handlers, hooks, browser APIs)
- **Memoization strategy:** selective
  - Use `React.memo` for components that re-render frequently with same props
  - Use `useMemo` for expensive computations
  - Use `useCallback` for callbacks passed as props

**State Management:**
- `useState` — Local component state
- `zustand` — Global client state — keep stores small and focused

## 📦 Import Rules

- Use absolute imports with alias `@` for all internal modules
  - ✅ `import { Button } from '@/components/Button'`
  - ❌ `import { Button } from '../../../components/Button'`
- Do not use barrel `index.ts` files that re-export everything — import directly from the file

**Import order (with blank line between groups):**
1. react
2. next
3. external
4. internal
5. relative
6. types
7. styles

## 🧪 Testing

- **Framework:** vitest
- **Testing Library:** @testing-library/react
- **Coverage threshold:** 80%
- **Test files:** In `__tests__/` directory
- **Naming:** `*.test.ts`

**Guidelines:**
- Test behavior, not implementation details
- One describe block per component/function
- Use descriptive test names: `it('should show error when email is invalid')`

## ⚡ Performance

- Add `priority` prop to above-the-fold `<Image>` components
- Lazy load images and components below the fold
- Use `next/dynamic` for large client-side components to reduce initial bundle
- Leverage Next.js caching: `fetch` with `cache` and `revalidate` options in Server Components

## 📦 Package Manager & Dependencies

**Package Manager:** `npm`

### Dependencies

- `next@latest` — The React Framework
- `react@latest` — React is a JavaScript library for building user interfaces
- `react-dom@latest` — React package for working with the DOM

### Dev Dependencies

- `typescript@latest` — TypeScript is a language for application-scale JavaScript
- `tailwindcss@latest` — A utility-first CSS framework

### Install Commands

```bash
npm install next react react-dom
npm install --save-dev typescript tailwindcss
```

---

*Generated by [Next.js Rules Builder](https://github.com) — 2026-06-15*