Guide pratique · E-commerce · SaaS · Finance · RH · Lecture : ~25 min Teste ton niveau sur modai-lab.com/test-sql/


Pourquoi ce guide existe

Tu as branché une IA sur ton warehouse. Claude, ChatGPT, un agent maison, peu importe. Tu lui poses une question simple : « Pourquoi le CA a chuté en février ? »

Elle te répond en 20 secondes, avec une requête SQL impeccable et une explication très convaincante : « Probablement un effet saisonnier post-fêtes. »

Sauf que non. Le 12 février, vous avez changé votre grille tarifaire. Le plan Starter est passé de 9 € à 12 €, et une partie des nouveaux clients a décroché. L'IA ne pouvait pas le savoir. Personne ne le lui a dit.

Le problème n'est pas le modèle. Les modèles écrivent du SQL syntaxiquement parfait. Le problème, c'est qu'ils arrivent dans ton entreprise comme un analyste brillant qu'on aurait lâché le premier jour sans onboarding :

  • Il ne sait pas quelle table est la bonne parmi orders, orders_v2 et orders_clean

  • Il ne sait pas que chez vous, un « client actif » c'est 30 jours et pas 90

  • Il ne sait pas que les comptes @test.com polluent la table users

  • Il ne sait pas ce qui s'est passé dans le business le mois dernier

Résultat : le SQL est juste, le chiffre est faux. Et c'est le pire scénario, parce que personne ne le voit.

La solution n'est pas un meilleur modèle. C'est une couche de contexte : quelques fichiers markdown, écrits par des humains, que l'IA lit avant de répondre.

Ce guide couvre :

  • Pourquoi une IA sans contexte se trompe (et pourquoi tu ne le vois pas)

  • Les 5 fichiers markdown à écrire, avec un modèle prêt à remplir pour chacun

  • Le dictionnaire des tables : grain, usage, tables interdites

  • Les définitions de métriques en texte : zéro ambiguïté

  • La timeline business : pour que l'IA explique un drop au lieu de l'inventer

  • Les règles de calcul critiques et les pièges connus

  • Le README qui dit à l'IA comment utiliser les 5 fichiers (sans lui, elle les lit mal)

  • Comment tester que ton contexte fonctionne vraiment

  • Un plan pour construire le kit en une semaine


🧪 Calibre ton niveau avant de commencer

Pour écrire un bon contexte, il faut toi-même savoir repérer quand une requête est fausse. Sais-tu identifier une jointure qui gonfle un CA, ou un AVG qui ignore silencieusement les NULL ? Fais le test en 5 minutes.

👉 Faire le test sur modai-lab.com/test-sql/

_Résultat en direct · Niveau calibré · Parcours personnalisé_


PARTIE 1 — Pourquoi ton IA se trompe sans que tu le voies

Le mécanisme

Quand tu poses une question à une IA connectée à ta base, voici ce qu'elle fait réellement :

  1. Elle lit la liste des tables et des colonnes disponibles

  2. Elle devine laquelle correspond à ta question, à partir des noms

  3. Elle devine la définition de ton KPI, à partir du sens commun

  4. Elle écrit une requête cohérente avec ses deux suppositions

  5. Elle invente une explication plausible si le résultat est surprenant

Les étapes 2, 3 et 5 sont des suppositions. Elles sont souvent bonnes. Mais quand elles sont fausses, le résultat a exactement la même tête qu'un résultat juste : une requête propre, un chiffre précis, une phrase assurée.

Le cas typique : la mauvaise table

-- ❌ Ce que l'IA écrit quand tu demandes « nombre de clients actifs ce mois-ci »
-- Elle voit une table `users` avec une colonne `last_login_at` : ça a l'air parfait
 
SELECT COUNT(*) AS clients_actifs
FROM users
WHERE last_login_at >= DATE_TRUNC(CURRENT_DATE(), MONTH);
 
-- Résultat : 18 420 clients actifs
-- Problèmes invisibles :
-- 1. `users` contient les comptes de test (@test.com, @modai-qa.com) : ~1 200 lignes
-- 2. Chez vous, « actif » = au moins une transaction, pas une connexion
-- 3. `last_login_at` n'est plus alimentée correctement depuis la migration de mai
-- Le vrai chiffre est 11 080 : celui-ci est surestimé de 66 %. Personne ne le saura.
kit-context-layer-ia · 01
-- ✅ Ce que l'IA écrit quand elle a lu ton dictionnaire et tes définitions
 
SELECT COUNT(DISTINCT t.user_id) AS clients_actifs
FROM transactions t
JOIN users u ON t.user_id = u.user_id
WHERE t.created_at >= DATE_TRUNC(CURRENT_DATE(), MONTH)
AND t.statut = 'validee'
AND u.is_test_account = FALSE; -- règle R1 de regles_calcul.md
 
-- Résultat : 11 080 clients actifs
-- Gain : la définition officielle (« au moins 1 transaction validée sur la période »)
-- est appliquée, les comptes de test sont exclus, la bonne table est utilisée.
kit-context-layer-ia · 02

Les deux requêtes sont syntaxiquement parfaites. Une seule est juste. Ce qui fait la différence, ce n'est pas le SQL, c'est le contexte.

Les 5 fichiers du kit

Fichier

Question à laquelle il répond

Erreur qu'il évite

dictionnaire_tables.md

Quelle table utiliser, à quel grain ?

Mauvaise table, doublons de jointure

definitions_metriques.md

Que veut dire ce KPI chez nous ?

Définition « sens commun » au lieu de la tienne

timeline_business.md

Que s'est-il passé et quand ?

Explication inventée d'un drop ou d'un pic

regles_calcul.md

Qu'est-ce qu'on exclut, toujours ?

Comptes de test, remboursements, devises

pieges_connus.md

Où sont les mines ?

Colonnes cassées, historiques trompeurs

Bonus : README_contexte.md

Comment utiliser les 5 autres ?

Fichiers lus à moitié, règles oubliées

Chaque fichier est un simple markdown. La partie 7 montre comment les brancher sur ton IA et lui dire dans quel ordre les lire. Le format compte moins que le contenu.

Comment lire les modèles. Pour illustrer, les exemples SQL passent d'un domaine à l'autre (e-commerce, SaaS, finance, RH) : le principe est le même partout. Les modèles, eux, sont remplis avec des exemples réalistes mais fictifs. Garde la structure, remplace tout le contenu par le tien. Un modèle recopié tel quel est pire que pas de modèle du tout : l'IA appliquerait des règles qui ne sont pas les tiennes.


PARTIE 2 — Le dictionnaire des tables

Ce que l'IA ne peut pas deviner

