docs: add root cause fix principle to coding standards

- add "no whack-a-mole" rule in CLAUDE.md to enforce fixing root causes over symptoms
- add equivalent root cause principle in docs/DEV.md coding standards section
This commit is contained in:
2026-04-25 12:39:06 -04:00
parent 7c1341d439
commit de745cb924
2 changed files with 6 additions and 0 deletions
+4
View File
@@ -7,3 +7,7 @@ After every code change, update the relevant documentation. This includes:
- co-located `README.md` files in `src/core/<module>/` and `src/features/<feature>/` for module-level behaviour
No task is complete until all impacted documentation is up to date.
## No whack-a-mole
Always fix the **root cause**, never the symptoms. If the same type of error appears in a second file after fixing the first, that's the signal the real fix is elsewhere — trace the import or call chain to understand why this code is reached in this context, then fix at that point.
+2
View File
@@ -20,6 +20,8 @@ Pour la création de modules externes `@zen/module-*` : [MODULES.md](./MODULES.m
## Standards de code
**On corrige la cause racine, jamais les symptômes.** Si le même type d'erreur réapparaît dans un deuxième fichier après avoir corrigé le premier, c'est le signe que le vrai fix est ailleurs. Remonter la chaîne d'imports ou d'appels jusqu'à comprendre *pourquoi* ce code est atteint dans ce contexte, puis corriger à cet endroit. Patcher les fichiers un par un (whack-a-mole) masque le problème et garantit qu'un troisième cas surgira.
**Les promesses ne s'ignorent pas.** Chaque `Promise` est `await`ée ou `.catch()`ée. Une promesse silencieuse qui échoue est un bug invisible.
**Les variables d'environnement et la documentation se mettent à jour avec le code.** Toute variable ajoutée, renommée ou supprimée doit être reflétée dans `.env.example`. Toute décision architecturale ou convention nouvelle doit être documentée dans le fichier `docs/` concerné.