Prompt engineering avancé avec Github Copilot : Guider l’IA avec les fichiers Markdown custom

Introduction : 

Pré-requis pour cette article et les exemples fournis : dernière versions LTS de Java (article écrit en juillet 2025 donc Java 21), l’IDE sera IntellIJ Ultimate et Github Copilot avec une licence pro. Les instructions sont décrites pour un projet Java qui utilise Spring Boot 3.5.4 et une documentation OpenAPI/Swagger. L’ensemble des instructions et du code utilisées pour cet exemple sont disponibles sur le repo Git du projet : https://github.com/ekit3/prompt-engineering-example

Les modèles d’IA générative sont extrêmement puissants, mais ils ont des limites. Ils s’appuient fortement sur le contexte et la qualité des instructions qu’ils reçoivent. Un prompt mal formulé peut mener à des résultats génériques, voire inutilisables. À l’inverse, un prompt bien conçu peut transformer l’IA en un collaborateur incroyablement efficace, capable de générer du code complexe qui s’intègre parfaitement à votre base de code existante. Historiquement, le Prompt Engineering se faisait principalement via des commentaires directs dans le code et les fichiers ouverts. Cependant, avec l’émergence de techniques plus avancées comme l’utilisation de fichiers Markdown custom, le Prompt Engineering prend une nouvelle dimension, permettant une guidance plus structurée à l’échelle d’un projet, d’une organisation ou de l’entreprise !

Pour des outils comme GitHub Copilot, le Prompt Engineering consiste à :

• Guider l’IA explicitement : Lui fournir des instructions claires sur ce que vous attendez, au-delà de ce qu’elle pourrait deviner.
• Affiner le contexte : S’assurer que l’IA dispose de toutes les informations nécessaires pour comprendre votre intention et générer du code qui correspond à vos besoins spécifiques.
• Optimiser les résultats : Minimiser les suggestions hors de propos, incorrectes ou non conformes aux standards de votre projet.

Dans cet article, nous utiliserons donc un exemple d’un projet Java simple mais qui renferme une bibliothèque complète d’instructions pour GitHub Copilot déjà prête à l’emploi !

1 – Comprendre le Prompt Engineering 

Le Prompt Engineering est l’art de concevoir et d’affiner les instructions ou requêtes données à une IA générative. L’objectif est d’obtenir les réponses les plus précises, pertinentes et utiles possibles de la part de l’IA. Cette discipline ne se limite pas à la simple saisie d’un texte, mais s’apparente à une communication stratégique avec une entité non humaine.

Dans le contexte du développement logiciel, le Prompt Engineering est crucial pour exploiter le plein potentiel des assistants de codage comme GitHub Copilot. Il permet de transformer une simple suggestion de code en une solution complète et conforme aux standards de votre projet. Les ingénieurs du logiciel appliquent le Prompt Engineering pour :

• Fournir un contexte riche : L’IA ne peut générer que du code basé sur ce qu’elle « voit ». Un prompt efficace lui donne des informations sur l’architecture, les conventions de nommage, les dépendances et les objectifs fonctionnels.
• Limiter les résultats non pertinents : Un prompt bien formulé inclut des contraintes et des exemples, ce qui réduit le nombre de suggestions inutiles ou incorrectes.
• Assurer la cohérence : L’IA peut imiter des styles de code, mais elle a besoin de directives claires pour s’aligner sur les normes de formatage et de conception de votre équipe.

2 – Les fichiers Markdown custom (MDC) : une nouvelle approche du contexte