Les noms de tables mentent. orders_clean n'est pas forcément propre. customers et users sont peut-être deux choses différentes. fact_sales est peut-être dépréciée depuis 2024. L'IA, elle, va choisir sur le nom.

Le dictionnaire répond à trois questions pour chaque table importante :

  • Le grain : une ligne = quoi exactement ?

  • L'usage : pour quelles questions utiliser cette table ?

  • Le statut : table de référence, table technique, ou table à ne plus utiliser ?

Le grain est le point le plus important. C'est lui qui évite la jointure qui multiplie les lignes.

-- ❌ L'IA ne connaît pas le grain de order_items
-- Question : « CA par catégorie de produit en mars »
 
SELECT p.categorie, SUM(o.montant) AS ca
FROM orders o
JOIN order_items i ON o.order_id = i.order_id
JOIN products p ON i.product_id = p.product_id
WHERE o.created_at >= '2026-03-01' AND o.created_at < '2026-04-01'
GROUP BY p.categorie;
 
-- Commande 5012 : montant 150 €, 3 articles (2 Maison, 1 Déco)
-- -> comptée 2 fois en Maison (300 €) et 1 fois en Déco (150 €)
-- -> 450 € de CA pour une commande de 150 €
-- Total du mois : 1,9 M€ au lieu de 812 k€
kit-context-layer-ia · 03
-- ✅ Avec le dictionnaire : « le CA par catégorie se calcule au grain article,
-- sur order_items.prix_unitaire * quantite »
 
SELECT p.categorie, SUM(i.prix_unitaire * i.quantite) AS ca
FROM order_items i
JOIN orders o ON i.order_id = o.order_id
JOIN products p ON i.product_id = p.product_id
WHERE o.created_at >= '2026-03-01' AND o.created_at < '2026-04-01'
AND o.statut = 'livree'
GROUP BY p.categorie;
 
-- Commande 5012 : Maison = 2 × 50 € = 100 €, Déco = 1 × 50 € = 50 € -> total 150 €
-- Total du mois : 798 k€ de CA produits
-- Attention : ce total ne fera JAMAIS exactement orders.montant (812 k€).
-- Les frais de port (14 k€) existent au niveau commande, pas au niveau article.
-- C'est normal, à condition que ce soit écrit dans le dictionnaire.
kit-context-layer-ia · 04

Ce dernier point est typiquement ce qui manque dans la tête d'une IA, et dans celle d'un junior : deux chiffres « de CA » peuvent être justes tous les deux et ne pas être égaux. Si l'écart n'est pas documenté, quelqu'un passera une après-midi à le chercher. Ou pire, l'IA « corrigera » l'un pour qu'il colle à l'autre.

📘 Modèle : `dictionnaire_tables.md`

# Dictionnaire des tables
 
