Les fichiers de contexte : CLAUDE.md, conventions, architecture

La qualité du contexte donné à un agent détermine la qualité de ce qu'il produit. Ce n'est pas un détail de configuration — c'est la compétence centrale de l'AI-first. Un CLAUDE.md mal rédigé, c'est un agent qui invente vos conventions à chaque session et que vous corrigez indéfiniment. Un CLAUDE.md bien rédigé, c'est un agent qui produit du code mergeable dès le premier jet sur 80 % des tâches courantes.

Ce qu'est un fichier de contexte

Ce que le fichier doit couvrir

Une structure qui fonctionne bien en pratique :

1. Contexte du projet (2-4 lignes)

Ce qu'est le projet, quelle techno, à quelle étape il en est. L'agent doit comprendre s'il travaille sur un SaaS Next.js en prod, une API Python en alpha, ou un monorepo en cours de découpage.

2. Commandes essentielles

Les commandes pour lancer, tester, builder le projet. L'agent les exécute — il doit savoir lesquelles sont correctes pour votre setup.

dev: corepack pnpm dev
test: corepack pnpm test
lint: corepack pnpm lint
build: corepack pnpm build

3. Architecture et conventions de fichiers

Où vivent les composants, les types, les services, les tests. Quelle convention de nommage. Si vous avez une structure inhabituelle, dites-le explicitement.

4. Patterns à suivre (avec exemples si besoin)

Comment vous gérez l'auth, quel ORM et comment vous l'utilisez, comment vos composants sont structurés. Si un pattern est non-évident, un exemple inline (3-5 lignes) vaut mieux qu'une description abstraite.

5. Anti-patterns explicitement bannis

Ce que l'agent ne doit jamais faire, même si ça semble raisonnable. Exemples : ne pas utiliser any TypeScript, ne pas écrire de SQL raw (ORM seulement), ne pas installer une nouvelle dépendance sans demander.

6. Ce qui ne touche pas (zones protégées)

Si certains fichiers sont hors périmètre (fichiers auto-générés, contrats publics, migrations en production), dites-le. Un agent qui touche un fichier de migration en pensant bien faire peut causer des dégâts irréversibles.

Ce qui ne va pas dans le CLAUDE.md

Un exemple réaliste

# Projet

SaaS Next.js 15 (App Router). Stack : TypeScript strict, Drizzle ORM, Neon (Postgres),
Clerk (auth), Zod (validation).

## Commandes

- dev: `corepack pnpm dev`
- test: `corepack pnpm test`
- db push: `corepack pnpm db:push`

## Conventions

- Components : `app/components/` (partagés) ou co-localisés avec la route
- Types : inférés depuis le schéma Drizzle (pas de types manuels pour les entités DB)
- API routes : `app/api/[resource]/route.ts`
- Jamais de SQL raw — Drizzle seulement
- Jamais de `any` TypeScript

## Auth

Clerk middleware gère l'auth sur toutes les routes `/app/*`.
`auth()` de `@clerk/nextjs/server` pour récupérer l'utilisateur côté serveur.
Ne pas réimplémenter de vérification d'auth dans les composants.

## Fichiers à ne pas modifier

- `drizzle/migrations/` — auto-généré, ne jamais éditer manuellement
- `app/api/webhooks/` — contrats Clerk, modifier avec prudence

Connecter vos bases de connaissances d'équipe (Obsidian, Notion, etc.)

Dans les vrais projets d'entreprise, les conventions et l'architecture ne sont pas les seules connaissances nécessaires. Vous disposez souvent d'une base de connaissances interne : un wiki, des notes d'architecture (ADR) dans un dossier Obsidian, ou des documentations fonctionnelles dans Notion.

Le piège classique consiste à copier-coller toute cette documentation dans votre CLAUDE.md. C'est une mauvaise pratique majeure (anti-pattern) :

• Token waste : Vous payez le coût de lecture de cette documentation à chaque requête.
• Dilution d'attention : L'agent a trop d'informations superflues et commence à halluciner ou à rater les règles prioritaires.

Pour intégrer ces bases de connaissances proprement, deux stratégies d'ingénierie s'offrent à vous :

Approche A : La compilation par script (Push)

Vous créez un script local (ex: en Node ou Python) qui s'exécute à la demande ou en pre-commit. Ce script va lire des dossiers spécifiques de votre coffre Obsidian (par exemple, uniquement le dossier Architecture/Active_Rules/) ou exporter des pages cibles de votre Notion, puis assembler un fichier de contexte temporaire (ex: .cursorrules ou une section dédiée dans CLAUDE.md).

• Avantage : Le contexte reste à jour automatiquement avec vos notes internes sans action manuelle répétée.

Approche B : La connexion dynamique par MCP (Pull)

Plutôt que d'injecter toute la base de connaissances dans le prompt de départ, vous donnez à l'agent la capacité de chercher et de lire vos notes par lui-même uniquement lorsqu'il en a besoin. C'est l'usage du Model Context Protocol (MCP).

• Exemple : Un serveur MCP Obsidian (obsidian-mcp-server) configuré localement donne accès à des outils comme search_notes ou read_note. Si la tâche concerne l'authentification, l'agent appellera de lui-même read_note("Design_System_Auth") pour s'aligner sur la convention d'équipe, sans que cette note n'ait été chargée au départ.

Le fonctionnement détaillé de la configuration de ces serveurs MCP est traité dans le Module 5.

À votre tour

En résumé

• Le fichier de contexte est lu avant chaque session : c'est votre levier le plus efficace pour améliorer la qualité du code généré.
• Il couvre : contexte projet, commandes, architecture, patterns, anti-patterns, zones protégées.
• Il ne couvre pas : les specs de tâches individuelles, la documentation interne, l'historique du projet.
• Un bon CLAUDE.md tient en moins de 100 lignes et est mis à jour dès qu'un agent manque une convention.