Personnaliser les réponses GitHub Copilot à l’aide de fichiers d’instructions

  • 8 minutes

Les fichiers d’instructions personnalisés permettent d’incorporer les normes de codage de votre équipe, les décisions architecturales et les instructions spécifiques au projet directement dans votre dépôt. Lorsque GitHub Copilot Chat traite une demande, il lit ces fichiers et incorpore leur contenu dans ses réponses, produisant des suggestions qui s’alignent sur les conventions de votre projet sans vous obliger à répéter le même contexte dans chaque invite.

Instructions personnalisées « Always-on »

Le mécanisme principal pour les instructions au niveau du référentiel est un fichier Markdown nommé .github/copilot-instructions.md placé à la racine de votre référentiel ou espace de travail. Ce fichier fournit à GitHub Copilot un contexte et des règles supplémentaires qui s’appliquent à toutes les interactions GitHub Copilot Chat au sein de ce projet. Les instructions sont automatiquement incluses dans chaque invite GitHub Copilot Chat, servant de directives toujours actives pour l'IA.

Par exemple, si votre .github/copilot-instructions.md fichier spécifie « Utiliser PascalCase pour les noms de classes et camelCase pour les variables locales » ou « Toujours utiliser le modèle de référentiel pour les classes d’accès aux données », GitHub Copilot incorpore ces conventions dans ses suggestions. Cette fonctionnalité réduit la quantité de modification manuelle nécessaire pour aligner le code généré par l’IA avec des instructions d’équipe, ce qui améliore l’efficacité et la cohérence dans la base de code.

Les instructions sont écrites en langage naturel à l’aide de la mise en forme Markdown. Chaque directive peut être présentée sous la forme d'un point de liste ou d'un paragraphe. L’espace blanc entre les instructions est ignoré lorsqu’il est envoyé au modèle. Vous pouvez donc mettre en forme le fichier pour une lisibilité sans affecter la façon dont GitHub Copilot le traite.

Vous pouvez utiliser la /init commande de barre oblique dans GitHub Copilot Chat pour générer automatiquement un copilot-instructions.md fichier pour votre projet. GitHub Copilot analyse votre espace de travail et produit un fichier d’instructions de démarrage adapté au langage, à l’infrastructure et à la structure de votre projet.

Note

Visual Studio Code prend également en charge les fichiers AGENTS.md et CLAUDE.md en tant qu’instructions toujours actives. Un AGENTS.md fichier placé à la racine de votre espace de travail fonctionne de la même façon copilot-instructions.md et est utile lorsque vous travaillez avec plusieurs agents IA et que vous souhaitez un ensemble unique d’instructions reconnues par tous. CLAUDE.md les fichiers suivent le même modèle. En outre, les fichiers imbriqués AGENTS.md peuvent être placés dans des sous-répertoires pour fournir des instructions spécifiques au contexte qui s’appliquent uniquement lorsque GitHub Copilot opère sur des fichiers au sein de ce répertoire ou de ses enfants.

Instructions spécifiques au chemin d’accès

Pour les projets où différentes parties du codebase nécessitent des instructions différentes, vous pouvez créer des fichiers d’instructions basés sur des fichiers à l’aide de l’extension .instructions.md . Ces fichiers sont stockés dans le .github/instructions/ répertoire (ou dans votre profil utilisateur pour une utilisation inter-espaces de travail) et incluent un en-tête frontmatter YAML avec un applyTo champ qui spécifie les fichiers ou les modèles de fichiers auxquels ils s’appliquent.

Par exemple, un fichier nommé database.instructions.md avec applyTo: "DataAccess/**/*.cs" peut contenir des règles qui s’appliquent uniquement aux fichiers C# dans le dossier DataAccess, tels que « Utiliser le modèle de référentiel pour les classes d’accès aux données » ou « Toujours inclure des requêtes paramétrables pour empêcher l’injection SQL ». Lorsque GitHub Copilot fonctionne avec des fichiers qui correspondent au modèle spécifié, il fusionne les instructions à l’échelle du référentiel et les instructions spécifiques au chemin d’accès pertinentes pour produire des suggestions contextuellement appropriées.

L’exemple suivant montre un fichier d’instructions spécifiques au chemin d’accès avec le frontmatter YAML :

---
name: 'C# Backend Standards'
description: 'Coding conventions for C# backend files'
applyTo: 'src/Backend/**/*.cs'
---
# C# backend coding standards
- Use PascalCase for public members and camelCase for private fields.
- Prefix private fields with an underscore (e.g., _orderService).
- Use async/await for all I/O-bound operations.
- Include XML documentation comments on all public methods.

