Rulesync : des règles communes pour Claude Code, Codex et Cursor

L'essentiel

Rulesync est une CLI qui conserve les règles du dépôt dans un seul répertoire, .rulesync/, et génère à partir de lui le fichier natif que lit chaque agent IA. Elle sert à ceux qui utilisent plus d'un agent sur le même projet et en ont assez de maintenir CLAUDE.md, AGENTS.md et .cursor/rules qui disent des choses différentes. La promesse affichée dans la documentation officielle est « Author rules once, generate everywhere », et les fichiers générés continuent de fonctionner même sans rulesync installé. Le tournant est conceptuel : une fois adopté, CLAUDE.md cesse d'être un endroit où l'on écrit et devient une sortie de build, comme un fichier compilé. Cela règle la divergence et crée un nouveau risque : lancer generate par-dessus des règles écrites à la main. Le chemin sûr consiste à importer l'existant avant de générer quoi que ce soit.

1. Le problème n'est pas d'avoir beaucoup d'agents, c'est d'avoir beaucoup de sources

Ceux qui livrent des systèmes ou des boutiques à des clients utilisent rarement un seul agent. Claude Code dans le terminal, Codex CLI dans un autre onglet, Cursor pour relire le diff, OpenCode sur un serveur. Chacun lit un fichier différent par défaut.

Claude Code charge ./CLAUDE.md ou ./.claude/CLAUDE.md comme instructions de projet. Cursor lit .cursor/rules dans des fichiers .mdc, et un .md déposé dans ce dossier est ignoré par le système de règles, faute de frontmatter pour déclarer description, globs et alwaysApply. OpenCode lit AGENTS.md à la racine et accepte des fichiers supplémentaires listés dans le champ instructions de opencode.json. Codex conserve la configuration dans ~/.codex/config.toml et accepte une surcharge par projet dans .codex/config.toml, chargée uniquement dans un projet marqué comme fiable.

Quatre endroits, quatre formats. En pratique : la norme de stack est dans CLAUDE.md, la convention de branche dans .cursor/rules, l'étape de déploiement dans AGENTS.md et le dossier que personne ne doit toucher n'est nulle part. Quand un agent travaille avec la moitié du contexte, c'est le code du client qui paie.

AGENTS.md a réduit une partie de la confusion : c'est un format ouvert, utilisé par plus de 60 000 projets open source, et sa précédence est simple, le fichier le plus proche du fichier modifié l'emporte. Mais il ne couvre ni .cursor/rules ni la configuration MCP, les hooks et les permissions.

2. Ce que fait rulesync (et ce qu'il n'est pas)

Rulesync inverse le sens : vous écrivez dans .rulesync/, lancez une commande et il écrit le fichier natif de chaque outil. Le README officiel décrit une CLI Node.js qui génère la configuration de plusieurs outils d'IA à partir de fichiers de règles unifiés, couvrant rules, commands, MCP, subagents et skills. Licence MIT.

Trois choses qu'il n'est pas :

• Ce n'est pas du MCP. MCP est le protocole qui relie l'agent à un outil externe, et il a déjà son propre article : MCP dans Claude Code et Cursor. Rulesync écrit seulement le fichier de configuration MCP de chaque outil à partir d'une source unique.
• Ce n'est pas un runtime. Il s'exécute, écrit des fichiers et s'arrête.
• Ce n'est pas une garantie de comportement. Ce qu'il synchronise, c'est du texte de contexte. La section 8 y revient.

L'avantage apparaît le jour où vous changez la convention de commit : au lieu de modifier quatre fichiers et d'en oublier un, vous en modifiez un dans .rulesync/rules/ et lancez generate.

3. Installer, et lancer import avant tout generate

La documentation officielle liste trois voies : npm global, tap Homebrew ou binaire unique. npm est la plus directe.

npm install -g rulesync
rulesync --version

Le tap Homebrew vit dans le dépôt lui-même et n'a pas de préfixe homebrew-, il exige donc la forme à deux arguments brew tap <nome> <url> ; le raccourci sans tap préalable ne fonctionne pas. Sur npm, le paquet porte une attestation de provenance, vérifiable avec npm audit signatures.

