Comme sans doute beaucoup d'autres développeurs et architectes, je travaille en ce moment dans un grand nombre de dépôts, et désormais en mode IA d'abord : presque chaque modification naît aujourd'hui avec un agent de codage. C'est rapide. Mais cela a un effet secondaire qui m'agaçait de plus en plus : je me répétais sans cesse. Dans chaque projet, souvent dans chaque session, les mêmes consignes. N'écris aucune affirmation que tu n'as pas vérifiée. Ne construis pas d'abstraction dont personne n'a besoin. Tiens la doc à jour. Écris des tests qui testent vraiment quelque chose.
À un moment, j'ai sorti ces règles de ma tête pour les mettre dans un outil, mon propre harness pour agents de codage. Dans cette série en trois parties, je montre ce qu'il contient, pourquoi, et ce que j'ai abandonné en chemin. Cette partie traite des règles de base. La partie 2 porte sur la documentation d'architecture et les ADR, la partie 3 sur le workflow.
Trois problèmes qui m'ont poussé
Sascha a expliqué ce qu'est un agentic harness dans sa série, en commençant par Qu'est-ce qu'un Agentic Harness ?. En bref : tout ce qui entoure le modèle et qui n'est pas le modèle lui-même. Cet article en est la mise en pratique.
1. La répétition. Les règles générales n'ont pas leur place dans un prompt, mais dans un endroit fixe que chaque agent lit dans chaque projet. Quand j'améliore une règle, l'amélioration doit arriver partout, pas seulement dans le dépôt où je me trouve.
2. La distance au projet. Je connais ce problème dans presque tous les projets, bien avant l'IA : les nouveaux développeurs, ou même les expérimentés qui ne touchent un projet que rarement, se sentent déconnectés de son état. Quel est l'objectif ? Qu'a-t-on décidé, et pourquoi ? Résultat : on hésite. Personne n'ose toucher à du code qu'il ne comprend pas. Avec les agents de codage, c'est pire, car le code change plus vite que quiconque ne peut mettre la doc à jour. L'agent doit donc s'en charger lui-même.
3. Des décisions qui tiennent. Des décisions d'architecture documentées créent de l'acceptation, surtout quand quelque chose tourne mal. À un niveau plus élevé, compréhensible aussi par le management, c'est le rôle de l'Architecture Communication Canvas. Plus de détails dans la partie 2.
Mes premières réponses sont quatre règles de base que chaque agent suit chez moi.
Règle 1 : savoir, pas supposer
La règle la plus importante s'appelle Know, do not assume : un agent n'écrit que ce qu'il peut prouver, avec un fichier lu, un test exécuté, une affirmation de ma part ou une source liée. « Ça devrait marcher » ou « probablement » sont interdits comme résultat, et aucune tâche n'est terminée avant que sa vérification ne passe.
La différence se voit tout de suite au quotidien. Sans la règle, une tâche se termine typiquement ainsi :
J'ai étendu le contrôle. Les commits sur la branche principale devraient maintenant être vérifiés correctement.
Avec la règle, le même résultat figure ainsi dans le rapport QA, voici une vraie ligne de mon harness :
| Scenario | Result | Evidence |
|---|---|---|
| Conventional commit messages: Trunk commit header is not conventional | passed | Test "Conventional commit messages: Trunk commit header is not conventional". node --test 'scripts/*.test.mjs': passed. |
Je n'ai pas besoin de croire que ça marche. Je vois comment cela a été vérifié et je peux le refaire moi-même. Ce qu'un agent ne peut pas prouver devient un point ouvert dans la doc, au lieu d'être masqué par une hypothèse plausible. Sascha a expliqué pourquoi les agents ne devraient pas se noter eux-mêmes dans Vérification & contrôle.
Règle 2 : la simplicité avant l'élégance
Les agents de codage ont tendance à la sur-ingénierie. Ils construisent volontiers une interface pour une seule implémentation, une factory pour un new, ou ajoutent un paquet pour une tâche qui demande dix lignes. En même temps, la simplicité a toujours été ma propre posture de développeur. La règle ne fait que la rendre explicite :
- Use the simplest solution that meets the spec.
- Add an abstraction only when two or more real uses need it.
- Do not add a dependency if 20 lines of clear code do the same work.
S'y ajoutent deux classiques : DRY (chaque information à un seul endroit, pour le code, la configuration et les documents) et les principes SOLID. Pour eux aussi : seulement quand cela a du sens. C'est pourquoi la règle dit explicitement : Use SOLID to make code easy to change. Do not use it to add layers without need. SOLID et DRY sont des outils pour du code facile à modifier, pas une licence pour empiler couches et abstractions. En cas de doute, la simplicité l'emporte.
Chaque tâche se termine par une courte étape de refactoring, mais uniquement avec des tests verts avant et après. Si le refactoring devient trop gros, l'agent ne le fait pas et l'inscrit dans le backlog. Cela garde les modifications petites et faciles à relire.
Règle 3 : des tests qui testent quelque chose
Dans Les code reviews à l'ère des agents de codage, j'ai raconté l'histoire de tests qui implémentent Assert.True(true), juste pour avoir « plus de tests ». Face à cela, une courte liste : un bon test vérifie un comportement via une interface publique, a exactement une raison claire d'échouer et correspond à un scénario de la spec. Un mauvais test mocke l'unité qu'il doit tester, vérifie un état privé ou reste vert alors que la fonctionnalité est cassée.
L'agent travaille en test-first et voit chaque test échouer d'abord pour la bonne raison. Et aucun test n'est désactivé ou affaibli juste pour qu'il passe.
Règle 4 : Simplified Technical English
Que les consignes aux agents et les documents pour les humains doivent être concis et sans ambiguïté fait désormais consensus dans la communauté des développeurs. J'en fais une règle fixe avec un standard établi : tous les textes en anglais, c'est-à-dire documents, specs, ADR, commentaires, messages de commit et rapports, suivent l'ASD-STE100 Simplified Technical English. C'est un anglais contrôlé issu de l'aéronautique, conçu à l'origine pour des manuels de maintenance que des non-natifs doivent lire sans malentendu.
Un standard fixe plutôt que « fais court, s'il te plaît » résout deux problèmes à la fois :
- Les LLM écrivent volontiers de façon prolixe et « poétique ». Beaucoup de prose augmente le risque de contradictions et d'ambiguïtés, surtout dans des documents qu'un agent relira plus tard comme consignes.
- Les humains sont vite submergés et frustrés par trop de texte. Une doc que personne ne lit n'est pas une doc.
Les règles sont assez simples pour qu'un agent les suive de façon fiable : un mot pour un sens, pas de phrasal verbs ni de contractions, au plus 20 mots par phrase dans les procédures et 25 dans les descriptions, voix active plutôt que passive. Un script trouve automatiquement les phrases trop longues. Il ne peut pas vérifier le vocabulaire, car le dictionnaire STE complet n'est pas dans le dépôt. C'est pourquoi un agent n'a pas le droit d'affirmer qu'un texte est « conforme à STE », seulement qu'il « suit les règles STE ». C'est la règle de preuve, appliquée à elle-même.
D'ailleurs, tous les extraits en anglais de cet article sont écrits dans ce style.
Ce qui en est sorti : sparc
De ces règles est né sparc. Le nom vient de spec, de arc (architecture) et de l'étincelle (spark) d'une idée, qui doit finir en logiciel qui fonctionne. sparc est un plugin pour Claude Code et repose sur OpenSpec, que j'ai découvert grâce à un podcast. Son approche sobre m'a convaincu : chaque modification est un petit dossier avec une proposition, des specs, un design et des tâches. Comme souvent : la simplicité est la clé.
En plus des règles, sparc contient des rôles fixes (product owner, architecte, UX designer, software engineer, QA engineer), un ensemble fixe de documents et un script qui vérifie après chaque exécution d'agent si la doc correspond encore au code. Chaque règle n'existe qu'une seule fois. Rôles et skills y renvoient au lieu de la copier, et un projet n'a qu'un seul AGENTS.md, pas de second CLAUDE.md au contenu légèrement différent.
sparc est lui-même un projet sparc et a accumulé douze décisions d'architecture en deux jours. Deux d'entre elles ont supprimé quelque chose qui ressemblait au départ à de la bonne architecture. Je raconte cette histoire dans la partie 3.
À retenir : trois règles pour votre AGENTS.md
Pas besoin de votre propre harness pour commencer. Ces trois lignes figurent presque mot pour mot dans chacun de mes projets et fonctionnent dans n'importe quel AGENTS.md ou CLAUDE.md :
- Write only what you know. Get evidence from files, tests or the user.
Do not write "should work" or "probably" as a result.
- Keep it simple. Add an abstraction only when two or more real uses need it.
Keep each fact in one place and link to it from other places.
- Write a test that fails for the right reason before you write the code.
Do not disable, skip or weaken a test to make it pass.
Conclusion
Un harness personnel demande moins d'effort qu'il n'y paraît, s'il se limite à ce qu'on exige de toute façon dans chaque projet. Pour moi, ce sont quatre règles de base : prouver ses affirmations, construire simplement, écrire de vrais tests, formuler clairement. Ce qui est nouveau, ce n'est pas le contenu de ces règles. C'est que je n'ai plus besoin de les répéter.
La deuxième partie aborde mon sujet préféré : une documentation d'architecture qui suit le rythme du code, et des ADR qui restent honnêtes après la décision.