Conventions CLAUDE.md
Le fichier CLAUDE.md est le fichier d'instructions que Claude Code lit automatiquement lorsqu'il démarre une session dans votre projet. Il sert de guide d'onboarding pour l'IA : il lui indique la stack que vous utilisez, l'organisation du code, les conventions à suivre et comment se connecter à des outils externes comme Almirant.
Un CLAUDE.md bien configuré fait la différence entre une IA qui génère du code générique et une IA qui respecte l'architecture, les patterns et les conventions de votre équipe.
Où placer le fichier
Placez CLAUDE.md à la racine de votre dépôt :
tu-proyecto/
CLAUDE.md # <-- aqui
.claude/
skills/
settings.json
src/
package.json
Claude Code cherche automatiquement ce fichier à l'ouverture du projet. Aucune configuration supplémentaire n'est nécessaire.
Si vous travaillez avec un monorepo, vous pouvez avoir un CLAUDE.md à la racine et d'autres dans des sous-répertoires. Claude Code les combine tous.
Ce qu'il faut inclure lorsque vous utilisez Almirant
1. Configuration MCP
Le plus important est que Claude Code sache comment se connecter à Almirant. Incluez la configuration du serveur MCP avec l'URL et l'API key.
## MCP - Almirant
Ce projet est connecté à Almirant pour la gestion des tâches.
Configuration dans `.claude/settings.json` ou `.mcp.json` :
\```json
{
"mcpServers": {
"almirant": {
"type": "http",
"url": "http://localhost:3001/mcp?projectId=<tu-project-uuid>",
"headers": {
"Authorization": "Bearer <tu-api-key>"
}
}
}
}
\```
Utilisez les outils MCP pour lire et mettre à jour les work items, les boards et les sprints.
Indiquez l'emplacement de la configuration MCP, mais n'incluez jamais l'API key directement dans CLAUDE.md. Utilisez .claude/settings.json (qui doit être dans .gitignore) ou des variables d'environnement.
2. Description du projet
Donnez un contexte général sur le projet et les technologies qu'il utilise.
## Description du projet
Application web e-commerce B2B construite avec :
- **Frontend**: Next.js 15 + React 19 + TypeScript + Tailwind CSS
- **Backend**: Bun + Elysia + Drizzle ORM
- **Base de données**: PostgreSQL 16
- **Auth**: Better-Auth avec Google OAuth
- **Tests**: Vitest + Playwright
3. Structure du dépôt
Expliquez comment le code est organisé afin que l'IA le parcoure efficacement.
## Structure
\```
src/
domains/ # Modulos por dominio (DDD)
users/
domain/ # Tipos e interfaces
application/ # Hooks y casos de uso
presentation/ # Componentes y containers
orders/
products/
components/ui/ # Componentes compartidos (shadcn/ui)
lib/ # Utilidades, API client, auth
\```
4. Conventions de code
Définissez les règles que Claude Code doit suivre lorsqu'il génère du code.
## Conventions
- **Fichiers**: kebab-case (`user-service.ts`, `order-form.tsx`)
- **Composants**: PascalCase (`UserProfile`, `OrderList`)
- **Hooks**: camelCase avec le préfixe `use` (`useUserProfile`, `useOrderList`)
- **Pas de classes**: Utiliser la programmation fonctionnelle. Fonctions pures, custom hooks, objets fonctionnels
- **Types**: Dans `domain/types.ts`, pas dans les composants .tsx
- **Composants .tsx**: Présentation uniquement. Sans useState, useEffect ni logique métier
- **Logique**: Dans des custom hooks au sein de `application/hooks/`
5. Commandes du projet
Incluez les commandes que Claude Code peut avoir besoin d'exécuter.
## Commandes
\```bash
bun run dev # Servidor de desarrollo
bun run build # Build de produccion
bun run lint # Linter
bun run test # Tests
bun run type-check # Verificacion de tipos
bun run db:generate # Generar migracion
bun run db:migrate # Aplicar migraciones
\```
6. Patterns de code
Documentez les patterns spécifiques que vous souhaitez voir l'IA reproduire.
## Patterns
### Appels API avec React Query
Tous les appels API utilisent React Query avec des query keys structurées :
\```typescript
export const userKeys = {
all: ['users'] as const,
list: (filters: UserFilters) => [...userKeys.all, 'list', filters] as const,
detail: (id: string) => [...userKeys.all, 'detail', id] as const,
};
export const useUsers = (filters: UserFilters) => {
return useQuery({
queryKey: userKeys.list(filters),
queryFn: () => usersApi.getAll(filters),
});
};
\```
### Mutations avec invalidation
\```typescript
export const useCreateUser = () => {
const queryClient = useQueryClient();
return useMutation({
mutationFn: usersApi.create,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: userKeys.all });
},
});
};
\```
7. Règles spécifiques au projet
Incluez les contraintes ou règles métier que l'IA doit respecter.
## Règles
- **JAMAIS** exécuter de SQL directement. Utiliser Drizzle ORM + migrations
- **JAMAIS** commiter des fichiers .env ou des identifiants
- **JAMAIS** modifier les fichiers dans `migrations/meta/`
- Les work items n'ont PAS de colonne `status` -- l'état est dérivé de la colonne du board
- Les work items utilisent `archived_at` (timestamp) au lieu d'un booléen pour l'archivage
- L'authentification utilise les cookies `better-auth.session_token`
Exemple complet
# CLAUDE.md
## Projet
E-commerce B2B pour la distribution de produits industriels.
**Stack**: Next.js 15 + React 19 + TypeScript + Tailwind CSS 4 + Elysia + Drizzle ORM + PostgreSQL 16
## MCP - Almirant
Gestion des tâches via MCP. Configuration dans `.mcp.json`.
Utiliser les outils MCP pour lire les work items avant d'implémenter et
mettre à jour l'état à la fin.
## Structure
\```
src/
domains/ # Modulos DDD
catalog/ # Productos y categorias
orders/ # Pedidos y facturacion
customers/ # Clientes B2B
components/ui/ # shadcn/ui
lib/ # API client, auth, utils
\```
## Conventions
- Fichiers en kebab-case
- Composants : présentation uniquement (sans hooks dans les fichiers .tsx)
- Logique : custom hooks dans application/hooks/
- Types : dans domain/types.ts
- Pas de classes : uniquement des fonctions, hooks, interfaces
## Commandes
\```bash
bun run dev # Dev server (port 3000)
bun run build # Production build
bun run lint # ESLint
bun run test # Vitest
bun run db:generate # Generar migracion
bun run db:migrate # Aplicar migraciones
\```
## Patterns
### React Query
Query keys structurées par domaine.
Les mutations invalident les queries associées dans onSuccess.
### API Client
Modules dans lib/api/client.ts :
- catalogApi.getProducts(filters)
- ordersApi.create(data)
- customersApi.getById(id)
## Règles
- JAMAIS de SQL direct, toujours Drizzle + migrations
- JAMAIS commiter .env
- Les commandes nécessitent une validation du stock avant confirmation
- Prix calculés côté serveur, ne jamais faire confiance au frontend
Conseils avancés
Segmenter par audience
Si votre équipe réunit différents profils (frontend, backend, devops), vous pouvez utiliser des sections aux en-têtes clairs afin que chaque skill ou flux sache où chercher les informations pertinentes.
Maintenir à jour
Considérez CLAUDE.md comme une documentation vivante. Lorsque vous changez un pattern, une convention ou la structure du projet, mettez le fichier à jour. Une instruction obsolète peut amener l'IA à générer du code incohérent.
Ne pas dupliquer l'évidence
Il n'est pas nécessaire de documenter le fonctionnement de React ou TypeScript. Concentrez-vous sur ce qui est spécifique à votre projet : conventions internes, patterns propres, contraintes métier.
Valider avec l'équipe
Comme les skills, le CLAUDE.md est versionné avec Git. Examinez-le en code review lors de changements importants afin de vous assurer que toute l'équipe est alignée.
N'incluez jamais directement dans CLAUDE.md des identifiants, API keys, tokens ou URL de production. Ce fichier est versionné avec Git et visible par toute l'équipe. Utilisez des variables d'environnement ou des fichiers de configuration dans .gitignore.