Les agents de programmation transforment la façon dont les logiciels sont développés.

Les modèles peuvent désormais tourner pendant des heures, réaliser d’ambitieux remaniements de code sur plusieurs fichiers et itérer jusqu’à ce que les tests passent. Mais pour tirer le meilleur parti des agents, il faut comprendre comment ils fonctionnent et adopter de nouvelles pratiques.

Ce guide présente des techniques pour travailler avec l’Agent Cursor. Que vous découvriez la programmation avec des agents ou que vous souhaitiez apprendre comment notre équipe utilise Cursor, nous allons passer en revue les meilleures pratiques pour coder avec des agents.

#Comprendre les infrastructures d’agent

Une infrastructure d’agent repose sur trois composants :

1. Instructions : Le prompt système et les règles qui guident le comportement de l’agent
2. Outils : Modification de fichiers, recherche dans la base de code, exécution de commandes dans le terminal, et bien plus encore
3. Messages utilisateur : Vos prompts et relances qui orientent le travail

L’infrastructure d’agent de Cursor orchestre ces composants pour chaque modèle que nous prenons en charge. Nous ajustons les instructions et les outils spécifiquement pour chaque modèle de pointe, sur la base d’évaluations internes et de benchmarks externes.

Cette infrastructure est importante, car différents modèles réagissent différemment aux mêmes prompts. Un modèle fortement entraîné sur des workflows orientés shell pourrait préférer grep à un outil de recherche dédié. Un autre pourrait avoir besoin d’instructions explicites pour appeler des outils de linting après les modifications. L’agent de Cursor gère cela pour vous afin que, lorsque de nouveaux modèles sont lancés, vous puissiez vous concentrer sur la création de logiciels.

#Commencer par la planification

Le changement le plus important que vous puissiez apporter consiste à planifier avant de coder.

Une étude de l’Université de Chicago a montré que les développeurs expérimentés ont davantage tendance à planifier avant de générer du code. La planification impose une réflexion claire sur ce que vous êtes en train de construire et donne à l’agent des objectifs concrets à atteindre.

#Utiliser le mode Plan

Appuyez sur Shift+Tab dans le champ de saisie de l'agent pour activer ou désactiver le mode Plan. Au lieu d'écrire immédiatement du code, l'agent va :

1. Explorer votre codebase pour trouver les fichiers pertinents
2. Poser des questions pour préciser vos besoins
3. Créer un plan de mise en œuvre détaillé avec les chemins de fichiers et les références de code
4. Attendre votre approbation avant de commencer la mise en œuvre

Les plans s'ouvrent sous forme de fichiers Markdown que vous pouvez modifier directement pour supprimer les étapes inutiles, ajuster l'approche ou ajouter du contexte que l'agent a pu manquer.

Astuce : Cliquez sur « Save to workspace » pour stocker les plans dans .cursor/plans/. Cela crée de la documentation pour votre équipe, facilite la reprise d'un travail interrompu et fournit du contexte aux futurs agents travaillant sur la même fonctionnalité.

Toutes les tâches ne nécessitent pas un plan détaillé. Pour des modifications rapides ou des tâches que vous avez déjà effectuées de nombreuses fois, vous pouvez tout à fait passer directement par l'agent.

#Repartir d'un plan

Parfois, l'agent génère quelque chose qui ne correspond pas à ce que vous vouliez. Au lieu d'essayer de le corriger avec des prompts supplémentaires, revenez au plan.

Annulez les modifications, affinez le plan pour préciser davantage ce dont vous avez besoin, puis relancez-le. C'est souvent plus rapide que de corriger un agent en cours d'exécution et cela donne des résultats plus nets.

#Gestion du contexte

À mesure que vous vous familiarisez avec les agents qui écrivent du code, votre rôle consiste à fournir à chaque agent le contexte dont il a besoin pour accomplir sa tâche.

#Laissez l'agent trouver le contexte

Vous n'avez pas besoin de référencer manuellement chaque fichier dans votre prompt.

L'agent de Cursor dispose de puissants outils de recherche et récupère le contexte à la demande. Quand vous posez une question sur « le flux d’authentification », l'agent trouve les fichiers pertinents via grep et la recherche sémantique, même si votre prompt ne contient pas exactement ces mots.

Restez simple : si vous connaissez le fichier exact, mentionnez-le. Sinon, l'agent le trouvera. Inclure des fichiers non pertinents peut induire l'agent en erreur sur ce qui est important.