Dernière mise à jour : [date] · Responsable : [nom de l'équipe]
 
## Règle générale
- Toujours utiliser les tables du schéma `analytics`, jamais `raw` ni `staging`
- En cas de doute entre deux tables, utiliser celle marquée ✅ RÉFÉRENCE
 
---
 
## analytics.orders ✅ RÉFÉRENCE
- **Grain** : 1 ligne = 1 commande
- **Clé** : order_id (unique)
- **Usage** : CA, nombre de commandes, panier moyen, CA par client
- **Colonnes clés** :
- montant : montant TTC en euros, remises déduites, frais de port inclus
- statut : 'en_cours', 'livree', 'annulee', 'remboursee'
- created_at : date de création de la commande (UTC)
- **Ne pas utiliser pour** : CA par produit ou par catégorie (voir order_items)
 
## analytics.order_items ✅ RÉFÉRENCE
- **Grain** : 1 ligne = 1 article dans une commande
- **Clé** : order_id + line_number
- **Usage** : CA par produit, par catégorie, mix produit
- **Calcul** : prix_unitaire * quantite (hors frais de port)
- **Attention** : ne jamais sommer orders.montant après une jointure avec cette table
- **Écart connu** : SUM(order_items) < SUM(orders.montant) d'environ 2 % (frais de port)
 
## analytics.transactions ✅ RÉFÉRENCE
- **Grain** : 1 ligne = 1 transaction de paiement
- **Usage** : clients actifs, flux, montants moyens
- **Colonnes clés** : statut ('validee', 'refusee', 'remboursee'), devise, is_virement_interne
 
## analytics.users ✅ RÉFÉRENCE
- **Grain** : 1 ligne = 1 compte utilisateur
- **Usage** : inscriptions, cohortes, attributs clients
- **Attention** : contient des comptes de test et de démo (voir règle R1)
 
## analytics.subscriptions ✅ RÉFÉRENCE
- **Grain** : 1 ligne = 1 version d'un abonnement (historique, valid_from / valid_to)
- **Usage** : churn, évolution du MRR, upgrades
- **Attention** : un même subscription_id a plusieurs lignes. Pour l'état actuel,
utiliser subscriptions_current
 
## analytics.orders_v1 ⛔ DÉPRÉCIÉE
- Ancienne table, plus alimentée depuis le 2025-09-01
- Ne pas utiliser, même pour l'historique (utiliser orders, qui contient tout)
kit-context-layer-ia · 05

Cas business : le dictionnaire minimal d'un SaaS

Tu n'as pas besoin de documenter 200 tables. Commence par les 5 à 10 tables qui répondent à 80 % des questions. Pour un SaaS typique :

Table

Grain

Usage principal

subscriptions

1 ligne = 1 abonnement (historique complet)

MRR, churn, upgrades

subscriptions_current

1 ligne = 1 abonnement, état actuel

Photo du jour, MRR actuel

invoices

1 ligne = 1 facture

Revenu encaissé, impayés

events

1 ligne = 1 action utilisateur

Activation, usage produit

accounts

1 ligne = 1 entreprise cliente

Segmentation, taille client

La ligne subscriptions vs subscriptions_current vaut à elle seule une demi-journée de debug évitée. Sans elle, l'IA prend la table historique et compte chaque abonné autant de fois qu'il a changé de plan.


🧪 Entraîne-toi à lire le grain d'une table

Sur Modai Lab, les exercices sont construits sur des schémas multi-tables réalistes, où le piège de la jointure qui gonfle les montants est volontairement présent. C'est en le rencontrant que tu apprends à le documenter.

👉 Pratiquer sur modai-lab.com

_Schémas réalistes · Pièges de grain · Correction détaillée_


PARTIE 3 — Les définitions de métriques en texte

Le problème du « sens commun »

Demande à 5 personnes de ton entreprise ce qu'est un « client actif ». Tu auras 5 réponses :

  • Le marketing : quelqu'un qui a ouvert un email ce mois-ci

  • Le produit : quelqu'un qui s'est connecté dans les 30 derniers jours

  • La finance : quelqu'un qui a payé quelque chose ce mois-ci

  • Le support : quelqu'un qui a un abonnement non résilié

  • L'IA : ce qui lui semble le plus probable vu les colonnes disponibles

Si ta définition officielle n'est écrite nulle part, l'IA choisit. Et elle ne choisira pas forcément la même chose deux fois de suite.

L'objectif d'une définition écrite : deux personnes qui posent la même question doivent obtenir le même chiffre. Avec ou sans IA.

-- ❌ « Quel est notre taux de churn mensuel ? »
-- Sans définition, l'IA prend la plus simple
 
SELECT
COUNTIF(statut = 'resilie') / COUNT(*) AS taux_churn
FROM subscriptions_current;
 
-- Résultat : 23 %
-- Problèmes :
-- 1. Calcule un stock (tous les résiliés depuis toujours), pas un flux mensuel
-- 2. Le dénominateur inclut des abonnés arrivés après le début du mois
-- 3. Compte les essais gratuits non convertis comme du churn
kit-context-layer-ia · 06
-- ✅ Avec la définition écrite :
-- « Churn mensuel = abonnés payants actifs au 1er du mois M
-- qui ne sont plus payants au 1er du mois M+1.
-- Les essais gratuits sont exclus du numérateur et du dénominateur. »
 
WITH debut_mois AS (
SELECT DISTINCT subscription_id
FROM subscriptions
WHERE plan != 'trial'
AND statut = 'actif'
AND valid_from <= '2026-10-01' AND (valid_to > '2026-10-01' OR valid_to IS NULL)
),
debut_mois_suivant AS (
SELECT DISTINCT subscription_id
FROM subscriptions
WHERE plan != 'trial'
AND statut = 'actif'
AND valid_from <= '2026-11-01' AND (valid_to > '2026-11-01' OR valid_to IS NULL)
)
SELECT
COUNT(*) AS abonnes_debut,
COUNTIF(s.subscription_id IS NULL) AS abonnes_perdus,
ROUND( * COUNTIF(s.subscription_id IS NULL) / COUNT(*), ) AS churn_pct
FROM debut_mois d
LEFT JOIN debut_mois_suivant s
ON d.subscription_id = s.subscription_id;
 
-- Résultat : 4 820 | 183 | 3.8
-- Gain : un churn mensuel comparable d'un mois sur l'autre, identique
-- quel que soit l'outil ou la personne qui le calcule
kit-context-layer-ia · 07

Remarque bien : même cette version « propre » repose sur une hypothèse. Si chez toi un changement de plan crée un nouveau subscription_id, un client qui passe de Pro à Business sera compté comme churné. Ce genre de détail n'est dans aucune colonne. Il doit être écrit dans la définition, sinon l'IA (et ton collègue) se trompera en silence.

📏 Modèle : `definitions_metriques.md`

# Définitions des métriques
 
Règle : si une métrique n'est pas dans ce fichier, demander avant de la calculer.
 
---
 
## Client actif
- **Définition** : utilisateur ayant au moins 1 transaction validée sur la période
- **Période par défaut** : mois calendaire
- **Table** : analytics.transactions (statut = 'validee')
- **Exclusions** : règle R1 (comptes de test, démo, internes)
- **Ce que ce n'est PAS** : une connexion à l'app, un email ouvert
- **Requête de référence** : voir sql/clients_actifs.sql
 
## Chiffre d'affaires (CA)
- **Définition** : somme des montants TTC des commandes livrées, remboursements déduits
- **Devise** : euros (convertir avec analytics.fx_rates au taux du jour de commande)
- **Date de rattachement** : date de commande (created_at), pas date de livraison
- **Exclusions** : commandes annulées, commandes de test
- **Écart connu avec la finance** : la finance rattache au mois de facturation, écart < 2 %
 
## Panier moyen
- **Définition** : CA / nombre de commandes livrées
- **Attention** : jamais AVG(montant) sur une table jointe à order_items
 
## Churn mensuel
- **Définition** : abonnés payants au 1er du mois M qui ne sont plus payants au 1er de M+1
- **Exclusions** : essais gratuits (plan = 'trial'), règle R1
- **Grain** : abonnement (subscription_id), pas client
- **Cas limite** : un changement de plan garde le même subscription_id,
ce n'est donc pas du churn
- **Ce que ce n'est PAS** : le nombre de résiliations du mois (une résiliation
prend effet en fin de période payée)
kit-context-layer-ia · 08

Les 3 éléments qui rendent une définition utilisable par une IA

  1. La phrase métier : ce que ça veut dire, en français, sans SQL

  2. L'ancrage technique : quelle table, quelle colonne, quel filtre

  3. Le « ce que ce n'est PAS » : la confusion la plus fréquente, nommée explicitement

Le troisième point est le plus sous-estimé. L'IA, comme un junior, va spontanément vers l'interprétation la plus évidente. Nommer la mauvaise interprétation l'empêche d'y aller.


🧪 Vérifie que tu sais traduire une définition en SQL

Écrire « churn mensuel = abonnés payants au 1er du mois qui ne le sont plus au 1er du mois suivant », c'est facile. Le traduire en requête juste, avec un historique d'abonnements, c'est une autre affaire. Le test te dit où tu en es.

👉 Faire le test sur modai-lab.com/test-sql/

_5 minutes · Niveau calibré · Points faibles identifiés_


PARTIE 4 — La timeline business

Le fichier que presque personne n'écrit

C'est le fichier le plus rentable du kit, et le plus rare.

Ton warehouse contient les conséquences de ce qui s'est passé : une baisse de commandes, un pic d'inscriptions, un panier moyen qui bondit. Il ne contient jamais les causes : le changement de prix, la campagne TV, la panne du moyen de paiement, le concurrent qui a lancé une promo.

Quand tu demandes à l'IA « pourquoi ? », elle n'a que les conséquences. Alors elle fait ce qu'un humain ferait sans information : elle invente une explication plausible. Saisonnalité, effet météo, « tendance de fond ».

La timeline business lui donne les causes.

-- ❌ « Pourquoi les nouveaux abonnés ont baissé en février ? »
-- L'IA trouve le drop et le commente
 
SELECT
DATE_TRUNC(started_at, WEEK(MONDAY)) AS semaine, -- WEEK seul commence le dimanche
plan,
COUNT(*) AS nouveaux_abonnes
FROM subscriptions
WHERE started_at >= '2026-01-01' AND started_at < '2026-03-15'
GROUP BY semaine, plan
ORDER BY semaine, plan;
 