Maintenant, la partie qui sauve le dépôt. Si le projet a déjà un CLAUDE.md et un .cursorrules écrits à la main, ne lancez pas rulesync generate en premier. generate écrit les fichiers natifs à partir de .rulesync/, et avec un .rulesync/ vide, ce qui était écrit à la main peut être écrasé. Importez d'abord :

rulesync init
rulesync import --targets claudecode
rulesync import --targets cursor

init crée .rulesync/ avec des fichiers d'exemple et rulesync.jsonc, et la documentation indique qu'il n'écrase jamais les fichiers existants. Le rulesync.jsonc généré arrive déjà avec des targets égales à codexcli, claudecode et opencode. import fait l'inverse de generate : il lit le CLAUDE.md, le .cursorrules ou le .github/copilot-instructions.md existants et enregistre leur contenu dans .rulesync/.

Après l'import, vérifiez ce qui est entré avant toute autre chose :

git status
git diff --stat

Si l'import a ramené moins que prévu, complétez à la main dans .rulesync/rules/ avant de générer.

4. La première règle : du Markdown avec frontmatter

Une règle rulesync est un fichier Markdown dans .rulesync/rules/, avec un frontmatter YAML. Quatre clés comptent au départ : root, targets, description et globs. La règle racine (root: true) devient le fichier principal de chaque outil ; les autres deviennent des fichiers modulaires à l'endroit attendu par chaque outil.

---
root: true
targets: ["*"]
description: "Convenções do repositório"
globs: ["**/*"]
---

Sous le frontmatter vient le corps, en Markdown ordinaire. Mettez-y ce que vous répéteriez à un nouveau développeur le premier jour :