L'agent de Cursor dispose aussi d'outils utiles, comme @Branch, qui vous permettent de donner à l'agent du contexte sur votre travail en cours. « Passe en revue les changements sur cette branche » ou « Sur quoi suis-je en train de travailler ? » deviennent des façons naturelles de situer l'agent par rapport à votre tâche actuelle.

#Quand démarrer une nouvelle conversation

L'une des questions les plus fréquentes : dois-je continuer cette conversation ou repartir de zéro ?

Démarrez une nouvelle conversation lorsque :

• Vous passez à une autre tâche ou fonctionnalité
• L'agent semble confus ou continue de faire les mêmes erreurs
• Vous avez terminé une unité de travail cohérente

Continuez la conversation lorsque :

• Vous itérez sur la même fonctionnalité
• L'agent a besoin du contexte des échanges précédents
• Vous déboguez quelque chose qu'il vient de générer

Les longues conversations peuvent faire perdre sa concentration à l'agent. Après de nombreux échanges et résumés, le contexte accumule du bruit et l'agent peut se laisser distraire ou basculer vers des tâches sans rapport. Si vous remarquez que l'efficacité de l'agent diminue, il est temps de démarrer une nouvelle conversation.

#Faire référence au travail précédent

Lorsque vous démarrez une nouvelle conversation, utilisez @Past Chats pour faire référence au travail précédent plutôt que de copier-coller l'intégralité de la conversation. L’Agent peut lire de manière sélective l’historique du chat pour ne récupérer que le contexte dont il a besoin.

C’est plus efficace que de dupliquer des conversations entières.

#Étendre l'agent

Cursor propose deux moyens principaux de personnaliser le comportement de l'agent : Rules pour un contexte statique qui s'applique à chaque conversation, et Skills pour des fonctionnalités dynamiques que l'agent peut utiliser lorsque c'est pertinent.

#Règles : contexte statique pour votre projet

Les règles fournissent des instructions persistantes qui définissent la façon dont l’agent travaille avec votre code. Considérez-les comme un contexte permanent auquel l’agent a accès au début de chaque conversation.

Créez des règles sous forme de fichiers Markdown dans .cursor/rules/ :

# Commandes

- `npm run build`: Compiler le projet
- `npm run typecheck`: Lancer le vérificateur de types
- `npm run test`: Lancer les tests (préférer les fichiers de test individuels pour plus de rapidité)

# Style de code

- Utiliser les modules ES (import/export), pas CommonJS (require)
- Déstructurer les imports si possible : `import { foo } from 'bar'`
- Voir `components/Button.tsx` pour la structure de composant canonique

# Workflow

- Toujours vérifier les types après une série de modifications du code
- Les routes API vont dans `app/api/` en suivant les patterns existants

Gardez vos règles concentrées sur l’essentiel : les commandes à exécuter, les modèles à suivre et des références à des exemples canoniques dans votre base de code. Faites référence aux fichiers plutôt que d’en copier le contenu ; ainsi, les règles restent concises et ne deviennent pas obsolètes au fur et à mesure que le code évolue.

À éviter dans vos règles :

• Copier des guides de style entiers (utilisez plutôt un linter)
• Documenter chaque commande possible (l’agent connaît les outils courants)
• Ajouter des consignes pour des cas limites rarement applicables

Astuce : Commencez simplement. Ajoutez des règles uniquement lorsque vous remarquez que l’agent fait la même erreur à répétition. Ne cherchez pas à sur-optimiser avant de bien comprendre vos propres modèles.

Validez vos règles dans Git pour que toute votre équipe en profite. Lorsque vous voyez l’agent faire une erreur, mettez à jour la règle. Vous pouvez même mentionner @cursor dans une issue GitHub ou une PR pour que l’agent mette la règle à jour pour vous.

#Compétences : capacités et workflows dynamiques

Agent Skills élargissent les capacités des agents. Les compétences encapsulent des connaissances spécifiques à un domaine, des workflows et des scripts que les agents peuvent invoquer lorsque c’est approprié.

Les compétences sont définies dans des fichiers SKILL.md et peuvent inclure :

• Commandes personnalisées : workflows réutilisables déclenchés avec / dans la saisie de l’agent
• Hooks : scripts exécutés avant ou après les actions de l’agent
• Connaissances métier : instructions pour des tâches spécifiques que l’agent peut utiliser à la demande

Contrairement aux Rules qui sont toujours incluses, les compétences sont chargées dynamiquement lorsque l’agent décide qu’elles sont pertinentes. Cela garde votre fenêtre de contexte dégagée tout en donnant à l’agent accès à des capacités spécialisées.