-- semaine | plan | nouveaux_abonnes
-- 2026-02-02 | Starter | 412
-- 2026-02-09 | Starter | 398
-- 2026-02-16 | Starter | 241 <- drop
-- 2026-02-16 | Pro | 188 <- hausse
--
-- Explication de l'IA : « La baisse de mi-février s'explique probablement
-- par un effet saisonnier après la période des soldes. »
-- -> Fausse. Et très convaincante.
kit-context-layer-ia · 09
-- ✅ Avec timeline_business.md, l'IA sait que :
-- « 2026-02-12 : prix du plan Starter passé de 9 € à 12 €/mois »
-- Elle peut donc vérifier l'hypothèse au lieu d'en inventer une
 
SELECT
CASE WHEN started_at < '2026-02-12' THEN 'avant hausse' ELSE 'après hausse' END AS periode,
plan,
COUNT(*) AS nouveaux_abonnes,
ROUND(COUNT(*) / COUNT(DISTINCT DATE(started_at)), ) AS abonnes_par_jour
FROM subscriptions
WHERE started_at >= '2026-01-22' AND started_at < '2026-03-05'
GROUP BY periode, plan
ORDER BY plan, periode;
 
-- periode | plan | nouveaux_abonnes | abonnes_par_jour
-- avant hausse | Pro | 520 | 24.8
-- après hausse | Pro | 610 | 29.0 <- +17 %
-- avant hausse | Starter | 1 230 | 58.6
-- après hausse | Starter | 790 | 37.6 <- -36 %
--
-- Lecture : la hausse de prix a fait fuir une partie des Starter,
-- mais une partie a basculé directement sur Pro.
-- Effet net sur les volumes : -21 Starter/jour, +4,2 Pro/jour.
-- Ce n'est pas de la saisonnalité, c'est une décision de pricing
-- dont on peut maintenant discuter l'effet réel.
kit-context-layer-ia · 10

Attention au piège inverse. La timeline donne une hypothèse prioritaire, pas une preuve. Un événement qui tombe au bon moment n'est pas forcément la cause : une campagne a peut-être pris fin le même jour. Ce que tu attends d'une IA bien briefée, c'est une phrase du type « la hausse de prix du 12 février est la cause la plus probable : la baisse touche uniquement le plan concerné, et commence le jour du changement ». Une cause, et les éléments qui la soutiennent. Pas une certitude.

C'est pour ça que la règle en tête du modèle ci-dessous demande de tester l'hypothèse, et pas seulement de la citer.

📅 Modèle : `timeline_business.md`

# Timeline business
 
Règle pour l'IA : avant d'expliquer une variation, vérifier si un événement
de cette timeline tombe dans la période (début OU fin). Si oui, tester cette
hypothèse en premier : la variation touche-t-elle le bon segment, à la bonne date ?
Si aucun événement ne correspond, le dire explicitement au lieu d'inventer une cause.
 
Format : date de début → date de fin · catégorie · événement · périmètre · impact attendu
 
---
 
## 2026
 
- 2026-11-03 → en cours · Produit · Lancement de l'export PDF · tous les plans · hausse d'usage
- 2026-10-14 → 2026-10-14 · Incident · Panne du paiement CB de 9h à 13h · tous · commandes du jour sous-estimées
- 2026-09-01 → 2026-09-30 · Marketing · Campagne rentrée -20 % sur l'annuel · nouveaux clients · pic d'annuels puis creux en octobre
- 2026-06-15 → 2026-06-22 · Tracking · Migration du tracking web · site web uniquement · sessions sous-comptées
- 2026-02-12 → permanent · Pricing · Plan Starter de 9 € à 12 €/mois · nouveaux clients uniquement · moins de Starter, report vers Pro
- 2026-01-05 → permanent · Organisation · Nouvelle équipe sales · comptes > 50 salariés · plus de gros comptes
 
## Catégories utilisées
- Pricing : changement de prix, nouveau plan, suppression de plan
- Produit : lancement ou retrait de fonctionnalité
- Marketing : campagne, promo, partenariat
- Incident : panne, bug impactant les données ou le business
- Tracking : changement dans la collecte de données (à vérifier en priorité !)
- Externe : concurrent, réglementation, actualité
kit-context-layer-ia · 11

Pourquoi une date de fin et un périmètre

Une campagne de septembre crée un pic en septembre… et souvent un creux en octobre, parce qu'elle a avancé des achats. Sans date de fin, l'IA ne fait pas le lien entre le creux d'octobre et la campagne. Et sans périmètre (« nouveaux clients uniquement »), elle ne peut pas vérifier que la variation touche le bon segment, ce qui est justement la façon de confirmer ou d'écarter l'hypothèse.

La catégorie la plus importante : « Tracking »

Une baisse de 30 % des sessions peut venir d'un vrai problème business… ou d'un tag analytics cassé pendant une semaine. Les événements de tracking sont ceux qui piègent le plus, humains comme IA, parce qu'ils produisent des variations qui ressemblent à des comportements clients.

Règle simple : chaque fois qu'un développeur touche au tracking, une ligne dans la timeline.

Comment construire la timeline en 30 minutes

  1. Ouvre le calendrier de l'année passée et les annonces internes (Slack, newsletters)

  2. Liste tous les changements de prix et de plans (demande à la finance ou au produit)

  3. Liste les grosses campagnes marketing (demande au marketing leur planning)

  4. Liste les incidents connus (cherche « incident » ou « panne » dans Slack)

  5. Demande à l'équipe data : « quelles variations bizarres a-t-on déjà dû expliquer ? »

Tu n'auras pas tout. Ce n'est pas grave. 15 lignes bien choisies valent mieux que rien du tout.


🧪 Apprends à décomposer un drop avant de l'expliquer

Avant de chercher la cause, il faut savoir isoler où la baisse se produit : quel segment, quel plan, quelle semaine. C'est exactement ce que travaillent les cas business de Modai Lab, à partir de vraies questions de manager.

👉 Pratiquer sur modai-lab.com

_Cas business réels · Datasets réalistes · Correction par l'IA_


PARTIE 5 — Les règles de calcul critiques

Ce qu'on exclut toujours, et que l'IA ne sait pas

Chaque entreprise a ses règles invisibles. Ce sont celles que les analystes seniors appliquent sans y penser, et que les nouveaux découvrent en se faisant reprendre en réunion :

  • Les comptes de test et les comptes internes

  • Les commandes remboursées (ou pas, selon le KPI)

  • Les montants en devises étrangères

  • Les transactions dupliquées par un bug connu

  • Les clients B2B qui faussent les moyennes B2C

Une IA sans ces règles fait exactement comme un nouvel arrivant : elle prend toutes les lignes.

-- ❌ Cas finance : « Montant moyen des virements sortants en octobre »
 
SELECT ROUND(AVG(montant), ) AS montant_moyen
FROM transactions
WHERE type = 'virement_sortant'
AND created_at >= '2026-10-01' AND created_at < '2026-11-01';
 
