Context engineering

To translate this course in your native langage:

  • In Chrome: right-click anywhere on the page and select “Translate to…”

  • Or use this language selector:

Les mots colorés en anglais représentent des mots-clés de la norme du langage C++. Ils sont conservés à l’identique lors de l’utilisation d’une traduction automatique avec Google Translate. Exemple : l’héritage (inheritance) est un principe fondamental de C++.

Vos agents IA sont comme des chevaux de course : si vous les lâchez sans contexte et avec des consignes vagues, ils vont foncer tête baissée et construire votre projet à grands coups de sabots ! En quelques minutes, le programme sera probablement fonctionnel. Mais ne soyez pas surpris si le code ressemble à une forêt en friche, si l’architecture est bancale ou si le programme se comporte bizarement. Nous allons voir comment gérer cette situation dans ce chapitre.

Contextualisation du projet

Avant de commencer le développement, nous allons définir le contexte du projet grâce au fichier AGENTS.md. Ce fichier servira de référence tout au long du développement. En effet, il décrit l’organisation du projet, les conventions à suivre et les règles à respecter. Ainsi, les différents agents s’y réfèrent pour travailler de manière cohérente et maintenir une ligne directrice commune. Voici sûrement la consigne la plus importante de ce chapitre : demandez à l’IA de créer un fichier AGENTS.md :

OpenCode : Crée un fichier AGENTS.md à la racine du projet.

Réponse (13 s) : Le fichier AGENTS.md a été créé vide à la racine du projet.

OpenCode : Analyse l’ensemble du projet situé dans le répertoire PICTOR. Mets à jour le fichier AGENTS.md avec des instructions claires et concises. Ne modifie aucun autre fichier, n’invente aucune règle.

Réponse (1 min 25) : Le projet est une application C++17 pour Windows x64, construite avec Visual Studio/MSBuild et SDL3. Je vais documenter sa structure, les commandes de compilation et les contrats de coordonnées et d’événements présents dans le code, sans toucher aux modifications existantes.

AGENTS.md a été mis à jour après analyse de PICTOR : structure, compilation, contrats du code et vérifications disponibles.

Les instructions reposent sur les fichiers existants. Aucun autre fichier n’a été modifié.

Avertissement

Les résultats présentés sont ceux produits par ChatGPT-6.1 Sol. En utilisant une autre IA, vous obtiendrez évidemment des réponses différentes. Il vous appartient de comprendre la progression demandée dans ce chapitre. Si votre IA oublie une étape ou ne respecte pas certaines consignes, n’hésitez pas à lui soumettre des demandes complémentaires pour corriger ou compléter son travail.

Consultez le fichier AGENTS.md avec un éditeur de texte. Dans mon cas, l’IA a fait les remarques suivantes :

AGENTS.md

## Projet

  • PICTOR est une application C++17 pour Windows, construite avec la solution Visual Studio PICTOR.sln en Debug|x64 ou Release|x64.

  • G2D/ contient la boucle principale et l’intégration SDL3. student.cpp contient initApp, processEvent et drawApp, les points d’entrée de la logique applicative.

  • Les en-têtes à la racine définissent les types et l’API graphique. images/ et font/ contiennent les ressources chargées à l’exécution.

  • SDL3import/ contient les dépendances SDL3 et SDL3_ttf fournies avec le projet. Éviter de modifier ces fichiers tiers.

## Modifications

  • Préserver les signatures de initApp, processEvent et drawApp utilisées par G2D/main.cpp.

  • Ajouter au projet PICTOR.vcxproj tout nouveau fichier source ou en-tête qui doit être compilé.

  • Garder les chemins des ressources compatibles avec la copie vers BUILD/bin/<Configuration>/ effectuée par le projet Visual Studio.

  • Limiter les changements aux fichiers nécessaires et conserver le style du code environnant.

Ainsi, l’IA a saisi :

  • Qu’il s’agissait d’un projet Visual Studio sous Windows utilisant la librairie SDL3

  • Qu’il ne faut pas toucher au répertoire SDL3import

  • Que student.cpp contient les fonctions initApp(), processEvent() et drawApp() qui sont des points d’entrée du programme.

L’IA n’a pas remarqué :

  • L’architecture MLR associé au projet

  • Le modèle stocké dans la classe Model dans Model.h

  • Les différents rôles des classes à la racine du projet (fait 50% du temps)

En conséquence, j’effectue une requête supplémentaire pour lui indiquer les points à consolider :

OpenCode : Ce projet utilise une architecture MLR : Model Logic Render. Le fichier student.cpp contient les deux points d’entrée de la logique et du rendu. Le modèle est stocké dans la classe model. Peux tu analyser les fichiers, expliquez ce que tu as compris et stockez les informations importantes dans AGENTS.md.

Réponse (2 min 10): J’ai analysé les fichiers et enrichi AGENTS.md avec l’architecture MLR. Ce que j’ai compris:

  • Model — PICTOR/Model.h : la structure Model centralise l’état persistant. Elle contient actuellement uniquement currentMousePos.

  • Logic — processEvent dans PICTOR/student.cpp : reçoit un événement et un modèle modifiable (Model&). Actuellement, elle mémorise les mouvements de souris.

  • Render — drawApp dans PICTOR/student.cpp : reçoit le modèle en lecture seule (const Model&) et dessine via Graphics, notamment le curseur.

  • Initialisation — initApp : hook supplémentaire appelé une fois avant le premier rendu.

  • Infrastructure — PICTOR/G2D/main.cpp : traduit les événements SDL, appelle la logique et déclenche le rendu. Le fonctionnement est événementiel, sans mise à jour continue.