#Exemple : boucle d’agent de longue durée

Un modèle puissant consiste à utiliser des skills pour créer des agents qui s’exécutent pendant de longues périodes, en itérant jusqu’à atteindre un objectif. Voici comment vous pouvez créer un hook qui fait travailler un agent jusqu’à ce que tous les tests passent.

Commencez par configurer le hook dans .cursor/hooks.json :

{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
  }
}

Le script hook (.cursor/hooks/grind.ts) reçoit le contexte sur stdin et renvoie un followup_message afin de poursuivre la boucle :

import { readFileSync, existsSync } from "fs";

interface StopHookInput {
  conversation_id: string;
  status: "completed" | "aborted" | "error";
  loop_count: number;
}

const input: StopHookInput = await Bun.stdin.json();
const MAX_ITERATIONS = 5;

if (input.status !== "completed" || input.loop_count >= MAX_ITERATIONS) {
  console.log(JSON.stringify({}));
  process.exit(0);
}

const scratchpad = existsSync(".cursor/scratchpad.md")
  ? readFileSync(".cursor/scratchpad.md", "utf-8")
  : "";

if (scratchpad.includes("DONE")) {
  console.log(JSON.stringify({}));
} else {
  console.log(JSON.stringify({
    followup_message: `[Iteration ${input.loop_count + 1}/${MAX_ITERATIONS}] Continue working. Update .cursor/scratchpad.md with DONE when complete.`
  }));
}

Ce schéma est utile pour :

• Exécuter (et corriger) jusqu’à ce que tous les tests réussissent
• Itérer sur une interface utilisateur jusqu’à ce qu’elle corresponde à une maquette
• Toute tâche orientée vers un objectif dont la réussite est vérifiable

Conseil : Les Skills avec hooks peuvent s’intégrer aux outils de sécurité, aux gestionnaires de secrets et aux plateformes d’observabilité. Consultez la documentation sur les hooks pour les intégrations avec nos partenaires.

Les Agent Skills ne sont actuellement disponibles que sur le canal de mise à jour Nightly. Ouvrez les paramètres de Cursor, sélectionnez Beta, puis définissez votre canal de mise à jour sur Nightly et redémarrez.

Au-delà du code, vous pouvez connecter l’agent à d’autres outils que vous utilisez au quotidien. MCP (Model Context Protocol) permet à l’agent de lire des messages Slack, d’examiner des journaux Datadog, de déboguer des erreurs provenant de Sentry, d’interroger des bases de données, et bien plus encore.

#Ajout d’images

L’agent peut traiter des images directement à partir de vos prompts. Collez des captures d’écran, faites glisser des fichiers de design ou indiquez des chemins d’images.

#Du design au code

Collez une maquette et demandez à l’agent de l’implémenter en code. L’agent analyse l’image et peut reproduire la mise en page, les couleurs et les espacements. Vous pouvez aussi utiliser le serveur MCP Figma.

#Débogage visuel

Faites une capture d’écran d’un état d’erreur ou d’une interface utilisateur inattendue et demandez à l’agent d’enquêter. C’est souvent plus rapide que de décrire le problème avec des mots.

L’agent peut aussi contrôler un navigateur pour effectuer ses propres captures d’écran, tester des applications et vérifier les modifications visuelles. Consultez la documentation Browser pour plus de détails.

#Workflows courants

Voici des modèles d’agents adaptés à différents types de tâches.

#Développement piloté par les tests

L’agent peut écrire du code, exécuter des tests et itérer automatiquement :

1. Demandez à l’agent d’écrire des tests à partir de couples entrée/sortie attendus. Indiquez clairement que vous pratiquez le développement piloté par les tests (TDD), afin qu’il évite de créer des implémentations factices pour des fonctionnalités qui n’existent pas encore.
2. Demandez à l’agent d’exécuter les tests et de confirmer qu’ils échouent. Précisez bien qu’il ne doit pas écrire de code d’implémentation à ce stade.
3. Effectuez un commit des tests lorsque vous en êtes satisfait.
4. Demandez à l’agent d’écrire du code qui fait réussir les tests, en lui indiquant de ne pas modifier les tests. Dites-lui de continuer à itérer jusqu’à ce que tous les tests réussissent.
5. Effectuez un commit de l’implémentation une fois que vous êtes satisfait des modifications.

