Cursor

Éditeur : Anysphere Nom d'installation : cursor Statut : GA Configuration native : .cursor/rules/ à la racine du projet

InstallationCopy Anchor Link

apothem install --harness cursor --project /path/to/project

L'adaptateur rend un seul fichier de règles .mdc de portée projet à partir de la surface partagée de règles et de gouvernance d'Apothem, écrit les auxiliaires d'Apothem en tant que subagents Cursor dans le projet (voir Subagents), et ajoute un hook au fichier hooks.json du projet (voir Hooks).

Il écrit aussi les skills d'Apothem, ainsi que les règles et templates qu'ils citent, dans votre répertoire personnel, avant de toucher au projet (voir Fichiers hors du projet).

Fichiers écrits :

• <project>/.cursor/rules/apothem-rules.mdc, le fichier de règles.
• <project>/.cursor/agents/<name>.md pour chaque auxiliaire Apothem, dans le projet.
• <project>/.cursor/hooks.json, auquel une entrée sessionStart est ajoutée. Vos propres entrées et clés y restent.
• <project>/.apothem/support/cursor/hooks/, les scripts de hooks, dans le projet.
• ~/.agents/skills/<name>/SKILL.md pour chaque skill et chaque commande Apothem, dans votre répertoire personnel.
• ~/.config/apothem/rules/ et ~/.config/apothem/templates/, dans votre répertoire personnel.

Le fichier de règles résume les disciplines et nomme ces dossiers, afin que le modèle puisse ouvrir un skill ou un fichier de règles lorsqu'une tâche l'exige.

Fichiers hors du projetCopy Anchor Link

L'installation écrit aussi les skills d'Apothem dans votre répertoire personnel, avant de modifier quoi que ce soit dans le projet :

Ces dossiers sont partagés. Ils ne sont pas propres au projet :

• Chaque projet dans lequel vous installez cursor, et chaque autre installation Apothem qui nomme ce dossier, utilise la même copie et écrit les mêmes fichiers, de sorte que l'ordre d'installation n'a pas d'importance. Plusieurs autres outils lisent aussi ~/.agents/skills/ ; le registre des environnements les liste.
• --project choisit le fichier de règles à écrire et le projet auquel l'installation appartient. Il ne change pas l'emplacement des skills.
• L'installation n'ajoute aucun fichier de skill ni de règle à votre dépôt. Le projet reçoit le fichier de règles, les fichiers de subagents dans .cursor/agents/, l'entrée de hook dans .cursor/hooks.json, plus le dossier .apothem/ que crée toute installation de projet, et qui contient aussi les scripts de hooks.
• Les dossiers du répertoire personnel sont écrits en premier. Si cela échoue, par exemple parce qu'un dossier du chemin est un lien qui sort de votre répertoire personnel (un lien qui reste à l'intérieur est suivi) ou ne peut pas être écrit, l'installation s'arrête avec l'erreur avant que quoi que ce soit ne change dans le projet.
• Un dossier de skill portant le nom d'un skill Apothem qu'Apothem n'a pas écrit est laissé tel quel, et l'installation affiche un avertissement qui le nomme. Renommez-le ou déplacez-le, puis exécutez apothem update. apothem verify échoue tant que ce nom est occupé.
• Les fichiers totalisent quelques mégaoctets.

L'installation affiche une note qui nomme les dossiers qu'elle écrit hors de --project, et --dry-run les liste.

SubagentsCopy Anchor Link

Cursor lit un subagent depuis un fichier Markdown dans <project>/.cursor/agents/, selon la documentation des subagents de Cursor. L'installation écrit un fichier par auxiliaire Apothem dans ce dossier. Elle installe pour le projet uniquement et n'écrit aucun dossier ~/.cursor/agents/.

Chaque fichier conserve les instructions de l'auxiliaire inchangées et porte ces clés de frontmatter :

Cursor n'a aucune clé qui liste ou refuse des outils : un subagent hérite de tous les outils de son parent. La seule limite qu'il peut imposer est readonly: true, qui n'autorise aucune modification de fichier ni aucune commande shell qui modifie l'état. Les lignes tools et disallowedTools de l'auxiliaire ne sont donc pas écrites, et la limite ne survit que sous la forme de ce drapeau :

