Un fichier Markdown spécial qui donne à Claude le contexte 
permanent de ton projet. Think of it as "onboarding docs for AI".

Vous écrivez pour Claude, pas pour onboarder un humain.
Chaque ligne compte dans votre budget de tokens !

# Project: Hero Platform
## Stack Technique
- Backend: Node.js 18+, TypeScript 5.2, PostgreSQL 15
- Frontend: Next.js 14, React 18, TailwindCSS 3.4
- Mobile: React Native 0.72
- Infra: AWS (Lambda, RDS, S3, CloudFront)

## Commandes Bash Essentielles
- `npm run dev` : Lance le dev server
- `npm run build` : Build production
- `npm run test` : Lance les tests Jest
- `npm run typecheck` : Vérification TypeScript
- `npm run lint` : ESLint + Prettier

## Style de Code
- ES modules (import/export), JAMAIS CommonJS (require)
- Functional components avec Hooks
- Arrow functions par défaut
- Destructuring imports : `import { foo } from 'bar'`
- Prefer async/await over .then()

## Architecture & Patterns
- Backend: Architecture hexagonale
  - Domain models dans /domain
  - Use cases dans /application
  - Infra dans /infrastructure
- Frontend: Feature-based structure
  - Chaque feature dans /features/{name}
  - Shared components dans /shared
- État global: Zustand (pas Redux)
- Routing: App Router (Next.js 14+)

## Workflow
1. Toujours typecheck avant commit
2. Prefer running single tests over full suite
3. Use conventional commits (feat:, fix:, refactor:)
4. Ne JAMAIS éditer les fichiers legacy dans /src/legacy
5. Toujours ajouter des tests pour new features

## Business Context
- Fintech B2B pour PMEs françaises
- 14 produits financiers actifs
- Compliance forte (ACPR, PCI-DSS)
- Multi-tenant avec isolation stricte

## Ne PAS Faire
- ❌ Commit direct sur main (toujours via PR)
- ❌ Modifier les migrations existantes
- ❌ Touch anything in /src/legacy without approval
- ❌ Use console.log (use our logger)

~/.claude/CLAUDE.md           # Global (toutes tes sessions)
    ↓
/project-root/CLAUDE.md       # Projet (tout le repo)
    ↓
/project-root/backend/CLAUDE.md   # Spécifique backend

# Dans votre CLAUDE.md
See @README.md for project overview
See @package.json for available commands

# Workflow git
@docs/git-workflow.md

# Instructions perso (pas dans git)
@~/.claude/hero-personal.md

# Dans Claude Code
/init
# Génère un template de CLAUDE.md à customizer

Mode read-only où Claude :
- Analyse ton codebase
- Fait de la recherche
- Crée un plan détaillé
- N'EXECUTE RIEN jusqu'à ton approval

"think"          →  Budget standard
"think hard"     →  Budget élevé
"think harder"   →  Budget max
"ultrathink"     →  Niveau Inception 🧠💥

1️⃣ RESEARCH (en Plan Mode)
Prompt: "Analyse comment implémenter [feature] dans notre stack.
         Quels sont les points d'attention ?"

2️⃣ PLAN (toujours en Plan Mode)
Prompt: "OK, crée-moi un plan détaillé step-by-step.
         Think hard sur les edge cases."

3️⃣ APPROVE & DOCUMENT (facultatif mais smart)
Prompt: "Génère un doc/PLAN.md avec ce plan,
         au cas où on doit reset."

4️⃣ EXECUTE (exit Plan Mode)
Shift+Tab pour sortir
Prompt: "Go, implémente le plan."

5️⃣ VERIFY
Prompt: "Vérifie que tout compile et passe les tests.
         Fix les issues."

6️⃣ COMMIT
Prompt: "Create PR avec commit messages descriptifs."

Opus 4.1 pour la planification (smart as fuck)
    ↓
Auto-switch to Sonnet 4 pour l'execution (fast & efficient)

