Maîtriser les Goals dans Codex pour un développement IA efficace

Introduction

Les Goals dans Codex sont une fonctionnalité puissante qui permet aux agents IA de travailler de manière persistante sur une tâche jusqu'à ce qu'une condition spécifique soit remplie, sans nécessiter d'intervention humaine continue.

Précis de configuration

Élément	Version / Lien
Langage / Runtime	JavaScript / TypeScript, Node.js
Librairie principale	Codex (via OpenAI Developers)
APIs requises	GitHub Actions, Vercel, Playwright, ESLint, Tanstack, Neon PostgreSQL, Prisma
Clés / credentials nécessaires	Clés d'API GitHub, Vercel, etc. (non spécifié, implicite pour les outils)

Guide étape par étape

Comprendre le fonctionnement des Goals

Historiquement, une requête simple à un agent IA suit un processus linéaire : l'utilisateur demande quelque chose, l'agent travaille, fournit un résultat, puis attend une nouvelle instruction humaine. Avec les Goals, le processus devient itératif et autonome :

1. Définir le Goal : L'utilisateur spécifie un objectif à atteindre (par exemple, "Je veux que mon déploiement Vercel soit vert").
2. Travailler : L'agent exécute les actions nécessaires pour progresser vers le Goal.
3. Vérifier : L'agent utilise des preuves (tests, logs, etc.) pour évaluer si le Goal est atteint.
4. Prochaine étape / Terminer : Si le Goal est atteint, l'agent le marque comme terminé. Sinon, il retourne à l'étape "Travailler" pour continuer ses efforts.

Ce cycle continu permet à l'agent de persévérer jusqu'à la complétion de la tâche, sans interruption.

Utiliser les Goals pour corriger les checks d'une Pull Request

Pour s'assurer que tous les checks d'une Pull Request (PR) sont verts, on peut définir un Goal qui guide l'agent à travers les étapes de correction et de validation.

Goal :

/goal je veux que tous les checks de ma pull request soit vert, sans tricher. Commit et push les changements jusqu'à que ce soit vert.

L'agent va alors :

• Identifier la PR courante.
• Tirer les checks GitHub.
• Reproduire les échecs localement si possible.
• Committer et pousser les changements jusqu'à ce que les checks soient verts.
• Utiliser le workflow GitHub/CI pour vérifier la demande.

Exemple de commande pour vérifier l'état d'une PR :

gh pr view --json number,headRefName,baseRefName,mergeableState

Corriger les erreurs TypeScript et ESLint avec un Goal

Un autre cas d'usage courant est la correction automatique des erreurs de linting et de typage. Le Goal peut être formulé pour exiger une propreté totale du code.

Goal :

/goal je veux plus aucune erreur / warning typescript et eslint. Tu dois tout corriger, sans tricher et sans désactiver les règles afin de ne plus avoir d'erreurs.

Vérification :
L'agent exécutera des commandes comme pnpm ts et pnpm lint:ci pour s'assurer qu'il n'y a aucune erreur ou avertissement. Les contraintes spécifient qu'il ne doit pas désactiver les règles pour "tricher".

Exemple de commandes utilisées par l'agent :

pnpm exec eslint src/routes src/components src/lib/actions src/router.tsx src/providers.tsx convex/auth convex/betterAuth convex/app.ts convex/http.ts convex/migrations/schema.ts convex/testHelpers.ts convex/convex.config.ts convex/utils scripts/migrate-prod-to-convex.ts vite.config.ts --max-warnings 0

Comprendre la structure d'un Goal

Un Goal est plus qu'une simple instruction ; c'est un contrat avec l'agent. Il se compose de trois éléments clés :

• Résultat attendu : Ce que l'agent doit accomplir. Il doit être mesurable et vérifiable.
• Évidence : La méthode ou les outils que l'agent doit utiliser pour prouver que le résultat est atteint (ex: tests unitaires, logs, fichiers modifiés).
• Contraintes : Les règles ou limitations que l'agent doit respecter pendant l'exécution de la tâche (ex: ne pas supprimer de fichiers, ne pas désactiver de règles de linting).

Effectuer un refactoring majeur avec un Goal

Pour des tâches complexes comme la migration d'un framework à un autre (ex: Next.js vers Tanstack), un Goal peut orchestrer l'ensemble du processus, en définissant des étapes de vérification claires.

Goal (exemple simplifié) :

/goal refactor this app from next.js + neon postgresql prisma to tanstack start + convex
Use /goal
* verify that next is completely removed from the dependencies
* verify that tanstack start is actually building in the vercel preview and that app is working
Constraint :
* you should NOT delete any pages any views, just refactor them
* you should NOT delete any features
* the UI should look exactly the same
Verify :
* use Dev Browser to verify that the goal is complete
* launch the production app (in the main branch) in another port and compare with the tanstack app [here] to launch them both and compare each url (migrate the data)

