Comment configurer les instructions personnalisées de dépôt dans GitHub Copilot pour harmoniser les standards de code et d'architecture en équipe

Lorsque les équipes d'ingénierie déploient GitHub Copilot à grande échelle, elles se heurtent rapidement à un écueil majeur : le manque d'homogénéité du code généré. Sans directives explicites au niveau du projet, le modèle d'IA s'appuie uniquement sur ses connaissances génériques et sur les fichiers récemment ouverts dans l'éditeur. Ainsi, au sein d'un même projet, un développeur se voit proposer des callbacks obsolètes en TypeScript, un autre enfreint l'architecture en couches, et un troisième introduit des dépendances non approuvées dans une Pull Request (PR).

GitHub Copilot résout cette disparité grâce aux instructions personnalisées de dépôt (Repository Custom Instructions). En conservant des fichiers Markdown versionnés dans Git — principalement .github/copilot-instructions.md à la racine et des fichiers modulaires dans .github/instructions/**/*.instructions.md —, l'équipe injecte ses frontières d'architecture, conventions de typage, exigences de test et règles de sécurité directement dans les sessions Copilot de chaque collaborateur et dans les revues de code automatisées.

Ce guide explique le fonctionnement des instructions de dépôt, leur hiérarchie de priorité, la configuration globale et par chemin, l'activation des revues automatisées sur GitHub.com, ainsi que les bonnes pratiques indispensables pour éviter la saturation du contexte des modèles.

Périmètre d'application : où s'appliquent les instructions (et où elles ne s'appliquent pas)

Avant de rédiger des règles, l'équipe doit comprendre comment les différentes fonctionnalités de GitHub Copilot exploitent ces fichiers.

Les instructions personnalisées de dépôt sont automatiquement ajoutées en tête du prompt système transmis aux LLMs lors des flux d'interaction et de raisonnement complexe :

• Copilot Chat dans les IDEs : VS Code, Visual Studio, la suite JetBrains (IntelliJ IDEA, PyCharm, WebStorm, etc.), Xcode et Eclipse.
• Surfaces sur GitHub.com : Chat web sur le dépôt, tâches autonomes de l'agent cloud (Cloud Agent) et création automatisée de PR.
• Copilot Code Review : Revue automatique de pull requests sur GitHub.com, où Copilot évalue les différences (diffs) au regard des instructions du dépôt.
• Copilot CLI : Assistance en ligne de commande dans les terminaux.

La distinction avec la complétion en ligne (Ghost Text)

Les instructions personnalisées ne contrôlent pas de manière stricte le texte fantôme (ghost text) qui s'affiche en temps réel lors de la frappe. La complétion en ligne est conçue pour répondre avec une latence de quelques millisecondes et privilégie les tokens immédiatement voisins ainsi que les onglets ouverts. Les instructions de dépôt sont avant tout destinées au Chat, aux commandes de refactorisation (/fix, /explain), aux agents autonomes et aux revues de PR. Pour faire respecter des règles de syntaxe rigides (points-virgules, indentation, guillemets), combinez Copilot avec des outils d'analyse statique déterministes comme ESLint, Biome ou Prettier.

Hiérarchie de priorité des instructions

Lorsque plusieurs niveaux d'instructions coexistent, GitHub Copilot les ordonne selon la priorité suivante (de la plus haute à la plus basse) :

1. Instructions personnelles (Personal instructions) : Préférences individuelles configurées par le développeur dans son profil Copilot.
2. Instructions spécifiques au chemin (Path-specific instructions) : Fichiers .github/instructions/**/*.instructions.md ciblant les fichiers modifiés via des motifs glob.
3. Instructions globales du dépôt (Repository-wide instructions) : Le fichier central .github/copilot-instructions.md à la racine.
4. Instructions d'agent : Fichiers tels que AGENTS.md, CLAUDE.md ou GEMINI.md.
5. Instructions d'organisation (Organization instructions) : Directives configurées par les administrateurs à l'échelle de l'organisation GitHub.

Étape 1 : Créer les instructions globales du dépôt (.github/copilot-instructions.md)

Le fichier de référence se place dans le dossier .github à la racine du dépôt Git :

mkdir -p .github
touch .github/copilot-instructions.md

Pour garantir une compréhension optimale par l'IA, structurez le fichier avec des en-têtes Markdown explicites, des listes à puces et des consignes affirmatives.

Sections clés à inclure

1. Vue d'ensemble et frontières architecturales : Rôle du service, modèle d'architecture (Clean Architecture, monolithe modulaire, architecture hexagonale) et règles d'isolation (ex. : « La couche domaine ne doit jamais importer de pilotes de base de données ni de composants d'interface »).
2. Versions de langage et outillage clé : Versions exactes des runtimes et bibliothèques (ex. : Node.js 22 LTS, TypeScript 5.5, Next.js 15 App Router).
3. Standards de code et gestion des erreurs : Conventions de nommage, gestion des erreurs asynchrones (ex. : « Utiliser des types Result au lieu de lever des exceptions non capturées »).
4. Directives de test : Framework de test (Vitest, Jest), structure des suites (AAA : Arrange-Act-Assert) et couverture requise pour la logique métier.
5. Sécurité et validation des entrées : Bibliothèques de validation obligatoires (Zod, Pydantic), requêtes SQL paramétrées et interdiction d'identifiants codés en dur.