-- Résultat : 1 842,30 €
-- Problèmes :
-- 1. Mélange EUR, GBP et USD (colonne devise ignorée)
-- 2. Inclut les virements internes entre comptes du même client
-- 3. Inclut les comptes de démonstration commerciale (montants fictifs à 50 000 €)
kit-context-layer-ia · 12
-- ✅ Avec regles_calcul.md : l'IA applique R1, R2, R3 et R4, et les cite
 
WITH virements AS (
SELECT
t.montant,
t.devise,
DATE(t.created_at, 'Europe/Paris') AS jour_paris -- R4 : heure de Paris
FROM transactions t
JOIN users u ON t.user_id = u.user_id
WHERE t.type = 'virement_sortant'
AND t.statut = 'validee'
AND t.is_virement_interne = FALSE -- R3 : pas de flux internes
AND u.is_test_account = FALSE -- R1 : comptes réels
AND u.type_compte NOT IN ('demo', 'interne') -- R1
)
SELECT
ROUND(AVG(v.montant * CASE WHEN v.devise = 'EUR' THEN ELSE fx.taux_vers_eur END), )
AS montant_moyen_eur
FROM virements v
LEFT JOIN fx_rates_daily fx -- R2 + piège P6 : table complétée les week-ends
ON fx.devise = v.devise
AND fx.date_taux = v.jour_paris
WHERE v.jour_paris >= '2026-10-01' AND v.jour_paris < '2026-11-01';
 
-- Résultat : 387,60 €
-- Règles appliquées : R1, R2, R3, R4 · Piège contourné : P6
-- Gain : un montant réel, en euros, sur des flux réels. Écart avec la version naïve : x4,7.
kit-context-layer-ia · 13

Deux détails de cette requête valent un paragraphe chacun, parce que ce sont exactement ceux qu'une IA rate :

  • Le LEFT JOIN sur les taux de change. Avec un JOIN classique, toutes les transactions en euros disparaissent si fx_rates ne contient pas de ligne EUR → EUR. Le résultat paraît normal, mais il est calculé sur 8 % des lignes.

  • Le filtre de date appliqué après la conversion en heure de Paris. Filtrer sur created_at en UTC ferait entrer les virements du 30 septembre entre 22h et minuit (heure de Paris) dans le mois d'octobre.

Aucun de ces deux points n'est une erreur de syntaxe. Ce sont des règles. Si elles ne sont écrites nulle part, personne ne les applique.

⚙️ Modèle : `regles_calcul.md`

# Règles de calcul critiques
 
Ces règles s'appliquent à TOUTES les requêtes, sauf mention contraire explicite
dans la question. En cas de conflit avec une définition de métrique,
la définition de métrique est prioritaire.
 
---
 
## R1 · Exclure les comptes non réels
- Filtrer users.is_test_account = FALSE
- Filtrer users.type_compte NOT IN ('demo', 'interne')
- Pourquoi : ~1 200 comptes de test ou de démo, avec des montants fictifs très élevés
 
## R2 · Toujours convertir en euros
- Tout montant agrégé doit être converti via analytics.fx_rates
- Taux à utiliser : taux du jour de la transaction (pas le taux actuel)
- Pas de ligne EUR dans la table des taux : LEFT JOIN + taux 1 pour l'euro
- Utiliser fx_rates_daily, pas fx_rates (voir piège P6)
- Pourquoi : ~8 % des transactions sont en GBP ou USD
 
## R3 · Exclure les mouvements internes
- Filtrer transactions.is_virement_interne = FALSE pour tous les KPI de flux
- Pourquoi : un client qui déplace de l'argent entre ses comptes n'est pas un flux
 
## R4 · Dates en heure de Paris
- Les colonnes *_at sont en UTC
- Pour tout découpage par jour ou par mois : convertir en Europe/Paris
- Pourquoi : sinon les transactions entre 23h et minuit tombent le mauvais jour
 
## R5 · Commandes remboursées
- CA : déduire les remboursements (statut = 'remboursee' exclu)
- Volume de commandes passées : les inclure
- En cas de doute : demander quel KPI est attendu
kit-context-layer-ia · 14

Numérote tes règles

C'est un détail qui change tout. Quand chaque règle a un identifiant (R1, R2…), tu peux demander à l'IA de citer les règles qu'elle a appliquées dans sa réponse. Si une règle attendue n'apparaît pas, tu le vois immédiatement, sans relire tout le SQL.


🧪 Repère les exclusions oubliées

Les pièges de filtres (NULL qui disparaissent, comptes de test, devises mélangées) sont exactement ceux qui passent sous le radar en entretien comme en production. Mesure ta capacité à les détecter.

👉 Faire le test sur modai-lab.com/test-sql/

_Niveau par compétence · Recommandations ciblées · Gratuit_


PARTIE 6 — Les pièges connus

La mémoire des erreurs passées

Ce fichier, c'est la mémoire collective de ton équipe data. Toutes les fois où quelqu'un a dit « ah oui, cette colonne, il ne faut pas l'utiliser ». Toutes les « bizarreries connues » qui ne sont écrites nulle part et qui disparaissent quand un analyste quitte l'équipe.

Différence avec les règles de calcul : une règle s'applique tout le temps. Un piège est une situation spécifique où il faut faire attention.

-- ❌ RH : « Effectif moyen par département en 2025 »
-- L'IA utilise la table employees, qui semble faite pour ça
 
SELECT departement, COUNT(*) AS effectif
FROM employees
WHERE statut = 'actif'
GROUP BY departement;
 