Ce Goal demande à l'agent de non seulement effectuer le refactoring, mais aussi de vérifier la suppression complète des dépendances Next.js, la construction réussie de l'application Tanstack en prévisualisation Vercel, et la conformité de l'interface utilisateur. Les contraintes empêchent l'agent de supprimer des pages ou des fonctionnalités existantes.

Mettre à jour un favicon avec un Goal

Un Goal peut également être utilisé pour des tâches de mise à jour d'actifs, en spécifiant les étapes de génération et de vérification.

Goal :

/goal update the favicon of the app using /Users/melvynx/Documents/Figma/NowStack-SaaS.png. You should generate the variants (of size) in order to have the logo everywhere. update also the logo in the app and everywhere needed.
Verify : * commit and push your change, fetch nowstack.melvynx.dev and verify the favicon is updated

Exemple de commandes pour la vérification du favicon :

bash (which magick convert sharp 2>/dev/null; magick --version 2>/dev/null | head -3; convert --version 2>/dev/null | head -3)
bash (which sips; sips --version 2>&1 | head -2)
bash (sips -g pixelWidth -g pixelHeight /Users/melvynx/Documents/Figma/NowStack-SaaS.png 2>&1)
vercel inspect https://nowstack-saas-k600631e8-codelynx.vercel.app 2>&1 | grep -i 'status' | head -1
curl -sI https://nowstack.melvynx.dev/favicon.ico 2>&1 | head -15
curl -s https://nowstack.melvynx.dev/favicon.ico -o /tmp/live-favicon.ico && \
echo "Local:" && shasum -a 256 /Users/melvynx/Developer/saas/nowstack-saas/public/favicon.ico

Tableaux comparatifs : Quand utiliser les Goals ?

Ne pas utiliser /goal	Utiliser /goal
One-line fix ou petit fix	Optimisation performance / test etc... (mesurable)
Question simple à répondre	Feature complète (testable)
Update sans vérification possible	Refactor (lint, typescript)
	Big refactor (ex: Next.js -> Tanstack)

⚠️ Erreurs fréquentes et pièges

1. Utilisation pour des tâches non vérifiables : Les Goals sont inefficaces si le résultat ne peut pas être mesuré ou prouvé par des évidences concrètes. Évitez les Goals pour des questions ouvertes ou des mises à jour sans impact visible.
2. Manque de contraintes claires : Sans contraintes précises (ex: "ne pas désactiver les règles de linting"), l'agent pourrait trouver des solutions "faciles" qui ne respectent pas les standards de qualité.
3. Définition imprécise du résultat : Un Goal doit avoir un objectif clair et un état de complétion binaire (réussi/échoué). Des objectifs vagues peuvent entraîner des boucles infinies ou des résultats insatisfaisants.
4. Ignorer le contexte du thread : Les Goals sont liés au thread de conversation et ne sont pas des instructions globales. L'état et les évidences sont conservés dans le thread, ce qui permet à l'agent de reprendre là où il s'est arrêté. Ne pas comprendre cela peut mener à des confusions ou à la perte de contexte.

Glossaire

Codex : Un modèle d'IA développé par OpenAI, spécialisé dans la génération et la compréhension de code, souvent utilisé comme assistant de codage.
Orchestrateur : Un système (comme Harness, mentionné dans la vidéo) qui gère l'exécution des tâches complexes, coordonne les agents IA et assure le suivi des Goals.
Goal : Un objectif persistant défini dans Codex, que l'agent s'efforce d'atteindre de manière itérative, en vérifiant les progrès par des preuves concrètes et en respectant des contraintes spécifiées.

Points clés à retenir

• Les Goals permettent aux agents IA de travailler de manière autonome et persistante jusqu'à ce qu'une condition soit remplie.
• Chaque Goal doit avoir un résultat attendu clair, des méthodes de vérification (évidence) et des contraintes spécifiques.
• Les Goals sont particulièrement utiles pour les tâches complexes, mesurables et testables comme les refactorings majeurs, les optimisations de performance ou la complétion de fonctionnalités.
• Évitez d'utiliser les Goals pour des corrections mineures ou des questions simples qui ne nécessitent pas de vérification itérative.
• Les Goals maintiennent un état durable dans le thread de conversation, permettant à l'agent de reprendre le travail entre les tours.
• L'orchestrateur (comme Harness) joue un rôle clé dans la gestion du cycle de vie des Goals.

Ressources

• Formation AI Blueprint : mlv.sh/formationAI
• Documentation OpenAI sur les Goals dans Codex : developers.openai.com/docs/codex/using-goals-in-codex