Le frontmatter YAML prend en charge les champs suivants :

  • applyTo : un motif glob qui détermine quels fichiers déclenchent les instructions. Les modèles courants incluent **/*.cs la correspondance entre tous les fichiers C#, src/Frontend/**/*.ts pour faire correspondre les fichiers TypeScript dans un répertoire spécifique ou **/Tests/**/*.cs pour faire correspondre les fichiers de test dans le projet. Quand le chemin d’accès d’un fichier correspond à un applyTo modèle, GitHub Copilot inclut automatiquement ces instructions en même temps que les instructions générales du référentiel.

  • description : description du langage naturel de ce que couvrent les instructions. GitHub Copilot utilise ce champ pour la correspondance sémantique : lorsque vous posez une question dans la conversation, GitHub Copilot évalue la description pour déterminer si les instructions sont pertinentes pour le contexte actuel, même si aucun fichier correspondant au applyTo modèle n’est ouvert. Par exemple, une description des « Instructions pour les scripts de migration de base de données » aide GitHub Copilot à inclure ces instructions lorsque vous demandez des migrations de base de données.

  • nom : nom complet du jeu d’instructions qui apparaît dans le menu Instructions de conversation et vue diagnostics.

Instructions au niveau de l’organisation

Pour les entreprises qui gèrent des normes de codage sur plusieurs référentiels, GitHub prend en charge les instructions au niveau de l’organisation. Ces instructions sont définies au niveau de l’organisation GitHub et sont appliquées dans tous les référentiels au sein de l’organisation. Ce comportement garantit la cohérence entre les équipes, par exemple, une norme de codage sécurisée partagée ou une directive architecturale à l’échelle de l’organisation afin que tous les projets commencent par la même ligne de base.

Dans Visual Studio Code, les instructions au niveau de l’organisation sont automatiquement détectées lorsque vous êtes connecté à un compte GitHub qui a accès à une organisation avec des instructions personnalisées configurées. Ces instructions s’affichent en même temps que vos instructions personnelles et de votre espace de travail dans le menu Instructions de conversation.

Note

Lorsque plusieurs types d’instructions personnalisées existent, GitHub Copilot les inclut tous, mais suit un ordre de priorité lors de la résolution des conflits. La chaîne de priorité d’instruction complète, du plus haut au plus bas, est la suivante :

  1. Instructions entrées manuellement dans le menu Instructions de conversation ou épinglées à la conversation.
  2. .instructions.md fichiers (instructions spécifiques au chemin).
  3. .github/copilot-instructions.md (instructions à l’échelle du référentiel).
  4. fichiers AGENTS.md ou CLAUDE.md.
  5. Instructions au niveau de l’organisation configurées par un administrateur d’organisation GitHub.

Les instructions de priorité supérieure sont prioritaires lorsque des conflits se produisent.

Guide pratique pour créer des fichiers d’instructions

La création de fichiers d’instructions personnalisés implique quelques étapes simples.

Activer la fonctionnalité

Vérifiez que les instructions personnalisées des .github fichiers sont activées dans les paramètres gitHub Copilot Chat de Visual Studio Code. Ce paramètre est activé par défaut. Vous pouvez le confirmer en vérifiant le chat.includeApplyingInstructions paramètre dans Visual Studio Code.

Ajouter .github/copilot-instructions.md

Dans la racine de votre référentiel, créez un .github dossier s’il n’en existe pas déjà. Dans ce dossier, créez un fichier nommé copilot-instructions.md. Écrivez vos instructions en langage naturel à l’aide de la mise en forme Markdown. Par exemple:

# Project coding guidelines
- Use PascalCase for class names and public members.
- Prefix private fields with an underscore (e.g., _logger).
- Follow the repository pattern for all data access operations.
- Use async/await for I/O-bound operations.
- Include error handling with try-catch blocks for all external API calls.
- Add XML documentation comments on all public methods and classes.

Ces instructions sont automatiquement ajoutées à chaque invite GitHub Copilot Chat dans le référentiel, de sorte qu’elles influencent toutes les réponses sans aucune action supplémentaire du développeur.

Ajouter des fichiers .instructions.md (si nécessaire)

Pour cibler des types de fichiers ou des sections spécifiques du projet, créez un instructions sous-dossier sous .github. Ajoutez un ou plusieurs fichiers Markdown avec des noms se terminant par .instructions.md (par exemple, logging.instructions.md ou sql.instructions.md). En haut de chaque fichier, incluez un en-tête YAML avec un applyTo champ répertoriant les modèles de chemin d’accès de fichier (modèles glob) auxquels les instructions doivent s’appliquer. Écrivez ensuite les instructions spécialisées dans le corps de Markdown.

Par exemple, un logging.instructions.md fichier peut spécifier applyTo: "**/*Logger.cs" et contenir des conseils sur l’utilisation d’une infrastructure de journalisation spécifique dans ces fichiers. Si le chemin d’accès d’un fichier actif correspond au applyTo modèle, GitHub Copilot combine à la fois les instructions générales du référentiel et les instructions spécifiques au chemin d’accès pertinentes pour ce contexte.