Historiquement, le Prompt Engineering se faisait de manière ponctuelle, en ajoutant des commentaires de code (// ou /**) ou en gardant des fichiers de référence ouverts à côté de la fenêtre de code. Bien que cette approche soit fonctionnelle, sa portée et sa réutilisation sont très limitées.

Les fichiers Markdown custom (MDC), souvent nommés copilot-instructions.md, style-guide.md, ou testing-guidelines.md, représentent une évolution de cette approche. Ces fichiers permettent de stocker des instructions structurées, détaillées et réutilisables à la racine ou dans des répertoires clés de votre projet.

Cette méthode offre plusieurs avantages majeurs :

• Centralisation des règles : Toutes les règles de codage, de sécurité, d’architecture ou de conception sont centralisées. L’IA peut les consulter et les appliquer de manière cohérente à l’échelle du projet.
• Contexte étendu : Un fichier MDC peut contenir des informations sur l’ensemble de l’application, ce qui permet à l’IA d’avoir une vision plus globale et de générer du code qui s’intègre mieux.
• Maintenabilité : Les instructions sont versionnées avec le code (via Git). Si les standards de l’équipe changent, il suffit de mettre à jour le fichier MDC.

3 – Appliquer le MDC à un projet Java dans IntelliJ avec GitHub Copilot

Maintenant, appliquons cette nouvelle approche à notre exemple de projet Java. Comme le montre la capture d’écran ci-dessous, notre projet est structuré pour maximiser l’efficacité de l’IA. Au sein du répertoire .github, nous avons un dossier agent qui contient l’ensemble de nos fichiers Markdown custom (MDC) :

• coding-standards.mdc : Ce fichier définit les règles de formatage et de style de code que l’IA doit suivre.
• structure.mdc : Il contient les directives d’organisation des fichiers et des modules, garantissant que tout nouveau code sera placé au bon endroit.
• api-interaction.mdc : Ce fichier guide l’agent sur la manière d’interagir avec les API, par exemple en décrivant comment gérer les erreurs ou les process de développement.
• testing-guidelines.mdc : Ce document fournit les instructions pour la création de tests unitaires et d’intégration, en spécifiant les frameworks et les méthodologies à utiliser.

Comment cela fonctionne ?

Le fichier copilot-instructions.md agit comme un manifeste central. Il ne contient pas les règles elles-mêmes, mais il fait référence aux autres fichiers MDC. C’est une stratégie clé : elle permet de garder les instructions organisées et de les réutiliser. Par exemple, au lieu de répéter les règles de test dans chaque fichier, copilot-instructions.md dit simplement à l’IA « pour les tests, reporte-toi au fichier testing-guidelines.mdc« . Voici un extrait du contenu de ce fichier :

## 3. Review & Completion
- **Testing:** Think through user flows and edge cases. Describe manual and automated tests as appropriate. Follow the rules defined in `.github/agent/testing-guidelines.mdc`.

Passons maintenant à la pratique : nous allons voir comment utiliser ces instructions directement dans IntelliJ pour interagir avec notre projet et l’analyser.

Dans la fenêtre « Github Copilot Chat », dans l’onglet « Ask » en cliquant sur « + », vous pouvez sélectionner manuellement un ou plusieurs fichiers .mdc pour guider l’agent (ou simplement faire un glisser/déposer des fichiers). Par exemple, si vous voulez que l’IA audit l’ensemble du projet et propose éventuellement des améliorations, vous pouvez ajouter l’ensemble des fichiers comme ceci et lui demander d’analyser tout le code à travers ces instructions. N’oubliez pas de choisir le model IA qui vous convient :

De cette manière, l’agent ne se contente pas de suggestions génériques. Il utilise les règles précises que vous avez définies pour générer un code qui correspond parfaitement aux standards de votre projet. Analysons un extrait des résultats :

Comme nous pouvons le voir, le rapport de l’agent confirme que notre projet respecte les standards définis. Il valide l’organisation des fichiers, les conventions de nommage et la séparation des responsabilités. Cela prouve que les instructions claires que nous lui avons fournies sont efficaces et pertinentes.

Pour compléter l’exemple, j’ai volontairement ajouter un package « python » avec un service Java inutile qui contient quelques warning comme ceci :

Voyons ensemble le résultat du nouvel analyse par GitHub Copilot :

Ce rapport illustre la capacité de l’agent à identifier des problèmes concrets dans le code, de la structure des packages aux erreurs de syntaxe, et à proposer des solutions directes pour les corriger. Il agit comme un véritable auditeur de code, garantissant la qualité et la cohérence du projet.

4 – Bilan : avantages, défis et bonnes pratiques du MDC

Avantages

• Cohérence du code : En centralisant les règles de style et d’architecture, vous assurez que tout le code généré ou modifié par l’IA respecte les conventions de l’équipe, ce qui réduit les erreurs et facilite la revue de code.
• Gain de productivité : L’agent agit comme un pair-programmeur toujours disponible, générant du code pertinent et conforme dès la première suggestion. Le développeur passe ainsi moins de temps à corriger des suggestions inutiles ou à chercher des informations sur les standards du projet.
• Intégration et formation : Les fichiers MDC servent de documentation vivante pour les nouveaux arrivants. Ils peuvent se familiariser rapidement avec les normes de l’équipe en consultant ces fichiers, sans avoir besoin d’un mentorat constant.
• Qualité du code : L’audit automatique et continu du code par l’agent permet de détecter et de corriger des problèmes de structure ou de syntaxe avant même qu’ils ne soient poussés dans le dépôt, améliorant ainsi la robustesse et la maintenabilité du code.

Défis

• Investissement initial : La création et la maintenance des fichiers MDC demandent du temps et des efforts. Pour que la méthode soit efficace, les instructions doivent être précises et à jour.
• Complexité de l’agent : Une sur-spécification des règles peut parfois limiter la créativité et la flexibilité de l’IA, la rendant moins utile pour des tâches complexes. Il faut trouver le bon équilibre entre la guidance et l’autonomie.
• Dépendance de l’outil : Bien que l’approche soit de plus en plus standard, l’efficacité peut varier selon les outils et les versions de l’IA.

Bonnes pratiques :

• Commencez simple : Créez d’abord des fichiers MDC pour les règles les plus importantes (style de code, structure de base), puis enrichissez-les au fur et à mesure que votre projet évolue.
• Mettez à jour vos MDCs : Considérez-les comme des documents vivants, soumis au même processus de revue et de versionnage que votre code.
• Soyez précis et clair : Utilisez un langage direct et des exemples de code dans vos instructions. L’IA interprète mieux les directives claires.
• Testez et itérez : N’hésitez pas à expérimenter avec vos prompts pour voir comment l’agent réagit. C’est en itérant que vous trouverez la meilleure façon d’optimiser les résultats.

Conclusion
L’utilisation des fichiers MDC transforme l’IA générative en un véritable collaborateur d’équipe. Cette approche assure la cohérence du code, accélère les processus de développement et sert de guide pour les nouveaux membres. Bien qu’elle demande un investissement initial pour la rédaction des instructions, le gain en productivité et en qualité du code surpasse largement ce coût. En maintenant ces fichiers à jour, vous créez un standard de projet qui est compris et appliqué par tous, y compris votre agent d’IA.