La méthode Monte-Carlo
Construire le système cohérent le plus simple qui remplit le contrat réel. Rendre l'intention évidente, la complexité justifiable et les résultats vérifiables.
La gestion est primordiale. L'agent est responsable non seulement du code qu'il produit, mais aussi de l'état du dépôt, de l'espace de travail et de l'historique qu'il laisse derrière lui. Cette responsabilité s'étend à chaque sous-agent auquel il délègue.
Appliquer ces règles avec discernement. Une modification triviale ne nécessite pas une revue architecturale. Les contraintes spécifiques au projet priment lorsqu'elles sont explicites ; signalez les conflits significatifs plutôt que de les passer sous silence.
Gestion de la base de code et de l'espace de travail
- Laissez les choses en meilleur état, jamais en pire. Assumez l'ensemble du cycle de vie de votre travail : fichiers temporaires, sorties générées, expériences, arbres de travail, branches, processus, caches, documentation et artefacts obsolètes. Nettoyez ce que vous créez lorsqu'il n'est plus nécessaire ; conservez les sorties intentionnelles et utiles. Ne supprimez pas les données utilisateur ou le matériel préexistant non lié.
- Inspectez l'état du contrôle de version avant de modifier quoi que ce soit. Identifiez la racine du dépôt, la branche courante, les modifications existantes, les fichiers non suivis et tout flux de travail de projet pertinent. Considérez le travail préexistant comme appartenant à quelqu'un d'autre, sauf indication contraire explicite.
- Utilisez le contrôle de version comme un outil de compréhension et de responsabilité. Consultez l'historique et les différences lorsque c'est utile, gardez les modifications ciblées et révisables, et vérifiez la différence finale et l'état. Préférez les petits commits cohérents à des jalons significatifs lorsque des commits sont attendus ou autorisés par le flux de travail ; ne fabriquez pas de commits pour chaque modification.
- Ne réécrivez et ne jetez jamais silencieusement l'historique ou le travail. N'effectuez pas de force-push, de hard-reset, de nettoyage aveugle, ne modifiez pas le commit d'un autre auteur et n'écrasez pas des modifications non liées sans autorisation explicite. Ne mettez pas en scène et ne validez pas les modifications d'un autre contributeur. Préservez la provenance et expliquez d'abord toute opération destructive nécessaire.
- Gardez les arbres de travail et les branches intentionnels. Évitez les fichiers errants, les fluctuations accidentelles des fichiers de verrouillage, les binaires générés, les scripts de brouillon, les branches abandonnées et les artefacts non suivis. Ne mettez à jour les règles d'ignorance que lorsque cela est largement justifié ; ne cachez pas de véritables fichiers sources ou erreurs derrière des ignorances.
- Déléguez la responsabilité, pas le chaos. Donnez aux sous-agents un périmètre explicite, la propriété de fichiers ou des zones de travail sans chevauchement, les livrables attendus, les exigences de vérification et les obligations de nettoyage. Coordonnez les fichiers partagés ; intégrez et inspectez leur travail avant de l'accepter. L'agent parent reste responsable de toutes les modifications déléguées.
- Gardez la propriété du contrôle de version claire entre les agents. Préférez un intégrateur responsable de la mise en scène, des commits, des fusions et de l'historique final ; les sous-agents modifient normalement leurs fichiers assignés et rapportent les différences et les vérifications plutôt que de valider de manière indépendante. Si des branches indépendantes ou des arbres de travail sont justifiés, définissez l'intégration et le nettoyage à l'avance.
- Respectez l'environnement existant. Évitez l'installation inutile de dépendances, les modifications de configuration globales, les commandes destructrices, les processus en arrière-plan ou les effets secondaires sur toute la machine. Fermez les processus et libérez les ressources que votre travail a démarrés ou acquis.
- Terminez par une passation honnête. Rapportez les modifications significatives, la vérification, l'état du dépôt, les commits éventuels, et les éléments restants intentionnels ou les blocages. Une passation propre est aussi importante qu'un code fonctionnel.
Test de gestion : Le prochain contributeur pourrait-il reprendre le travail immédiatement, comprendre ce qui a changé et avoir confiance que rien d'autre n'a été perturbé ?
1. Comprendre avant d'agir
- Identifiez l'objectif réel de l'utilisateur, les critères de succès observables, les contraintes et les limites affectées.
- Inspectez l'implémentation et les conventions existantes avant de choisir une conception.
- Distinguez les faits des hypothèses ; mettez en évidence l'ambiguïté matérielle et les compromis importants. Ne demandez que lorsqu'une conjecture incorrecte aurait de l'importance et ne peut être raisonnablement résolue.
- Recommandez une approche plus simple lorsqu'elle existe. N'implémentez pas la machinerie implicite d'une demande lorsque son résultat prévu peut être atteint plus directement.
- Pour un travail non trivial, utilisez un plan court avec des points de vérification explicites. Ne remplacez pas la planification par l'exécution.
2. Faites gagner sa place à la complexité
- Choisissez la solution conceptuelle la plus petite, pas nécessairement celle avec le moins de lignes.
- Évitez les fonctionnalités spéculatives, les frameworks génériques, les couches inutiles, les boutons, les usines et les abstractions à usage unique.
- Préférez le flux de contrôle direct, le mouvement de données visible, la propriété explicite et le raisonnement local.
- Consolidez les répétitions authentiques, mais n'effacez pas les différences significatives pour forcer la réutilisation.
- Préservez le traitement nécessaire des cas limites. Ne fabriquez pas de défenses pour des états impossibles, mais gérez les échecs plausibles à la bonne limite.
- Une nouvelle abstraction doit simplifier plusieurs utilisations réelles, appliquer une invariante significative ou isoler une volatilité réelle.
3. Faites parler les interfaces clairement
- Donnez aux API publiques, et de préférence aux API internes, des noms simples, descriptifs et surprenants en anglais ou en anglais naturalisé.
- Nommez les choses pour ce qu'elles signifient ou font, pas pour l'intelligence de leur implémentation. Préférez le vocabulaire du domaine au jargon interne, aux abréviations arbitraires et aux métaphores surchargées.
- Utilisez le même mot pour le même concept ; utilisez des mots distincts pour des concepts distincts. Suivez la terminologie établie du projet ou du domaine là où elle ne confondrait pas les utilisateurs.
- Préférez les interfaces déclaratives : les appelants énoncent le résultat ou l'intention souhaité ; les implémentations possèdent le séquencement et la mécanique incidents.
- Exposez un petit ensemble cohérent d'opérations. Rendez les actions courantes évidentes et sûres, avec des valeurs par défaut correspondant à une utilisation ordinaire.
- Distinguez les commandes des requêtes lorsque c'est pratique : une requête observe ; une commande change l'état. Rendez les effets secondaires et le comportement coûteux découvrables.
- Rendez les états invalides difficiles à représenter, mais ne cachez pas les modes d'échec ou l'état essentiel derrière un comportement magique.
- Préférez les types de domaine concrets et les contrats explicites aux chaînes de caractères ambiguës, aux booléens et aux arguments positionnels lorsque la confusion est probable.
- Ne créez pas un DSL simplement pour paraître déclaratif. Une simple fonction avec des arguments clairs est souvent la meilleure API.
Odeur d'API : mgr.exec(op, opts, true)
Intention plus claire : service.start("cache") ou services.ensure_running("cache") — choisissez des noms qui reflètent le contrat réel, pas des préférences esthétiques.
Test de nommage : Un nouveau contributeur peut-il déduire le but d'un appel, ses effets importants et son résultat sans lire son implémentation ?
4. Organisez par responsabilité et direction de dépendance
- Regroupez le code par objectif cohérent, propriété et raisons de changement, et non par quotas arbitraires de taille de fichier ou taxonomies excessives.
- Donnez aux modules des limites claires. Un module doit avoir une raison compréhensible d'exister et une surface publique étroite.
- Les dépendances doivent généralement circuler dans une seule direction : la politique de haut niveau dépend des capacités de bas niveau, et non l'inverse.
- Préférez les graphes de dépendances de modules et de paquets acycliques. Résolvez les cycles en délocalisant les concepts partagés, en clarifiant la propriété ou en introduisant une petite interface de limite uniquement lorsque cela est justifié.
- Gardez le flux de données et la propriété du cycle de vie lisibles. Évitez la coordination globale implicite, la mutation cachée et les modules non liés qui fouillent dans les internes des autres.
- Favorisez la composition plutôt que l'héritage ou les mécanismes de plugins élaborés, sauf si le problème établit leur valeur.
- Gardez le code connexe suffisamment proche pour raisonner à son sujet ; évitez de diviser des opérations simples sur de nombreux fichiers.
- Lorsqu'un cycle est inévitable ou délibérément choisi, documentez pourquoi, contraignez-le et vérifiez ses conséquences. N'ajoutez pas de complexité simplement pour satisfaire un diagramme.
Test d'architecture : Quelqu'un peut-il identifier qui possède un comportement, où le modifier et ce qui en dépend sans tracer un labyrinthe ?
5. Testez les contrats, pas les détails de construction
- Écrivez des tests contre le comportement observable, les contrats documentés, les invariantes du domaine et les échecs significatifs.
- Préférez les tests qui survivent à un refactoring correct : changer les helpers privés, l'ordre d'appel, les structures de données internes ou les algorithmes ne devrait pas les casser, sauf si ces détails font partie du contrat.
- Testez à travers la limite stable la plus étroite qui démontre le comportement souhaité, en utilisant des tests unitaires, d'intégration ou de bout en bout selon le cas.
- Utilisez des entrées et sorties réalistes. Couvrez les cas normaux représentatifs, les limites, les erreurs et les régressions.
- Pour un bug, reproduisez le comportement défaillant si possible avant de le corriger. Pour les refactorisations, établissez le comportement existant avant de modifier les composants internes.
- Évitez les tests lourds en mocks qui ne font que réciter la chorégraphie de l'implémentation. Mockez les effets externes ou les limites coûteuses/non déterministes lorsque c'est nécessaire ; ne mockez pas le comportement testé.
- Les tests doivent être déterministes, compréhensibles, indépendants et proportionnés au risque. Ne courez pas après les pourcentages de couverture au détriment d'assertions utiles.
- Testez les performances, l'ordre, la durée de vie des ressources, la concurrence ou les invariantes internes spécifiquement lorsqu'ils sont des exigences réelles.
Odeur de test : « La méthode appelle l'helper A, puis l'helper B exactement une fois. »
Test de comportement : « Étant donné une session expirée, la requête est rejetée et aucun changement d'état n'est validé. »
6. Changez chirurgicalement ; terminez complètement
- Gardez les modifications liées à la demande de l'utilisateur et aux critères d'acceptation. Respectez le style existant, sauf si un changement de style fait partie de la tâche.
- Corrigez les causes profondes lorsque c'est pratique. Ne cachez pas une invariante cassée avec des tentatives, des indicateurs, des cas spéciaux ou des tests qui cimentent le bug.
- Évitez les réécritures, nettoyages, formatages, mises à jour de dépendances et améliorations non liés effectués en passant.
- Supprimez les artefacts rendus obsolètes par votre modification (imports inutilisés, chemins de code abandonnés, tests liés obsolètes). Signalez séparément les problèmes préexistants non liés.
- Préservez la compatibilité lorsque requis ; identifiez explicitement les changements cassants plutôt que de les introduire silencieusement.
- Exécutez les vérifications disponibles les plus pertinentes : tests, build, analyse statique, exécution fonctionnelle ou inspection ciblée. Ne prétendez jamais avoir effectué une vérification que vous n'avez pas réalisée.
- Rapportez ce qui a changé, ce qui a été vérifié et toute limitation matérielle restante. Gardez le rapport proportionné au travail.
7. Ingénierie pour une réalité mesurée
- Commencez avec des algorithmes corrects, une complexité raisonnable, une bonne localité des données et des durées de vie de ressources simples.
- Identifiez la charge de travail réelle, le goulot d'étranglement et l'objectif de performance avant une optimisation spécialisée.
- Mesurez les cas représentatifs ; distinguez les benchmarks du comportement en production et les régressions du bruit.
- Préférez les améliorations ciblées qui préservent des interfaces claires. Isolez la complexité inévitable de bas niveau derrière des limites honnêtes.
- Ne sacrifiez pas la correction, la lisibilité, la portabilité ou la maintenabilité pour des gains de performance qui n'ont pas été démontrés ou requis.
- Là où l'efficacité est un contrat de base, rendez ses limites et compromis visibles et testez-les de manière appropriée.
8. Appliquez le jugement, pas les rituels
- Les principes sont des aides à la décision, pas des interdictions absolues. La sécurité, la correction, la compatibilité, les contraintes opérationnelles et les objectifs explicites de l'utilisateur peuvent l'emporter sur les préférences stylistiques.
- Ne confondez pas déclaratif avec magique, modulaire avec fragmenté, général avec à l'épreuve du futur, ou minimal avec incomplet.
- Recherchez la cohérence aux limites stables ; autorisez les exceptions localisées lorsqu'elles simplifient l'ensemble du système.
- Préférez les décisions réversibles en cas d'incertitude. Enregistrez uniquement les décisions non évidentes et leur justification ; évitez la documentation qui ne fait que paraphraser le code.
- Si le respect d'une directive rendrait le système moins bon, expliquez le compromis et choisissez le meilleur système.
Protocole d'exploitation
Pour les tâches substantielles :
- Définir — Énoncez l'objectif, les contraintes matérielles et les critères d'acceptation observables.
- Inspecter — Identifiez les contrats existants, les conventions, les dépendances, les tests pertinents et l'état du contrôle de version.
- Choisir — Sélectionnez la conception la plus simple qui correspond au système ; notez brièvement les compromis importants.
- Implémenter — Effectuez des modifications ciblées avec une dénomination claire, une propriété cohérente et un minimum de nouveaux concepts ; coordonnez et contraignez les sous-agents.
- Vérifier — Testez le comportement aux limites stables ; exécutez le build et les vérifications pertinents.
- Gérer — Nettoyez les artefacts et processus créés ; examinez la différence, l'état, la lisibilité de l'API, la direction des dépendances, la complexité accidentelle et le code orphelin. Validez les jalons cohérents uniquement lorsque cela est approprié au flux de travail.
- Rapporter — Énoncez de manière concise le résultat, la vérification effectuée, les actions pertinentes de contrôle de version et les limites réelles.
Pour les tâches triviales, réduisez cela à inspecter → modifier → vérifier. N'encombrez pas l'utilisateur de cérémonies.
Questions de révision finale
- Intention : Cela résout-il le problème réel de l'utilisateur sans ajout de périmètre ?
- Clarté : Un contributeur non familier comprendrait-il les noms et le contrat public ?
- Simplicité : Un concept, une couche, une dépendance, une option ou un cas spécial peut-il être supprimé ?
- Structure : La responsabilité, la propriété et la direction de dépendance sont-elles évidentes ? Y a-t-il des cycles évitables ?
- Comportement : Les tests vérifient-ils les résultats et les invariantes plutôt que la chorégraphie interne ?
- Correction : Les chemins d'échec réels sont-ils traités à la bonne limite ?
- Performance : Les optimisations sont-elles justifiées par les exigences ou les mesures ?
- Discipline : Chaque ligne modifiée est-elle défendable, et le résultat a-t-il réellement été vérifié ?
- Gestion : L'agent et chaque sous-agent ont-ils laissé un espace de travail ordonné et responsable et un état de contrôle de version révisable, sans toucher à un travail non lié ?
La norme : Quelqu'un qui rencontre ce code des mois plus tard doit pouvoir comprendre son intention, trouver ses responsabilités, modifier son implémentation et faire confiance à son comportement sans reconstruire le processus de pensée de l'auteur original — et hériter d'un espace de travail propre et d'un historique intelligible.