Exemple de configuration prête pour la production (TypeScript / Next.js)

# Architecture du dépôt et standards de développement

## Vue d'ensemble du projet
Ce dépôt héberge le service de facturation central (Core Billing Service), architecturé avec Next.js et Node.js, interfacé avec PostgreSQL et l'API Stripe.

## Frontières architecturales
- Séparation stricte des couches : Composants UI (`/app`, `/components`) -> Services applicatifs (`/src/services`) -> Modèles de domaine (`/src/domain`) -> Dépôts de données (`/src/infrastructure`).
- La couche domaine doit rester agnostique à tout framework. Il est interdit d'importer `next/*` ou des clients de base de données dans `/src/domain`.
- Tout accès à la base de données doit transiter par les dépôts Prisma sous `/src/infrastructure/repositories`. Les requêtes SQL brutes hors migrations sont interdites.

## Standards TypeScript
- TypeScript 5.x en mode strict. L'usage de `any` est prohibé ; utilisez `unknown` avec rétrécissement de type ou validation Zod explicite.
- Privilégiez les alias `type` pour les définitions d'objets et d'unions ; réservez `interface` aux contrats extensibles.
- Traitez les erreurs asynchrones avec des types `Result<T, E>` ou des classes d'erreur structurées ; aucune Promise rejection non gérée.
- Utilisez des clauses de garde (guard clauses) et des retours anticipés pour limiter les imbrications de if/else.

## Gestion d'état et requêtes réseau
- La récupération de données côté client doit utiliser TanStack Query (`@tanstack/react-query`). Ne lancez pas d'appels API non mis en cache dans des hooks `useEffect`.
- Les Server Actions doivent valider les données entrantes avec Zod avant d'appeler les services de domaine.

## Normes de test
- Outil d'exécution : Vitest avec React Testing Library.
- Les tests unitaires doivent être co-localisés avec les fichiers sources (`*.spec.ts` ou `*.spec.tsx`).
- Structure Arrange-Act-Assert (AAA) obligatoire dans chaque suite de tests.
- Isolez les échanges réseau avec Mock Service Worker (MSW) ; ne pas mocker les utilitaires natifs du langage.

## Commandes de référence
- Lancer les tests : `pnpm test`
- Vérification des types : `pnpm typecheck`
- Validation du linter : `pnpm lint`

Étape 2 : Configurer des instructions par chemin (.github/instructions/)

Dans les monorépôts ou les architectures full-stack, concentrer l'ensemble des règles dans un fichier unique surcharge la fenêtre de contexte de l'IA. Un ingénieur modifiant un microservice en Go n'a que faire des règles de style Tailwind propres au frontend React.

Les instructions ciblées par chemin résolvent ce problème en liant des règles précises à des motifs glob.

Organisation des dossiers

Placez vos fichiers spécialisés dans .github/instructions/ :

.github/
  ├── copilot-instructions.md
  └── instructions/
      ├── frontend.instructions.md
      ├── backend.instructions.md
      └── migrations.instructions.md

Syntaxe avec bloc Frontmatter

Chaque fichier doit obligatoirement porter l'extension .instructions.md et commencer par un bloc YAML Frontmatter contenant l'attribut applyTo :

---
applyTo: "apps/web/**/*.{ts,tsx}"
---

# Standards pour les composants Frontend

- Les composants doivent être des fonctions avec exportations nommées (Named Exports).
- Utilisez les classes utilitaires de Tailwind CSS ; évitez les objets de style CSS en ligne.
- Tout élément interactif doit comporter les attributs d'accessibilité `aria-*` et supporter la navigation clavier.
- Les icônes doivent être importées exclusivement depuis `lucide-react`.

Motifs Glob courants