Les agents donnent les meilleurs résultats lorsqu’ils ont une cible claire à atteindre. Les tests permettent à l’agent de modifier le code, d’évaluer les résultats et de s’améliorer progressivement jusqu’à réussir.

#Compréhension de la base de code

Lors de votre intégration sur une nouvelle base de code, utilisez l’Agent pour apprendre et explorer. Posez les mêmes questions que vous poseriez à un membre de votre équipe :

• « Comment fonctionne le logging dans ce projet ? »
• « Comment ajouter un nouvel endpoint d’API ? »
• « Quels cas limites CustomerOnboardingFlow gère-t-il ? »
• « Pourquoi appelons-nous setUser() au lieu de createUser() à la ligne 1738 ? »

L’Agent utilise à la fois grep et la recherche sémantique pour parcourir la base de code et trouver des réponses. C’est l’un des moyens les plus rapides de se mettre à niveau sur un code que vous ne connaissez pas encore.

#Workflows Git

Les Agents peuvent rechercher dans l’historique Git, résoudre les conflits de fusion et automatiser votre workflow Git.

Par exemple, une commande /pr qui crée un commit, pousse les modifications et ouvre une PR :

Create a pull request for the current changes.

1. Look at the staged and unstaged changes with `git diff`
2. Write a clear commit message based on what changed
3. Commit and push to the current branch
4. Use `gh pr create` to open a pull request with title/description
5. Return the PR URL when done

Les commandes sont idéales pour les workflows que vous exécutez plusieurs fois par jour. Stockez‑les sous forme de fichiers Markdown dans .cursor/commands/ et validez‑les dans Git pour que toute votre équipe puisse les utiliser.

Autres exemples de commandes que nous utilisons :

• /fix-issue [number] : Récupérer les détails du ticket avec gh issue view, trouver le code pertinent, implémenter un correctif et ouvrir une PR
• /review : Exécuter les linters, rechercher les problèmes courants et résumer ce qui peut nécessiter une attention particulière
• /update-deps : Vérifier les dépendances obsolètes et les mettre à jour une par une, en lançant les tests après chacune

L’agent peut utiliser ces commandes de manière autonome, ce qui vous permet de déléguer des workflows en plusieurs étapes avec un seul appel à /.

#Revue de code

Le code généré par l’IA doit être revu, et Cursor propose plusieurs options.

#Pendant la génération

Regardez l’agent en action. La vue des différences affiche les modifications au fur et à mesure qu’elles se produisent. Si vous voyez que l’agent part dans la mauvaise direction, appuyez sur Échap pour l’interrompre et le rediriger.

#Relecture par l’Agent

Une fois que l’Agent a terminé, cliquez sur Review → Find Issues pour lancer une phase de revue dédiée. L’Agent analyse les modifications proposées ligne par ligne et signale les problèmes potentiels.

Pour toutes les modifications locales, ouvrez l’onglet Source Control et exécutez Agent Review pour comparer avec votre branche principale.

#Bugbot pour les pull requests

Effectuez un push vers votre dépôt pour obtenir des revues automatisées de vos pull requests. Bugbot applique une analyse avancée pour détecter les problèmes en amont et suggérer des améliorations pour chaque PR.

#Diagrammes d’architecture

Pour des modifications majeures, demandez à l’agent de générer des diagrammes d’architecture. Essayez l’invite suivante : « Create a Mermaid diagram showing the data flow for our authentication system, including OAuth providers, session management, and token refresh. » Ces diagrammes sont utiles pour la documentation et peuvent révéler des problèmes d’architecture avant la revue de code.

#Exécuter des agents en parallèle

Cursor facilite l’exécution de nombreux agents en parallèle sans qu’ils n’interfèrent entre eux. Nous avons constaté que le fait de laisser plusieurs modèles tenter de résoudre le même problème, puis de choisir le meilleur résultat, améliore considérablement le résultat final, en particulier pour les tâches plus difficiles.

#Prise en charge native des worktrees

Cursor crée et gère automatiquement des git worktrees pour les agents parallèles. Chaque agent s’exécute dans son propre worktree avec des fichiers et des modifications isolés, afin que les agents puissent modifier, compiler et tester le code sans se gêner mutuellement.

Pour exécuter un agent dans un worktree, sélectionnez l’option worktree dans le menu déroulant de l’agent. Lorsque l’agent a terminé, cliquez sur Apply pour réintégrer ses modifications dans votre branche de travail.

#Exécuter plusieurs modèles en parallèle