-- Résultat : Data = 31, Sales = 58, Ops = 44
-- Problème : employees est une photo à date (aujourd'hui), pas un historique.
-- Les départs de 2025 ont disparu, les arrivées de 2026 sont comptées.
-- Et le département est celui d'aujourd'hui, pas celui de l'époque.
kit-context-layer-ia · 15
-- ✅ Avec pieges_connus.md :
-- « P2 : employees = état actuel uniquement.
-- Pour toute question historique, utiliser employees_history (SCD2). »
 
WITH jours_2025 AS (
SELECT jour
FROM UNNEST(GENERATE_DATE_ARRAY('2025-01-01', '2025-12-31')) AS jour
)
SELECT
h.departement,
ROUND(COUNT(*) / , ) AS effectif_moyen_2025
FROM jours_2025 j
JOIN employees_history h
ON j.jour >= h.valid_from
AND (j.jour < h.valid_to OR h.valid_to IS NULL)
WHERE h.statut = 'actif'
GROUP BY h.departement
ORDER BY effectif_moyen_2025 DESC;
 
-- Résultat : Sales = 52.4, Ops = 46.1, Data = 24.7
-- Gain : un vrai effectif moyen sur l'année, avec le bon département à chaque date.
-- L'équipe Data a grossi en 2026 : la version naïve la surestimait de 25 %.
kit-context-layer-ia · 16

⚠️ Modèle : `pieges_connus.md`

# Pièges connus
 
Format : identifiant · symptôme · cause · ce qu'il faut faire
Ajouter une ligne à chaque fois qu'un chiffre faux a été présenté ou corrigé.
 
---
 
## P1 · last_login_at n'est plus fiable
- **Symptôme** : chute des utilisateurs « connectés » depuis mai 2026
- **Cause** : la migration de l'app mobile n'alimente plus cette colonne
- **À faire** : utiliser events (event_name = 'app_open') pour l'activité
 
## P2 · employees est une photo, pas un historique
- **Symptôme** : effectifs passés qui ne collent pas avec les rapports RH
- **Cause** : employees écrase les données à chaque mise à jour
- **À faire** : pour toute question historique, utiliser employees_history
 
## P3 · Commandes dupliquées du 2026-03-18
- **Symptôme** : pic de commandes ce jour-là
- **Cause** : bug du webhook de paiement, ~340 commandes enregistrées deux fois
- **À faire** : dédoublonner sur payment_id pour cette date
 
## P4 · Tables orders et invoices ne réconcilient pas au centime
- **Symptôme** : écart de 1 à 2 % entre CA commandes et CA facturé
- **Cause** : remises appliquées après facturation, frais de port facturés à part
- **À faire** : normal, ne pas chercher à réconcilier ligne à ligne. Citer l'écart.
 
## P5 · Région vide pour les clients avant 2024
- **Symptôme** : ~15 % de NULL dans users.region
- **Cause** : champ ajouté au formulaire en 2024
- **À faire** : ne jamais filtrer sur region sans traiter les NULL (« Non renseigné »)
 
## P6 · Pas de taux de change le week-end
- **Symptôme** : montants en devises qui disparaissent les samedis et dimanches
- **Cause** : fx_rates ne contient que les jours ouvrés (taux publiés par la banque)
- **À faire** : utiliser fx_rates_daily, complétée avec le dernier taux connu
kit-context-layer-ia · 17

La règle d'or

À chaque fois qu'un chiffre faux a été présenté en réunion, ou corrigé après coup, une ligne s'ajoute à ce fichier. En six mois, c'est le document le plus précieux de ton équipe. Pour les humains comme pour l'IA.


🧪 Travaille sur des données qui ont des défauts

Les vrais datasets ont des colonnes cassées, des historiques trompeurs et des doublons datés. Sur Modai Lab, les exercices en contiennent volontairement, pour que tu apprennes à les repérer avant qu'ils ne finissent dans un comité.

👉 Pratiquer sur modai-lab.com

_Pièges réels · Explications de senior · Progression mesurée_


PARTIE 7 — Brancher le kit : le README pour l'IA

5 fichiers, mais aucune consigne

Tu as écrit tes 5 fichiers. Tu les donnes à ton IA. Et elle les utilise… à moitié. Elle lit le dictionnaire, mais oublie de vérifier la timeline avant d'expliquer un drop. Elle applique R1, mais pas R4. Elle invente une définition au lieu de dire qu'elle n'en a pas.

C'est normal : tu lui as donné des informations, pas une méthode. Le sixième fichier, court, lui dit comment se servir des cinq autres. C'est le chef d'orchestre du kit.

🧭 Modèle : `README_contexte.md`

# Contexte data · Mode d'emploi pour l'IA
 
Tu réponds à des questions business en écrivant du SQL sur notre warehouse.
Avant chaque requête, applique cette méthode.
 
## Ordre de lecture
1. definitions_metriques.md : la question utilise-t-elle un KPI défini ?
Si oui, applique la définition à la lettre.
2. dictionnaire_tables.md : choisis uniquement des tables ✅ RÉFÉRENCE.
Vérifie le grain avant chaque jointure.
3. regles_calcul.md : applique toutes les règles R1 à R5, sauf mention contraire.
4. pieges_connus.md : vérifie si un piège concerne tes tables, colonnes ou dates.
5. timeline_business.md : seulement pour expliquer une variation.
 
## Ce que tu dois toujours faire
- Citer à la fin de ta réponse : tables utilisées, règles appliquées (R…),
pièges contournés (P…)
- Si une métrique demandée n'est pas définie : le dire et proposer une définition,
ne pas en choisir une en silence
- Si tu expliques une variation : citer l'événement de la timeline qui la soutient,
et ce que tu as vérifié. Si aucun événement ne correspond, le dire.
- Si deux fichiers se contredisent : le signaler
 
## Ce que tu ne dois jamais faire
- Utiliser une table ⛔ DÉPRÉCIÉE ou des schémas raw / staging
- Inventer une cause business qui n'est pas dans la timeline
- Arrondir ou « corriger » un chiffre pour qu'il colle à un autre
kit-context-layer-ia · 18

Où mettre le kit, concrètement

Ton outil

Où mettre les fichiers

Claude (claude.ai)

Les 6 fichiers dans les connaissances d'un Projet dédié à l'analyse

Claude Code ou un agent qui lit un dossier

Un dossier context/ dans le repo, avec le README à la racine

dbt

Les définitions et le dictionnaire dans les description des modèles, le reste en fichiers à côté

Un agent maison

Le README en prompt système, les 5 fichiers chargés dans le contexte

Quel que soit l'outil, une règle : une seule source de vérité. Si la définition du CA existe dans dbt ET dans un fichier markdown, elles finiront par diverger. Choisis un endroit, et fais pointer les autres vers lui.


PARTIE 8 — Tester que ton contexte fonctionne vraiment

Le pouce levé ne vaut rien

Le réflexe classique pour évaluer une IA data : demander aux utilisateurs si la réponse leur convient. Problème : l'utilisateur qui pose la question ne connaît pas la réponse. S'il la connaissait, il ne la poserait pas. Une réponse fausse mais bien formulée récolte un pouce levé.

La seule façon fiable de tester ta couche de contexte : un jeu de questions dont tu connais déjà la réponse.

Le jeu de questions de référence

Construis une liste de 10 à 20 questions, avec pour chacune :

  • La question, formulée comme un utilisateur la poserait

  • Le chiffre attendu (calculé par un humain, validé)

  • La table qui doit être utilisée

  • Les règles qui doivent être appliquées

-- Table de suivi des tests de contexte
-- À relancer après chaque modification des fichiers du kit
 
CREATE TABLE IF NOT EXISTS analytics.tests_contexte_ia (
question_id STRING,
question STRING,
valeur_attendue FLOAT64,
table_attendue STRING,
regles_attendues STRING,
valeur_obtenue FLOAT64,
table_utilisee STRING,
date_test DATE
);
 
-- Contrôle : quelles questions dérivent ?
SELECT
question_id,
question,
valeur_attendue,
valeur_obtenue,
ROUND( * (valeur_obtenue - valeur_attendue) / NULLIF(valeur_attendue, ), ) AS ecart_pct,
table_attendue = table_utilisee AS bonne_table
FROM analytics.tests_contexte_ia
WHERE date_test = CURRENT_DATE()
AND (ABS(valeur_obtenue - valeur_attendue) / NULLIF(valeur_attendue, ) > .
OR table_attendue != table_utilisee)
ORDER BY ABS(ecart_pct) DESC;
 
-- question_id | question | attendu | obtenu | ecart_pct | bonne_table
-- Q07 | Clients actifs en octobre | 11 080 | 18 420 | 66.2 | false
-- Q12 | Churn mensuel septembre | 3.8 | 3.8 | 0.0 | false
--
-- Q12 : le chiffre est bon mais la table est mauvaise -> fragile, à corriger aussi
kit-context-layer-ia · 19

Comment remplir `valeur_obtenue` sans y passer ta journée

Pas besoin d'outillage au début. Une fois par semaine, ou après chaque modification du kit :

  1. Ouvre une nouvelle conversation avec ton IA et ses fichiers de contexte

  2. Pose les 10 questions, une par une, telles qu'un utilisateur les poserait

  3. Demande-lui de terminer chaque réponse par une ligne fixe : RESULTAT: [valeur] | TABLE: [table principale] | REGLES: [R1, R3…]

  4. Reporte ces lignes dans la table (ou dans un Google Sheet, ça marche aussi)

Pose chaque question deux fois, dans deux conversations différentes. Une IA peut répondre juste une fois et faux la suivante. Si les deux réponses diffèrent, c'est le signe d'une définition encore ambiguë, même si l'une des deux est bonne.

Quand tu auras 20 questions et que tu relances le test chaque semaine, automatise-le avec l'API de ton IA. Pas avant : l'important, c'est d'avoir le jeu de questions, pas le script.

Pourquoi vérifier la table, pas seulement le chiffre

Une IA peut tomber sur le bon chiffre par hasard, en passant par le mauvais chemin. Le mois suivant, avec d'autres données, le hasard ne jouera plus. Vérifier où elle va chercher la réponse est aussi important que vérifier ce qu'elle répond.

Les questions à mettre dans ton jeu de tests

Type de question

Exemple

Ce qu'elle teste

KPI de base

« CA du mois dernier »

Définition + règles d'exclusion

Métrique ambiguë

« Combien de clients actifs ? »

Définition écrite vs sens commun

Jointure à risque

« CA par catégorie »

Dictionnaire + grain

Question historique

« Effectif moyen en 2025 »

Pièges connus (photo vs historique)

Explication de variation

« Pourquoi le drop de février ? »

Timeline business

Question sans réponse

« Pourquoi le pic du 3 août ? » (rien dans la timeline)

L'IA admet-elle ne pas savoir ?

La dernière ligne est la plus révélatrice. Une IA bien contextualisée doit répondre « aucun événement connu ne correspond à cette date, voici les hypothèses à vérifier », et pas inventer une cause.


PARTIE 9 — Les erreurs classiques en construisant son contexte

Erreur 1 : vouloir tout documenter avant de commencer

❌ Le junior lance un grand chantier « documenter les 300 tables du warehouse ». Trois semaines plus tard, 40 tables sont documentées, le projet s'essouffle, rien n'est utilisé.

✅ Le senior liste les 20 questions les plus posées à l'équipe data, identifie les 8 tables qui y répondent, et documente celles-là en une journée. Il étend ensuite selon les erreurs rencontrées.

Erreur 2 : écrire du SQL à la place des définitions

❌ Le junior met la requête de référence comme seule définition du KPI. L'IA copie la requête, mais ne comprend pas l'intention. Dès que la question change un peu (« churn sur les clients Pro uniquement »), elle ne sait plus adapter.

✅ Le senior écrit d'abord la phrase métier, puis l'ancrage technique, puis la requête de référence en lien. L'IA comprend le pourquoi et peut adapter à une variante.

Erreur 3 : laisser le contexte vieillir

❌ Le junior écrit les fichiers une fois et n'y touche plus. Six mois plus tard, une table a été dépréciée, deux prix ont changé, et l'IA applique des règles fausses avec une confiance totale. Un contexte obsolète est pire que pas de contexte : il donne une fausse légitimité.

✅ Le senior met une date de mise à jour en haut de chaque fichier, un responsable par fichier, et un rituel : 15 minutes par semaine pour ajouter les nouveaux événements à la timeline et les nouveaux pièges rencontrés.

Erreur 4 : un contexte que seuls les techniques peuvent modifier

❌ Le junior met tout dans un repo Git. Le marketing qui lance une campagne, la finance qui change un prix, le produit qui retire une fonctionnalité : aucun ne sait ouvrir une pull request. La timeline business reste vide.

✅ Le senior met la timeline business dans un outil que tout le monde utilise (une page Notion, un Google Doc, un canal Slack dédié), avec une synchronisation vers l'IA. L'équipe data porte la plateforme, mais le contenu métier appartient aux métiers.

Erreur 5 : croire que le contexte remplace la vérification

❌ Le junior a écrit ses 5 fichiers et considère que l'IA est désormais fiable. Il copie les chiffres sans les relire.

✅ Le senior sait que le contexte réduit les erreurs, il ne les supprime pas. Il garde ses réflexes : vérifier le grain, comparer à un ordre de grandeur connu, relire les filtres. Le kit rend l'IA meilleure. Il ne te dispense pas de savoir lire son SQL.

Erreur 6 : mettre n'importe quoi dans le contexte

❌ Le junior colle dans ses fichiers des extraits de données clients pour « donner des exemples » à l'IA : des emails, des noms, des montants réels. Le fichier de contexte se retrouve partagé dans un outil externe, avec des données personnelles dedans.

✅ Le senior ne met dans le contexte que de la structure et des règles : noms de tables, définitions, événements, pièges. Jamais de données clients, jamais d'identifiants, jamais de mots de passe ou de clés d'accès. Et il vérifie avec son équipe sécurité ou son DPO quels outils IA ont le droit de recevoir des informations internes (une timeline de pricing, par exemple, peut être confidentielle).


🧪 Garde la compétence qui rend tout ça possible

Écrire un bon contexte et vérifier ce que l'IA produit, ça demande la même chose : savoir lire et challenger une requête SQL. C'est le socle que tu travailles sur Modai Lab, sur des cas métiers réalistes.

👉 Faire le test sur modai-lab.com/test-sql/

_Mesure ta progression · Repère tes lacunes · Prépare tes entretiens_


Plan d'action : ton kit en 5 jours

Jour

Fichier

Temps

Livrable minimal

Lundi

dictionnaire_tables.md

1 h

Les 8 tables qui répondent à 80 % des questions

Mardi

definitions_metriques.md

1 h

Les 5 KPI les plus demandés, avec « ce que ce n'est PAS »

Mercredi

timeline_business.md

30 min

15 événements des 12 derniers mois

Jeudi

regles_calcul.md + pieges_connus.md

1 h

5 règles numérotées, 5 pièges

Vendredi

README_contexte.md + jeu de tests

1 h 30

Le mode d'emploi pour l'IA, 10 questions avec réponse attendue, premier passage

Cinq heures de travail. C'est moins que le temps perdu sur un seul chiffre faux présenté en comité.


Prompt Claude pour auditer tes requêtes (et ton contexte)

Copie-colle ce prompt dans Claude, puis colle tes fichiers de contexte, ta question et la requête produite par l'IA en dessous.

Tu es un data analyst senior chargé de vérifier qu'une requête SQL produite
par une IA respecte le contexte métier de l'entreprise. Tu dois être exigeant :
une requête syntaxiquement correcte peut produire un chiffre faux.
 
Je vais te donner :
1. Les fichiers de contexte de l'entreprise (README, dictionnaire des tables,
définitions des métriques, timeline business, règles de calcul, pièges connus)
2. La question business posée
3. La requête SQL produite et, si disponible, son résultat
 