• La stack autorisée et ce qui est figé (la version du framework, le gestionnaire de paquets, si c'est pnpm et pas npm).
• Les conventions de commit et de branche, écrites sous forme d'exemples et non d'adjectifs.
• Les dossiers interdits : celui du build, celui des dépendances vendorisées, celui des fichiers générés par un autre processus.
• L'étape de déploiement et la commande de vérification qui la précède.

Le conseil d'écriture est cohérent d'une documentation à l'autre : une instruction précise fonctionne mieux qu'une instruction vague. Claude Code recommande moins de 200 lignes par CLAUDE.md, parce qu'un fichier long consomme du contexte et réduit l'adhésion. Cursor recommande de garder une règle sous 500 lignes et de découper une grande règle en règles composables.

Pour une règle qui ne vaut que pour une partie du code, utilisez globs. Une règle avec globs: ["src/api/**/*.ts"] est traduite par chaque cible dans le mécanisme dont elle dispose : paths dans Claude Code, globs dans le .mdc de Cursor, un frontmatter propre dans les autres.

Le détail de Cursor qui casse en silence

Dans Cursor, alwaysApply: true et globs ensemble forment un conflit sémantique : la documentation officielle indique que les globs sont ignorés quand l'option est activée, et certaines versions classent la règle selon le glob au lieu de l'appliquer toujours. Rulesync gère cela dans la traduction, mais connaissez le comportement : c'est une cause fréquente de « la règle est là et l'agent l'ignore ».

5. Générer pour plusieurs cibles d'un coup

La commande est generate, et ce qui décide où elle écrit, c'est --targets. La valeur est littérale : une erreur de nom casse l'exécution. Voici les valeurs vérifiées dans la référence officielle le jour de la lecture.

Source : Rulesync, pages Supported Tools et File Formats, consultées le 22/09/2026. La liste complète dépasse 40 outils et change souvent : vérifiez la valeur dans la référence avant de la figer dans un script.

rulesync generate --targets claudecode,codexcli,cursor --features rules
rulesync generate --targets "*" --features "*"

La première ligne génère seulement les règles, pour les trois cibles. La seconde génère tout pour toutes les cibles configurées. Commencez par la première. --features accepte rules, commands, subagents, skills, mcp, hooks, permissions et checks : activez-les une par une, plutôt que de découvrir dans le diff que permissions a réécrit un .codex/config.toml réglé à la main.

Avant d'écrire le moindre fichier, il existe la répétition générale :

rulesync generate --dry-run --targets claudecode --features rules
rulesync generate --check --targets "*" --features "*"

--dry-run montre ce qui changerait sans rien toucher. --check fait de même et sort avec le code 1 quand les fichiers ne sont pas à jour, ce qui permet de l'utiliser en CI.

L'ordre des cibles compte plus qu'il n'y paraît

Plusieurs outils lisent le même AGENTS.md : Codex CLI, OpenCode, Antigravity CLI, Grok CLI et Warp, entre autres. Dans un generate à plusieurs cibles, plus d'une écrit au même chemin, chacune avec sa propre sémantique. Rulesync ne fait le balayage des orphelins qu'après que toutes les cibles ont écrit, pour que l'une n'efface pas le fichier fraîchement écrit par l'autre. Malgré tout : après avoir généré, ouvrez AGENTS.md et lisez-le. Ne présumez rien.

6. Vérifier dans le git diff, et décider si le généré entre dans le dépôt

Après le premier generate, la vérification qui compte est le diff.

git diff --stat
git diff CLAUDE.md AGENTS.md
git diff .cursor/rules/

Cherchez trois choses : du contenu disparu (un paragraphe du CLAUDE.md manuel non importé), du contenu dupliqué (la même instruction venant de AGENTS.md et de la règle racine) et un fichier inattendu, comme un .codex/config.toml apparu parce que --features "*" a activé permissions.

Vient ensuite la décision de versionnement, binaire.

Versionner le généré est la voie pour une équipe. Qui clone reçoit des règles qui fonctionnent sans rien installer, ce qui correspond à la promesse de la documentation. Le coût est un diff plus bruyant dans chaque pull request et l'obligation de lancer rulesync generate --check en CI pour que le généré ne vieillisse pas en silence.

Ne pas versionner garde le dépôt propre : seul .rulesync/ entre dans git et generate devient une étape de setup. Il existe une commande prête :

rulesync gitignore --targets claudecode,cursor

Le coût est que qui clone sans lancer le setup travaille sans aucune règle. Réserve documentée : les fichiers partagés comme opencode.json, .claude/settings.json, .codex/config.toml et .vscode/settings.json n'entrent pas dans le .gitignore exprès, parce que vous y écrivez aussi vos propres réglages.

Pour un projet client, versionner a tendance à être le bon choix : le dépôt doit fonctionner entre les mains de celui qui le reprend, et celui qui le reprend ne lit pas la documentation de setup.

7. Mettre à jour l'outil sans mauvaise surprise

La version en cours à la lecture de la page, le 22/09/2026, est la 17.0.0, publiée le 21/09/2026. Elle apporte un changement incompatible propre à Codex CLI : les règles edit et write marquées ask ou deny génèrent désormais read au lieu de deny. Codex n'a pas d'état d'approbation d'écriture par chemin, donc les deux actions qui ne sont pas allow conservent la lecture sans l'écriture, avec un avertissement. Les notes de version demandent de revoir le .codex/config.toml régénéré si vous dépendiez de l'ancienne sortie.

Cela résume son mode de fonctionnement : l'outil évolue vite, avec des releases quasi quotidiennes, et suit ce que chaque agent change de son côté. Deux pratiques couvrent le risque : figer la version dans le projet au lieu d'installer toujours la plus récente, et lancer rulesync generate --dry-run après toute mise à jour.

8. La limite honnête : une règle aligne le contexte, elle n'oblige pas le modèle

C'est la partie que presque aucun tutoriel ne mentionne, et que la documentation officielle des outils dit sans détour.

Claude Code est direct : les instructions de mémoire sont traitées comme du contexte, pas comme une configuration imposée, et le contenu de CLAUDE.md est transmis comme message utilisateur après le prompt système, sans garantie de respect strict, surtout quand l'instruction est vague ou en contredit une autre. La recommandation de la page elle-même, pour ce qui doit toujours s'appliquer, est d'utiliser un hook PreToolUse, qui s'exécute quel que soit le choix du modèle. Cursor fait la réserve équivalente en parlant des règles d'équipe : l'orientation par l'IA ne doit pas être le seul contrôle de sécurité.

La conclusion opérationnelle répartit le travail en deux couches :

• Couche de contexte : conventions de nommage, style, architecture, où se trouvent les choses. Cela vit dans les règles, et rulesync règle la duplication.
• Couche d'imposition : ce qui ne doit jamais arriver. Cela vit dans les hooks, dans les permissions (permissions.deny dans Claude Code, sandbox_mode et politique d'approbation dans Codex), dans les tests et dans les règles de CI.