Session 1: 1000 tokens
Session 2: 5000 tokens  
Session 3: 15000 tokens
Session 4: 50000 tokens ⚠️
Session 5: *Claude starts compressing/forgetting stuff*

# À CHAQUE nouvelle feature/task
/clear

# Pourquoi ?
- Reset context à zero
- Évite confusion cross-features  
- Garde Claude focused
- Save tons of tokens

Feature A : implement → test → commit
/clear
Feature B : implement → test → commit
/clear

# Flèche Haut : parcours l'historique
↑

# Double ESC : jump back et édite un prompt passé
ESC ESC

1 Chat = 1 Feature/Task

Chat 1: "Implémente payment webhook handler"
        ↓ Done ↓
        /clear

Chat 2: "Add tests pour webhook handler"  
        ↓ Done ↓
        /clear

Chat 3: "Refactor error handling in webhooks"

Chat 1: "Webhooks + tests + refactor + docs + deploy"
        ↓ Context explosion ↓
        ↓ Claude confused ↓
        ↓ You confused ↓
        😵‍💫

# ❌ Mauvais
claude "Voici 50 fichiers, fais quelque chose"

# ✅ Bon  
# Use tab-completion pour référencer précisément
claude "Analyse @src/features/payment/webhook.ts et 
        propose amélioration du error handling.
        See @docs/error-patterns.md pour nos conventions."

1. /clear
2. "Écris les tests pour [feature], think hard"
3. Review tests
4. "Implémente le code pour passer ces tests"
5. "Run tests et fix les failures"
6. "Commit avec message approprié"

1. Copy/paste screenshot from Figma
   (macOS: Cmd+Ctrl+Shift+4, then Ctrl+V dans Claude)

2. "Implémente ce design en React.
    See @CLAUDE.md pour nos patterns components."

3. Claude génère le code

4. "Take screenshot du résultat et compare with original"
   (Avec MCP Playwright si setup)

5. Iterate jusqu'à pixel-perfect

6. "Commit quand satisfied"

1. Plan Mode activé
2. "Voici l'error stack trace + logs.
    Analyse et propose des hypothèses. Think harder."
    
3. Claude fait research, propose 3-4 hypothèses

4. "Test l'hypothèse la plus probable"

5. Fix ou next hypothesis

6. Once fixed: "Update CLAUDE.md si c'est un pattern 
   error récurrent"

# Setup: /install-github-app (one-time)

# Customize review prompt
# .claude/claude-code-review.yml
direct_prompt: |
  Review ce PR pour bugs et security issues.
  Sois concis. Focus sur les problèmes réels,
  pas sur le style.
  
# Claude review automatiquement les PRs
# Trouve bugs, logic errors, vulnérabilités
# Humans review architecture & UX

Claude : Bugs, security, logic errors
Humans : Architecture, naming, UX decisions

Terminal 1 (Backend) :
  claude "Implémente webhook handler"
  
Terminal 2 (Frontend) :
  claude "Crée UI pour webhook status"
  
Terminal 3 (Tests) :
  claude "Write e2e tests pour le flow complet"
  
# En parallèle, isolation parfaite !

# Setup different branches in different folders
git worktree add ../hero-backend-feature backend-feature
git worktree add ../hero-frontend-feature frontend-feature

# Run claude in each
# No conflicts, full parallelization

Shift+Tab         : Toggle Auto-Accept Mode
Shift+Tab x2      : Enter/Exit Plan Mode
ESC               : Stop Claude (pas Ctrl+C !)
ESC ESC           : Jump back in history
Ctrl+V            : Paste images (NOT Cmd+V)
Shift+Enter       : New line in prompt

/terminal-setup   : Configure ton terminal properly
/init             : Generate CLAUDE.md template
/clear            : Reset context
/memory           : Edit memory files
/permissions      : Allowlist domains

# Pipe data into Claude
cat logs/error.log | claude -p "Analyse ces errors"

