Un agent qui redécouvre vos conventions à chaque tâche est un agent qu’on doit reprendre à chaque tâche. Le vrai gain de productivité arrive quand l’agent connaît, une fois pour toutes, les règles de votre projet : la bibliothèque imposée, le style de code, les cas à toujours gérer. Antigravity offre pour cela trois leviers : un fichier d’instructions persistantes (AGENTS.md), des règles (Rules) et des routines réutilisables (Workflows). Ce tutoriel vous apprend à cadrer durablement le comportement de vos agents sur l’application Suivi.

📘 Guide principal de la série : Google Antigravity : développer avec des agents IA autonomes.

🎯 Ce que vous allez apprendre

Écrire un fichier AGENTS.md qui transmet vos conventions à tous les agents du projet.
Distinguer instructions persistantes, règles et routines, et savoir quoi mettre où.
Créer un Workflow déclenchable d’un simple / pour automatiser une tâche récurrente.
Poser des garde-fous de permissions pour encadrer ce que l’agent a le droit de faire.

🛠️ Ce que vous allez construire

Nous dotons l’application Suivi d’un cadre de travail explicite. Vous allez rédiger un AGENTS.md qui impose nos conventions (Express, pas de dépendance superflue, toujours gérer l’identifiant introuvable), puis créer un Workflow /test qui lance une vérification standardisée. À la fin, n’importe quel agent lancé sur Suivi respectera ces règles sans que vous ayez à les répéter.

Prérequis

L’application Suivi des tutoriels précédents — voir Vérifier le travail d’un agent : les artifacts.
Antigravity connecté, à l’aise avec l’éditeur et l’Agent Manager.
Niveau : intermédiaire débutant.
⏱️ Temps estimé : ~35 minutes.

Étape 1 — Comprendre les trois niveaux de cadrage

Avant d’écrire quoi que ce soit, distinguons les trois mécanismes, car les confondre mène à un projet désordonné. Les instructions persistantes, réunies dans un fichier AGENTS.md à la racine du projet, décrivent le contexte général : ce qu’est le projet, ses conventions, ses interdits. L’agent les lit au démarrage de chaque tâche. Les règles (Rules) sont des directives ciblées — style de code, standards de documentation — que l’on range dans un dossier dédié du projet. Enfin les workflows sont des prompts enregistrés que vous déclenchez à la demande avec un préfixe /, comme des raccourcis pour des tâches que vous répétez souvent.

La logique est simple : AGENTS.md répond à « que doit toujours savoir l’agent ? », les règles à « comment doit-il coder ? », et les workflows à « quelle tâche je veux relancer d’un clic ? ». Cette séparation évite l’écueil du fichier d’instructions fourre-tout, illisible et contre-productif.

Étape 2 — Écrire le fichier AGENTS.md du projet

Un mot d’avertissement avant de commencer, car c’est l’erreur que tout le monde commet. La tentation est d’écrire un AGENTS.md immense, comme si entasser des consignes rendait l’agent plus obéissant. C’est l’inverse qui se produit : noyé sous trente règles, un modèle en applique mal certaines et en oublie d’autres. Le bon AGENTS.md tient sur une page. Il dit l’essentiel — le quoi, les interdits, les deux ou trois exigences non négociables — et laisse le reste à des règles ciblées ou au prompt du moment. Pensez-y comme à l’accueil d’un nouveau collègue : on lui donne les conventions vitales le premier jour, pas le règlement intérieur complet en trois cents pages.

Passons à la pratique. À la racine du dossier suivi, créez un fichier AGENTS.md. Ce fichier est lu par les agents comme un cahier des charges permanent. Restez concis et concret : des consignes vagues produisent des comportements vagues.

# Projet Suivi

## Contexte
Petite application de gestion de taches d'equipe : une API REST Express
et une interface web en HTML/JavaScript natif, sans framework.

## Conventions
- Langage : JavaScript moderne (const/let, async/await).
- Aucune dependance superflue : ne pas ajouter de bibliotheque sans
  justification explicite dans le plan.
- Toujours gerer le cas d'un identifiant de tache introuvable par une
  reponse HTTP 404 claire.
- Les reponses de l'API sont en JSON.

## Tests
- Pour toute nouvelle route, proposer une commande curl de verification.
- Ne jamais modifier l'endpoint /health.

Enregistrez. À partir de maintenant, tout agent lancé sur ce projet lira ces consignes avant d’agir. Vous pouvez le vérifier en lançant une petite tâche et en observant son plan : il devrait spontanément prévoir la gestion du 404 et une commande de test, sans que vous l’ayez demandé dans le prompt.