Vérifie point par point :
 
A. Choix des tables
- Les tables utilisées sont-elles marquées comme référence dans le dictionnaire ?
- Une table dépréciée ou une table « photo » est-elle utilisée pour une question historique ?
- Le grain de chaque table est-il respecté (pas de somme après une jointure qui duplique) ?
 
B. Définitions
- Le KPI calculé correspond-il exactement à la définition écrite ?
- La requête tombe-t-elle dans le « ce que ce n'est PAS » d'une définition ?
- La période et la date de rattachement sont-elles les bonnes ?
 
C. Règles de calcul
- Liste chaque règle (R1, R2…) et indique si elle est appliquée, non applicable,
ou manquante
- Les montants sont-ils dans la bonne devise ? Les dates dans le bon fuseau ?
 
D. Pièges connus
- Un piège documenté (P1, P2…) concerne-t-il les tables, colonnes ou dates utilisées ?
- Si oui, la requête le contourne-t-elle correctement ?
 
E. Explication du résultat
- Si une variation est expliquée, l'explication s'appuie-t-elle sur un événement
de la timeline ou est-elle inventée ?
- Si aucun événement ne correspond, l'IA l'a-t-elle dit clairement ?
 
F. Trous dans le contexte
- Quelle information manquait dans les fichiers de contexte pour que l'IA
réponde juste du premier coup ?
- Propose la ligne exacte à ajouter, et dans quel fichier
 
