Dans les coulisses de mon dernier side project: le harness

Je me suis lancé dans un side project pour gérer les rétrospectives de mon équipe, une application que je construis depuis plusieurs mois et dont j’ai décidé de raconter les coulisses de la création.

L’article précédent a présenté l’architecture technique du projet, dont le code a été écrit en grande partie par des agents. Pour que ces derniers puissent respecter les standards que je me suis fixés et livrent des fonctionnalités qui marchent réellement, il faut leur fournir un environnement et une infrastructure permettant d’instrumenter et d’évaluer leur travail: c’est ce qu’on appelle le harness.

Un agent n’a pas de mémoire. Chaque session démarre ainsi avec le contexte qui lui est donné. C’est pourquoi il est essentiel de pouvoir rendre explicite tout ce qui est implicite. J’ai évoqué, lors de la présentation de l’architecture, qu’il existait de nombreux fichiers documentant le projet. Certaines de ces documentations sont destinées à l’humain, d’autres à la machine.

J’utilise principalement Claude Code pour le développement du projet. Ainsi, une (grande) partie de la documentation destinée aux agents est spécifique à Claude. Elle est découpée de la manière suivante:

• Des règles Claude Code pour orienter la manière de travailler (.claude/rules/*),
• Les décisions d’architecture (docs/adr/*),
• Le glossaire des contextes du projet (CONTEXT.md),
• Une description précise de l’architecture en place (docs/architecture.md),
• Une description (fonctionnelle et technique) de chaque contexte borné (AGENTS.md et src/{Context}/AGENTS.md).

Les fichiers décrits précédemment permettent de comprendre comment fonctionne et est écrit le projet. Cela permet de guider les agents dans leur travail sans être des instructions strictes. Rien ne garantit que l’IA respectera ce qui est indiqué, mais c’est la première chose à mettre en place pour permettre de produire le code que l’on souhaite.

Le contexte d’un LLM n’est pas illimité et mettre en place de nombreuses règles peut sur le long terme devenir problématique. Il est important de veiller à surveiller et entretenir ces dernières. Car même si les modèles les plus récents ont des fenêtres de contexte d’un million de tokens, les résultats sont meilleurs pour des sessions avec des fenêtres réduites. C’est pour cela que j’ai un découpage des fichiers AGENTS.md par contexte, Claude ne chargeant ces derniers que lorsqu’il doit travailler dans un contexte précis. De même, les règles globales sont écrites avec des chargements conditionnels en fonction des fichiers touchés (via la clé paths par exemple).

Pour m’aider à maintenir et à garantir la cohérence des règles, je me suis construit une compétence dédiée rules-audit. Cette dernière, comme son nom l’indique, va vérifier le contenu des règles pour s’assurer que le code suit bien ce qui a été défini. Avec cela, il existe également un test automatisé dont l’objectif est de contrôler la structure des règles en place pour garantir que chaque règle soit bien scopée et ne risque pas de faire exploser le contexte.

Ce qu’il faut surtout retenir lors de la mise en place d’un harness:

• Une règle trop longue n’est pas forcément lue en entier,
• Une règle chargée non pertinente va polluer le contexte inutilement et potentiellement diluer les autres,
• Les règles de chargement ont une importance et peuvent entrainer des règles “mortes” si le chemin est incorrect,
• Pour qu’une règle soit correctement appliquée, elle doit idéalement indiquer ce qu’elle doit faire et ne pas faire,
• Une règle n’est qu’une intention, rien ne garantit qu’elle soit appliquée.

Tout cet écosystème autour des agents n’est pas déterministe et n’est pas assuré d’être appliqué. C’est pour cela qu’en plus de toutes les instructions qui sont fournies, un certain nombre de tests automatisés et déterministes ont été mis en place et que l’on détaillera dans un prochain article.