Le flux est donc : Événement → logique → modification du modèle → rendu …

Seul AGENTS.md a été modifié ; aucun changement du code ni test d’exécution.

Le contexte du projet est maintenant bien décrit, nous partons sur de bonnes bases. Les points essentiels sur lesquels nous nous sommes concentrés, ont été :

  • L’architecture globale de l’application

  • Le rôle des principales classes

  • L’organisation des fichiers / technos utilisées

Cela semble être un bon point de départ.

Consignes de développement

On pourrait presque se lancer dans l’ajout de nouvelles fonctionnalités maintenant, mais à ce niveau, il manque encore une partie importante du contexte : les demandes du client, les règles de codage ou encore les conventions de nommmage ! Les principales demandes faites durant ce cours ont été :

  • D’interdire l’utilisation des pointeurs et des fonctions new et free et de priviligier une allocation des ressources mémoire à partir des containers de la STL : vector array map.

  • D’utiliser des smarts pointeurs au cas où des pointeurs seraient requis pour du polymorphisme d’héritage

  • D’utiliser le programme du cours : structure, template, STL, Smart pointer, héritage et polymorphisme, functor et lambda. Les aspects plus avancés ou plus obscurs du C++ sont à éviter.

  • De priviligier la programmation orienté objet

  • De respecter le principe d’encapsulation en utilisant les mots clefs private et public. De mettre en place des getter / setter lorsque cela est nécessaire.

  • De mettre une classe / structure par fichier

  • D’utiliser la classe V2 pour les calculs géométriques 2D

  • De qualifier des méthodes membres const lorsque cela est judicieux

  • D’utiliser des const référence plutôt que des références lorsque cela est judicieux

On peut aussi ajouter les demandes suivantes :

  • Respecter la convention de nommage camelCase

  • Ajouter des commentaires juste au-dessus de chaque nouvelle fonction pour expliquer son fonctionnement

  • Ne pas gérer les exceptions du C++ ou les signaux d’erreur retournés par des fonctions afin d’alléger le code

  • Ne pas vérifier ni traiter les valeurs de retour des fonctions SDL3 lorsqu’elles servent à signaler une erreur ou un échec.

A ce niveau, il y a encore beaucoup d’implicite. Les consignes sont effectivement données rapidement. C’est peut-être un peu trop succinct pour l’IA. Je vais utiliser la version Web de ChatGPT pour lui demander, en dehors d’OpenCode, de clarifier et de mettre en forme cette liste :

ChatGPT WEB : A partir de cette liste de consignes, crée un prompt pour une IA agentique afin qu’elle adapte son fichier agents.md en conséquence

  • D’interdire l’utilisation des pointeurs et des fonctions new et free et de priviligier une allocation des ressources mémoire à partir des containers de la STL : vector array map.

  • D’utiliser des smarts pointeurs au cas où des pointeurs seraient requis pour du polymorphisme d’héritage

  • D’utiliser le programme du cours : structure, template, STL, Smart pointer, héritage et polymorphisme, functor et lambda. Les aspects plus avancés ou plus obscurs du C++ sont à éviter.

  • De priviligier la programmation orienté objet

  • De respecter le principe d’encapsulation en utilisant les mots clefs private et public. De mettre en place des getter / setter lorsque cela est nécessaire.

  • De mettre une classe / structure par fichier

  • D’utiliser la classe V2 pour les calculs géométriques 2D

  • De qualifier des méthodes membres const lorsque cela est judicieux

  • D’utiliser des const référence plutôt que des références lorsque cela est judicieux

  • Respecter la convention de nommage camelCase

  • Ajouter des commentaires juste au-dessus de chaque nouvelle fonction pour expliquer son fonctionnement

  • Ne pas gérer les exceptions du C++ ou les signaux d’erreur retournés par des fonctions afin d’alléger le code

  • Ne pas vérifier ni traiter les valeurs de retour des fonctions SDL3 lorsqu’elles servent à signaler une erreur ou un échec.

REPONSES : consignes.txt guidelines.txt

ChatGPT a clarifié de nombreux points en ajoutant des informations utiles. Nous transferons donc ces consignes à OpenCode :

OpenCode : (Recopiez les consignes)

REPONSES (1min30) :

Je vais intégrer ces conventions comme règles obligatoires, en distinguant l’état actuel du code des règles à appliquer à l’avenir. La séparation MLR sera conservée, mais sans imposer const dans les nouvelles signatures.

AGENTS.md a été mis à jour et relu intégralement.

Toutes les conventions obligatoires ont été intégrées.

Leur priorité sur les pratiques du code existant est explicite.

La documentation MLR, la compilation et les contrats compatibles ont été conservés.

L’instruction imposant les signatures avec const a été adaptée.

Aucun fichier source n’a été modifié.

Conclusion

Nous avons clarifié les consignes et mis en place un fichier agents.md assez complet.

Voici le résultat obtenu pour le fichier agents.md. Vous pouvez le reprendre tel quel directement dans votre projet en cas de problème :