Construire un SaaS avec un agent de code : un flux pratique

Commencez par un résultat observable

Un agent de code peut produire un écran convaincant avant même que vous ayez décidé ce qu'il doit faire. Commencez par un petit résultat utilisateur : un utilisateur connecté modifie son profil, l'enregistre, et voit le nom sauvegardé après rechargement. Cela donne à l'implémentation comme à la relecture une cible concrète.

Incluez dans le brief le comportement actuel, le comportement attendu et les cas d'échec importants. Nommez le module existant qui porte le travail. Une demande d'ajout d'édition de profil doit pointer vers la couche d'authentification plutôt que laisser l'agent inventer un second magasin d'utilisateurs. Gardez les identifiants hors des prompts et des captures d'écran — un apps/web/.env.local collé ou un cookie de session devient partie intégrante de l'historique de conversation.

Un brief exploitable se lit ainsi : « Dans l'écran de compte, laissez un utilisateur connecté modifier son nom d'affichage et le voir après rechargement. Le module auth possède l'enregistrement utilisateur ; n'ajoutez pas de table. Un nom vide, ou une requête qui nomme l'enregistrement d'un autre utilisateur, doit être rejeté. Prouvez-le avec pnpm test et un enregistrement manuel sur une largeur étroite. » Cinq phrases, et la plupart des conjectures disparaissent.

• Le résultat visible par l'utilisateur, formulé de façon à pouvoir le vérifier dans l'application qui tourne.
• Le fichier ou module qui possède le comportement aujourd'hui — et les zones qui doivent rester intactes.
• Au moins un cas d'échec : une tentative non authentifiée, une entrée invalide ou une requête répétée.
• Le contrôle qui le prouve — une commande de test, une fixture ou un parcours manuel explicite.

Faites en sorte que le dépôt s'explique de lui-même

Documentez comment lancer l'application, quels contrôles sont déterministes et où l'appartenance est vérifiée. Dans supastack, AGENTS.md consigne le périmètre d'espace de travail et .ai/ les décisions au niveau des fichiers. Ces notes sont utiles quand elles expliquent au prochain contributeur — humain ou agent — pourquoi une implémentation existe, pas seulement quels fichiers ont changé. Le guide de configuration d'agent montre comment le kit expose ce matériau, et le guide d'installation locale est le parcours que l'agent suivra réellement.

Demandez à l'agent de lire le code concerné avant de modifier. Un changement étroit a généralement besoin de l'UI, de sa frontière serveur et des tests autour de cette frontière. Charger tout le dépôt est moins utile que comprendre les quelques endroits qui décident si le nouveau comportement est correct : le contrôle d'appartenance, le schéma, le droit d'accès.

Quand une fonctionnalité touche la configuration, nommez le fichier plutôt que de le transcrire — « ajoutez la clé à apps/web/.env.local » garde les secrets sur le disque. La même discipline s'applique aux consoles des fournisseurs : décrivez la destination, ne collez pas l'identifiant.

Travaillez par petits changements relisables

Les agents sont les plus fiables quand un changement a un seul responsable et un seul résultat vérifiable. « Ajoutez l'édition de profil » est relisable ; « améliorez la zone de compte » invite des refactors que personne n'a demandés. Si une fonctionnalité se décompose en changement de schéma, frontière serveur et écran, exécutez-les comme des briefs séparés qui laissent chacun le build vert.

Faites un commit ou un point de contrôle avant chaque exécution de l'agent. Une base propre transforme une mauvaise sortie en diff supprimé plutôt qu'en exercice d'archéologie, et elle donne à votre relecture un avant-après stable à comparer.

Relisez un changement complet à la fois

Écrivez un test d'acceptation avant de modifier le comportement. Pour l'édition de profil, couvrez une mise à jour valide et une tentative non autorisée. Construisez la plus petite implémentation qui satisfasse ces cas, puis inspectez l'interaction réelle avec du texte réaliste et un viewport étroit.

Relisez le diff autant que le résultat. Cherchez la logique métier dupliquée, la gestion d'exceptions trop large et les nouvelles dépendances qui résolvent un problème déjà couvert par la stack. Lancez les vérifications du projet et consignez ce qu'elles établissent. Une fixture navigateur peut vérifier une interaction de formulaire ; elle ne peut pas établir que la base de production ou un fournisseur externe est correctement configuré.

Chaque commande répond à une question différente. pnpm test exerce le comportement contre des adaptateurs fake et locaux déterministes, pnpm check couvre lint, vérification de types et formatage, et pnpm build fait remonter les erreurs d'intégration qui n'apparaissent qu'à la compilation. Ensemble, elles forment un plancher de relecture — la checklist de lancement couvre ce qui doit encore être prouvé dans l'environnement réel.

pnpm test
pnpm check
pnpm build

Quand l'agent se trompe

Quand un résultat est faux, résistez à l'envie d'empiler des prompts de suivi sur un mauvais diff. Revenez au point de contrôle, resserrez le brief autour de ce qui a été mal compris — généralement une contrainte non formulée ou un responsable manquant — et relancez. Chaque nouvel essai doit porter une information nouvelle, pas seulement une urgence nouvelle.

Un échec persistant signifie généralement que le brief suppose un contexte que le dépôt ne contient pas. Si l'agent continue d'inventer un second endroit où stocker les utilisateurs, le correctif est une phrase dans AGENTS.md sur l'endroit où vit l'identité, pas un ton plus ferme. Mettez le document à jour, puis retentez la tâche — le guide des agents est l'endroit où le kit conserve ce flux de travail.

Questions fréquentes sur les flux avec agents

Quelques questions reviennent dès qu'un fondateur commence à confier du vrai travail produit à un agent de code.

• Un agent de code peut-il construire un SaaS entier tout seul ? — Il peut assembler rapidement les parties visibles, mais les parties durables — autorisation, cycle de vie de facturation, isolation des données — ont toujours besoin d'un brief, d'un contrôle et d'une relecture. La vitesse sans cette boucle se transforme en reprise.
• Quelle taille doit avoir une tâche confiée à un agent de code ? — Assez petite pour que vous puissiez vérifier le résultat dans l'application qui tourne en quelques minutes : un résultat visible par l'utilisateur, un module responsable, un contrôle d'acceptation.
• Que ne faut-il jamais mettre dans un prompt ? — Les secrets des fournisseurs, les cookies de session, le contenu de .env.local et les données clients. Nommez les fichiers et laissez l'outil les lire localement plutôt que de copier des valeurs dans un journal de chat.
• Le code écrit par un agent change-t-il ma façon de relire ? — La relecture passe de la frappe à la lecture : inspectez le diff pour la logique dupliquée, la gestion d'exceptions trop large et les dépendances qui résolvent à nouveau un problème déjà couvert par la stack.
• Quels tests comptent le plus pour la sortie d'un agent ? — Ceux qui verrouillent l'appartenance et le comportement en échec : requêtes non autorisées, entrées invalides et soumissions répétées, pas seulement le chemin nominal que montre la démo.