Pourquoi ce fichier est-il si puissant ? Parce qu’il déplace l’effort au bon endroit. Sans lui, vous répétez les mêmes consignes dans chaque prompt — « utilise Express, gère le 404, propose un test » — au risque d’en oublier une et d’obtenir un résultat incohérent. Avec lui, ces exigences deviennent un acquis du projet, appliqué de façon uniforme par tous les agents et toutes les sessions. Vous ne pilotez plus chaque tâche dans le détail ; vous avez défini une fois pour toutes ce que « bien fait » signifie ici. C’est exactement ce qui distingue un usage amateur d’un usage professionnel d’un agent de code.

✅ Point d’étape — Lancez un agent avec une consigne minimale comme « Ajoute une route DELETE /tasks/:id ». Son plan doit, de lui-même, mentionner la gestion d’un identifiant introuvable et proposer un test curl. Si c’est le cas, votre AGENTS.md est bien pris en compte.

Étape 3 — Ajouter des règles ciblées

Le fichier d’instructions donne le cadre général ; les règles précisent des points particuliers que vous voulez voir appliqués systématiquement. On les place dans le dossier de configuration du projet prévu à cet effet, sous un sous-dossier dédié aux règles. Chaque règle est un court fichier au format texte décrivant une attente unique.

Par exemple, une règle de documentation : « Toute fonction exportée doit être précédée d’un commentaire d’une ligne expliquant son rôle. » En isolant chaque règle dans son propre fichier, vous gardez un ensemble lisible et facile à activer ou désactiver. C’est préférable à un AGENTS.md qui gonflerait jusqu’à devenir un pavé que l’agent applique mal. Pensez aux règles comme à des post-it précis, et au fichier d’instructions comme à la note d’intention du projet.

Pour des conventions partagées par toute votre machine — et pas seulement par le projet Suivi — Antigravity prévoit également une configuration au niveau global, rangée dans votre dossier de configuration utilisateur. Selon la version installée, l’emplacement exact peut varier ; le plus simple est de passer par le menu de personnalisation de l’application, qui ouvre directement les bons fichiers sans avoir à les chercher.

Projet ou global : où ranger quoi ?

La question du périmètre revient sans cesse. La règle est intuitive une fois posée. Tout ce qui est propre à un projet — sa pile technique, ses conventions, ses interdits — appartient au projet : AGENTS.md à la racine, règles et workflows dans le dossier de configuration du dépôt. Tout ce qui relève de votre façon de travailler en général — une préférence de style que vous appliquez partout, un workflow personnel de revue — appartient à la configuration globale de votre machine. Ce partage a une conséquence pratique précieuse : en versionnant le cadre au niveau du projet, vous le transmettez à toute l’équipe, tandis que vos préférences personnelles vous suivent d’un projet à l’autre sans polluer les dépôts des autres.

Étape 4 — Créer un Workflow réutilisable

Venons-en au levier le plus satisfaisant au quotidien : les workflows. Un workflow est un prompt que vous écrivez une fois et rejouez à volonté en tapant / suivi de son nom. Idéal pour une routine que vous répétez : lancer les tests, préparer une revue, générer un changelog.

Créons un workflow test pour Suivi. Dans le dossier de configuration du projet, sous le sous-dossier des workflows, ajoutez un fichier décrivant la routine :

# Workflow : test

Verifie l'application Suivi de bout en bout :
1. Lance le serveur avec node server.js.
2. Cree une tache via POST /tasks.
3. Liste les taches via GET /tasks et confirme la presence de la tache.
4. Marque la tache comme terminee via PATCH /tasks/:id.
5. Resume les resultats et signale toute reponse inattendue.

Désormais, dans le panneau de l’agent, taper /test déclenche cette séquence sans la réécrire. Le gain est double : vous gagnez du temps, et surtout vous standardisez la vérification — chaque exécution suit exactement les mêmes étapes, ce qui rend les résultats comparables d’une fois sur l’autre.

✅ Point d’étape — Dans la zone de saisie de l’agent, tapez / : votre workflow test doit apparaître dans la liste des suggestions. Lancez-le et vérifiez que l’agent suit bien les cinq étapes décrites.

Étape 5 — Poser des garde-fous de permissions

Cadrer le comportement, c’est aussi limiter le pouvoir d’action. Antigravity gère un système de permissions où chaque autorisation s’exprime sous la forme action(cible), classée en listes « autoriser », « refuser » et « demander ». Les actions couvrent l’exécution de commandes, la lecture et l’écriture de fichiers, la lecture d’URL et l’usage de serveurs externes.

