Comment empêcher Claude Code ou Cursor de casser l'architecture d'un monorepo ?
Tout dépend de votre capacité à donner à l'agent le même contexte qu'un ingénieur senior : des contrats d'architecture lisibles par machine (AGENTS.md plus les docs-miroir .ai/ qui consignent les frontières de chaque package), des playbooks de tâches sous .agents/skills/, un serveur MCP (@supastack/mcp) qui laisse l'agent inspecter le dépôt via des outils structurés plutôt que de deviner des greps, et un gate de tests déterministe de 693+ tests — sans identifiants — qui doit passer avant toute revue. supastack pré-câble les quatre couches.
Le mur des dix mille lignes que rencontre tout utilisateur d'agent
Les 5 000 premières lignes avec Claude Code ou Cursor semblent magiques. Puis le dépôt devient trop grand pour que l'agent le voie entier — et les échecs cessent de ressembler à des coquilles : il réimplémente un utilitaire qui existe deux packages plus loin ; il ajoute une requête qui oublie workspaceId ; il « répare » un handler de webhook et supprime la vérification d'idempotence qui vous avait coûté un week-end.
C'est un échec de contexte, pas de capacité. Un ingénieur senior ne marche pas dans ces fissures parce qu'il porte l'architecture dans sa tête : quel package possède quoi, quelles invariants sont porteuses, ce que les tests promettent. L'agent y marche parce que personne ne l'a écrit pour lui.
Couche un : un contrat écrit que l'agent peut lire
supastack traite le contexte pour agents comme un artefact de premier ordre. AGENTS.md à la racine consigne le contrat d'architecture — ce que chaque package possède, ce que le gate de tests exige, quels motifs sont interdits. .ai/PROJECT_CONTEXT.md enregistre l'état courant et le raisonnement derrière les décisions, et les docs-miroir par fichier font voyager le contexte avec le code au lieu de pourrir dans un wiki.
Au-dessus, ~29 playbooks de tâches sous .agents/skills/ — ajouter une feature web, modifier le schéma de base, brancher un prestataire de paiement, vérifier un changement — font exécuter à l'agent les propres procédures du dépôt au lieu d'improviser.
your-saas/
AGENTS.md architecture contract every agent reads first
.ai/
PROJECT_CONTEXT.md current state, decisions, ship status
apps/web/src/... per-file mirror docs that travel with code
.agents/skills/ ~29 task playbooks for agent workflows
packages/mcp/ MCP server: structured repo access for agentsCouche deux : @supastack/mcp donne aux agents un accès structuré au dépôt
Sans outillage, l'exploration d'un monorepo de 700 fichiers par un agent se résume à : greper, lire les mauvais fichiers, deviner. @supastack/mcp est un vrai serveur Model Context Protocol construit sur @modelcontextprotocol/sdk et le runtime d'outils @supastack/agents — il expose le dépôt aux agents compatibles MCP (Claude Code, Cursor, Devin, Windsurf) via des outils structurés, des ressources documentaires et des prompts prêts.
La différence se lit dans le taux d'échec. Un agent qui peut interroger « que exporte ce package » ou « qu'exige le gate de tests » via des outils typés cesse d'inventer des réponses à partir du fichier qu'il a ouvert par hasard. Notre article sur le starter kit pour agents de coding IA couvre le même workflow côté build.
Couche trois : le gate de tests déterministe que l'agent doit franchir
Des garde-fous sans application ne sont que des suggestions. supastack embarque 693+ tests automatisés avec des providers factices sans identifiants pour la facturation, l'auth, l'email et le stockage — le chemin en or complet, inscription, webhook de paiement, attribution d'entitlement, invitation d'équipe, se vérifie localement en quelques secondes.
La boucle qui rend un agent sûr est banale : l'agent écrit le diff, lance le gate, lit l'échec et se corrige — tout cela avant la revue humaine. Le skill verify-changes du dépôt lui indique quels checks lancer selon le type de changement ; « l'agent a cassé la facturation » devient « l'agent l'a attrapé lui-même ».
| Mode d'échec | Dépôt sans garde-fous | Avec les garde-fous supastack |
|---|---|---|
| L'agent réimplémente du code existant | Découvert en revue — peut-être | Les frontières de packages dans AGENTS.md + miroirs .ai/ préviennent |
| Vérif de tenant silencieusement supprimée | Explose en production | Règles workspace écrites et couvertes par les tests |
| Régression de webhook | Révélée par un incident de paiement | Ledger webhook idempotent figé par des tests de replay |
| Exploration du dépôt | Grep et devinettes | Outils @supastack/mcp + ressources doc |
| Vérification | L'agent déclare « terminé » | Gate de 693+ tests obligatoire avant revue |
Pourquoi les garde-fous font boule de neige sur le travail client
Pour une agence, le calcul est direct : chaque dépôt client hérite du même contrat, donc un nouvel agent sur un nouveau projet est productif dès la première heure au lieu d'apprendre les frontières en les cassant. C'est la différence entre vendre de la vitesse d'agent et vendre du nettoyage d'agent.
Les trois paliers du kit correspondent à ce que les agences achètent réellement — Starter à $199 pour les projets mono-surface, Full Bundle à $299 pour toutes les surfaces avec 3 sièges, Agency à $799 avec 10 sièges — et chaque palier autorise des projets clients commerciaux illimités. Comparez sur la page tarifaire.
FAQ : agents de coding IA sur de vrais monorepos
Les questions que posent les équipes avant de confier une codebase de production à des agents :
- Avec quels agents ces garde-fous fonctionnent-ils ?, Avec tout agent capable de lire du Markdown — Claude Code, Cursor, Windsurf, Copilot, Devin. Les clients compatibles MCP obtiennent en plus des outils structurés via
@supastack/mcp; les docs .ai/ et les skills sont eux-mêmes agnostiques. - AGENTS.md seul ne suffit pas ?, Ça aide, mais un fichier unique pourrit. La combinaison qui tient : contrat (AGENTS.md) + mémoire (miroirs .ai/) + procédures (Agent Skills) + vérification (gate de tests) — il ne faut qu'une couche manquante pour fuiter.
- Quelle est la taille réelle de la suite de tests ?, 693+ tests automatisés couvrant idempotence de facturation, auth de session, isolation de workspace, clés API et packages orientés agents — tous exécutables sans identifiants réels.
- Peut-on ajouter ces garde-fous à un dépôt existant ?, Oui — comptez environ deux semaines d'écriture soignée plus un serveur MCP maison. Le kit est le raccourci : contrat, skills, serveur MCP et tests sont déjà alignés entre eux.