Astuces, raccourcis et angles cachés 2026+

Archive de conception. Cette page raconte ce qui etait vise le jour ou elle a ete ecrite, pas l'etat du code aujourd'hui. Ce qui a ete livre depuis est recense dans le README.

← retour au README

11. Astuces, raccourcis et angles cachés 2026+

Section dense : ce que j'ai trop peu couvert dans le plan principal et qui peut faire la différence entre « ça marche » et « ça impressionne ». Chaque item est un angle à intégrer (pas un lot séparé).

Couche de connaissance : au-delà de Shopify

• Outils BoostEcom internes : @Atlas doit savoir lire Task[], StoreReport[], StoreNote[], ThemeVersion[] et l'historique Conversation[]. Pas seulement Shopify : la mémoire interne de la plateforme aussi.
• Connaissance partagée entre boutiques : si l'organisation a 5 boutiques, @Atlas apprend des patterns d'une boutique et les propose aux autres (« tu as résolu X sur la boutique A, veux-tu l'appliquer à la boutique B ? »).
• Mémoire épinglée par boutique : préférences de marque, ton, contraintes, « ne touche jamais à X ». Stockée via agent-memory (règle globale), scopes local + project.
• Extraction de l'ADN de marque : depuis le thème actuel, extraire automatiquement palette OKLch / typographie / ton → injectés dans le contexte d'@Atlas pour toute génération.

Filets de sécurité du thème

• Theme Check avant commit : bloquer themeFilesUpsert si le Theme Check officiel de Shopify échoue avec une sévérité error. @Atlas voit l'erreur et propose un correctif.
• Sauvegarde des fichiers de thème hors site : Vercel Blob ou S3, snapshot redondant en plus de Shopify. Plan de reprise si la custom app perd ses scopes.
• Rollback automatique sur régression de perf après publication : contrôle Lighthouse ou score Web Vitals 5 min après themePublish. Si chute > X %, notification + proposition de rollback.
• Validation de la syntaxe Liquid côté serveur avant push (parseur local léger, pas un Theme Check complet) : retour immédiat dans Monaco.
• Thème fantôme : un draft caché synchronisé avec le live, qui sert de base de référence pour les tests A/B + reprise rapide.

Garde-fous des agents

• Outils séparés lecture / action : shopify_list_pages (lecture pure, zéro friction) vs shopify_publish_theme (action, approbation par défaut via l'outil requestUserApproval).
• Politique d'agent immuable : @Atlas ne peut pas publier sans approbation, ne peut pas supprimer un thème, ne peut pas toucher au live (toujours via une branche). Encodé dans le prompt système + refus structuré au niveau de la définition de l'outil.
• Budget par tâche : « cette tâche ne doit pas dépasser $0.50 / 20 étapes / 60 s ». Plafond dur côté Workflow DevKit, via stopWhen.

Observabilité + suivi des coûts

• Tracer chaque appel d'outil : durée, succès/échec, coût AI Gateway, scope Shopify utilisé. Vercel Observability + logger structuré.
• Attribution des coûts à plusieurs niveaux : organisation / boutique / tâche / agent / conversation. Pour les plafonds utilisateur (déjà en place côté Stripe) + le reporting interne (« @Maya a coûté $12 ce mois-ci sur la boutique X »).
• Détection d'anomalies : agent qui boucle, tâche bloquée depuis plus de N min, run de workflow qui expire → alerte cost-alerts.
• Rejeu / débogage par voyage dans le temps : Workflow DevKit permet un rejeu déterministe. Une UI pour rejouer un run d'agent étape par étape : crucial pour comprendre ce qu'@Atlas a fait quand le résultat est inattendu.

UX avancée de l'IDE

• Visionneuse de diff (essentielle) : côte à côte + en ligne. Pastilles « modifié / ajouté / supprimé » dans l'arbre de fichiers. Cmd+Shift+D pour ouvrir le diff de la branche courante par rapport au live.
• Analyse de dépendances / d'impact : si on modifie un snippet utilisé dans 5 templates, prévenir avec la liste des templates touchés. Analyse statique du Liquid (parse de {% render '...' %}, {% include '...' %}, {% section '...' %}).
• Palette de commandes Cmd+Shift+P : ouvrir un fichier, changer de branche, lancer une tâche, interroger iRen, …
• Cmd+K = « interroger iRen sur ce code » en ligne (style Cursor). L'utilisateur sélectionne du Liquid, Cmd+K → @Atlas propose une modification avec un diff en ligne à accepter.
• Texte fantôme IA dans Monaco : comme Copilot, des suggestions en ligne pendant l'édition. Bonus V3.
• Source maps Liquid → Monaco : en cas d'erreur à l'exécution sur le storefront, lien direct vers le fichier source ouvert au bon endroit.

Preview live : pour aller plus loin

• Cache CDN de Shopify : themeFilesUpsert n'invalide pas instantanément. Pattern : fetch(storefrontUrl + '?_cache_bust=' + version) ou attendre 2-5 s + rafraîchissement automatique de l'iframe.
• Panier, checkout, comptes clients : preview soumise à l'authentification Shopify. V1 = documenter la limite. V2 = cookie transmis pour une preview en tant qu'utilisateur connecté.
• App embeds : extensions de checkout, UI des comptes clients, preview via ?preview_extension_id= (dev Shopify).
• Preview multi-segment : bascule « Mobile US / Desktop EU » dans l'en-tête → l'iframe se rend à nouveau avec des en-têtes Accept-Language + un user agent simulés. Crucial pour les boutiques multilingues.
• Superposition de diff : surligner dans l'iframe les éléments du DOM qui ont changé entre 2 versions. Bonus V2.

Versionnage étendu (au-delà du thème)

• En V2, versionner aussi : pages CMS, blogs, articles, descriptions de produits, menus de navigation. Quand @Atlas modifie un titre de produit → snapshot.
• Fork du Workspace = « cloner cette boutique en draft » : duplique tout (thème, pages, réglages, produits selon les scopes) vers une nouvelle boutique de développement pour un test A/B du BFCM. Pattern « fork » de v0.
• Storyboard : une séquence de versions vers un objectif (3 itérations du hero BFCM), visualisable comme une branche.

Collaboration en temps réel

• V1 : verrou optimiste + avertissement : « @Maya travaille sur cette branche, tes modifications entreront en conflit ». Rien de bloquant.
• V2 : présence : avatars à la Figma en haut du worktree.
• V3 : OT/CRDT : édition simultanée fluide. Yjs + binding Monaco (mature, open source).
• Flux de demande de changement : pour les organisations à plusieurs membres, l'utilisateur A propose, l'utilisateur B (admin) approuve avant themePublish.

Performance / bundle

• Chargement différé du chat @Atlas s'il n'est pas ouvert (frontière Suspense).
• Analyse différée du thème : les 200 fichiers ne se chargent pas tous, seulement l'arbre, puis à la demande au clic.
• Éditions hors ligne par Service Worker : mettre les modifications en file si Shopify est indisponible, réessayer au retour. Bonus V3.

Repli mobile

• Workspace = desktop uniquement (clarifié). Sur mobile :
  • Chat @Atlas seul (déjà responsive)
  • Vues en lecture seule des tâches, rapports et notes
  • CTA « Open Workspace on desktop » si l'utilisateur clique sur Worktree
• Pas d'IDE mobile : UX intenable.

Mode simple ou avancé

• Mode simple (par défaut pour les marchands non techniques) : pas d'IDE visible, seulement le chat + la preview. @Atlas propose un diff, l'utilisateur accepte → appliqué. Pas de fichiers, pas de Liquid.
• Mode avancé : IDE complet débloqué. Bascule dans les réglages de l'utilisateur (pas par boutique).
• Cf. v0, qui a aussi 2 modes (chat seul ou éditeur de code).

Webhooks Shopify pour une synchronisation bidirectionnelle

• Synchronisation inverse : si l'utilisateur édite directement dans l'admin Shopify, webhook → synchronisation dans BoostEcom (snapshot dans la branche courante, notification « modifications externes détectées »).
• Tâches déclenchées automatiquement : products/create → tâche « audit SEO du nouveau produit ». themes/publish (manuel, hors BoostEcom) → snapshot.
• Pattern : webhooks Shopify → route API → étape Workflow DevKit.

Tracking + analytics branchés automatiquement

• Quand l'utilisateur installe Datafast / GA4 / Klaviyo via la marketplace, @Atlas propose d'injecter automatiquement le tracking dans le thème (ajout de snippet, mise à jour des réglages).
• Optimisation automatique des assets : les images téléversées passent par /api/optimize (redimensionnement + WebP/AVIF) avant Shopify.
• Injection automatique de Schema.org : quand @Atlas crée une page produit, il injecte automatiquement le JSON-LD Product / Offer / AggregateRating.

Test A/B intégré : encapsuler Shopify Rollouts

Shopify Rollouts (Winter '26 Edition) = test A/B natif intégré à l'admin Shopify. Pas d'app, pas de script, gratuit. Duplication au niveau du thème + répartition du trafic.

Décision : encapsuler Rollouts au lieu de le réinventer.

• Notre modèle ThemeBranch s'y prête parfaitement : branch.publish() devient branch.publishAsRollout(trafficPct)
• UI déjà prête (badge de timeline → bouton « Test 50/50 » au lieu de « Publish »)
• Mesure de la conversion = lire les statistiques Rollouts via Admin GraphQL + Datafast

Limites de Rollouts (ce qu'on ne couvre pas) :

• Niveau thème uniquement (pas de prix, pas de réductions, pas de multivarié, pas de segmentation d'audience, pas d'intervalles de confiance)
• Pour du CRO sérieux, orienté marge : proposer l'intégration d'Intelligems / Shoplift via la marketplace, ne pas les concurrencer

Risque : l'API Rollouts est en accès anticipé ; l'encapsuler derrière une abstraction abTestProvider pour pouvoir en changer si besoin.

Fonctions de l'AI SDK 6 inutilisées (à activer)

• Prompt caching explicite (Anthropic) : prompt système + définition d'agent mis en cache → ~80 % d'économie sur les outils fréquents.
• Output.object() pour la sortie structurée au lieu de generateObject (legacy).
• Compaction de contexte automatique pour les sessions longues.
• AI Elements au complet : Message, MessageResponse, Citation, pas de <p>{text}</p> brut.
• Raisonnement multi-étapes visible dans l'UI via le streaming des appels d'outils (déjà partiel).

UI optimiste

• Appliquer le changement localement et instantanément dans Monaco + l'iframe, rollback si Shopify échoue. Pattern useOptimistic (React 19).

Mises à jour partielles de l'UI en streaming

• Au lieu de recharger toute la timeline des versions, diffuser la nouvelle version en SSE quand @Atlas termine son appel d'outil. L'UI l'ajoute en temps réel.

Transparence des prix et de la facturation

• Compteur de tokens en direct dans le workspace : coût en dollars en cours pour la conversation. Infobulle de détail (modèle utilisé, tokens en entrée/sortie).
• Pause automatique quand le plafond est dépassé : @Atlas explique avec tact, propose un passage à l'offre supérieure ou le BYOK.
• Repli BYOK : si les crédits BoostEcom sont épuisés et qu'un BYOK est configuré, bascule automatique sur la clé de l'utilisateur (déjà pris en charge par AI Gateway).

Flux d'activité entre boutiques

• Flux unifié : « ce que les agents ont fait la semaine dernière sur toutes mes boutiques ». Affiché dans la vue d'ensemble /[orgSlug].

Application du budget de performance

• Alerte si une modification augmente le LCP au-delà d'un seuil (mesuré via Lighthouse sur le proxy).
• Publication bloquée si le score de perf chute de plus de 10 % sans approbation explicite.

Agents installables depuis la marketplace

• Système de plug-ins : un agent tiers (depuis la marketplace /marketplace/skills ou /marketplace/mcp) peut s'ajouter au workspace comme spécialiste supplémentaire.
• Pattern : serveur MCP externe + descripteur de skill → installation via les réglages de la boutique.

13. AGENTS.md du dépôt (à créer)

Standard officiel sous l'égide de la Linux Foundation (Agentic AI Foundation), adopté par plus de 60 000 dépôts (dont OpenAI, Apache Airflow, Temporal), et reconnu par tous les grands agents IA : Codex, Cursor, Gemini CLI, Windsurf, GitHub Copilot, Aider, Jules, Factory, Amp, l'agent de VS Code.

État au 27 août 2026. AGENTS.md existe à la racine : cette section décrit un plan qui a été exécuté, et le paragraphe ci-dessous a été corrigé sur un point, parce qu'il donnait la consigne inverse de CLAUDE.md sur le même sujet (item inbox/0062). Un répertoire de règles sous le HOME n'est la source de vérité de rien dans ce dépôt : il est injoignable depuis un clone, depuis la CI et depuis tout agent. Ce qui fait autorité est ce que le dépôt contient : CLAUDE.md, les CLAUDE.md locaux, et AGENTS.md.

Fichier à la racine du dépôt qui informe les agents IA externes des conventions de build / test / lint / style de code. Markdown simple, sans frontmatter, sections libres.

Rôle : résumé compact à la racine pour les agents externes, et source consultable par quiconque clone le dépôt.

Contre la dérive : le risque reste réel si la même règle est écrite à deux endroits du dépôt. La réponse retenue ailleurs (scripts/check-doc-claims.mjs) est de dériver le chiffre ou la liste plutôt que de les recopier.

Contenu suggéré pour AGENTS.md

# AGENTS.md — BoostEcom Platform

## Commands
- Install : `pnpm install`
- Dev : `pnpm dev` (Next 16 / Turbopack, port 3000)
- Typecheck : `NODE_OPTIONS=--max-old-space-size=8192 pnpm typecheck`
- Build : `NODE_OPTIONS=--max-old-space-size=8192 pnpm build`
- DB push : `pnpm db:push`

## Code style
- TypeScript strict, jamais `any` (utiliser `unknown`)
- File names : kebab-case
- Components : PascalCase identifiers, kebab-case files
- Imports absolus avec `@/`
- Server Components par défaut, `"use client"` uniquement si nécessaire
- Tailwind 4 (OKLch tokens)
- Aucun emoji dans les fichiers (sauf si demandé)

## Architecture
- Mono-repo plat depuis avril 2026 (pas de workspaces)
- Source dans `src/` au root
- Prisma dans `prisma/schema.prisma`
- Routes Next.js App Router

## Testing
- (à compléter — pas de framework actuellement, à ajouter avec Vitest)

## SEO/GEO surface
- Helpers centralisés dans `src/lib/seo/`
- buildMarketingMetadata pour toute nouvelle page marketing
- JsonLd component pour structured data

## AI / Agents
- Stack : Vercel AI SDK v6 + AI Gateway + Workflow DevKit
- Agents définis dans `src/features/ai/agents/`
- Tools Shopify dans `src/features/shopify/mcp/`
- Models : opus-4-7 (lead), opus-4-7 (subagents), haiku-4-5 (cheap)

## Don't
- ❌ Jamais REST Admin API Shopify (legacy depuis 2024-10) — GraphQL only
- ❌ Jamais d'i18n nouvelle dans les pages marketing récentes (anglais
  hardcoded, à i18ner plus tard si besoin)
- ❌ Jamais de couleurs Tailwind statiques (`bg-gray-*`) dans les
  composants pages — préférer tokens shadcn (bg-muted, bg-card, etc.)
- ❌ Jamais publish theme sans approval explicite user

À créer dans la prochaine session : pas critique pour la V1, mais accélère les itérations des agents IA sur le dépôt.

Suivant : migration-rollout.md