Pour chaque problème trouvé, donne :
- La gravité (chiffre faux / chiffre fragile / amélioration)
- L'impact estimé sur le résultat (ordre de grandeur)
- La correction
 
Termine par :
1. La requête corrigée complète, commentée, avec les règles appliquées citées
2. Une requête de contrôle pour vérifier le résultat
3. Les lignes à ajouter dans les fichiers de contexte pour éviter cette erreur à l'avenir
kit-context-layer-ia · 20

Récapitulatif

Fichier

Contenu clé

Ce qu'il évite

Mise à jour

dictionnaire_tables.md

Grain, usage, statut de chaque table

Mauvaise table, jointure qui gonfle

À chaque nouvelle table ou dépréciation

definitions_metriques.md

Phrase métier + ancrage technique + « ce que ce n'est PAS »

KPI calculé au « sens commun »

À chaque nouveau KPI ou changement de définition

timeline_business.md

Début → fin · catégorie · événement · périmètre · impact

Explication inventée d'une variation

Chaque semaine

regles_calcul.md

Exclusions numérotées (R1, R2…)

Comptes de test, devises, fuseaux, flux internes

À chaque nouvelle règle

pieges_connus.md

Symptôme · cause · ce qu'il faut faire (P1, P2…)

Colonnes cassées, photos vs historiques

Après chaque chiffre faux corrigé

README_contexte.md

Ordre de lecture, obligations, interdits

Fichiers lus à moitié, définitions inventées

Quand un nouveau fichier s'ajoute

Jeu de tests

10-20 questions avec réponse attendue

Dérive silencieuse du contexte

Relancé après chaque modification


✅ Checklist context layer

  • ☐ J'ai listé les 20 questions les plus posées à l'équipe data

  • ☐ J'ai documenté les tables qui y répondent, avec leur grain

  • ☐ J'ai marqué les tables dépréciées et les tables « photo » à ne pas utiliser pour l'historique

  • ☐ Mes 5 KPI principaux ont une définition en français, pas seulement une requête

  • ☐ Chaque définition a un « ce que ce n'est PAS »

  • ☐ Ma timeline business contient les changements de prix, campagnes et incidents des 12 derniers mois

  • ☐ Les changements de tracking sont dans la timeline

  • ☐ Mes règles de calcul sont numérotées (R1, R2…)

  • ☐ Les comptes de test, devises et flux internes sont couverts par une règle

  • ☐ Mon fichier de pièges connus contient au moins 5 entrées

  • ☐ J'ai remplacé tout le contenu des modèles par mes propres tables, règles et événements

  • ☐ Mon README dit à l'IA dans quel ordre lire les fichiers et quoi citer dans ses réponses

  • ☐ Chaque définition n'existe qu'à un seul endroit (une seule source de vérité)

  • ☐ Chaque fichier a une date de mise à jour et un responsable

  • ☐ Les métiers peuvent alimenter la timeline sans passer par l'équipe data

  • ☐ Aucune donnée client, aucun identifiant ni aucune clé d'accès dans mes fichiers

  • ☐ J'ai un jeu de 10 questions avec réponse attendue, et je vérifie la table utilisée

  • ☐ Je pose chaque question de test deux fois pour repérer les réponses instables

  • ☐ Je continue à relire le SQL produit par l'IA, contexte ou pas


🚀 Une IA bien briefée, un analyste qui sait vérifier

Le kit rend ton IA bien meilleure. Mais pour écrire un bon contexte et repérer ce qui cloche dans une requête, il faut d'abord maîtriser le SQL. Mesure ton niveau, puis entraîne-toi sur les cas business que tu retrouveras en poste.

👉 modai-lab.com/test-sql/ — Exercices calibrés · Cas business réels · Feedback senior


_Guide offert suite au post LinkedIn · Entraînez-vous sur modai-lab.com/test-sql/ · Partagez librement ♻️_