Maîtriser GitHub Copilot dans VSCode : le guide ultime des instructions personnalisées

GitHub Copilot, lorsqu’il est utilisé dans Visual Studio Code, n’est pas seulement un outil d’autocomplétion : c’est un assistant capable de s’adapter à ton environnement, ton style et tes besoins.

Sans règles, Copilot agit comme un modèle générique : il propose du code standard, parfois en décalage avec tes conventions internes, tes contraintes techniques ou ta façon de rédiger. Avec des custom instructions, tu transformes Copilot en un collaborateur aligné avec ta façon de travailler.

Les custom instructions permettent de guider Copilot de manière précise : elles l’aident à produire du code conforme à ton style et à tes standards, à réaliser des revues de code ou des modifications en respectant les conventions de ton équipe, à adapter le ton et la structure des réponses selon ton public — qu’il soit technique ou non technique — et enfin à prioriser certains frameworks, bibliothèques ou patterns spécifiques à ton projet.

En définissant des règles, tu injectes ta voix et tes pratiques métiers dans les suggestions :

• Style de code : indentation, nommage, organisation des imports.
• Stack technique : préciser les bibliothèques, frameworks ou outils à utiliser.
• Structure des livrables : exiger des tests, des commentaires, ou un format précis pour les commits.
• Niveau de détail : demander des explications pédagogiques ou au contraire un code concis.

TL;DR — panorama des types de règles

Exemple concret

Utilisons un prompt simple pour développer une roue de sélection de noms. Les utilisateurs pourraient y entrer des noms, et il y aurait un bouton "Choisir un gagnant". Quand on clique dessus, la roue tourne et affiche un nom gagnant.

Develop a name picker widget in the form of a wheel. This widget should allow users to input names and include a "Choose Winner" button that, when clicked, spins the wheel and displays a winning name.

Sans règles personnalisées

La première version est très générique : elle se concentre sur la rotation de la roue et l'affichage du gagnant, sans trop se soucier de l'expérience utilisateur, du thème ou de la localisation. Les libellés sont en anglais, les commentaires s'affichent directement sous forme de texte brut et le style est minimaliste. Cela fonctionne, mais on a l'impression d'un code standard qui pourrait s'adapter à n'importe quel projet sans vraiment s'adapter à l'environnement.

Avec des custom instructions

Grâce à l’application créée pour un autre article sur les patrons de conception avec Flutter, je lui ai demandé de générer des instructions qui correspondent à mon style d’écriture. Mais vous verrez plus tard dans l’article que Copilot propose des solutions pour créer automatiquement ces règles.

You are an expert software assistant.  
I want you to analyze this codebase and generate a **custom instruction guide** for GitHub Copilot so that its suggestions match the project’s coding style and best practices.

### Steps:
1. **Analyze the codebase**:
   - Frameworks, libraries, architecture.
   - Naming conventions.
   - State management patterns.
   - File and folder structure.
   - Testing strategy.
   - Commenting/documentation style.

2. **Generate a structured Copilot instruction guide** with the following sections:
   - **Identity & Context** → who the developer is in this project context, what stack/framework is used.
   - **Goals & Expectations** → what to optimize for (readability, testability, performance, etc.).
   - **Style & Conventions** → naming rules, file structure, code style, widget/component design rules.
   - **Do’s & Don’ts** → explicit rules for what to prefer/avoid in code generation.
   - **Interaction Style** → how Copilot should explain or suggest code (minimal, detailed, alternatives, etc.).

3. **Output**:
   - Clear, concise, and copy-paste ready.
   - Written as if I will paste it directly into Copilot’s “Custom Instructions” section.
   

La deuxième version, cependant, montre une nette amélioration des pratiques. Le widget s'intègre mieux à Material Design en utilisant des Card, des Border, des Chip pour la gestion des participants et des AlertDialog pour les commentaires. Il respecte le thème de l'application en utilisant la palette de couleurs et adapte même les libellés au français. Le processus de sélection du gagnant est également plus abouti, avec une désactivation appropriée des boutons lorsque le nombre de participants ajoutés est insuffisant et une AlertDialog dédiée pour célébrer le résultat.

Au-delà de la simple fonctionnalité, des instructions claires transforment un extrait générique en composant prêt à s’intégrer à ton design system, ton langage et tes normes d’expérience utilisateur. C’est la différence entre du code standard e du code aligné sur les standards de ton équipe.