Une stratégie très efficace consiste à exécuter le même prompt sur plusieurs modèles simultanément. Sélectionnez plusieurs modèles dans la liste déroulante, soumettez votre prompt et comparez les résultats côte à côte. Cursor vous suggérera également la solution qu’il juge la meilleure.

C’est particulièrement utile pour :

• les problèmes difficiles où différents modèles peuvent adopter des approches différentes
• comparer la qualité du code entre différentes familles de modèles
• trouver des cas limites qu’un modèle pourrait ne pas détecter

Lorsque vous exécutez de nombreux agents en parallèle, configurez les notifications et les sons pour savoir quand ils ont terminé.

#Déléguer aux agents cloud

Les agents cloud sont parfaits pour les tâches que vous mettriez normalement sur une liste de choses à faire :

• Corrections de bugs apparus pendant que vous travailliez sur autre chose
• Refactorisations de modifications de code récentes
• Génération de tests pour du code existant
• Mises à jour de la documentation

Vous pouvez basculer entre agents locaux et agents cloud selon la tâche. Lancez des agents cloud depuis cursor.com/agents, depuis l’éditeur Cursor ou depuis votre téléphone. Consultez les sessions sur le web ou sur mobile lorsque vous êtes loin de votre bureau. Les agents cloud s’exécutent dans des environnements isolés distants (sandboxes), vous pouvez donc fermer votre ordinateur portable et vérifier les résultats plus tard.

Voici comment fonctionnent les agents cloud sous le capot :

1. Décrivez la tâche et tout contexte pertinent
2. L’agent clone votre dépôt et crée une branche
3. Il travaille de manière autonome et ouvre une pull request une fois terminé
4. Vous recevez une notification lorsqu’il a fini (via Slack, e-mail ou l’interface web)
5. Examinez les modifications et fusionnez quand vous êtes prêt

Astuce : vous pouvez déclencher des agents depuis Slack avec « @Cursor ». En savoir plus.

#Mode Debug pour les bugs complexes

Lorsque les interactions standard avec l'agent peinent à résoudre un bug, le Mode Debug propose une approche différente.

Au lieu de deviner des correctifs, le Mode Debug :

1. Génère plusieurs hypothèses sur ce qui pourrait ne pas aller
2. Instrumente votre code avec des instructions de log
3. Vous demande de reproduire le bug tout en collectant les données d'exécution
4. Analyse le comportement réel pour identifier la cause racine
5. Apporte des correctifs ciblés basés sur des éléments concrets

Cela fonctionne particulièrement bien pour :

• Les bugs que vous pouvez reproduire mais que vous ne parvenez pas à expliquer
• Les race conditions et les problèmes de synchronisation
• Les problèmes de performance et les fuites de mémoire
• Les régressions où quelque chose fonctionnait auparavant

L'essentiel est de fournir un contexte détaillé sur la façon de reproduire le problème. Plus vous êtes précis, plus l'instrumentation ajoutée par l'agent sera utile.

#Développer votre workflow

Les développeurs qui tirent le plus parti des agents partagent quelques caractéristiques :

Ils rédigent des prompts spécifiques. Le taux de réussite de l’agent s’améliore nettement avec des instructions précises. Comparez « add tests for auth.ts » avec « Write a test case for auth.ts covering the logout edge case, using the patterns in __tests__/ and avoiding mocks. »

Ils itèrent sur leur configuration. Commencez simplement. N’ajoutez des règles que lorsque vous remarquez que l’agent commet plusieurs fois la même erreur. N’ajoutez des commandes qu’une fois que vous avez identifié un workflow que vous souhaitez répéter. N’optimisez pas à l’excès avant de comprendre vos patterns.

Ils relisent avec attention. Le code généré par l’IA peut sembler correct tout en étant subtilement erroné. Lisez les diffs et examinez-les attentivement. Plus l’agent travaille vite, plus votre processus de revue devient important.

Ils définissent des objectifs vérifiables. Les agents ne peuvent pas corriger ce qu’ils ne connaissent pas. Utilisez des langages typés, configurez des linters et écrivez des tests. Donnez à l’agent des signaux clairs indiquant si les changements sont corrects.

Ils traitent les agents comme des collaborateurs compétents. Demandez des plans. Demandez des explications. Remettez en question les approches qui ne vous conviennent pas.

Les agents s’améliorent rapidement. Même si les patterns évolueront avec les nouveaux modèles, nous espérons que cela vous aidera dès aujourd’hui à être plus productif avec les agents de code.

Commencez avec l’agent de Cursor pour essayer ces techniques.