Construire avec un agent de code

Parcours pas à pas pour débuter

Prérequis : lisez les deux guides débutants ci-dessous et terminez la configuration locale Desktop. Un agent de codage 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 ce qui figure sur cette page s'applique à 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 .agents/skills/ à la racine du dépôt et copiez le skill le plus proche de votre tâche — add-a-desktop-capability est un bon premier essai.

2. Collez-le dans votre agent et décrivez votre changement, puis ajoutez une ligne : Lisez 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, la distribution d'installateurs et les appels de fournisseurs payants 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 du bureau

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.

Les skills livrés

Chaque fichier sous .agents/skills/ est un brief complet : collez-le ou laissez l'agent le lire, et les règles du kit voyagent avec lui — l'UI produit reste dans l'application web, seul le comportement OS va dans Rust.

La bibliothèque prompts/ prête à coller n'est livrée que dans le dépôt Web ; ce checkout emporte des skills à la place. Pour une configuration sans surveillance, utilisez le prompt prêt à l'emploi du guide agent-setup.

• Laissez l'agent exécuter la configuration

• add-a-desktop-capability — changements de fenêtre, barre d'état, raccourci, mise à jour ou build
• adding-a-dependency — ajouter, mettre à niveau ou déplacer une dépendance npm en sécurité
• reviewing-a-pr — relire un diff pour sa correction, l'isolation du workspace et les secrets
• upgrading-from-upstream — tirer une version plus récente du kit dans votre shell
• verify-changes — choisir et exécuter les bonnes vérifications avant la passation

Comment l'agent se souvient entre les sessions

Les agents n'ont pas de mémoire entre les sessions — le dossier .ai/ est la mémoire. .ai/PROJECT_CONTEXT.md consigne ce qui a changé récemment et pourquoi. À côté, un document miroir comme .ai/apps/desktop/src-tauri/src/lib.md explique les décisions derrière apps/desktop/src-tauri/src/lib.rs 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.

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 vérifications qu'il prétend — cargo test, cargo check ou le preflight de release — demandez la commande et sa sortie, pas une conclusion.
• Les secrets sont restés côté serveur — aucune clé de signature ou certificat n'a été imprimé dans un rapport ou un commit, et le shell ne porte toujours aucun identifiant de fournisseur.
• Le comportement produit est resté dans l'application web — le diff n'ajoute aucune UI, auth ou logique de chat parallèle en Rust.
• Le miroir .ai/ de chaque fichier modifié a bougé avec le code.
• La publication, la distribution d'installateurs et les appels de fournisseurs payants sont restés des étapes séparées que vous avez approuvées — l'agent n'a jamais fusionné, poussé ou publié 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.