Si l'instruction est « ne déploie pas sans lancer les tests », ce n'est pas une règle de fichier, c'est un hook ou une étape de pipeline. Si c'est « un nouvel endpoint va dans src/api/handlers/ », alors oui, c'est une règle, et elle gagne à vivre en un seul endroit. Rulesync règle la divergence entre sources. Il ne règle pas, et ne promet pas de régler, l'obéissance du modèle.

Questions fréquentes

Dois-je remplacer mon CLAUDE.md par autre chose ?

Non. Il continue d'exister et d'être lu par Claude Code. Ce qui change, c'est qui écrit dedans : vous modifiez .rulesync/rules/ et generate réécrit CLAUDE.md. Si quelqu'un de l'équipe modifie CLAUDE.md directement, la modification disparaît au generate suivant, d'où l'intérêt d'un commentaire en tête indiquant qu'il est généré.

Peut-on l'utiliser avec un seul outil ?

Oui, et c'est sensé comme transition. Lancer seulement avec --targets claudecode permet déjà de garder un grand ensemble de règles organisé en fichiers séparés. Mais si vous utilisez un seul agent, le gain est faible : l'outil a été conçu pour plusieurs cibles.

Et les règles qui sont dans .cursor/rules depuis des mois ?

Lancez rulesync import --targets cursor avant le premier generate, vérifiez dans le git diff ce qui est entré dans .rulesync/ et seulement ensuite générez. Si l'import ne ramène pas tout, complétez à la main avant.

Cela remplace-t-il la configuration MCP dans chaque outil ?

En partie. Avec la feature mcp activée, il écrit la configuration MCP de chaque outil à partir d'une source unique. Ce qu'il ne fait pas, c'est la partie laborieuse : choisir le serveur, gérer les identifiants et diagnostiquer un serveur qui ne démarre pas. C'est le sujet de MCP dans Claude Code et Cursor.

Est-ce utile sur un VPS où l'agent tourne seul ?

Encore plus, parce que là personne ne corrige l'agent sur le moment. Mais une règle de fichier reste du contexte : sans supervision, ce qui protège, ce sont les permissions et les hooks, pas le texte. Pour faire tourner un agent sur un serveur : Claude Code 24/7 sur un VPS.

Conclusion

Rulesync est un outil ennuyeux, et c'est un compliment : il ne fait rien que vous ne pourriez faire à la main, il empêche seulement quatre fichiers de commencer à se contredire en silence. Le gain apparaît dans un dépôt qui passe entre plusieurs agents et plusieurs personnes, et le coût est faible, puisque l'outil est sous licence MIT et que le résultat continue de fonctionner même sans lui. Ce qui change vraiment, c'est la discipline : les règles s'écrivent dans .rulesync/, le fichier natif est un artefact, et le git diff est le test après chaque generate. Et ce qui doit toujours s'appliquer n'entre dans aucune règle, il va dans un hook, une permission ou un test.

Si ce dont vous avez besoin, c'est l'agent qui lit votre ERP, votre boutique ou votre base de données, c'est de l'intégration sur mesure (MCP, webhook, file d'attente). Décrivez le système et ce que vous voulez automatiser sur oailton.dev/fr/contato.