Lorsque les équipes d'ingénierie déploient des assistants de programmation basés sur l'IA, elles constatent rapidement une disparité notable dans la maturité des usages. Alors que les architectes et développeurs seniors formulent des requêtes précises intégrant les règles de conception et les cas limites, d'autres membres de l'équipe se contentent d'instructions sommaires comme « corrige ce bug » ou « écris un test ». Cette hétérogénéité fragmente la qualité du code produit : disparités de bibliothèques de test, assertions incohérentes, conventions de nommage fluctuantes et perte des bonnes pratiques internes.
Sourcegraph Cody apporte une réponse structurelle à cette problématique directement au niveau du dépôt : les commandes personnalisées (Custom Commands) configurées dans le fichier .vscode/cody.json. En consignant des modèles d'instructions éprouvés, des modes d'exécution adaptés et un ciblage contextuel rigoureux dans un fichier versionné (« Prompts as Code »), les équipes transforment l'ingénierie de prompts en une infrastructure technique partagée. Tout développeur qui clone le projet dispose immédiatement des mêmes commandes slash, garantissant un niveau de qualité homogène sur l'ensemble du code.
Architecture et fonctionnement de .vscode/cody.json
Cody distingue les commandes personnalisées globales (définies dans la configuration utilisateur) des commandes liées à l'espace de travail (Workspace Level). En plaçant le fichier cody.json dans le dossier .vscode/ à la racine du projet, les commandes s'arriment directement à la pile technologique, aux dépendances et aux standards de test du dépôt :
repository-root/
├── .vscode/
│ ├── cody.json <-- Définition des commandes d'équipe
│ └── settings.json
├── src/
├── tests/
└── package.json
Une fois validé dans Git, le fichier est automatiquement analysé par l'extension Cody dans VS Code à l'ouverture de l'espace de travail. Les développeurs peuvent lancer ces commandes via la palette dédiée (Option + C sur macOS ou Alt + C sur Windows/Linux) ou en saisissant directement la commande slash correspondante (par exemple /unit-test) dans le panneau de chat de Cody.
Schéma de configuration JSON
Le fichier .vscode/cody.json regroupe l'ensemble des commandes au sein d'un objet racine commands :
{
"commands": {
"command-identifier": {
"prompt": "Modèle d'instructions détaillé envoyé au grand modèle de langage (LLM).",
"description": "Description succincte affichée dans le menu des commandes de Cody.",
"mode": "ask",
"context": {
"codebase": false,
"selection": true,
"currentDir": false,
"openTabs": false
}
}
}
}
Détail des propriétés fondamentales :
| Champ | Type | Description |
|---|---|---|
prompt | String | Le modèle d'instruction transmis au modèle d'IA, précisant le rôle, les contraintes métier, les conventions de test et le format de sortie attendu. |
description | String | Une description explicative qui apparaît dans la palette de commandes pour guider le choix du développeur. |
mode | String | Le mode d'exécution et de restitution du code généré (ask, edit ou insert). |
context | Object | Un ensemble de bascules permettant de définir avec précision le périmètre du code source injecté dans le prompt. |
Modes d'exécution : Maîtriser la restitution du code
La propriété mode gouverne la façon dont la réponse générée par l'IA interagit avec l'éditeur :
-
ask(Dialogue et revue interactive) :- Affiche la réponse dans le volet latéral Cody Chat.
- Particulièrement indiqué pour les revues d'architecture, les audits de sécurité, l'explication d'algorithmes complexes ou la synthèse de Pull Requests, où une validation humaine préalable est requise.
-
edit(Remplacement direct dans le code) :- Remplace directement la sélection active dans l'éditeur par le code généré.
- Conçu pour les refactorisations ciblées : renforcement du typage TypeScript, élimination d'expressions ternaires imbriquées ou adoption de structures de données immuables.
-
insert(Insertion ciblée à l'emplacement du curseur) :- Insère le contenu produit immédiatement au-dessus ou à l'emplacement de la sélection.
- Idéal pour ajouter des blocs de documentation formalisés (TSDoc/JSDoc) ou injecter l'ossature d'une suite de tests dans un nouveau fichier.
Délimitation du contexte : Trouver le bon équilibre entre pertinence et latence
Un manque de contexte conduit l'IA à des hallucinations, tandis qu'une saturation de fichiers non pertinents consomme inutilement des jetons et ralentit les temps de réponse. L'objet context de .vscode/cody.json assure un contrôle minutieux :
selection(booléen) : Transmet les lignes de code actuellement surlignées dans l'éditeur. Pour les refactorisations locales ou la documentation de fonctions, activer cette option focalise l'attention du modèle sur le bloc cible.codebase(booléen) : Déclenche la recherche sémantique et l'indexation de Sourcegraph sur l'ensemble du dépôt. Permet à Cody d'identifier les classes utilitaires, les modèles transversaux et les mocks existants. Cette option doit rester désactivée pour les modifications isolées afin d'éviter les temps d'interrogation réseau superflus.currentDir(booléen) : Intègre les fichiers situés dans le même répertoire que le fichier actif. Très utile dans les architectures modulaires où les composants, les types et les fichiers de test résident dans un même dossier.openTabs(booléen) : Prend en compte les fichiers ouverts dans les autres onglets de l'éditeur. Utile lors d'implémentations multifichiers, mais susceptible d'introduire du bruit si des fichiers sans rapport restent ouverts.
Recettes concrètes pour les équipes d'ingénierie
Voici une configuration .vscode/cody.json éprouvée pour des projets TypeScript et React en production, regroupant quatre commandes standardisées :
{
"commands": {
"unit-test": {
"description": "Génère des tests unitaires Vitest conformes aux standards avec mocks et gestion des cas limites",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": true,
"openTabs": false
},
"prompt": "Tu es un ingénieur senior en automatisation de tests. Rédige une suite de tests complète pour le code sélectionné en utilisant Vitest et @testing-library/react le cas échéant.\n\nRègles strictes :\n1. Organise chaque test selon le modèle Arrange-Act-Assert (AAA).\n2. Réutilise impérativement les fixtures et conventions de mock déjà établies dans le projet.\n3. Couvre les scénarios nominaux, les valeurs limites, les entrées null/undefined et les rejets de promesses asynchrones.\n4. N'importe aucune bibliothèque de mock non validée ; utilise exclusivement vi.fn() et vi.spyOn() de Vitest.\n5. Fournis un code complet et directement exécutable, sans commentaires tronqués du type '// implémenter ici'."
},
"refactor-clean": {
"description": "Refactorise la sélection selon les principes de Clean Code et un typage TypeScript strict",
"mode": "edit",
"context": {
"selection": true,
"codebase": false,
"currentDir": false,
"openTabs": false
},
"prompt": "Refactorise le bloc de code sélectionné en appliquant les règles de Clean Code et de TypeScript strict :\n1. Conserve strictement les signatures d'API publiques, les contrats de paramètres et le comportement à l'exécution.\n2. Remplace les types 'any' lâches par des unions discriminées précises ou des contraintes génériques.\n3. Remplace les mutations d'état par des fonctions pures et des mises à jour immuables.\n4. Transforme les conditions profondément imbriquées en clauses de sortie rapide (early returns).\n5. Renvoie UNIQUEMENT le code de remplacement, sans balisage markdown ni commentaires superflus."
},
"security-audit": {
"description": "Analyse la sélection pour identifier les failles OWASP Top 10 et les fuites de données",
"mode": "ask",
"context": {
"selection": true,
"codebase": true,
"currentDir": false,
"openTabs": false
},
"prompt": "Réalise un audit de sécurité approfondi sur le segment de code sélectionné.\n\nExamine les vecteurs de vulnérabilité suivants :\n1. Failles d'injection (SQL, NoSQL, commandes système, templates ou XSS).\n2. Défauts d'autorisation, contrôles d'accès manquants et élévation de privilèges.\n3. Références directes non sécurisées à des objets (IDOR) et absence de validation des entrées utilisateur.\n4. Clés d'API, secrets ou données personnelles (PII) exposés dans le code ou les journaux.\n5. Gestion inadéquate des exceptions risquant de divulguer des traces d'appels internes.\n\nFormat de sortie obligatoire : [Gravité: Haute/Moyenne/Basse] | [Type de vulnérabilité] | [Ligne concernée] | [Correctif recommandé et Diff]."
},
"doc-api": {
"description": "Insère une documentation TSDoc/JSDoc normalisée pour une fonction ou une interface",
"mode": "insert",
"context": {
"selection": true,
"codebase": false,
"currentDir": false,
"openTabs": false
},
"prompt": "Génère un bloc de documentation TSDoc de niveau production pour la fonction ou l'interface sélectionnée :\n1. Rédige un résumé clair en une ligne, suivi d'une description détaillée du comportement.\n2. Renseigne chaque balise @param avec son type précis et sa signification sémantique.\n3. Renseigne la balise @returns en explicitant le type et les conditions associées.\n4. Décris toutes les exceptions potentielles via les balises @throws.\n5. Ajoute un exemple pratique d'utilisation via @example.\n6. Formate la sortie sous forme d'un bloc JSDoc/TSDoc prêt à être inséré directement au-dessus du code."
}
}
}
Gouvernance et transition vers la Prompt Library
Pour pérenniser l'usage de .vscode/cody.json, les équipes de développement gagnent à formaliser leur démarche :
1. Gérer les prompts comme du code de production (Prompts as Code)
Les commandes consignées dans .vscode/cody.json constituent des actifs techniques collectifs. Toute modification ou ajout doit faire l'objet d'une Pull Request soumise à revue de code, avec une validation syntaxique du schéma JSON dans la chaîne d'intégration continue (CI) pour prévenir toute anomalie dans VS Code.
2. Maîtriser le coût du contexte global
Activer systématiquement "codebase": true surcharge les échanges réseau et allonge inutilement le temps de calcul. Il convient de réserver ce paramètre aux opérations nécessitant des recoupements inter-fichiers et de privilégier "selection": true pour les traitements locaux.
3. Évolution vers la Prompt Library de Sourcegraph
Lorsque l'organisation s'étend à des dizaines de microservices, synchroniser manuellement des fichiers .vscode/cody.json entre de multiples dépôts peut devenir complexe. Sourcegraph propose la Prompt Library (Bibliothèque de prompts) via l'interface web (disponible à partir de Cody v1.30 et dans Sourcegraph Enterprise).
Les équipes peuvent ainsi prototyper et éprouver leurs commandes dans le fichier .vscode/cody.json d'un projet, puis promouvoir les modèles validés au sein de la Prompt Library centrale. Cette dernière permet de catégoriser les prompts par étiquettes (tags), de mettre en avant des modèles officiels (Promoted Prompts) et d'exploiter les mentions dynamiques @ (@selection, @file, @repo) sur différents environnements de développement (VS Code et JetBrains).