Caliber : générer et garder à jour les fichiers de contexte de vos agents

Le problème visé : un CLAUDE.md qui ment

Le README ouvre sur une constatation simple : un fichier CLAUDE.md écrit à la main devient faux dès le premier refactoring. L'agent continue alors de citer des chemins disparus, ignore les dépendances ajoutées et raisonne sur une architecture qui n'existe plus. Le projet ne prétend pas améliorer le raisonnement du modèle. Il s'attaque à la couche documentaire que l'agent lit avant de travailler, et il la traite comme un artefact de build plutôt que comme une note rédigée une fois pour toutes. Le public visé est une équipe où plusieurs personnes utilisent des agents différents sur le même dépôt : Claude Code pour l'une, Cursor pour l'autre, Codex ou Copilot pour une troisième. Sans outil, chacun entretient son propre fichier et les versions divergent. Caliber prend en charge cette divergence en générant les formats propres à chaque plateforme depuis une même analyse du code.

Audit déterministe, pas de LLM dans la boucle de notation

Le README décrit un score sur 100 réparti en six postes : FILES & SETUP sur 25, QUALITY sur 25, GROUNDING sur 20, ACCURACY sur 15, FRESHNESS sur 10 et BONUS sur 5. La notation est présentée comme déterministe, sans appel LLM ni appel API. Le mécanisme consiste à confronter les fichiers de configuration au système de fichiers réel du projet : les chemins cités existent-ils, les blocs de code sont-ils présents, la configuration a-t-elle dérivé depuis le dernier commit. C'est le choix de conception le plus intéressant du projet, et aussi le plus limité. Un audit qui vérifie l'existence des chemins et la fraîcheur ne dit rien de la justesse d'une consigne d'architecture. Un CLAUDE.md peut citer des fichiers réels, être à jour, et décrire une convention que l'équipe n'applique plus. Le score mesure la cohérence entre la documentation et l'arborescence, pas la qualité du contenu. La commande caliber score --compare main permet de voir l'effet d'une branche sur ce score, ce qui en fait un indicateur de dérive plus qu'un indicateur de qualité.

Le flux : bootstrap, skill, refresh

Le README détaille une boucle en trois temps. D'abord npx @rely-ai/caliber bootstrap, décrit comme une opération locale d'environ deux secondes, sans appel LLM et sans envoi de code. Ce bootstrap installe une skill /setup-caliber que l'agent exécute ensuite depuis une session CLI, pas depuis une fenêtre de chat IDE. L'agent analyse la pile technique, les frameworks, les dépendances et l'architecture, puis génère les configurations et installe les hooks. Ensuite vient la partie continue : les hooks pre-commit déclenchent caliber refresh, qui régénère les fichiers quand le code évolue. Les artefacts produits varient selon la cible. Pour Claude Code : CLAUDE.md, CALIBER_LEARNINGS.md, .claude/skills/*/SKILL.md au format OpenSkills, .mcp.json et .claude/settings.json. Pour Cursor : .cursor/rules/*.mdc avec frontmatter, .cursor/skills/*/SKILL.md et .cursor/mcp.json. Pour Codex : AGENTS.md et .agents/skills/*/SKILL.md. Pour OpenCode : AGENTS.md, partagé avec Codex quand les deux sont ciblés, et .opencode/skills/*/SKILL.md. Pour Copilot : .github/copilot-instructions.md. La détection MCP est décrite comme automatique, ce qui signifie que la liste des serveurs déclarés dans vos fichiers de configuration devient elle aussi un artefact généré.

Écrire sans écraser : diff, sauvegarde, undo

Le projet insiste sur un point : rien n'est écrasé sans confirmation. La séquence annoncée est audit, proposition sous forme de diff, revue avec possibilité d'accepter, d'affiner par échange ou de refuser chaque changement, sauvegarde des originaux dans .caliber/backups/ avant toute écriture, puis caliber undo pour revenir à l'état précédent. Un cas particulier est documenté : si la configuration existante dépasse 95 de score, Caliber saute la régénération complète et applique des correctifs ciblés sur les vérifications en échec. C'est un comportement raisonnable, mais il crée une asymétrie. Sur un dépôt déjà bien noté, vous ne verrez pas de réécriture complète et il devient plus difficile de juger ce que l'outil aurait produit ailleurs. Le dossier .caliber/backups/ s'accumule au fil des commits, et le README ne précise pas de politique de purge. À vérifier avant de laisser les hooks tourner en continu sur une longue période.

Mise en route et clés de configuration