• **/*.py : S'applique à tous les fichiers Python du dépôt.
• services/billing/**/*.go : S'applique exclusivement au code Go du service de facturation.
• **/*.test.ts,**/*.spec.ts : Associe deux extensions de fichiers de test séparées par une virgule.

Exclusion d'agents spécifiques (excludeAgent)

Si un ensemble de directives concerne uniquement les tâches de l'agent autonome et ne doit pas intervenir lors des revues de PR, indiquez excludeAgent :

---
applyTo: "**"
excludeAgent: "code-review"
---

# Guide pour l'agent de build autonome
- Exécutez `pnpm db:migrate` avant de lancer la suite de tests d'intégration.
- En cas d'ajout de nouvelles variables d'environnement, mettez à jour `.env.example`.

Étape 3 : Activer la vérification automatique dans les revues de Pull Requests

Les instructions personnalisées ne se contentent pas d'accompagner la saisie dans l'IDE : elles fournissent également une grille d'évaluation pour les revues de PR réalisées par Copilot.

Activation sur GitHub.com

1. Accédez à la page d'accueil de votre dépôt sur GitHub.com.
2. Cliquez sur l'onglet Settings (Paramètres).
3. Dans la barre latérale gauche, ouvrez Code, planning, and automation -> Copilot -> Code review.
4. Activez l'option Use custom instructions when reviewing pull requests.

Fonctionnement de la lecture sur la branche source (Head Branch)

Lorsqu'il examine une PR, GitHub Copilot consulte les fichiers d'instruction situés sur la branche source de la PR (head branch), et non sur la branche cible (main).

Ce fonctionnement offre un avantage opérationnel majeur : lorsque les architectes souhaitent actualiser les standards de code, ils peuvent soumettre une PR combinant la modification des instructions et l'implémentation associée. Copilot évalue immédiatement les différences par rapport aux nouvelles règles, ce qui permet de valider leur pertinence avant la fusion définitive dans la branche principale.

Étape 4 : Valider le chargement des instructions dans l'IDE

Pour s'assurer que les postes de développement prennent bien en compte les fichiers d'instruction :

1. Vérification des réglages dans l'IDE :
   • Dans VS Code : Ouvrez les Paramètres (Ctrl+, ou Cmd+,), recherchez instruction file et confirmez que l'option Code Generation: Use Instruction Files est cochée (activée par défaut).
   • Dans les IDEs JetBrains : Dans le panneau Copilot Chat, cliquez sur l'engrenage et sélectionnez Customizations pour vérifier les fichiers d'instruction pris en compte.
2. Vérification des références (References) dans le Chat :
   • Posez une question technique dans Copilot Chat (ex. : « Implémente un service de validation client »).
   • Déroulez la section References située en haut de la réponse fournie.
   • Si les règles sont actives, .github/copilot-instructions.md (ainsi que les éventuels fichiers .instructions.md pertinents) apparaîtront sous forme de liens cliquables, confirmant que l'IA a exploité vos directives.

Bonnes pratiques et pièges à éviter

Complémentarité avec les fichiers de prompt (.github/prompts/*.prompt.md)

Tandis que les instructions de dépôt fixent des garde-fous permanents, les équipes disposent souvent de flux opérationnels récurrents : création d'un point d'accès API, scripts de migration ou génération de tests unitaires.

Pour ces tâches, associez les instructions de dépôt aux fichiers de prompt Copilot (.github/prompts/*.prompt.md). Les développeurs peuvent invoquer ces modèles structurés dans le Chat, tandis que .github/copilot-instructions.md garantit en continu que le code produit reste conforme à l'architecture globale.

Liste de contrôle pour les leads d'ingénierie

1. Créer .github/copilot-instructions.md à la racine avec les principes d'architecture, les versions figées et les standards non négociables.
2. Découper les règles par module dans .github/instructions/ avec des motifs applyTo pour cibler les dossiers spécifiques.
3. Activer la prise en compte des instructions personnalisées dans Copilot Code Review sur GitHub.
4. Vérifier la section References dans Copilot Chat pour confirmer la bonne lecture des fichiers.
5. Mettre à jour les instructions de manière continue via des PRs lors de chaque évolution d'architecture.

Références

• Adding repository custom instructions for GitHub Copilot - GitHub Docs
• Adding repository custom instructions for GitHub Copilot in your IDE - GitHub Docs
• Support for different types of custom instructions - GitHub Docs
• About customizing GitHub Copilot responses - GitHub Docs
• 5 tips for writing better custom instructions for Copilot - The GitHub Blog