Documentation in-file : la seule qui survit aux refactos
La doc dans Notion meurt en 3 mois. La doc dans le code vit tant que le code vit. Règle Next Generation : chaque fichier non-trivial commence par un commentaire qui explique POURQUOI, pas QUOI.
Le template d'en-tête obligatoire
/**
* <Nom court — rôle métier en 1 phrase>
*
* Pourquoi ce fichier existe :
* - <raison 1 (DRY, SOLID, perf…)>
* - <raison 2>
*
* Dépendances entrantes : <qui m'importe>
* Dépendances sortantes : <ce que j'importe de critique>
*
* Anti-patterns connus :
* - <ne JAMAIS faire X car Y>
*
* Refacto YYYY-MM : <historique des décisions>
*/Pourquoi l'IA en a besoin
Sans en-tête, l'IA (Lovable, Copilot, Cursor) doit lire 12 fichiers pour comprendre le contexte → contexte saturé, réponses approximatives, bugs. Avec en-tête, 1 lecture suffit.
Anti-pattern : commentaires "WHAT"
// increment counter au-dessus de counter++ = bruit. Les commentaires utiles expliquent POURQUOI (// reset à 0 chaque dimanche UTC, voir cron weekly-reset).
Mémoire projet (mem://)
Pour les décisions cross-fichiers (rejets, contraintes business, conventions), une couche mem:// indexée. L'IA y accède en 1 call. Sans ça, chaque refacto réintroduit une idée déjà rejetée.
Race conditions & RCP : documenter le pourquoi
Toute logique async (revalidation cache, queue, websocket) DOIT documenter l'ordre attendu et le fallback en cas de desync. Sinon, race condition latente = bug 1-fois-sur-50 invisible en dev.
Partager