Types de règles (custom instructions)

Dans Visual Studio Code, Copilot peut être guidé par différents types de règles, chacune ayant sa portée et son utilité.

Même si certaines sont spécifiques à GitHub Web ou à Copilot Enterprise, nous allons surtout nous concentrer sur celles qui influencent l’expérience dans VS Code.

Instructions personnelles (Personal custom instructions)

C’est une phrase, un ordre que l’on met au début du chat, comme contexte, juste avant d’écrire ton prompt. Principalement utilisées dans GitHub Web, mais la logique est la même pour fixer un style global.

Adding personal custom instructions for GitHub Copilot - GitHub Enterprise Cloud Docs

Ces réglages s'appliquent à toutes tes conversations Copilot, peu importe le projet. Ils te permettent de personnaliser ton style de communication, tes préférences techniques et le format de sortie désiré.

Exemples :

• “Explique toujours le code en commentaires.”
• “Utilise le style Python PEP8 et des docstrings Google-style.”
• “Réponds toujours en français sauf si le code est en anglais.”

Ces instructions servent de socle : elles assurent une cohérence dans toutes les interactions avec Copilot.

Instructions par dépôt (Repository custom instructions)

Le cœur de la personnalisation dans VS Code. Adding repository custom instructions for GitHub Copilot - GitHub Enterprise Cloud Docs

Les instructions pour GitHub Copilot sont limitées à un projet précis et sont implémentées via un fichier .github/copilot-instructions.md à la racine du dépôt. Ce fichier, rédigé en Markdown et en langage naturel, sert à définir des conventions de code, spécifier les outils à utiliser (frameworks, CI/CD, test runners), et imposer des règles d'architecture ou de performance.

Note de disponibilité : la configuration multi-fichiers avec front matter applyTo peut dépendre de la version/du tenant et n’est pas toujours activée. Si elle n’est pas disponible, utilisez le fichier unique recommandé .github/copilot-instructions.md.

---
applyTo: "src/**/*.ts"
---
Always explicitly type all TypeScript functions.
Prohibit `any`.
Use ESLint according to `.eslintrc`.

Instructions organisationnelles (Organization custom instructions)

Elles fonctionnent comme les instructions personnelles et sont réservées à Copilot Enterprise – non spécifiques à VS Code mais compatibles.

Adding organization custom instructions for GitHub Copilot - GitHub Enterprise Cloud Docs

Ces paramètres et règles s'appliquent à tous les dépôts et utilisateurs de l'organisation. Leur administration est gérée par les owners de l'organisation. Ils servent à uniformiser les conventions de code, les pratiques de développement, et à appliquer de manière cohérente les politiques de sécurité et les exigences de conformité sur l'ensemble des projets.

Prompt files (VS Code)

Si tu dois réécrire le même prompt, si tu as des usages redondants. C’est un outil puissant pour automatiser des prompts réutilisables.

Use prompt files in VS Code

Les fichiers *.prompt.md sont utilisés dans VS Code pour encapsuler et permettant de standardiser des actions récurrentes telles que les revues de code, les refactorings ou les audits. Leur contenu comprend un titre ou une description, des instructions claires et, si nécessaire, des variables dynamiques comme {{fileName}} ou {{selectedText}}.

# Title: Code review
Analyses the {{fileName}} file and identifies:
- Potential bugs
- Possible optimisations
- Style violations

Copilot Edits et Agents dans VS Code

Le mode agent transforme Copilot en un assistant autonome capable de prendre en charge des tâches complètes, pas seulement des suggestions ligne par ligne. Use agent mode in VS Code

Dans ce mode, Copilot planifie, exécute et itère sur ses actions pour atteindre un objectif donné, à partir d’un simple prompt.

En mode Agent, Copilot peut :

• Modifier plusieurs fichiers en une seule tâche.
• Naviguer dans tout le projet pour trouver les points concernés.
• Exécuter des commandes (scripts, build, tests) selon le contexte.
• Proposer des plans de refactorisation détaillés avant de les appliquer.
• S’adapter dynamiquement aux résultats intermédiaires pour ajuster sa stratégie.