• Les cinq auxiliaires ci-dessus sont en lecture seule et n'ont pas de Bash ; ils reçoivent donc readonly: true et conservent la mention de lecture seule dans leurs descriptions.
• Sept auxiliaires sont en lecture seule mais exécutent des commandes (codebase-explorer, dependency-auditor, design-critic, prompt-evaluator, quality-gate, security-scanner et test-runner). readonly: true bloquerait aussi leurs exécutions de tests et de lint ; ils ne reçoivent donc aucun drapeau, et leurs descriptions perdent la mention de lecture seule que Cursor n'imposerait pas. Seule la description change : les instructions sont copiées sans modification, elles qualifient donc toujours l'auxiliaire de lecture seule et mentionnent une restriction d'outils qu'un fichier Cursor n'a pas. Le modèle suit ce texte, mais Cursor ne l'impose pas, et l'auxiliaire s'exécute avec tous les outils dont dispose le parent.
• mcp-builder et refactor-surgeon écrivent des fichiers et sont inchangés.

L'installation n'écrit aucune clé model, de sorte qu'un auxiliaire s'exécute sur le modèle qu'utilise le parent, ni is_background, ni limite de tours, ni les clés version, updated et portability d'Apothem.

À savoir :

• Les fichiers de subagents sont des fichiers de projet ordinaires. Commitez-les avec le projet ou listez .cursor/agents/ dans .gitignore ; Apothem ne choisit pas à votre place.
• Cursor charge aussi les dossiers d'auxiliaires écrits pour d'autres outils, parmi lesquels .claude/agents/ dans le projet et ~/.claude/agents/ dans votre répertoire personnel (le registre des environnements liste les autres). En cas de conflit de noms, le projet l'emporte sur le dossier personnel et .cursor/ l'emporte sur les autres ; dans un projet doté de cette installation, les fichiers natifs remplacent donc les copies Claude Code que Cursor importerait depuis ~/.claude/agents/. La documentation de Cursor ne dit pas s'il charge les deux copies ou écarte celle de rang inférieur, ni s'il applique les lignes tools et disallowedTools d'un fichier Claude Code qu'il importe.
• Un fichier à vous portant le nom d'un auxiliaire Apothem est enregistré sous ~/.apothem/backups/ puis remplacé. La désinstallation ne le remet pas en place. Les fichiers portant d'autres noms ne sont jamais touchés.
• Apothem n'a pas confirmé si Cursor lit les fichiers TOML qu'un autre outil écrit dans les dossiers qu'il importe, si le paramètre Third-Party Imports désactive ces dossiers importés, ni s'il lit des extensions autres que .md ou des dossiers imbriqués dans .cursor/agents/.

HooksCopy Anchor Link

Cursor exécute les hooks déclarés dans des fichiers hooks.json, selon la documentation des hooks de Cursor. L'installation ajoute une entrée à <project>/.cursor/hooks.json :

Le hook ajoute du contexte pour le modèle. Il ne bloque rien, et Cursor n'attend pas un hook sessionStart.

Cette première version n'enregistre rien d'autre. La documentation de Cursor liste aussi additional_context pour postToolUse, et Apothem y enregistrera le compteur de taille de contexte dès qu'une sonde montrera que le contexte atteint le modèle. Elle n'enregistre aucune garde preToolUse : Cursor ne documente agent_message, le champ par lequel une garde s'exprimerait, que pour une action qu'il refuse, et les gardes d'Apothem ne refusent jamais. Les gardes d'écriture, d'édition et de shell, la vérification AskUserQuestion et le protocole de fin de session restent sur les outils qui les transmettent.

Où vont les fichiers

hooks.json est votre fichier, et Cursor documente les hooks de projet comme versionnés. L'installation ajoute l'entrée d'Apothem après les vôtres et laisse vos entrées et autres clés telles quelles ; une mise à jour ne remplace que l'entrée dont la commande exécute le répartiteur d'Apothem (.apothem/support/cursor/hooks/dispatch.py avec --contract cursor, quel que soit le chemin de projet sous lequel il a été écrit), et une désinstallation ne supprime que cette entrée. Un hook à vous qui ne fait que partager le nom, comme tools/hooks/dispatch.py dans votre projet, ou qui exécute python -m apothem.conformity.gate, n'est jamais pris pour celui d'Apothem. La désinstallation supprime le fichier lorsque rien d'autre n'y subsiste, après en avoir enregistré une copie sous ~/.apothem/backups/. Un fichier contenant des commentaires, une virgule finale ou une valeur hooks de forme incorrecte ne peut pas être réécrit sans perte ; l'installation signale donc une erreur config.unparseable pour ce fichier, le laisse intact et s'arrête, en supprimant de nouveau les autres fichiers qu'elle avait commencé à écrire : corrigez le fichier, ou ajoutez vous-même l'entrée.

Le fichier versionné nomme votre machine. La commande de l'entrée contient l'interpréteur qu'Apothem a trouvé lors de son exécution et le chemin absolu du projet ; un coéquipier qui récupère le fichier obtient donc une commande qui pointe vers votre machine. Cursor signale comme en échec une commande qu'il ne trouve pas et la session continue ; rien ne casse, mais le hook n'y fait rien. Ne commitez le fichier que si votre équipe partage cette disposition. Cursor ne documente aucune variante non versionnée du fichier de hooks du projet. Le dossier .apothem/ est l'emplacement des scripts, et l'extrait .gitignore du projet le tient hors du contrôle de version.

