Vous utilisez déjà Cursor — Tab, le chat, parfois l’agent. La différence entre « ça marche » et « c’est fiable au quotidien » tient surtout à comment vous cadrez l’agent, pas au modèle choisi.
Ce guide décrit le harness, le cadre qui fait passer Cursor du chat ponctuel à un agent fiable à travers rules, skills, subagents, modes et les fichiers à placer dans .cursor/.
Le mode compte autant que le prompt
On a tendance à laisser Cursor en Agent : c’est le mode par défaut, il répond, il modifie, on a l’impression d’avancer. Sauf que pour comprendre un fichier ou découper une fonctionnalité sur plusieurs modules, ce n’est pas le bon outil, c’est comme demander à un maçon de faire l’étude de sol en même temps que les murs finalement.
Chaque mode correspond à une intention. Avant d’envoyer un message, interrogez-vous sur le comportement attendu de l’agent. Ci dessous un tableau récapitulatif :
| Intention | Mode | En pratique |
|---|---|---|
| Comprendre | Ask | Poser des questions ou demander des explications sur le code, les concepts ou les bonnes pratiques sans modification de code. |
| Concevoir / découper | Plan | Générer un plan d’action ou une feuille de route pour résoudre un problème, implémenter une fonctionnalité ou structurer un projet. |
| Produire du code | Agent | L’agent agit de manière autonome, il analyse, génère, modifie ou refactorise du code selon vos instructions ou un plan établi. |
| Diagnostiquer | Debug | Analyse et identifie les causes d’un bug, propose des corrections ou des pistes de résolution. |
La règle qui change le quotidien : dès que la tâche touche plus de trois fichiers, passez par le mode Plan avant Agent. Vous limitez les grosses vagues de modifications à valider d’un coup, et vous gardez une trace claire de ce que vous aviez décidé.
Remarque : séparez toujours « décider quoi faire » et « le faire ». Quand Cursor propose le mode Plan, considérez que c’est un signal utile pas une popup à ignorer.
Les rules : le plancher, pas le manuel entier
Si vous vous surprenez à retaper à chaque session « réponds en français », « ne touche pas au reste du projet » ou « on est en React 18 », ce n’est pas le LLM qui déraille, mais c’est votre prompt qui se répète. Lassé de recoller les mêmes consignes à chaque message ? C’est précisément à cela que servent les rules.
Les rules vivent dans .cursor/rules/, en fichiers .mdc. Elles disent à l’agent ce qui doit rester vrai d’une conversation à l’autre : langue, périmètre des modifications, stack, interdits. Une fois écrites, elles travaillent en arrière-plan ; vous n’avez plus à négocier les mêmes consignes.
En pratique, Cursor propose deux formats pour ces consignes persistantes :
**AGENTS.md(à la racine) — markdown simple, sans frontmatter. C’est l’option la plus directe pour un petit projet : vous y mettez vos standards généraux (« réponds en français », « ne touche pas hors scope », stack) et la carte du repo** (structure, commande de test, dossiers sensibles). La doc Cursor le présente comme une alternative à.cursor/rules/quand vous n’avez pas besoin de finesse.**.cursor/rules/*.mdc— fichiers modulaires avec frontmatter. Utile dès que vous voulez cibler : une rule globale toujours active, une autre seulement sur les fichiers React, etc. Vous pouvez aussi séparer** rôles :AGENTS.mdpour la carte, une rule pour le comportement.
Le frontmatter, c’est le bloc YAML en tête d’un .mdc : Cursor y lit quand activer la rule (alwaysApply, globs…), le markdown en dessous porte quoi imposer à l’agent.
Deux niveaux suffisent presque toujours : vos standards (dans AGENTS.md ou une rule alwaysApply: true), puis si besoin une rule par techno avec globs, elle ne s’active que sur les bons fichiers (composants UI, API, tests…).
Voici un exemple si vous choisissez une rule globale plutôt que tout mettre dans AGENTS.md, .cursor/rules/standards-projet.mdc :
---
description: Standards perso sur ce projet
alwaysApply: true
---
- Ne pas refactorer hors du scope de la demande
- Répondre en français
- Respecter la stack et les versions du projet
- Préférer des changements petits et ciblésEt une rule qui ne s’applique qu’à l’interface, utile quand le front et le back ne suivent pas les mêmes conventions :
---
description: Conventions composants React
globs: **/*.{jsx,tsx}
alwaysApply: false
---
- Composants fonctionnels uniquement
- Fichiers de composants en PascalCaseLa tentation, c’est d’en ajouter une dizaine « au cas où ». Résultat : l’agent reçoit trop d’instructions, certaines se contredisent, et vous avez l’impression qu’il ne vous écoute plus. Gardez le strict nécessaire, en général une globale et une ou deux ciblées, pas davantage.
Remarque : une rule doit répondre à « qu’est-ce qu’on refuse toujours ? », pas à « comment je fais cette tâche aujourd’hui ? ». Pour les procédures récurrentes (commit, tests, revue), ce sera le rôle des skills, dans la section suivante.
Les skills : automatiser ce que vous refaites chaque semaine
Tout d’abord, les rules posent le cadre ; les skills décrivent une marche à suivre — commit, lancer les tests, préparer une revue. Chaque skill est un dossier avec un fichier SKILL.md dans .cursor/skills/. L’agent le repère quand votre demande correspond à sa description, ou quand vous l’appelez depuis le menu slash (/commit, par exemple).
La distinction en une ligne :
| Rule | Skill | |
|---|---|---|
| Rôle | Ce qui doit rester vrai | Comment faire une tâche précise |
| Quand | En permanence | Quand vous le déclenchez |
| Exemple | « Ne pas toucher hors scope » | « Comment créer un commit propre » |
L’idée n’est pas de tout regrouper dans un seul fichier fourre-tout, mais d’en avoir autant que de tâches précises : commit, run-checks, revue d’une merge request, déploiement, migration d’une table, etc. Chaque skill reste court et ciblé, un workflow par skill, pour que l’agent sache exactement quoi appliquer quand vous le déclenchez.
Le point délicat, c’est la description en tête de fichier : c’est elle qui dit à l’agent quand charger le skill. Soyez concret « Utiliser sur « commit », /commit, ou avant push » plutôt que vague (« aide sur git »). Listez des étapes que l’on peut cocher : commandes à lancer, format du message, fichiers à ne jamais inclure.
Exemple concret pour ne plus improviser vos commits, .cursor/skills/commit/SKILL.md :
---
name: commit
description: Créer un commit git formaté. Utiliser sur "commit", /commit, ou "commit avec le bon format".
---
# Commit
1. Vérifier l'état du dépôt (`git status`) et les modifications (`git diff`).
2. Rédiger un message : `type(scope): résumé court`.
3. Ne jamais committer `.env`, clés API ou credentials.
4. Utiliser un message multiligne propre si le résumé dépasse une ligne.Placez les skills dans le projet (.cursor/skills/) pour les partager avec le dépôt, ou dans votre dossier perso (~/.cursor/skills/) pour les retrouver sur tous vos repos.
Remarque : si vous vous retrouvez à réécrire la même procédure dans le chat, ce n’est pas un mauvais prompt c’est un skill qui manque. Affinez le fichier une fois, au lieu de vous répéter à chaque session.
Les subagents : un collègue à part, pas une deuxième conversation
Premièrement, imaginez que vous demandez à un collègue d’explorer un dossier ou de relire vos changements pendant que vous continuez à discuter avec l’agent principal. Le subagent, c’est un peu ça : il travaille à part, dans son propre contexte, et ne vous renvoie en général qu’un résumé. Votre conversation principale reste claire, pas une avalanche de fichiers « au cas où ».
Cursor en propose déjà (exploration, commandes terminal, etc.). Le plus utile c’est souvent d’en créer un sur mesure et de commencer par un profil lecture seule (readonly: true) : il commente, il ne modifie pas. Idéal pour une relecture avant commit.
Comme pour les skills, la description fait office de fiche de poste : « Revue en lecture seule des changements non commités, avant commit ». Donnez aussi un périmètre : les modifications en cours, ou un dossier précis, pas « tout le dépôt » sans limite. Pour le retour, demandez un tri par gravité : d’abord les bloquants (bug, faille, régression), puis les suggestions (amélioration utile mais non obligatoire), enfin les détails (style, nommage, formulation, le genre de remarque qu’on corrige « si on a le temps »).
Exemple de relecteur, .cursor/agents/code-reviewer.md :
---
name: code-reviewer
description: Revue de code en lecture seule après modification. Utiliser avant commit ou après des changements importants.
readonly: true
---
Tu es relecteur. Analyse les changements demandés.
Réponds en trois sections : Bloquant, Suggestion, Détail — chaque point cite un chemin de fichier.
Ne modifie aucun fichier.Fichiers dans .cursor/agents/ pour le projet, ou ~/.cursor/agents/ pour tous vos repos. Vous pouvez en définir plusieurs (explorateur d’un module, auditeur sécurité, etc.) : un rôle par fichier, une mission claire.
Remarque : évitez de lancer plusieurs subagents qui écrivent en parallèle sur les mêmes fichiers vous vous retrouverez avec des propositions de modifications difficiles à réconcilier. En revanche, enchaîner relecteur readonly puis corrections dans l’agent principal, c’est le schéma qui fonctionne le mieux.
Mettre tout ça bout à bout
Jusqu’ici, chaque brique a son rôle. La question qui reste : dans quel ordre les enchaîner sur une vraie tâche ?
Prenons un exemple concret : vous devez ajouter une validation sur un formulaire. Rien de très complexe, mais assez sensible pour que « laisser l’agent faire » sans cadre finisse mal. Voici un enchaînement qui tient la route :
flowchart LR
A[Plan] --> B[Agent]
B --> C[Subagent relecteur]
C --> D[Agent corrections]
D --> E[Skills]Plan d’abord, si le périmètre est flou ou si plusieurs fichiers sont concernés. Vous fixez ce qui sera touché avant la première ligne de code et vous gardez une trace de ce que vous aviez décidé.
Agent ensuite, pour implémenter. Validez les changements fichier par fichier ; refusez ce qui dépasse le plan ou votre demande initiale. C’est le moment où une rule « pas de refactor hors scope » paie vraiment.
Subagent relecteur une fois le code en place : lecture seule, sur les modifications en cours. Il vous renvoie un tri par gravité bloquants d’abord, suggestions ensuite, détails en dernier.
Agent à nouveau, pour corriger les bloquants. Les suggestions et les détails peuvent attendre la prochaine passe. Inutile de tout traiter avant de committer.
Skills pour finir : run-checks si vous l’avez, puis commit, ou tout autre skill qui fait partie de votre routine. C’est la procédure automatisée qui remplace le « bon, je fais un git status à la main ».
Dès que vous touchez à la logique métier ou que le diff grossit, faites une pause avant le commit : passez par le relecteur. C’est là que le subagent readonly montre son utilité, pas pour le quotidien anodin, mais pour les changements où une seconde paire d’yeux évite une mauvaise surprise.
Quand les consignes se contredisent
Ça arrive plus souvent qu’on ne le croit : une rule dit une chose, un skill en dit une autre, et vous ajoutez une consigne dans le chat en plus. L’agent hésite, vous aussi.
Pas besoin d’un tribunal. Un ordre de priorité suffit :
- Ce que vous demandez explicitement maintenant.
- Les rules du dépôt — le plancher, ce qui ne se négocie pas.
- Le skill de la tâche en cours.
- Le prompt du subagent.
Si un skill contredit une rule, la rule gagne. Corrigez le skill, pas l’inverse : une rule trop vague ou contradictoire pollue toutes les conversations ; un skill mal calibré ne touche qu’une tâche.
Par où commencer dans .cursor/
Inutile de tout configurer le premier jour. Mieux vaut un socle modeste que dix fichiers jamais relus :
| Élément | Rôle |
|---|---|
AGENTS.md | Socle minimal : standards généraux + carte du repo + commandes de test |
ex. react-conventions.mdc | Conventions par techno, quand le projet grossit |
standards-projet.mdc | Optionnel — si vous préférez sortir les standards de AGENTS.md et garder ce fichier pour la carte seule |
| Skills | Une procédure par tâche récurrente (commit, run-checks, revue PR…) |
Subagent code-reviewer | Relecture readonly avant commit |
Ensuite, vous étoffez au fil de l’eau. Chaque fois que vous retapez la même consigne dans le chat, posez-vous la question : est-ce qu’il manque une rule, un skill ou un subagent ?
Remarque : une fois par mois, cinq minutes suffisent pour retirer ce qui ne sert plus et affiner une description qui ne déclenche jamais. Souvent plus rentable qu’ajouter un fichier de plus « au cas où ».
Quand ça coince, reconnaître les symptômes
Quelques signaux familiers et ce qu’ils indiquent en général :
L’agent refactorise sans qu’on lui demande. Souvent : pas de Plan, pas de rule sur le scope. Repassez par le mode Plan et rappelez « pas de refactor hors demande » dans une rule.
Les commits sont incohérents. Un skill commit manque, ou sa description est trop vague pour que l’agent sache quand le charger.
La conversation devient illisible. Trop d’étapes dans le même fil ; séparez décision (Plan) et exécution (Agent), et déléguez l’exploration ou la relecture à un subagent.
Le subagent ne part jamais. Sa description ressemble à une étiquette, pas à une fiche de poste. Réécrivez-la : « avant commit », « lecture seule », « changements non commités ».
L’agent se contredit d’une réponse à l’autre. Signe classique : trop de rules globales qui s’accumulent et se contredisent. Fusionnez-les, ou déplacez ce qui ne concerne qu’une partie du code vers une rule ciblée par globs.
En résumé
Ce n’est pas une course au nombre de fichiers dans .cursor/. C’est une question de rôles clairs :
- Modes — à quoi vous pensez : comprendre, concevoir, coder, déboguer.
- Rules — ce qui ne se négocie pas, d’une session à l’autre.
- Skills — les procédures que vous répétez, une par tâche.
- Subagents — l’exploration et la relecture, sans encombrer la conversation principale.
Bien configuré, Cursor cesse d’être un chat où il faut tout réexpliquer à chaque fois. Chaque type de demande sait déjà où aller et ainsi vous gardez la main sur le reste.
Merci pour votre lecture. Bon code !
