Le problème
Les refactorisations se dégradent au fil des sessions et des agents. Un agent renomme une fonction. Un autre met à jour les tests. Un troisième agent revient deux jours plus tard pour « finir le travail » — et annule silencieusement la décision d’architecture qui a déclenché le renommage en premier lieu, car il n’a jamais vu le raisonnement.
Les décisions qui ont déclenché la refactorisation se trouvent généralement dans l’historique du chat, les messages de commit, ou nulle part. Au moment où elles sont importantes, elles ont disparu.
L’approche brainclaw
- Capturer le pourquoi avant de changer les surfaces.
bclaw_create(entity='decision', data={text: 'rename UserContext → AgentContext because the type now covers both'})place le raisonnement dans la mémoire du projet, et non dans un fil Slack. - Marquer les traps connus.
bclaw_create(entity='trap', data=...)pour les modèles que la refactorisation ne doit PAS recréer. Les agents futurs les voient dans leur contexte avant d’éditer. - Claimer des répertoires, pas des fichiers individuels. Une migration touche des douzaines de fichiers. Claimez le module entier :
bclaw_work(intent='execute', scope='src/auth/'). Le prochain agent qui claimsrc/auth/voit le vôtre et attend. - Tirer le digest avant chaque passe.
bclaw_context(kind='memory', path='src/auth/')filtre la mémoire pour ne garder que ce qui est pertinent pour le périmètre actuel — décisions, pièges, plans connexes — afin que le prochain agent saisisse l’intention, et pas seulement le diff.
Ce qui change
Une refactorisation cesse d’être une poussée par session qu’un agent pourrait annuler lors de la session suivante. L’intention persiste dans la mémoire. Les nouveaux agents qui rejoignent le projet la lisent avant de toucher au code.
Quand cela devient indispensable
Plus la refactorisation est grande et plus d’agents sont impliqués, plus le levier est important. Un renommage de 3 lignes n’en a pas besoin. Un mouvement d’architecture de 20 fichiers sur 3 sessions, oui.