Une commande ressemble à ceci, avec votre interpréteur et le chemin de votre projet à la place des deux chemins :

"/path/to/python" "/path/to/project/.apothem/support/cursor/hooks/dispatch.py" --contract cursor sessionStart

Sur un hôte Windows, la commande commence par & , l'opérateur d'appel de PowerShell, car l'application de bureau de Cursor exécute les commandes de hooks via PowerShell, où une ligne qui commence par un chemin de programme entre guillemets n'est pas un appel. sh lit un & initial comme une erreur de syntaxe ; aucun autre hôte ne le reçoit donc. La documentation nomme le shell mais pas la syntaxe de guillemets ; il s'agit donc de la lecture que fait Apothem de la syntaxe de PowerShell.

--contract cursor lit les champs conversation_id et workspace_roots de Cursor et répond avec {"additional_context": ...} et rien d'autre.

Chemins que le shell interpréterait mal. Un chemin de projet ou d'interpréteur qui contient $, un accent grave, un guillemet double ou une barre oblique inverse est refusé avant toute écriture : à l'intérieur de la commande entre guillemets, il exécuterait un autre fichier, ou casserait le JSON dans lequel la commande est écrite. L'erreur nomme le chemin ; déplacez ou renommez le projet et relancez l'installation. Une espace ou une apostrophe dans un chemin ne pose pas de problème.

Cursor exécute aussi les hooks écrits par Claude Code. Cursor charge les hooks de ~/.claude/settings.json, .claude/settings.json et .claude/settings.local.json tant que « Include Third-Party Plugins, Skills, and Other Configs » est activé (dans Cursor Settings, sous Third-Party Imports), ce qui est la valeur par défaut, et il exécute chaque hook correspondant de chaque source. Si vous avez aussi installé Apothem pour Claude Code, les deux ensembles de hooks peuvent s'exécuter. La commande sessionStart d'ici et sa copie Claude Code partagent un seul marqueur par session dans le dossier d'état des hooks d'Apothem ; celle qui s'exécute en second reste donc silencieuse et l'amorçage n'atteint le modèle qu'une fois ; Apothem reconnaît Cursor grâce aux variables CURSOR_PROJECT_DIR et CURSOR_VERSION que Cursor définit pour ses hooks. Le marqueur couvre dix secondes, de sorte qu'un démarrage ultérieur de la même session, comme une deuxième compaction, transmet quand même. Le compteur de taille de contexte de la copie Claude Code s'exécute en plus, et Apothem ne dédoublonne pas les compteurs. Pour n'exécuter que le hook d'ici, désactivez ce paramètre ; cela empêche aussi Cursor d'importer des plugins, skills et autres configurations tiers. L'installation l'affiche sous forme de note.

À savoir. Cursor recharge hooks.json lorsqu'il est enregistré ; aucun redémarrage n'est donc nécessaire. Les hooks de projet s'exécutent dans les espaces de travail de confiance. Le cloud de Cursor exécute les hooks de projet d'un dépôt mais diffère sessionStart ; l'entrée ne s'y déclenche donc pas. Définissez APOTHEM_HOOKS_DISABLE=1 dans l'environnement de Cursor pour rendre le hook Apothem silencieux.

Correspondance entre le profil et la configuration nativeCopy Anchor Link

L'adaptateur lit le profil partagé d'Apothem et rend le fichier de règles du projet à chaque exécution de apothem install ou de apothem update. Le profil partagé est la source de vérité ; les modifications locales au projet apportées au fichier généré sont sauvegardées avant que la synchronisation suivante ne remplace le contenu géré par Apothem.

Le fichier commence par son frontmatter YAML (description, globs, alwaysApply: true), car Cursor ne lit le type d'une règle que dans un frontmatter placé au début du fichier. Le bloc géré par Apothem le suit ; le texte que vous ajoutez après le bloc est conservé à chaque synchronisation.

Notes de compatibilitéCopy Anchor Link

Cursor 0.45+ prend en charge des instructions au niveau du projet via .cursor/rules/. L'adaptateur écrit par défaut dans le répertoire .cursor/rules/ de portée projet ; Cursor ne documente aucun chemin de règles globales utilisateur sous forme de fichiers que cet adaptateur pourrait gérer.