Les custom instructions jouent ici un double rôle. Elles servent de garde-fou afin d’éviter des choix techniques incompatibles avec ton projet, tout en constituant un cadre stratégique qui oriente les décisions de l’agent vers tes propres standards.

Exemple de comportement d’agent avec une règle d’instruction

Always document the functions you create with a Google-style docstring.

Avec Agent Mode activé, cette consigne s’applique à chaque fonction générée, quel que soit le nombre de fichiers modifiés.

Implement a clear and intuitive checkbox option, labeled "Delete winning name," which, when selected, will automatically remove the name chosen as the winner from the list.

En tant qu’agent, Copilot a lu les fichiers pertinents pour repérer le point d’intégration, et a implémenté la solution en ajoutant une option de suppression automatique du gagnant avec sa logique dédiée.

Il a ensuite vérifié le respect du style (libellés, widgets, gestion d’état) et des docstrings au format Google, a passé le lint et corrigé les ajustements nécessaires, et a contrôlé la conformité aux conventions du projet (structure, nommage, accessibilité).

Enfin, Copilot a conclu par un débrief indiquant que la fonctionnalité est isolée, contrôlable via la case à cocher, correctement documentée et sans régression observée.

Utilisation avancée dans VS Code

Génération des instructions

Bonne nouvelle, il y a un bouton magique pour créer ton fichier de règles.

Tu peux générer ces fichiers depuis l’interface de VS Code, sans passer par un éditeur externe :

• Palette de commandes → taper "Copilot: Create Instruction File".

Cette commande crée un prompt qui active Copilot afin qu'il génère un fichier .github/copilot-instructions.md spécifiquement adapté aux besoins et à la structure de ton projet actuel. Ce fichier contiendra des instructions détaillées et personnalisées pour l'utilisation optimale de Copilot dans le contexte de ton environnement de développement. L'objectif est de maximiser l'efficacité de Copilot en lui fournissant les informations nécessaires pour qu'il puisse proposer des suggestions de code, des complétions et des refactorisations pertinentes, en accord avec les conventions et les spécifications de ton projet.

Application des fichiers d’instructions dans Copilot Chat

Une fois que tes fichiers d’instructions sont en place (.github/copilot-instructions.md ou .instructions.md dans .github/instructions/), VS Code les charge automatiquement dès que tu ouvres le projet.

Ces instructions influencent directement le comportement de l’outil. D’une part, elles orientent les réponses du Chat, puisque Copilot adapte son ton, son style et respecte les contraintes définies.

D’autre part, elles guident également les Copilot Edits : lorsque tu sélectionnes du code et demandes une modification, Copilot applique les règles établies afin de produire un résultat conforme aux attentes.

La fonctionnalité Copilot peut être activée ou désactivée globalement dans les paramètres de VS Code. Il est également possible de désactiver temporairement la prise en compte des instructions pour tester un comportement "neutre" de Copilot ou en cas de changement de contexte de projet. Les modifications prennent effet immédiatement lors de la prochaine interaction avec le Chat ou le mode Edits.

Organisation des instructions

Afin de maximiser la clarté et la maintenabilité, structure les fichiers par type de tâche : src.instructions.md pour les règles de génération et d'organisation du code, tests.instructions.md pour les règles spécifiques aux tests (framework, structure, conventions), et docs.instructions.md pour les règles de documentation (format, ton, sections obligatoires).

Limitations et portée

Les règles définies dans les fichiers d’instructions influencent Copilot Chat et Copilot Edits, mais n’ont aucun effet sur les complétions inline acceptées via Tab. Leur portée est limitée au dépôt ouvert : dès qu’une instruction est modifiée dans le fichier du projet, l’impact est visible à la prochaine interaction, que ce soit une nouvelle question ou une demande d’édition.

Il est important de garder à l’esprit que des instructions trop longues augmentent le nombre de tokens utilisés, ce qui peut ralentir les réponses ou diminuer la pertinence des suggestions ; il est donc préférable de rédiger des sections concises et ciblées.