# Chain with other CLIs
gh issue list | claude -p "Prioritize ces issues"

# Headless mode (-p)
claude -p "List tous les TODOs dans src/" --output-format stream-json

# Analyze CSV
cat data.csv | claude -p "Top 10 users by activity?"

# Git diff analysis
git diff main...feature | claude -p "Summary des changes"

# Log analysis
tail -f app.log | claude -p "Alert si errors critiques"

# macOS : Screenshot to clipboard
Cmd+Ctrl+Shift+4 → Sélectionne zone

# Paste in Claude
Ctrl+V  # NOT Cmd+V !

"Read https://docs.stripe.com/api/charges 
 et génère notre wrapper StripeClient"

/permissions add docs.stripe.com
# Plus de prompt pour ce domain

/model                    # See current model
/model sonnet-4           # Switch to Sonnet 4
/model opus-4             # Switch to Opus 4.1

Sonnet 4 : 95% des tasks, fast, efficient
Opus 4   : Complex architecture, deep debugging

Claude Code (MCP Client)
    ↕️ MCP Protocol
MCP Server (tool-specific)
    ↕️ Tool API
Your Tool (Figma, DB, etc)

claude mcp add context7 -- npx -y @upstash/context7-mcp

"Create a Stripe checkout avec latest API - use context7"
→ Context7 fetch la doc Stripe latest version
→ Code généré avec APIs actuelles (no deprecated stuff)

# Built-in, pas besoin d'install
# Juste auth GitHub

"Create PR for this fix with description"
"Review PR #123 et add comments"
"Get status of CI runs for branch feature-x"

Code fix → Tests → PR creation → CI check → Alert si failures
                                   ↑
                            All automated !

1. "Extract design tokens from Figma file"
   → Auto-génère variables CSS/JS

2. "Implement this Figma component in React"
   [Paste Figma link]
   → Pixel-perfect implementation

3. "Compare implemented Button with Figma specs"
   → Détecte inconsistencies

4. "Generate design system documentation from Figma"
   → Auto-docs à jour

Design Handoff :
Figma → Claude Code → React Component → Tests → PR

No more:
- "C'est 2px off"
- "Quel spacing ici déjà ?"
- Screenshots back-and-forth

"Navigate to staging.hero.fr and test login flow"
"Extract all prices from competitor site"
"Take screenshots of dashboard at breakpoints [mobile, tablet, desktop]"
"Fill form avec test data and check validation"
"Run visual regression test on this component"

1. Implement component
2. "Run playwright test on it"
3. Claude sees failures
4. Auto-fixes
5. Re-run until green ✅

"Create Linear ticket for this bug avec screenshot"
"List my assigned issues priority high"
"Update issue status to In Progress"
"Get sprint summary"

Bug detected → Linear issue created → Assigned → Fixed → Status updated
                                                   ↓
                              All in one Claude session !

"Query users table for accounts created today"
"Analyze slow queries in pg_stat_statements"
"Generate migration to add index on email column"
"Explain this query plan"
"Check database health metrics"

App error → Check logs → Query DB pour confirm → Fix → Test
                                       ↑
                        MCP direct access !

"Create payment confirmation page:
1. Use figma to get design specs from [figma-link]
2. Implement React component avec notre design system
3. Query postgres to understand payment schema
4. Use context7 pour Stripe API latest best practices
5. Generate playwright tests
6. Create GitHub PR avec description"

Figma MCP → Design tokens
↓
Code implementation
↓
PostgreSQL MCP → DB schema check
↓
Context7 MCP → Stripe integration code
↓
Playwright MCP → Tests generation
↓
GitHub MCP → PR creation

# Launch avec debug
claude --mcp-debug

# Logs détaillés de MCP connections & calls

/mcp            # Status de tous les servers
claude mcp list # Liste dans terminal

# Terminal 1
cd backend
claude "Implement GraphQL resolver for payments"

