Transformez votre fichier de contexte en spécification exécutable pour agent

Dans le chapitre précédent, vous avez analysé les fondements et la boucle d'action d'un agent IA. Votre dépôt contient déjà un fichier  AGENTS.md  de base résumant la structure de votre projet Express/Prisma. Pour que votre agent de documentation fonctionne de manière autonome, vous devez faire évoluer ce fichier vers une spécification exécutable. Vous allez apprendre à formaliser le rôle, le périmètre, les permissions d'accès, les entrées/sorties et les critères d'acceptation de votre agent en traitant ce fichier comme un artefact de code versionné et testable. Vous transformez ainsi votre fichier  AGENTS.md  en une spécification exécutable pour la documentation d'API.

Isolez les acquis d'un fichier de contexte AGENTS.md existant

Le fichier  AGENTS.md  à la racine du dépôt constitue votre point de départ. Il décrit la structure du projet Express/Prisma, les conventions de style et les commandes d'environnement. Avant d'y ajouter des consignes ciblées, distinguez le rôle de chaque format dans votre IDE :

• AGENTS.md (à la racine) : Définit les instructions transversales du projet et sert de standard de découverte pour les agents.

• .github/copilot-instructions.md : Contient les consignes générales spécifiques à GitHub Copilot (chat et revue de code).

• .github/instructions/*.instructions.md : Cible des sous-dossiers spécifiques via la propriétéapplyTo.

Considérez le fichier  AGENTS.md  existant comme un prérequis à enrichir pour la documentation d'API.

Auditez le fichierAGENTS.md  présent à la racine de votre projet Express/Prisma pour identifier les informations manquantes relatives à l'API (notamment les routes authentifiées par JWT).

Définissez le périmètre de responsabilité et les permissions d'action de l'agent

Pour garantir que votre agent ne modifie pas le code applicatif lors de la génération documentaire, encadrez son rôle et restreignez ses permissions.

Assignez-lui un rôle restreint : attribuez à l'agent le rôle exclusif de "Documentation Specialist API".

Définissez ensuite ses permissions d'action :

• Permissions d'écriture : Autorisez l'écriture uniquement dans le dossier dédié à la documentation (/docs/openapi).

• Permissions de lecture : Limitez la lecture aux fichiers nécessaires dans les modules concernés (*.controller.ts,schema.prismaet DTO associés).

• Interdictions strictes : Interdisez formellement la modification du code applicatif (*.controller.ts,*.service.ts,*.module.tset DTO).

Rédigez la section ## Périmètre et Permissions dans votre fichier  AGENTS.md  . Autorisez l'agent à consulter les contrôleurs et DTO nécessaires (incluant les routes JWT sur  /api/v1/orders  ), tout en réservant ses droits d'écriture au dossier  /docs/openapi  .

Formulez des critères d'acceptation univoques et des paires entrée/sortie

Pour que l'agent évalue la conformité de sa production de façon autonome, établissez une structure d'entrée/sortie explicite et des critères d'acceptation mesurables.

Définissez la spécification des entrées/sorties :

• Entrée : Contrôleur Express + Schéma Prisma (schema.prisma).

• Sortie : Fichier JSON OpenAPI 3.0 dansdocs/openapi/.

Formulez des critères d'acceptation univoques :

1. Chaque endpoint doit comporter au moins un code retour HTTP200 ou 201(succès),400(erreur client) et500(erreur serveur).

2. Pour les routes protégées par authentification JWT, le code401et le schéma de sécurité Bearer doivent être présents.

3. Le fichier produit doit respecter la syntaxe OpenAPI 3.0.

Enrichissez  AGENTS.md  avec un tableau d'exemples montrant une spec OpenAPI valide (avec réponses 200, 400, 401 et 500) et une spec invalide.

Dans la vidéo suivante, vous allez voir comment transformer un simple fichierAGENTS.mden une spécification opérationnelle pour encadrer les actions d'un agent IA sur un projet Express/Prisma.

Étapes clés de la démonstration

1. Analysez le fichierAGENTS.mdexistant à la racine du dépôt pour identifier les limites de ses instructions initiales.

2. Définissez le rôle et les permissions de l'agent en limitant ses modifications au répertoire/docs/openapi, afin de protéger le code métier.

3. Formalisez les critères d'acceptation OpenAPI 3.0, notamment la présence des codes HTTP 200, 401 et 500.

4. Intégrez une commande de validation avecnpm run test:docet testez la capacité de l'agent à détecter et corriger ses erreurs.

Vous avez découvert comment des instructions précises et des critères vérifiables permettent d'encadrer le travail d'un agent. Intéressons-nous maintenant à l'intégration d'outils externes dans son environnement.

Intégrez les commandes de build et de validation au cœur des instructions

Pour que votre agent valide lui-même sa production, déclarez les commandes d'environnement au cœur de votre fichier d'instructions.

Déclarez les commandes système nécessaires dans  AGENTS.md  :

• Indiquez la commande exacte de linter (npx @redocly/cli lint).

• Imposez une règle d'auto-vérification : l'agent doit exécuter la commande avant de déclarer sa tâche terminée.

• Procédez au versionnage du contrat : committezAGENTS.mddans Git pour en faire un artefact de code suivi.

## Commandes de Validation

Exécutez impérativement la commande suivante avant de terminer :

npx @redocly/cli lint docs/openapi/*.json

En cas d'erreur renvoyée par le linter, corrigez le fichier JSON et réexécutez la vérification.

Ajoutez la section ## Commandes de Validation dans  AGENTS.md  et testez son exécution par l'agent dans VS Code lors de la génération de la documentation de la route  /orders  .

À vous de jouer !

Contexte

Suite au diagnostic établi sur l'API REST Express/Prisma, formalisez la spécification exécutable de votre agent de documentation d'API pour la livrer à l'équipe.

Consignes

Transformez le fichier  AGENTS.md  existant en une spécification complète avec le rôle, les permissions, la structure d'entrée/sortie, les critères OpenAPI 3.0 et la commande de validation npm run test:doc.

En résumé

• Transformez votre fichierAGENTS.mdsitué à la racine du dépôt en une spécification exécutable pour définir un contrat d'exécution clair avec l'agent.

• Restreignez le périmètre de l'agent en lui accordant la lecture des contrôleurs et du schéma Prisma, tout en limitant ses droits d'écriture au dossier/docs/openapi.

• Formulez des critères d'acceptation univoques imposant la conformité OpenAPI 3.0 et la gestion des codes d'erreur HTTP (400, 401 JWT, 500).

• Intégrez la commande de validationnpx @redocly/cli lintdirectement dans les instructions pour que l'agent contrôle lui-même son travail.

Vous avez transformé votre fichier de contexte en spécification exécutable ! Vous pouvez maintenant poursuivre avec le chapitre suivant pour incorporer du contexte ciblé et des outils MCP dans votre environnement VS Code.