Vérification

Pour vérifier que GitHub Copilot utilise vos instructions, consultez la section Références d’une réponse GitHub Copilot Chat. Lorsque des instructions personnalisées sont appliquées, le fichier d’instructions apparaît sous la forme d’une référence citée. Si les instructions ne sont pas récupérées, vérifiez que la fonctionnalité est activée dans les paramètres et que le chemin d’accès au fichier et le nommage suivent les conventions attendues.

Vous pouvez également utiliser la vue diagnostics de personnalisation de conversation pour afficher tous les fichiers d’instructions chargés et toutes les erreurs. Cliquez avec le bouton droit dans la vue Conversation et sélectionnez Diagnostics pour inspecter l’état actuel.

Avantages des instructions personnalisées

Les instructions au niveau du référentiel alignent la sortie IA avec les conventions d’équipe et réduisent la modification manuelle nécessaire pour chaque suggestion. Voici plusieurs façons dont les instructions personnalisées améliorent l’expérience de développement :

  • Conventions d’affectation de noms : appliquer des modèles tels que « les champs C# privés doivent commencer par un trait de soulignement » ou « utiliser PascalCase pour les propriétés publiques » dans toutes les suggestions De Copilot GitHub.

  • Utilisation de la bibliothèque et de l’infrastructure : spécifiez les bibliothèques préférées, telles que « Utiliser Serilog pour la journalisation » ou « Utiliser FluentValidation pour la validation d’entrée », de sorte que GitHub Copilot ne suggère pas d’alternatives que votre équipe choisit de ne pas utiliser.

  • Styles de commentaires de code : Exiger des formats de documentation spécifiques, tels que « Inclure des commentaires de documentation XML sur toutes les méthodes publiques » ou « Utiliser // pour les commentaires inline, et non /* */».

  • Modèles architecturaux : Incorporer des décisions telles que « Toutes les classes d’accès aux données doivent implémenter l’interface IRepository<T> » ou « Utiliser l’injection de dépendances pour toutes les dépendances de service ».

  • Sécurité et conformité : incluez des règles telles que « Toujours utiliser des requêtes paramétrables pour l’accès à la base de données » ou « Valider toutes les entrées utilisateur aux limites de l’API ».

Les instructions spécifiques au chemin permettent d’obtenir des conseils encore plus ciblés. Différentes règles peuvent s’appliquer au serveur frontal et au code principal, aux fichiers de test et au code de production, ou à des modules spécifiques avec des exigences uniques. Cette granularité garantit que les suggestions sont pertinentes pour la zone spécifique de la base de code dans laquelle le développeur travaille.

Conseils pour écrire des instructions efficaces

Des instructions bien conçues produisent de meilleurs résultats. Voici des conseils pour tirer le meilleur parti des fichiers d’instructions personnalisés :

  • Expliquer le raisonnement derrière les règles. Au lieu de simplement « préfixer des champs privés avec _», écrivez « Préfixer les champs privés avec _ pour les distinguer des paramètres et des variables locales en un clin d’œil ». Lorsque GitHub Copilot comprend pourquoi une règle existe, elle applique la règle de manière plus cohérente et peut étendre le principe à des situations similaires.

  • Incluez des exemples de code court. Associez des instructions avec de brefs extraits de code montrant le modèle attendu. Par exemple, suivez « Utiliser le modèle de fabrique pour la création d’objets complexes » avec un exemple à deux lignes. Les exemples concrets réduisent l’ambiguïté.

  • Concentrez-vous sur les règles non évidentes. Ne répétez pas ce que les linters et les formateurs de code appliquent déjà. Au lieu de cela, documentez les conventions que seule votre équipe sait, comme les bibliothèques à préférer, quels modèles suivre pour la gestion des erreurs ou quelles limites architecturales existent entre les modules.

  • Conservez les instructions concises et spécifiques. Des fichiers d’instructions trop longs ou vagues diluent l’attention de GitHub Copilot. Chaque instruction doit exprimer une règle claire. Supprimez les instructions qui se chevauchent ou contredisent les uns les autres.

  • Séparez les problèmes liés à l’utilisation de fichiers spécifiques au chemin d’accès. Utilisez les fichiers .instructions.md avec des motifs applyTo pour séparer les règles backend et frontend, pour tester la logique distinctement du code de production, et pour garder les scripts d’infrastructure isolés du code d’application.

Fichiers de prompts

Outre les fichiers d’instructions qui fournissent un contexte toujours actif, Visual Studio Code prend en charge les fichiers d’invite : les modèles d’invite réutilisables stockés en tant que .prompt.md fichiers que vous pouvez appeler en tant que commandes obliques dans GitHub Copilot Chat.