# Terminal 2  
cd frontend
claude "Create React hook for payment flow"

# Terminal 3
cd e2e-tests
claude "Write Playwright tests for payment"

git worktree add ../hero-api-v2 feature/api-v2
git worktree add ../hero-web-v2 feature/web-v2

cd ../hero-api-v2 && claude
cd ../hero-web-v2 && claude

You: "Implement this big refactoring"
Agent: *works in background sandbox*
You: *continue other tasks*
Agent: "Done! Here's the PR"

# Terminal 1 : Active work
claude

# Terminal 2 : Long-running task
claude --auto-accept "Migrate all class components to hooks"

# Terminal 3 : Monitoring
watch -n 30 'git status'

# tasks.md
- [ ] Migrate Payment service to TypeScript
- [ ] Update frontend to new API
- [ ] Write E2E tests
- [ ] Update OpenAPI specs

# Distribute
claude instance-1 "Task #1 from tasks.md"
claude instance-2 "Task #2 from tasks.md"
claude instance-3 "Task #3 from tasks.md"

Agent A : Research → writes research.md
Agent B : reads research.md → Plans → writes plan.md
Agent C : reads plan.md → Implements → writes code
Agent D : reads code → Tests → reports

/install-github-app

# .claude/claude-code-review.yml
direct_prompt: |
  Review for:
  - Security vulnerabilities
  - Logic errors
  - Performance issues
  
  Ignore:
  - Style (Prettier handles)
  - Naming conventions
  
  Be concise and actionable.

PR opened → Claude triggered → Analysis → Comments added → Labels applied

# In CI
claude -p "Generate report from test failures" --verbose > ai-usage.log

# Parse logs
grep "tokens used" ai-usage.log

// In your automation
const cost = calculateCost(tokensUsed, model);
sendToDatadog({ metric: 'claude.cost', value: cost });

- PRs accepted without human changes
- Bugs caught in review
- Time saved per PR
- Test coverage improvement

Feature: Onboarding pour SaaS Hero avec paiement upfront
Composants: Multi-step form + Checkout integration
Scope: Frontend only (mock backend pour la démo)
Tech: Next.js 14 App Router + React Hook Form + Tailwind

1. Multi-step onboarding flow (4 steps)
   - Informations entreprise
   - Coordonnées responsable
   - Choix du plan (3 tiers)
   - Paiement par carte

2. Checkout Elements intégration
3. Form validation robuste
4. Progress indicator
5. Data persistence (localStorage)
6. Responsive design
7. Error handling UI

# Avec MCP Figma configuré
"Analyse this Figma design:
[Coller link Figma ou screenshot]

Extract:
- Design tokens (colors, spacing, typography)
- Component structure
- Responsive breakpoints
- Interactive states

See @CLAUDE.md for our Next.js patterns and @design-system/ for components."

"Implement the onboarding flow in Next.js 14 App Router.

Requirements:
- 4-step wizard with progress indicator
- React Hook Form with Zod validation
- Checkout Elements integration (test mode)
- Persistent state with localStorage
- Responsive design (mobile-first)
- Animations with Framer Motion
- Mock API calls (no real backend yet)

Structure:
/app/onboarding/
  layout.tsx
  page.tsx (redirects to step/1)
  step/[step]/page.tsx

Create reusable components in /components/onboarding/

Use our design tokens from @hero/krypton/tokens.ts"

"Generate Playwright tests:
1. Complete flow test (all 4 steps)
2. Form validation tests
3. Persistence test (refresh mid-flow)
4. Responsive tests
5. Error handling tests

Use @tests/e2e patterns."

Questions ?
Concerns ?
Ideas ?

1. [ ] Everyone installs Claude Code
2. [ ] Create team CLAUDE.md (workshop?)
3. [ ] Pick pilot features for experimentation
4. [ ] Setup monitoring & feedback loop
5. [ ] Schedule follow-up in 2 weeks