Certaines fonctionnalités, comme le champ applyTo ou la configuration multi-fichiers via .github/instructions/*.instructions.md, dépendent de la version ou du tenant et peuvent être en preview : par défaut, il est recommandé d’utiliser le fichier unique .github/copilot-instructions.md.

Lorsque plusieurs fichiers d’instructions sont présents, Copilot fusionne les règles, mais celles ciblées via applyTo prennent le dessus sur les règles globales. Il est donc essentiel d’éviter toute contradiction entre les instructions personnelles, d’organisation et de dépôt. Par ailleurs, il ne faut jamais inclure de secrets (clés API, tokens, données sensibles) ni d’URL internes confidentielles dans les instructions, pour des raisons de sécurité.

Bonnes pratiques pour les règles

Pour que Copilot suive efficacement tes standards, tes instructions doivent être rédigées avec soin. Elles doivent être claires et concises, sans jargon inutile ni formulations ambiguës, afin d’éviter toute interprétation erronée. Elles doivent aussi être impératives, en privilégiant l’infinitif ou l’impératif direct : par exemple, au lieu d’écrire “On pourrait utiliser des doubles quotes”, mieux vaut préciser “Utilise uniquement des doubles quotes”. Enfin, elles doivent être contextuelles, en mentionnant explicitement les éléments clés de ton environnement, comme la stack technique (“Projet React avec TypeScript”), l’outil de build (“Utilise Bazel”) ou encore les règles de style de code à respecter (“Respecte les règles ESLint standard + Prettier”).

Plus ces instructions sont précises et adaptées à ton contexte, plus Copilot pourra produire un code aligné sur tes conventions et directement exploitable.

Tester et ajuster les effets

Pour optimiser les règles de Copilot, vérifie les instructions actives, ajuste le niveau de rigueur (alléger ou renforcer), assure la cohérence entre les règles personnelles, de dépôt et d'organisation, et utilise applyTo pour cibler précisément certains fichiers ou répertoires (si disponible).

Rechercher des règles sur des projets publics existants sur GitHub

De nombreux contributeurs mettent à disposition leurs règles Copilot, souvent tirées de projets open source. N'hésite pas à explorer ces ressources publiques : elles constituent une mine d'or d'inspiration pour affiner tes propres configurations et découvrir des approches que tu n'aurais pas envisagées. Par exemple le site https://www.copilotcraft.dev/ qui te permet de générer un template de règles.

Conclusion

Optimiser GitHub Copilot avec des custom instructions transforme ton flux de travail en l'alignant sur tes standards et ta culture d'équipe. Copilot s'adapte à ton style de code, tes outils et le niveau de détail de tes livrables, améliorant la qualité et la cohérence de tes projets.

L'expérimentation est cruciale : commence simple, observe l'impact, puis affine, en utilisant des fonctionnalités comme "applyTo" et en t'inspirant des travaux de la communauté dev.

En intégrant ces pratiques, Copilot devient un prolongement de ton expertise, garantissant un code de meilleure qualité, une productivité accrue et une harmonie technique. C'est le passage d'un simple outil à un partenaire de code indispensable.

Annexes

// .github/copilot-instructions.md
# Custom instructions for GitHub Copilot — flutter-design-pattern-configuration-builder

## Identity & context
- You are assisting a Flutter/Dart developer working on a small demo app that showcases a Builder + Director design pattern around “vehicle cards”.
- Tech stack: Flutter (Material 3), Dart null-safety, default flutter_lints.
- App uses simple state (setState in local StatefulWidgets). No Provider/Bloc/Riverpod.
- Project language is mixed FR/EN in UI strings; keep French labels in UI. The code intentionally uses the spelling “Vehicule” in many symbols and files—preserve it.

## Goals & expectations
- Optimize for clarity, immutability, and testability over micro-optimizations.
- Generate idiomatic Flutter widgets: prefer StatelessWidget, const constructors, final fields.
- Keep the design pattern separation: configuration objects, builders, and a director that sequences builder steps.
- Suggestions should compile with flutter_lints defaults and fit existing folder/barrel structure.
- When adding features, also propose/update minimal widget tests following the existing style.

## Style & conventions
Naming
- Classes, enums: PascalCase (e.g., `VehiculeCard`, `VehicleType`, `CarBuilder`).
- Methods, fields, variables: lowerCamelCase (e.g., `buildSpecsSection`, `isActionLoading`).
- Keep "Vehicule" spelling where already used (do not “correct” to Vehicle in identifiers or filenames).

Files & folders
- Widgets: `lib/widgets/` (icons, sections, card, header, button). New small reusable UI pieces go here.
- Views/pages: `lib/views/` (screens like bike demo pages).
- Models: `lib/models/` (simple data classes like `VehicleSpecsData`, `EngineData`, `VehicleType`).
- Config-only pattern: `lib/vehicule_with_configuration/` with `VehicleConfiguration` subclasses and a `VehicleWidget` factory.
- Builder pattern: `lib/vehicule_with_configuration_and_builder/` with `*CardConfiguration`, builders (e.g., `CarBuilder`, `BikeBuilder`), and `VehicleWidgetDirector`.
- Barrel exports: keep `lib/widgets/widgets.dart`, `lib/models/models.dart`, `lib/lib.dart` updated when adding public modules.
- Tests: `test/*.dart`, name with `_test.dart` and use `flutter_test`.

Widget & code style
- Prefer StatelessWidget. Use StatefulWidget + `setState` only for local UI state (e.g., loading toggles).
- Constructors: `const` when possible; mark parameters `required` and fields `final`.
- UI: Use Material widgets, simple layout, and consistent theming (`ColorScheme.fromSeed(seedColor: Colors.indigo)`).
- Card look: rounded corners (~18), subtle shadow, padding ~18, vertical spacing via SizedBox or Column spacing.
- Optional sections return null and are conditionally rendered with `if (widget != null) widget!`.
- Keep public APIs small and explicit; avoid global state/singletons.

Design pattern contracts
- Config-only flow (`vehicule_with_configuration`):
    - Create configuration subtype (`CarConfiguration`, `BicycleConfiguration`) implementing:
        - `buildIcon()`, `buildSpecsSection()`, `buildEngineSection()`, `buildButton()`.
    - Use `VehicleWidget.car(...)` / `.bicycle(...)` factories to wrap config and render `VehiculeCard`.
- Builder flow (`vehicule_with_configuration_and_builder`):
    - Define a `*CardConfiguration` with plain data.
    - Implement a `VehiculeCardBuilder` subclass with step methods: `withType`, `withTitle`, `withSubtitle`, `withIcon`, `withSpecs`, `withEngine`, `withButton`.
    - Use `VehicleWidgetDirector` to sequence steps into a recipe (may include/exclude sections).
    - Call `builder.build()` to get a `VehiculeCard`.

Strings & localization
- Keep UI strings in French where present (e.g., “Immatriculation”, “Mon garage”, button labels like “Réessayer”). No i18n framework is used.

Testing
- Wrap widgets in `MaterialApp(home: Scaffold(body: widget))` for tests.
- Use `flutter_test` finders: `find.text`, `find.textContaining`, `find.byIcon`, `find.byType`.
- For button taps, `await tester.tap(find.byType(ElevatedButton)); await tester.pump();` and assert side effects.
- Prefer focused tests that assert visible text, icons, and conditional sections.

## Do’s & Don’ts
Do
- Use `const` and `final` aggressively; keep constructors `const` when possible.
- Follow existing naming and file placement; update barrel files when adding exports.
- Keep “Vehicule” spelling in identifiers and paths to match the project.
- In builders, implement all step methods even if some are no-ops for a given type.
- Keep UI minimal and accessible; use standard Material components and theming.
- For new public behavior, add/adjust a small widget test mirroring the existing style.

Don’t
- Don’t introduce state management frameworks (Provider/Bloc/Riverpod) or navigation libraries.
- Don’t print to console for UX; use SnackBar in UI code when needed.
- Don’t refactor to English spelling or rename established APIs.
- Don’t mix platform-specific code or plugins; keep pure Flutter where possible.
- Don’t over-abstract; prefer simple data classes and small widgets over deep hierarchies.

## Interaction style
- Default to concise, single-solution suggestions that match the established patterns.
- When multiple patterns exist (config-only vs builder), pick the one already used in the touched file/folder; otherwise, suggest config-only for simple cases and builder+director when demonstrating recipes.
- Show minimal explanatory comments inline only where the pattern isn’t obvious; otherwise, keep code comment-light as in the repo.
- Prefer imports from barrel files (e.g., `widgets/widgets.dart`, `models/models.dart`) when adding sample code.
- If creating files, propose filenames and locations that fit the structure and add the necessary exports.

— End of Copilot custom instructions —

# Copilot instructions for this repo

Context: Flutter app with Material 3 theme and simple stateful widgets. UI text mixes French/English. Analyzer uses `flutter_lints`. Keep code concise, null-safe, and idiomatic Flutter.

Note on existing rules: `.github/instructions/best_practice.instructions.md` describes a “Vehicule builder” demo. That structure does not exist here. You can reuse general style points from it (Material 3, `const`/`final`, French labels), but follow the actual files and patterns below for this app.

## Big picture
- Entry: `lib/main.dart` → `MyStartApp` (MaterialApp with `ColorScheme.fromSeed(Colors.indigo)`), shows a top-end `Banner("Thomas D.")`, home is `StartPage`.
- Primary screen: `lib/start_page.dart` renders the wheel picker UI via `Generated2` (see below).
- Two wheel implementations exist:
  - `lib/generated_1.dart` (`Generated1`, `WheelPainter`) – earlier version.
  - `lib/widgets/generated2.dart` (`Generated2`, `_WheelPainter`) – current version used by `StartPage`.
- Custom painters draw the pie slices, labels, and a pointer; state is local (`setState`) with `AnimationController` for spin effects.

## Current patterns & conventions
- Keep UI strings in French where present (e.g., "Gagnant !", "Choisir le gagnant"). No i18n framework.
- Prefer `StatelessWidget`; use `StatefulWidget` + `setState` for local UI state only (text input, animation, selection).
- Constructors `const` when possible; fields `final`. Dispose controllers in `dispose()`.
- Small reusable UI pieces go in `lib/widgets/`. A barrel exists: `lib/widgets/widgets.dart`.
- Theming: use `Theme.of(context)` and Material 3 components; keep rounded corners (~18) and subtle elevation consistent with `Generated2`.
- Lints: follow `analysis_options.yaml` (inherits `flutter_lints`). Use `flutter analyze` to validate.

## Known quirks to mind
- `start_page.dart` imports `package:copitot_rules/widgets/name_picker_wheel.dart`, but that file is not present. The screen currently uses `Generated2`. Prefer importing from the barrel `widgets/widgets.dart` or the actual file `widgets/generated2.dart`. If you add `name_picker_wheel.dart`, export it from the barrel.
- There are two similar wheel implementations; avoid duplicating logic—prefer `Generated2` unless you are intentionally comparing versions.

## Typical workflows
- Install deps: `flutter pub get`
- Analyze: `flutter analyze`
- Run (hot reload): `flutter run` (select device; Android and web configs are present)
- Test: add widget tests under `test/*.dart` then `flutter test`

## Extension points and examples
- Adding a new widget:
  - Place in `lib/widgets/your_widget.dart`.
  - Export in `lib/widgets/widgets.dart` and import via `package:copitot_rules/widgets/widgets.dart`.
- Animation pattern (see `Generated2`):
  - Mixin `SingleTickerProviderStateMixin`.
  - Create/`dispose` `AnimationController` in `initState`/`dispose`.
  - Drive `Tween<double>(begin: _currentAngle, end: targetAngle)` with a curved animation; update `_currentAngle` in the listener and call `setState`.
  - On completion, compute winner index and show a dialog with the name.
- CustomPainter pattern:
  - Compute `anglePerName = 2*pi / names.length`.
  - Loop to draw arcs with `Colors.primaries[i % ...].withOpacity(0.8)`.
  - Use `TextPainter` to draw labels at `radius * 0.65` along the mid-angle; draw a triangle pointer above the circle.

## When adding features
- Keep labels French where the UI already uses FR.
- Maintain the Material 3 look and spacing similar to `Generated2` (padding ~18, rounded corners ~18).
- Validate with `flutter analyze` and ensure controllers are disposed.
- If you introduce new public widgets, add minimal widget tests (wrap with `MaterialApp(home: Scaffold(body: widget))` and assert visible text/icons).

## Key files
- `lib/main.dart` – app entry, theme, banner, home.
- `lib/start_page.dart` – home screen using `Generated2`.
- `lib/widgets/generated2.dart` – current wheel UI + painter.
- `lib/generated_1.dart` – earlier wheel variant for reference.
- `lib/widgets/widgets.dart` – barrel export for widgets.

Questions or gaps? If anything above is unclear (e.g., desired barrel usage or which wheel to standardize on), ask for confirmation before broad refactors.