Pendant que les fichiers d’instructions définissent la façon dont GitHub Copilot répond, les fichiers d’invite définissent ce qu’il faut demander. Un fichier d’invite contient une invite préécrite, avec des espaces réservés pour des variables facultatives, que vous pouvez exécuter au besoin pour réaliser une tâche commune de manière cohérente. Par exemple, vous pouvez créer un fichier d’invite qui génère une liste de contrôle de révision du code, créer un test unitaire pour le fichier actif ou produire la documentation de l’API dans un format spécifique.

Fonctionnement des fichiers d’invite

Les fichiers d’invite utilisent les extensions .prompt.md et peuvent être stockés dans le dossier .github/prompts/ de votre espace de travail (partagé avec votre équipe via le contrôle de version) ou dans votre profil utilisateur Visual Studio Code (personnel, accessible depuis tous les espaces de travail). Chaque fichier contient un en-tête facultatif de type "frontmatter YAML" et un corps Markdown avec le texte du prompt.

L’exemple suivant montre un fichier d’invite qui génère des tests unitaires :

---
description: 'Generate unit tests for the current file'
agent: 'copilot'
tools: ['search', 'read']
---
# Generate Unit Tests

Analyze the code in the active file and generate comprehensive unit tests.

For each public method or function:
1. Write a test for the expected behavior (happy path).
2. Write tests for edge cases and error conditions.
3. Use the project's existing test framework and naming conventions.

Output the tests as a complete, runnable test file.

Le frontmatter YAML pour les fichiers d’invite prend en charge les champs suivants :

Champ Descriptif
description Description en langage naturel de ce que fait l'invite. Apparaît dans le sélecteur de commandes barre oblique.
name Nom d'affichage facultatif. S’il est omis, le nom de fichier est utilisé.
agent L'agent qui devrait gérer l’invite (par exemple, copilot).
model Préférence facultative de modèle pour cette invite.
tools Les outils à l’invite doivent avoir accès lors de l’exécution.

Utilisation des fichiers de commande

Une fois créés, les fichiers d’invite apparaissent sous forme de commandes obliques dans l’entrée GitHub Copilot Chat. Saisissez / suivi du nom du fichier d’invite (sans l’extension .prompt.md) pour le sélectionner et l’exécuter. Par exemple, un fichier nommé generate-tests.prompt.md devient la /generate-tests commande.

Les fichiers d’invite prennent en charge les espaces réservés variables à l’aide de la syntaxe ${variable}. La variable ${file} fait référence au fichier actif et ${selection} fait référence à la sélection de texte actuelle. Vous pouvez également définir des variables personnalisées qui invitent l’utilisateur à entrer une fois le fichier d’invite exécuté.

Note

Pour activer les fichiers d’invite, vérifiez que le chat.promptFiles paramètre est activé dans Visual Studio Code. Lorsqu'ils sont activés, vos fichiers .prompt.md sont automatiquement détectés et enregistrés comme commandes slash disponibles.

Limites

Les fichiers d’instructions personnalisés présentent quelques limitations importantes à garder à l’esprit :

  • Aucun effet sur la saisie semi-automatique en ligne : les instructions personnalisées s’appliquent à GitHub Copilot Chat ainsi qu'à d'autres requêtes de haut niveau. Ils n'influencent pas les remplissages de code en ligne basiques qui apparaissent à mesure que vous tapez dans l'éditeur.

  • Concision : les fichiers d’instructions volumineux et non concentrés peuvent entraîner des résultats dilués ou imprévisibles. Gardez les instructions concises et pertinentes pour les recommandations les plus importantes. Concentrez-vous sur les règles qui ne sont pas déjà appliquées par les linters ou les formateurs.

  • Aucune conformité garantie : les instructions guident le comportement de GitHub Copilot, mais n’appliquent pas de règles strictes. L’IA considère les instructions en même temps que d’autres contextes, de sorte que les résultats peuvent parfois varier des attentes.

Résumé

Les fichiers d’instructions personnalisés et les fichiers d’invite fournissent un moyen structuré de guider le comportement de GitHub Copilot au niveau du référentiel, du chemin et de l’organisation. En créant un fichier .github/copilot-instructions.md pour les normes du projet, des fichiers .instructions.md facultatifs pour les règles spécifiques de chemin, et des fichiers .prompt.md pour des modèles d'invitation réutilisables, vous pouvez aligner les suggestions générées par l’IA avec les conventions de codage de votre équipe. Lorsque vous écrivez des instructions efficaces, avec des raisonnements, des exemples et une étendue ciblée, elle optimise la valeur de ces fonctionnalités de personnalisation. Ensemble, ces outils réduisent les corrections manuelles, améliorent la cohérence du code et incorporent les connaissances de votre équipe directement dans le flux de travail de développement.