La contrainte de version est explicite : Node.js >= 20. La commande d'amorçage est npx @rely-ai/caliber bootstrap. Si vous n'utilisez ni Claude Code ni Cursor, le README propose caliber init, présenté comme le même paramétrage sous forme d'assistant CLI, compatible avec un fournisseur LLM au choix en apportant sa propre clé Anthropic, OpenAI, MiniMax ou Vertex AI. L'audit se lance avec caliber score, et la comparaison entre branches avec caliber score --compare main. Le retour arrière se fait avec caliber undo. Sur Windows, trois points sont documentés. Il faut lancer les commandes depuis un terminal et non depuis une fenêtre de chat IDE. Git Bash est recommandé, car les hooks pre-commit et les scripts d'auto-synchronisation utilisent de la syntaxe shell, et le README avertit que sous PowerShell seul les hooks peuvent être ignorés silencieusement. Enfin, une seule session de terminal à la fois : plusieurs instances simultanées peuvent produire un état contradictoire et une détection de fournisseur inattendue. Cette dernière remarque est un signe que l'outil maintient un état local partagé, ce que le README ne détaille pas davantage.

Les limites que le README ne cache pas, et celles qu'il laisse ouvertes

La limite la plus concrète concerne Windows et l'avertissement sur les hooks ignorés en silence sous PowerShell. Un hook qui ne s'exécute pas ne produit pas d'erreur : vous croyez la synchronisation active alors qu'elle ne l'est plus. C'est un mode de défaillance silencieux, le plus coûteux qui soit pour un outil de maintenance. La deuxième limite tient au score lui-même, déjà évoquée : il mesure la cohérence, pas la pertinence. La troisième est le bruit de revue. Chaque commit peut produire un diff de configuration à relire, et la valeur du score ne dit pas si le changement est souhaitable. Sur un dépôt où les chemins bougent souvent, la revue peut devenir une corvée régulière. Enfin, le rythme de publication est dense : trois versions publiées le même jour, v1.53.3, v1.53.4 et v1.53.5, toutes le 26 juillet 2026. Cela indique un projet actif, et cela implique aussi que les fichiers générés peuvent changer de forme entre deux mises à jour. Le README ne décrit pas de mécanisme de compatibilité entre versions des artefacts générés.

Face à quoi : écrire ses propres règles à la main

L'alternative évidente n'est pas un autre outil, c'est le statu quo : un CLAUDE.md rédigé et relu par l'équipe, plus un .cursor/rules séparé, plus un AGENTS.md pour Codex. L'approche manuelle a un avantage réel que Caliber ne remplace pas : chaque phrase est un choix humain, et rien n'est généré à partir d'une heuristique de détection de pile technique. Elle a un coût tout aussi réel : la synchronisation entre plateformes repose sur la discipline, et personne ne détecte automatiquement qu'un chemin cité n'existe plus. La différence d'approche est nette. Caliber dérive la documentation depuis le dépôt et la rafraîchit à chaque commit, avec un score pour objectiver la dérive. La rédaction manuelle dérive la documentation depuis l'intention de l'équipe et la laisse vieillir jusqu'à ce qu'un agent se trompe visiblement. Le compromis est celui de tout artefact généré : vous gagnez la fraîcheur et l'uniformité entre agents, vous perdez le contrôle éditorial précis sur ce que lit le modèle.

Licence, maintenance et coût réel

Le dépôt est publié sous licence MIT, ce qui autorise la modification et la redistribution avec conservation de la notice de licence. Le README ne mentionne aucune clause supplémentaire, aucune limitation d'usage commercial et aucun service payant obligatoire. La génération utilise votre propre abonnement IA ou votre propre clé API, ce qui déplace la dépense hors de Caliber et vers votre fournisseur. Le coût de maintenance se situe ailleurs. Il faut suivre les publications, puisque trois correctifs sont sortis le même jour en juillet 2026, et vérifier après chaque mise à jour que les hooks pre-commit produisent toujours les mêmes fichiers. Il faut aussi décider qui relit les diffs de configuration dans une équipe, question que l'outil ne tranche pas. Le paquet est distribué sous le nom @rely-ai/caliber sur npm, tandis que le dépôt est référencé comme caliber-ai-org/ai-setup : cette différence de nom entre le paquet et le dépôt mérite d'être notée avant d'épingler une version dans un script d'installation.

Conclusion éditoriale

Caliber convient aux équipes qui font déjà tourner plusieurs agents sur un même dépôt et qui acceptent de relire des diffs de configuration à chaque commit. Il ne convient pas à un projet solo avec un seul agent, ni à une équipe sans droit d'écriture sur les hooks Git : le gain de synchronisation ne compense pas la surface ajoutée. Avant d'adopter, lancez npx @rely-ai/caliber bootstrap puis caliber score sur une branche jetable et vérifiez ce que les hooks pre-commit écrivent réellement dans .caliber/backups/.

Sources officielles

1. caliber-ai-org/ai-setup on GitHub
2. License: MIT
3. Project website
4. README
5. Releases