# CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

## Commands

### Development

- `pnpm dev` - Start development server with Turbopack on http://localhost:3000
- `pnpm build` - Build for production (withContentCollections handles content generation)
- `pnpm start` - Start production server

### Code Quality

- `pnpm lint` - Run Biome linting checks
- `pnpm format` - Auto-format code with Biome

## Architecture

Next.js 16 application using the App Router with React 19 and Tailwind CSS v4.

### Key Technologies

- **Next.js 16.1.6** with App Router (not Pages Router)
- **React 19.1.0**
- **TypeScript** with strict mode
- **Tailwind CSS v4** with PostCSS
- **Biome** for linting/formatting (replaces ESLint/Prettier)
- **Turbopack** for builds and dev server
- **pnpm** as package manager
- **content-collections** for MDX blog posts (Zod schema + compileMDX)
- **next-intl** for i18n (FR default, EN)
- **recharts** + **shadcn/ui** for charts
- **@tabler/icons-react** for UI icons, **simple-icons** for brand logos

### Project Structure

- `/app` - Next.js App Router (layouts, pages, routes)
- `/components` - Reusable components (blog/, sections/, ui/)
- `/content/blog` - MDX blog posts (`/fr/*.mdx`, `/en/*.mdx`)
- `/data` - Navigation links and static data
- `/messages` - i18n translation files (en.json, fr.json)
- `/public` - Static assets (images, SVGs, fonts)

### Important Patterns

- Path imports use `@/*` alias pointing to project root
- Tailwind v4 uses inline theme configuration in globals.css
- Dark mode by default (site is always dark). No light mode toggle.
- Font optimization using `next/font` with Geist Sans and Geist Mono

## Core Principles

- **Simplicity First**: Make every change as simple as possible. Minimal code impact.
- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs.
- **No Invention**: When information is missing, propose in writing and ask for validation before implementing. Never assume.
- **No Emoji**: Use @tabler/icons-react for UI icons, simple-icons for brand logos. Never emoji.

## Workflow Orchestration

### 1. Plan Mode Default

- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
- If something goes sideways, STOP and re-plan immediately
- Use plan mode for verification steps, not just building
- Write detailed specs upfront to reduce ambiguity

### 2. Subagent Strategy

- Use subagents liberally to keep main context window clean
- Offload research, exploration, and parallel analysis to subagents
- For complex problems, throw more compute at it via subagents
- One task per subagent for focused execution

### 3. Self-Improvement Loop

- After ANY correction from the user: update `tasks/lessons.md` with the pattern
- Write rules that prevent the same mistake
- Ruthlessly iterate on these lessons until mistake rate drops
- Review lessons at session start

### 4. Verification Before Done

- Never mark a task complete without proving it works
- Diff behavior between main and your changes when relevant
- Ask yourself: "Would a staff engineer approve this?"
- Run tests, check logs, demonstrate correctness

### 5. Demand Elegance (Balanced)

- For non-trivial changes: pause and ask "is there a more elegant way?"
- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
- Skip this for simple, obvious fixes
- Challenge your own work before presenting it

### 6. Autonomous Bug Fixing

- When given a bug report: just fix it. Don't ask for hand-holding.
- Point at logs, errors, failing tests, then resolve them
- Zero context switching required from the user
- Go fix failing CI tests without being told how

## Task Management

1. **Plan First**: Write plan to `tasks/todo.md` with checkable items
2. **Verify Plan**: Check in before starting implementation
3. **Track Progress**: Mark items complete as you go
4. **Explain Changes**: High-level summary at each step
5. **Document Results**: Add review section to `tasks/todo.md`
6. **Capture Lessons**: Update `tasks/lessons.md` after corrections

## Design & UI Rules

### Gradients

Gradient directions must alternate correctly between sections to create visual flow:
- Odd sections: `bg-gradient-to-br from-[#000] to-[#1A2428]`
- Even sections: `bg-gradient-to-tr from-[#000] to-[#1A2428]`
- Beyond 2 sections: alternate `to-bl` / `to-tl` to avoid monotony, keeping `from-[#000] to-[#1A2428]`
- Never swap TR and BR. Always verify gradient directions follow the correct pattern.

### Visual Coherence

- Reuse the exact same palette and gradients as the Home page
- Brand color: `#fd105e`
- Background: `#000` to `#1A2428`
- Keep everything consistent across pages and sections

### Icons and Charts

- UI icons: `@tabler/icons-react` (consistent size/stroke)
- Brand logos: `simple-icons`
- Charts: shadcn/ui ChartContainer + recharts. Choose chart type based on data shape (bar for comparisons, area for trends, radar for multi-axis). No emoji for charts.
- When in doubt about a visual, ask or search for the right SVG/chart

### Component Naming

Name components clearly after what they are: `footer` not `with-section`, `header` not `nav-wrapper`.

## Section-by-Section Process

1. **Prepare**: List expected content and dependencies (components, hooks, API, assets). Check latest docs via context7.
2. **Propose**: If a section doesn't exist, ask for a design template or propose a minimal wireframe for validation.
3. **Implement**: Integrate respecting UI rules. Use clear placeholders + TODO notes if content is missing.
4. **Review & Test**: Check basic a11y (landmarks, alt, contrast), responsive, and state copies. Update TODO in docs/TODO/.
5. **Validate**: Submit section for explicit validation (OK/NOK). Don't proceed without OK.
6. **Commit**: After validation, commit immediately with Conventional Commits.

## Git Conventions

- New page or feature = new branch
- Branches: `feat/<slug>`, `fix/<slug>`, `chore/<slug>`, `refactor/<slug>`
- Commits: Conventional Commits (`feat(section): header responsive`, `fix(api): handle 429`)
- Commit only after validation of the section
- PR: short description, screenshots if useful, checklist (UI, responsive, a11y, perf, docs updated, TODO updated)

## API & Package Documentation

- Before implementing: check the latest docs via context7 for every API/package
- Track the version used (CHANGELOG, README, or PR comment)
- If ambiguity in docs: write a proposal (expected behavior, inputs/outputs) and ask for validation

## Missing Information Procedure

1. Note exactly what is missing
2. Write a clear proposal (structure, behaviors, alternatives)
3. Ask for validation. Without OK, do not implement.

## File Organization

- Maintain clean structure, consistent naming, no orphan files
- Debug: place temporary code/logs in a dedicated TMP file, delete after resolution
- TODO per page in `docs/TODO/<page>.md`

## Exceptions

Any exception to these rules must be justified in the corresponding PR and validated before merge.