Agent Systématique — Pratiques de Codage Disciplinées
Quand l'utiliser
Chaque tâche de codage, modification, session de débogage ou travail d'implémentation. Cette compétence est un système d'exploitation de base pour aborder tout changement de code — pas un ajout optionnel.
Invoquée automatiquement pour toutes les tâches liées au code. Si l'utilisateur vous demande de modifier, ajouter, corriger ou construire du code, suivez cette compétence.
Règles Fondamentales
1. Ne jamais supposer des faits sur le projet
Avant de toucher à un fichier, vous devez savoir ce qu'il contient réellement. Lisez le fichier. Vérifiez son état actuel. Ne vous fiez pas à votre mémoire de ce qui « devrait » être là — lisez-le.
Actions concrètes :
read_filedu fichier que vous allez modifier, y compris le contexte environnantsearch_filespour le code associé, les imports, les appelants de fonctions et les références- Vérifiez que le serveur est en cours d'exécution et que les points de terminaison répondent avant de tester les modifications
- Vérifiez que les fichiers de configuration contiennent réellement ce que vous pensez
2. Inspecter les fichiers concernés avant toute modification
Ne modifiez pas à l'aveugle. Pour chaque fichier que vous prévoyez de modifier :
- Lisez le fichier complet (ou la section pertinente avec suffisamment de contexte)
- Comprenez la structure actuelle, les imports, les dépendances et les motifs
- Identifiez ce qui doit changer et pourquoi
- Alors seulement, écrivez le correctif ou la modification
Lors de l'application d'un patch : incluez suffisamment de contexte dans old_string pour que la correspondance soit unique. Un patch qui correspond à plusieurs emplacements s'appliquera au mauvais endroit.
Lors de la lecture de gros fichiers : utilisez offset/limit pour lire progressivement. N'essayez pas de charger un fichier de 1600 lignes en un seul appel si vous n'avez besoin que d'une fonction — mais lisez BIEN la fonction que vous modifiez en entier, y compris sa signature et tous ses sites d'appel.
3. Établir un plan concis avant l'exécution
Avant toute tâche de codage non triviale, rédigez un plan bref (3 à 7 points) qui répond à :
- Quels fichiers doivent changer
- Ce que chaque changement fait (une ligne par changement)
- Dans quel ordre les changements doivent avoir lieu
- Quelles étapes de vérification confirmeront le succès
Exemple :
Plan :
1. Lire app.py lignes 762-770 — vérifier la signature _get_hermes_response
2. Ajouter le paramètre image_url: str = None à la signature
3. Ajouter image_url=image_url aux 5 appels _call_api dans la fonction
4. Passer image_url de chat() à _get_hermes_response
5. Redémarrer le serveur, tester avec curl pour une image
Ne commencez pas à coder avant d'avoir énoncé le plan. Si le plan est erroné, le code le sera aussi.
4. Utiliser des outils pour vérifier les affirmations plutôt que de deviner
Chaque affirmation concernant la base de code doit être étayée par le résultat d'un outil, pas par un souvenir.
| Affirmation | Comment vérifier |
|---|---|
| « Le fichier X a la fonction Y » | grep -n ou read_file du fichier |
| « Le serveur est en cours d'exécution » | curl le point de terminaison santé |
| « La modification fonctionne » | Exécutez le test réel, ne supposez pas |
| « La clé API est configurée » | Lire storage/apis.json |
| « Le CSS est chargé » | curl le fichier statique, vérifiez le statut HTTP |
| « Le patch s'est appliqué correctement » | grep pour le nouveau texte, ou read_file de la zone |
N'écrivez jamais une réponse qui dit « ça devrait fonctionner » sans avoir vérifié que c'est effectivement le cas.
5. Après chaque modification significative, tester ou inspecter le résultat
Après tout changement de code :
- Vérification syntaxique :
python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)"— doit réussir avant de redémarrer - Redémarrer le serveur si la modification est dans app.py
- Tester le comportement modifié :
- Pour les modifications d'API :
curlle point de terminaison avec une charge utile représentative - Pour les modifications front-end : vérifier que le fichier statique est servi (HTTP 200)
- Pour les modifications de configuration : lire le fichier de configuration pour confirmer
- Pour les modifications d'API :
- Vérifiez le résultat réel — pas ce que vous attendiez, mais ce que l'outil a retourné
Une modification n'est pas terminée tant que vous n'avez pas vu le résultat du test. « Je pense que ça marche » n'est pas une vérification.
6. En cas d'échec, diagnostiquer l'erreur réelle avant d'essayer une autre approche
Lorsqu'un test échoue ou qu'un patch ne s'applique pas :
- Lisez le message d'erreur réel — copiez-le textuellement. Ne le résumez pas.
- Identifiez la cause racine — ce qui a spécifiquement échoué et pourquoi
- Formez une hypothèse sur la correction
- Testez l'hypothèse avec un outil — ne vous contentez pas d'essayer un autre patch
- Si la correction ne fonctionne pas, relisez l'erreur — elle a peut-être changé ou vous l'avez mal lue
Anti-modèles à éviter :
- Appliquer trois patches différents à la suite sans vérifier si l'un d'eux a fonctionné
- Deviner la correction en se basant sur le type d'erreur plutôt que de lire le texte de l'erreur
- Modifier du code non lié alors que l'erreur se trouve à un seul endroit spécifique
- Redémarrer le serveur sans corriger l'erreur de syntaxe qui l'empêche de démarrer
7. Ne pas déclarer une tâche terminée tant que le résultat n'a pas été vérifié
Une tâche n'est terminée que lorsque :
- La modification de code est écrite et vérifiée syntaxiquement ✓
- Le serveur est en cours d'exécution avec le nouveau code ✓
- Le comportement modifié produit le résultat attendu (vérifié par un outil) ✓
- Vous pouvez pointer vers la commande/test/sortie spécifique qui le prouve ✓
Ne déclarez jamais « terminé » en vous basant sur le fait que le patch s'est appliqué avec succès. Un patch peut s'appliquer au mauvais endroit, introduire une erreur de syntaxe ou ne pas résoudre le problème. L'application du patch est l'étape 1 de la vérification, pas la fin.
Procédure
Pour tout changement de code :
- Lire — inspectez le(s) fichier(s) que vous allez modifier. Connaissez l'état actuel.
- Planifier — rédigez 3 à 7 points : quels changements, dans quel ordre, comment vérifier.
- Modifier — effectuez les modifications. Un changement atomique à la fois pour un travail multi-fichiers.
- Vérifier la syntaxe —
py_compileou équivalent. Corrigez les erreurs avant de continuer. - Redémarrer — si le serveur en cours d'exécution a besoin du nouveau code.
- Tester — curl, exécution ou inspection. Vérifiez que le comportement réel correspond à l'intention.
- Rapporter — indiquez ce qui a changé, ce que le test a montré et si c'est vérifié.
Pour le débogage :
- Reproduire — obtenez le résultat d'erreur réel. Copiez-le textuellement.
- Localiser — trouvez où dans le code l'erreur prend naissance.
grep,read_file, trace de pile. - Comprendre — lisez le code défaillant en entier. Ne devinez pas ce qu'il fait — lisez-le.
- Hypothèse — quel changement spécifique corrigerait cette erreur spécifique ?
- Corriger — apportez le changement minimal qui traite la cause racine.
- Vérifier — réexécutez le test qui échouait. Confirmez que l'erreur a disparu ET que rien d'autre n'est cassé.
- Si toujours en échec — retournez à l'étape 1. L'erreur a peut-être changé. Relisez-la.
Pour les tâches en plusieurs étapes :
- Faites une étape à la fois. Vérifiez chaque étape avant de passer à la suivante.
- Si l'étape 3 dépend de l'exactitude de l'étape 2, vérifiez d'abord l'étape 2.
- Ne regroupez pas des modifications non vérifiées — si l'étape 2 est erronée, la « correction » de l'étape 3 le sera aussi.
Pièges
- Lire les mêmes lignes à plusieurs reprises sans agir. Si vous avez lu une fonction 3 fois sans l'avoir modifiée, vous êtes bloqué. Soit faites le changement, soit indiquez ce qui vous bloque.
- Deviner le contenu du fichier. Lisez toujours le fichier. La mémoire de ce qui « était là » n'est pas fiable après plusieurs patches.
- Sauter la vérification syntaxique. Un patch peut s'appliquer proprement et toujours casser la syntaxe. Vérifiez toujours.
- Tester sans redémarrer. Si app.py a changé, le serveur en cours d'exécution a l'ancien code. Redémarrez avant de tester.
- Déclarer terminé sur le succès du patch. « Patch appliqué » ≠ « tâche terminée. » Vérifiez le comportement.
- Ne pas lire les messages d'erreur. Le texte de l'erreur vous dit ce qui a échoué. Lisez-le. Ne déduisez pas uniquement du type d'erreur.
- Surcharger de modifications. Appliquez le changement minimal qui corrige le problème spécifique. Ne réécrivez pas des fonctions entières quand une seule ligne est erronée.
Liste de Vérification
Avant de déclarer une tâche de codage terminée, confirmez chaque élément :
- Fichier(s) lus avant modification (connaître l'état actuel)
- Plan rédigé (quels changements, dans quel ordre)
- Vérification syntaxique réussie (
py_compileou équivalent) - Serveur redémarré si app.py a changé
- Test exécuté (curl, exécution ou inspection) — résultat réel vu
- Résultat conforme au comportement attendu
- Aucune nouvelle erreur introduite
Comment Cette Compétence Interagit avec les Autres
- C'est une compétence de base — elle s'applique à TOUT travail de codage, quelle que soit l'autre compétence active
- Lorsque
test-driven-developmentest actif, le TDD est la méthode de test ; cette compétence régit la discipline globale - Lorsque
systematic-debuggingest actif, le débogage a sa propre procédure détaillée ; la règle 6 de cette compétence s'applique toujours - Lorsque
spikeest actif (expérience jetable), les règles « inspecter avant de modifier » et « vérifier après » s'appliquent toujours — les spikes peuvent être désordonnés mais pas négligents - Lorsque
human-first-uiouwebmxerzsont actifs pour le travail de conception, cette compétence régit les changements de code qui implémentent la conception : les compétences de conception informent SUR QUOI construire, cette compétence régit COMMENT le construire en toute sécurité - Les compétences sont chargées à la demande via
skill_view(name)— elles ne sont PAS des processus d'arrière-plan continus. Une compétence n'est en jeu que pendant le(s) tour(s) de session où elle est chargée. Les compétences d'assistance à la conception (webmxerz, human-first-ui) sont consultées pour des tâches d'interface utilisateur spécifiques ; cette compétence reste la base pour le travail de code qui implémente la conception.