Cursor charge les skills depuis ~/.agents/skills/, de sorte que les skills qu'écrit l'installation apparaissent dans Cursor sans configuration supplémentaire. Cursor charge aussi ~/.claude/skills/ ; sur une machine qui dispose aussi d'une installation Claude Code, il peut donc lister deux fois les mêmes noms de skills, et sa documentation ne dit pas quelle copie l'emporte. Apothem n'a pas confirmé comment Cursor traite une clé d'en-tête de SKILL.md qu'il ne liste pas ; les skills portent user-invocable, disable-model-invocation, allowed-tools, argument-hint, et une table metadata.

VérificationCopy Anchor Link

apothem verify --harness cursor --project /path/to/project

La commande verify confirme que :

1. La configuration native existe au chemin attendu.
2. Chaque cible gérée existe, y compris le dossier .cursor/agents/ et le fichier de hooks .cursor/hooks.json ; les fichiers gérés ne sont pas vides, et les configurations JSON ou YAML s'analysent correctement. Le fichier de hooks doit contenir une entrée qui exécute le répartiteur d'Apothem (la vérification ne l'exécute pas), de sorte qu'un fichier rétabli ou vidé ne passe plus la vérification. Ajoutez --profile PATH pour vérifier en plus que les fichiers installés correspondent à ce profil. Pour .cursor/agents/, la vérification porte sur l'existence du dossier, et non sur la présence de chaque fichier d'auxiliaire ; la commande apothem diff --harness cursor --project /path/to/project liste les fichiers d'auxiliaires manquants ou obsolètes.
3. Chaque dossier de skill Apothem est en place avec un SKILL.md, quelle que soit l'installation qui l'a écrit, et aucun dossier de skill portant un nom Apothem n'appartient à quelque chose qu'Apothem n'a pas écrit. Une vérification en échec nomme les dossiers manquants ou étrangers.
4. La routine de vérification propre à l'adaptateur signale un succès.

Mise à jourCopy Anchor Link

apothem update --harness cursor --project /path/to/project

Redérive le fichier de règles du projet à partir de l'état actuel du profil partagé.

La mise à jour réécrit aussi tout dossier de skill dont les fichiers diffèrent des fichiers actuels. Si vous avez installé avec une version antérieure qui n'écrivait aucun skill, la mise à jour les ajoute. Elle réécrit les fichiers de subagents qui diffèrent des fichiers actuels, et ajoute ceux qui manquent. Elle actualise aussi les scripts de hooks et l'entrée Apothem de .cursor/hooks.json, sans toucher à vos propres entrées.

DésinstallationCopy Anchor Link

apothem uninstall --harness cursor --project /path/to/project

Supprime le bloc Apothem, ainsi que le frontmatter qu'Apothem a écrit au-dessus de lui, de <project>/.cursor/rules/apothem-rules.mdc et conserve tout autre texte qui s'y trouve. Le fichier n'est supprimé que lorsqu'il n'y reste plus rien d'autre. Avant la modification, une copie horodatée du fichier est enregistrée sous ~/.apothem/backups/ ; aucun fichier de sauvegarde n'est laissé dans le projet. Le YAML du profil partagé et le moteur Apothem ne sont pas affectés.

La désinstallation supprime aussi les fichiers de subagents qu'elle a écrits dans <project>/.cursor/agents/ et conserve tout autre fichier qui s'y trouve ; le dossier est supprimé lorsqu'il reste vide. Elle supprime l'entrée Apothem de <project>/.cursor/hooks.json, en la reconnaissant au chemin du répartiteur dans sa commande, et conserve vos propres entrées et clés. Le fichier n'est supprimé que si rien d'autre n'y subsiste. Les scripts de hooks de <project>/.apothem/support/cursor/hooks/ sont supprimés aussi. Si un fichier contient des commentaires que la désinstallation ne peut pas lire, elle laisse ce fichier tel quel et signale l'entrée comme ignorée, avec la raison ; supprimez l'entrée Apothem à la main. Elle supprime les dossiers de skills qu'elle a écrits dans ~/.agents/skills/ ainsi que les règles et templates de ~/.config/apothem/, mais seulement si aucune autre installation Apothem ne les utilise encore. Un autre projet, ou un autre outil qui partage le dossier, peut les utiliser. Dans ce cas, la désinstallation conserve les dossiers, affiche quelle installation les utilise, et la dernière désinstallation les supprime. Les fichiers que vous avez ajoutés à ces dossiers restent, et un dossier laissé vide est supprimé. Chaque dossier est sauvegardé sous ~/.apothem/backups/ avant d'être supprimé.

Portail de conformitéCopy Anchor Link

python -m apothem.conformity.gate --all .

DépannageCopy Anchor Link

Paramètres de configurationCopy Anchor Link

Voir aussiCopy Anchor Link

• Tous les environnements — le catalogue complet des outils pris en charge
• Guide d'installation — installer Apothem dans cet environnement
• Référence de apothem harnesses — lister et inspecter les adaptateurs depuis la CLI