Construire avec un agent de code

Parcours pas à pas pour débuter

Prérequis : lisez les deux guides pour débutants ci-dessous, terminez la configuration locale Web et ouvrez ce dépôt à sa racine dans votre éditeur. Un agent de code est un outil d'IA — Cursor, Claude Code, Devin ou un assistant similaire — qui lit votre projet, modifie des fichiers et exécute des commandes. Tout le contenu de cette page s'applique quel que soit celui que vous utilisez.

Termes rapides : un prompt est le texte d'instruction que vous collez dans l'agent. Un diff est la liste des modifications de fichiers qu'il propose. La racine du dépôt est le dossier le plus haut contenant package.json — l'agent doit toujours partir de là.

1. Ouvrez le dossier prompts/ à la racine du dépôt et copiez le prompt le plus proche de votre tâche. new-landing-page.md est un bon premier essai.

2. Collez-le dans votre agent et remplissez les <placeholders> : la route voulue, ce que la page ou l'écran doit faire, qui peut l'utiliser et à quoi ressemble le succès. Ajoutez ensuite une ligne : lis llms.txt, puis AGENTS.md, puis .ai/PROJECT_CONTEXT.md avant de toucher au code.

3. Laissez l'agent lister les fichiers qu'il va modifier et les vérifications qu'il exécutera avant d'éditer. Quand il a terminé, relisez le diff — vous approuvez de vraies modifications de votre produit.

4. La publication, le déploiement et les appels payants aux fournisseurs ne font jamais partie d'un prompt de tâche. Gardez-les comme des étapes séparées que vous approuvez explicitement.

• Avant de commencer
• Bases du terminal
• Configuration locale Web

Les fichiers que lit votre agent

Le dépôt embarque un petit ensemble de fichiers écrits pour les agents, pas seulement pour les humains. Vous ne collez jamais ce contexte à la main — pointez l'agent vers llms.txt et il lit le reste lui-même.

L'ordre de lecture compte : llms.txt est la carte, AGENTS.md fixe les limites et .ai/PROJECT_CONTEXT.md conserve ce que les sessions précédentes ont appris. Un agent qui saute les limites produit du code que vous ne pouvez pas livrer.

La bibliothèque de prompts

prompts/README.md est l'index. Chaque fichier est un brief complet : collez-le, remplissez les <placeholders> et les règles du kit — jetons de design plutôt que couleurs codées en dur, blocs du kit plutôt que motifs inventés — voyagent avec lui.

Pour le parcours de zéro à l'exécution, collez plutôt prompts/agent-setup.md — il pilote l'installation sans supervision décrite ensuite.

• Laissez l'agent exécuter l'installation pour vous

• agent-setup.md — monter le kit et le déployer avec un agent
• pick-a-style.md — appliquer un style de design à tout le produit
• new-landing-page.md — générer une page marketing à partir des blocs du kit
• new-app-screen.md — ajouter un écran dans le shell applicatif de l'espace de travail
• restyle-product.md — re-thémer une page existante sur les jetons du kit
• ui-audit.md — lancer l'audit visuel et d'accessibilité sur une route

Laisser l'agent installer et déployer

Le kit peut en grande partie s'installer tout seul. Coller prompts/agent-setup.md fait exécuter à l'agent docs/agent-setup.md — le runbook livré — phase par phase : vérifications préalables, fichiers d'environnement, installation, démarrage de la base de données, migrations, démarrage de l'app et, en option, un déploiement VPS. Après chaque phase, il exécute le point de vérification de cette phase et rapporte la sortie réelle, pas une affirmation.

Deux utilitaires gardent cela sûr. scripts/setup-env.mjs amorce les fichiers env à partir de .env.example : il ne crée que les fichiers manquants, ne génère que les secrets absents ou en placeholder, et son mode --check valide sans écrire. docker-compose.dev.yml est un environnement de développement entièrement conteneurisé — Postgres plus un conteneur de développement Node 22 — donc l'agent n'a pas besoin de Node.js installé sur votre ordinateur.

Le dépôt que vous avez reçu compte ici. Le dépôt Web et le monorepo All Platforms livrent le runbook, les fichiers compose, scripts/setup-env.mjs et prompts/. Les dépôts Mobile et Desktop autonomes livrent un llms.txt ciblé, AGENTS.md, les docs miroirs .ai/ et une sélection de docs dont docs/agent-security.md — mais pas le runbook d'installation ni les fichiers compose, car le backend auquel ces apps parlent vit dans le dépôt Web.

• Suivez l'installation pilotée par l'agent

Comment l'agent se souvient entre les sessions

Les agents n'ont pas de mémoire entre les sessions — le dossier .ai/ est cette mémoire. .ai/PROJECT_CONTEXT.md consigne ce qui a changé récemment et pourquoi. À côté, un doc miroir comme .ai/apps/web/src/reports.md explique les décisions derrière apps/web/src/reports.ts que le code seul ne montre pas.

Le contrat est simple : lisez le miroir d'un fichier avant de le modifier, et mettez à jour le miroir quand le changement est intégré. Les entrées Open Threads consignent le travail inachevé pour que la session suivante reprenne au lieu de repartir de zéro. Un miroir obsolète est pire que pas de miroir — quand vous relisez le diff de l'agent, vérifiez que les miroirs des fichiers modifiés ont bougé avec lui.

La surface agent de l'app en cours d'exécution

Votre produit déployé répond aussi aux agents — ces endpoints existent sur l'app en cours d'exécution, pas seulement dans le dépôt.

• GET /llms.txt — l'app sert son propre index llmstxt.org : les guides, les pages publiques et les endpoints publics, avec des URL absolues.
• POST /api/mcp — un endpoint MCP sans état qui expose les outils de l'app. Il accepte les clés API sk_ comme jetons bearer uniquement — les sessions de cookie du navigateur ne s'appliquent jamais. Créez des clés sous Settings → Developers.
• GET /api/v1/openapi — la spécification OpenAPI de l'API REST publique, pour les générateurs de clients et les outils d'agent.
• GET /api/health — la sonde de disponibilité et de dépendances qu'appellent les répartiteurs de charge et les contrôles d'uptime ; elle rapporte les types de configuration des fournisseurs, jamais de secrets.
• /status — une page lisible qui rapporte la santé de chaque sous-système.

Relisez honnêtement le travail de l'agent

Une tâche terminée est une preuve, pas un résumé. Avant de garder le travail de l'agent, vérifiez-le comme docs/agent-security.md vérifie un déploiement :

Quand quelque chose ne va pas, renvoyez le diff — l'agent corrige son propre travail plus vite quand vous nommez la vérification en échec. Pour tout ce qu'il n'aurait jamais dû tenter seul, dites-le explicitement une fois ; la limite tient pour le reste de la session.

• Portes de vérification et suite de tests

• Il a exécuté les tests qu'il prétend — demandez la commande et sa sortie, pas une conclusion.
• Les secrets sont restés côté serveur — rien de nouveau ne porte un préfixe NEXT_PUBLIC_ ou EXPO_PUBLIC_, et aucune clé n'a été imprimée dans un rapport ou un commit.
• Chaque lecture et écriture appartenant à l'utilisateur est restée cloisonnée par workspaceId — aucune requête ne fait confiance à un id envoyé par le navigateur.
• Le miroir .ai/ de chaque fichier modifié a bougé avec le code.
• La publication, le déploiement et les appels payants aux fournisseurs sont restés des étapes séparées que vous avez approuvées — l'agent n'a jamais fusionné, poussé ni déployé de lui-même.
• Si une étape a échoué deux fois, il s'est arrêté et a rapporté la commande en échec au lieu d'improviser autour.