Quelques exemples parlants : command(git) couvre toutes les commandes git ; read_file sur un chemin précis autorise la lecture d’un fichier donné ; read_url sur un domaine englobe ses sous-domaines. Pour le projet Suivi, une politique raisonnable consiste à autoriser les commandes node et npm, à demander confirmation pour tout le reste, et à restreindre l’accès aux fichiers au seul dossier du projet. Antigravity propose d’ailleurs de limiter par défaut l’agent au périmètre de l’espace de travail, et permet d’activer un bac à sable (sandbox) pour exécuter les commandes dans un environnement restreint. Combinés au niveau d’autonomie « supervisé », ces réglages forment une ceinture de sécurité solide pendant que vous apprenez à faire confiance à l’agent.

Au-delà du confort, ces garde-fous répondent à un enjeu réel. Un agent qui peut exécuter des commandes et écrire des fichiers est puissant, donc potentiellement dangereux s’il interprète mal une consigne ou s’il rencontre, dans un fichier ou une page web, une instruction malveillante. Restreindre les actions par défaut, demander confirmation pour les opérations sensibles et cantonner l’agent au dossier du projet ne sont pas des précautions paranoïaques : ce sont les pratiques de base d’un travail sérieux avec des agents autonomes. Le principe directeur tient en une phrase : n’accordez que les droits strictement nécessaires à la tâche, et élargissez seulement quand le besoin est avéré.

🐞 Pièges fréquents

Symptôme	Cause probable	Correctif
L’agent ignore vos conventions	`AGENTS.md` absent de la racine ou trop vague	Placer le fichier à la racine du projet, formuler des consignes concrètes et vérifiables
Le workflow n’apparaît pas avec `/`	Fichier mal placé ou mal nommé	Vérifier le dossier des workflows du projet et le nom du fichier
Instructions contradictoires	Une règle contredit l’`AGENTS.md`	Harmoniser : le fichier d’instructions donne le cap, les règles le précisent sans le contredire
L’agent demande sans cesse une validation	Permissions trop restrictives	Ajouter les actions sûres et fréquentes à la liste « autoriser »

✅ Récapitulatif

Vous savez maintenant cadrer durablement un agent. Le fichier AGENTS.md transmet le contexte et les conventions du projet ; les règles précisent des attentes ciblées ; les workflows transforment vos tâches récurrentes en raccourcis déclenchés par / ; et les permissions délimitent ce que l’agent a le droit de faire. Ensemble, ces leviers font passer votre usage d’Antigravity de l’improvisation à un environnement de travail discipliné, où chaque agent démarre déjà aligné sur vos exigences.

🧾 Aide-mémoire

Levier	Rôle	Déclenchement
`AGENTS.md` (racine)	Contexte et conventions du projet	Lu automatiquement à chaque tâche
Règles	Attentes ciblées (style, doc)	Appliquées en continu
Workflows	Routines réutilisables	`/` suivi du nom
Permissions `action(cible)`	Encadrer les droits de l’agent	Listes autoriser / refuser / demander

💪 À vous de jouer

Ajoutez à l’AGENTS.md une convention imposant que chaque réponse d’erreur de l’API renvoie un JSON de la forme {« erreur »: »message »}, puis lancez un agent sur une nouvelle route et vérifiez qu’il applique spontanément ce format.

Voir une piste de solution

Ajoutez sous « Conventions » : « Toute réponse d’erreur renvoie un JSON { erreur: message } avec le bon code HTTP. » Lancez ensuite « Ajoute une route GET /tasks/:id qui renvoie une tâche ». Dans le plan puis la diff, l’agent doit gérer le cas introuvable avec un 404 et un corps { erreur: ... }, sans que vous l’ayez précisé dans le prompt.

Ressources officielles

Tutoriel Google : Getting Started with Google Antigravity
Site officiel : antigravity.google

FAQ

Faut-il versionner l’AGENTS.md avec le projet ?
Oui, c’est recommandé : placé à la racine et suivi par votre gestionnaire de versions, il profite à toute l’équipe et garantit que chacun travaille avec les mêmes conventions d’agent.

Quelle différence entre une règle et une ligne de l’AGENTS.md ?
La frontière est souple. En pratique, mettez dans l’AGENTS.md ce qui décrit le projet et son cadre, et isolez en règles les attentes transversales et réutilisables que vous voudriez peut-être activer ou désactiver indépendamment.

Les workflows peuvent-ils être partagés ?
Un workflow rangé dans le dossier de configuration du projet est partagé avec le dépôt ; un workflow global reste propre à votre machine. Choisissez selon que la routine concerne le projet ou votre façon de travailler en général.

Cadrer un agent Antigravity : AGENTS.md, Rules et Workflows