Cours Vibe coding avec Claude Code · Module 12: Clone de Medium
La vigie du mât : erreurs de production, Sentry et MCP
Dans cette leçon11
Après la leçon 11_3, tu as demandé à Claude des extraits, c'est-à-dire le début du texte sous chaque titre sur la page de publication : "Sous les titres, montre le premier paragraphe, 160 caractères au maximum, fonction excerpt dans lib/excerpt.ts". Si tu ne l'as pas encore fait, fais-le maintenant. Le lint et le build sont passés, le commit est parti. Une semaine plus tard, Mary Read a transformé l'unique paragraphe de son texte dans la Cambuse en citation. Depuis, la page /publications/cambuse répond par une erreur 500 à chaque lecteur, et toi, tu n'en sais rien, car chez toi tout fonctionne. Le lecteur n'écrit pas de signalement, il s'en va. Il te faut une vigie au sommet du mât : un service qui voit chaque erreur en production et sonne l'alarme aussitôt.
Ce que tu vas apprendre
- brancher Sentry avec l'assistant et lire dans Cursor chaque fichier qu'il a ajouté ;
- garder le jeton Sentry hors de la conversation avec Claude et hors du dépôt ;
- déboguer une erreur de production avec Claude Code : la cause, un test qui la reproduit, et seulement ensuite la correction ;
- distinguer
error.tsx,global-error.tsxet unErrorBoundaryà toi ; - brancher le serveur MCP de Sentry et savoir quand la simple CLI suffit.
L'assistant Sentry, c'est toi qui le lances
Sentry collecte les erreurs de l'application avec leur trace de pile, c'est-à-dire la liste des fonctions, des fichiers et des lignes par lesquels le programme est passé avant de tomber. Il te faut ton propre compte et ton propre projet dans Sentry. Le guide officiel pour Next.js recommande l'assistant (état en novembre 2026) :
npx @sentry/wizard@latest -i nextjsCette commande, tu la tapes toi-même, dans un onglet séparé du terminal de Cursor. L'assistant te connecte dans le navigateur, demande s'il faut suivre les performances, enregistrer les sessions et créer une page d'exemple, puis enregistre le jeton. Tu sais depuis la leçon 8_5 que le résultat d'une commande lancée avec ! arrive dans la conversation avec Claude, et ici rien de tout cela n'a besoin d'être vu par Claude.
Selon la documentation de Sentry, l'assistant enregistre le jeton dans le fichier .env.sentry-build-plugin et ajoute ce fichier à .gitignore. Avec ce jeton, le build envoie à Sentry les cartes source, c'est-à-dire les fichiers qui retraduisent le code compilé vers tes fichiers et tes lignes. Le jeton est un secret. Le DSN, l'adresse à laquelle le SDK envoie les erreurs, est différent : il part dans le navigateur de chaque lecteur, donc ce n'est pas un secret. La règle Read(./.env.*) de la leçon 8_4 couvre aussi le fichier du jeton, car l'étoile correspond à tout nom après .env.. Si ce projet ne l'a pas encore, copie les règles dans .claude/settings.json avant de lancer l'assistant.
Ce que l'assistant a ajouté
Ouvre le panneau Source Control dans Cursor et lis le diff fichier par fichier avant de faire un commit. L'assistant crée trois fichiers de départ, car Next.js exécute du code dans trois environnements : instrumentation-client.ts pour le navigateur, sentry.server.config.ts pour Node.js et sentry.edge.config.ts pour l'environnement Edge. Le fichier du navigateur ressemble à ceci :
// instrumentation-client.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
});
export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;L'assistant écrit le DSN en dur, et la documentation autorise aussi la variable publique NEXT_PUBLIC_SENTRY_DSN. tracesSampleRate indique quelle part des requêtes Sentry enregistre comme traces de performance. L'assistant écrit 1, donc toutes, alors que la documentation conseille de baisser cette valeur en production et montre 0.1. Cela ne concerne pas les erreurs : pour elles, une autre option, sampleRate, envoie par défaut chacune. Le plus important reste pourtant instrumentation.ts :
// instrumentation.ts
import * as Sentry from "@sentry/nextjs";
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
await import("./sentry.server.config");
}
if (process.env.NEXT_RUNTIME === "edge") {
await import("./sentry.edge.config");
}
}
export const onRequestError = Sentry.captureRequestError;register charge la configuration propre à l'environnement. onRequestError est un crochet de Next.js qui, selon la documentation de Sentry, attrape les erreurs des Server Components, des routes d'API et du middleware, donc exactement l'erreur qu'a provoquée le changement de Mary. Plus loin dans le diff : app/global-error.tsx avec Sentry.captureException dans un useEffect, et next.config.ts enveloppé dans withSentryConfig de @sentry/nextjs/config, qui envoie les cartes au moment du build.
Première alarme
La documentation demande de vérifier l'installation sur la page /sentry-example-page créée par l'assistant : le bouton "Throw Sample Error" lance une erreur dans le navigateur et sur le serveur. Reproduis ensuite le vrai cas : dans lib/articles.ts, change le type du seul bloc de texte de a3 de "paragraph" en "quote", lance npm run build && npm start et ouvre /publications/cambuse.
Nous n'avions pas de compte Sentry, donc le DSN pointait vers un récepteur local qui jouait Sentry. Il a reçu le signalement : TypeError: Cannot read properties of undefined (reading 'text'), mécanisme auto.function.nextjs.on_request_error, route /publications/[slug]. Les cadres de la trace désignaient le fichier _next/server/chunks/ssr/...js, ligne 2 : voilà à quoi ressemble une trace sans cartes source. Avec npm run dev, la même erreur dans le terminal pointait vers ton code :
⨯ TypeError: Cannot read properties of undefined (reading 'text')
at excerpt (lib/excerpt.ts:5:54)
at <unknown> (app/publications/[slug]/page.tsx:20:18)Avec les cartes source, Sentry montre dans la trace tes fichiers et tes lignes, et c'est pourquoi le jeton de l'assistant en vaut la peine.
Demande pour Claude Code : d'abord la cause
Tu connais l'ordre depuis les leçons 2_8 et 4_1 : la cause, un test qui échoue, et seulement ensuite la correction.
Demande pour Claude Code :
Sentry : /publications/cambuse renvoie 500 depuis que l'unique
paragraphe du texte a3 est devenu une citation. La trace :
TypeError: Cannot read properties of undefined (reading 'text')
at excerpt (lib/excerpt.ts:5:54)
at <unknown> (app/publications/[slug]/page.tsx:20:18)
D'abord, décris la cause, ne change pas le code. Ensuite, ajoute à
lib/excerpt.test.ts un test qui reproduit l'erreur, lance-le et
montre qu'il échoue. N'écris la correction qu'après mon "ok" : un
texte sans paragraphe reçoit un extrait du premier bloc, un texte
sans blocs un extrait vide.Ce que Claude a écrit : le test et la correction
La cause tient en une phrase : excerpt suppose que chaque texte a un paragraphe, et le signe ! après find(...) promet à TypeScript qu'on trouvera quelque chose. Cette promesse est passée chez nous par npm run lint et npx tsc --noEmit. Ouvre lib/excerpt.test.ts dans Cursor :
// lib/excerpt.test.ts
test("poème fait de citations seules : extrait tiré de la première citation", () => {
const poem = article([{ id: "q1", type: "quote", text: "Les étoiles sont une horloge." }]);
expect(excerpt(poem)).toBe("Les étoiles sont une horloge.");
});article est une fonction d'aide du test, qui prend un article d'exemple et remplace ses blocs. Avant la correction, le test a échoué avec le même TypeError qu'en production, donc il reproduit bien l'erreur. Après ton "ok", Claude a modifié la fonction :
// lib/excerpt.ts
export function excerpt(article: Article, max = 160): string {
const block = article.blocks.find((b) => b.type === "paragraph") ?? article.blocks[0];
if (!block) return "";
const text = block.text.trim();
return text.length > max ? text.slice(0, max - 1).trimEnd() + "…" : text;
}?? prend le premier bloc de n'importe quel type quand il n'y a pas de paragraphe, et un article vide reçoit un extrait vide. Les deux cas sont des décisions que tu as prises toi-même dans la demande, et les deux ont un test. Chez nous, après la correction, tous les tests sont passés.
Une erreur typique de l'agent : le try/catch qui éteint l'alarme
Au lieu de la cause, l'agent peut faire taire le symptôme :
// lib/excerpt.ts (version de l'agent)
try {
const text = article.blocks.find((b) => b.type === "paragraph")!.text;
return text.length > max ? text.slice(0, max - 1).trimEnd() + "…" : text;
} catch {
return "";
}Chez nous, cette version est passée par le lint et tsc, et la page de la Cambuse répondait 200 avec un extrait vide. Rien ne serait arrivé à Sentry, car selon sa documentation une erreur attrapée et non relancée n'y arrive jamais. C'est seulement le test qui a dit la vérité : expected '' to be 'Les étoiles sont une horloge.'. Un catch vide, c'est une vigie qui s'est endormie au sommet du mât.
Trois gardes : error.tsx, global-error.tsx et ErrorBoundary
Une erreur survenue pendant le dessin de la page est attrapée par une limite d'erreur (error boundary) : un composant qui, à la place de la partie cassée, montre un texte de remplacement. Next.js en fournit deux toutes prêtes. error.tsx dans le dossier d'une route couvre sa page et les layouts imbriqués. global-error.tsx est la dernière ligne de défense quand le layout racine casse, c'est pourquoi il a ses propres <html> et <body>. La documentation de Sentry avertit : une erreur attrapée par error.tsx n'arrive pas toute seule à Sentry, donc chaque limite de ce type appelle Sentry.captureException.
Ta propre limite, tu la poses autour d'une seule partie de la page, pour que sa panne n'emporte pas le reste. La documentation de React dit qu'une limite s'écrit comme une classe avec deux méthodes : static getDerivedStateFromError change l'état pour afficher le texte de remplacement, et componentDidCatch sert à envoyer le rapport :
// components/ErrorBoundary.tsx
export default class ErrorBoundary extends Component<Props, { hasError: boolean }> {
state = { hasError: false };
static getDerivedStateFromError() {
return { hasError: true };
}
componentDidCatch(error: Error, info: ErrorInfo) {
Sentry.captureException(error, { contexts: { react: { componentStack: info.componentStack } } });
}
render() {
if (this.state.hasError) return this.props.fallback;
return this.props.children;
}
}Le fichier commence par "use client", et Props se compose de fallback et children. Un test avec un composant qui lance une erreur nous a montré l'ordre : getDerivedStateFromError met hasError, render dessine le texte de remplacement, et seulement ensuite React appelle componentDidCatch. Sur la page d'article, la limite entoure les applaudissements, pour que leur panne n'emporte pas le texte :
// app/articles/[id]/page.tsx
<ErrorBoundary fallback={<p className="text-sm text-gray-500">Les applaudissements sont momentanément indisponibles.</p>}>
<ClapButton articleId={article.id} initial={claps} />
</ErrorBoundary>Deux limites de cette limite, elles aussi tirées de la documentation de React : elle n'attrape pas les erreurs dans la gestion des événements (par exemple dans onClick) ni dans le code asynchrone, et dans la version de production, une erreur attrapée dans componentDidCatch ne remonte pas plus haut. Sans captureException, Sentry ne la verrait pas. Depuis la version 16.3, Next.js a aussi catchError de next/error, qui ajoute retry et laisse passer notFound(), mais la classe de React est le fondement que tu travailles dans l'exercice.
La vigie dans la conversation : le serveur MCP de Sentry
Jusqu'ici, tu copiais la trace de Sentry dans la demande. MCP (Model Context Protocol) est un standard ouvert par lequel Claude Code se connecte à d'autres outils : un serveur MCP donne à Claude des outils pour lire et agir dans un autre système. La documentation de Claude Code conseille de brancher un serveur justement quand tu te surprends à coller des données d'un autre outil, par exemple d'un tableau de bord de monitoring. La page du serveur Sentry (mcp.sentry.dev) cite la recherche d'erreurs, l'analyse des performances, le tri des problèmes, la lecture de la documentation et la gestion des projets. Tu tapes la commande dans le terminal, dans le dossier du projet :
claude mcp add --transport http --scope project sentry https://mcp.sentry.dev/mcp/ton-organisation/captains-chronicle--transport http est, selon la documentation, la manière recommandée de se connecter à un serveur distant. Les deux derniers éléments de l'adresse limitent le serveur à une seule organisation et à un seul projet, ce que la page de Sentry recommande. La portée décide où va la configuration : local (par défaut) seulement pour toi et ce projet dans ~/.claude.json, user pour tous tes projets dans le même fichier, project dans le fichier .mcp.json du dépôt, pour tout l'équipage. Tu choisis project, car le fichier ne contient que l'adresse, sans jeton. Chez nous, il en est sorti ce .mcp.json :
{
"mcpServers": {
"sentry": {
"type": "http",
"url": "https://mcp.sentry.dev/mcp/ton-organisation/captains-chronicle"
}
}
}claude mcp list a montré à côté du serveur ⏸ Pending approval, avec une invitation à lancer claude : un serveur de .mcp.json attend que tu l'approuves dans une session, car un dépôt cloné ne peut pas activer des serveurs tout seul. Dans la session, /mcp affiche l'état des serveurs, te guide dans la connexion OAuth dans le navigateur, permet de désactiver un serveur et d'effacer la connexion. Chaque membre de l'équipage se connecte avec son propre compte, donc Claude ne voit dans Sentry que ce à quoi ton compte a accès. Maintenant, tu demandes :
Récupère dans Sentry les erreurs non résolues des dernières 24
heures. Pour chacune, donne le titre, le nombre d'occurrences et les
fichiers de notre dépôt concernés par la trace. Ne change rien.Chaque fichier indiqué, tu l'ouvres dans Cursor et tu le compares au rapport. Les messages d'erreur peuvent contenir du texte saisi par des inconnus, et la documentation de Claude Code met en garde contre l'injection de commandes par les serveurs qui lisent du contenu extérieur. Ce sont des données à lire, pas des ordres.
Mais demande-toi d'abord si MCP est même nécessaire. Les bonnes pratiques de Claude Code disent : si le système a une CLI, c'est en général le chemin le plus simple, et MCP est pour les systèmes qui n'en ont pas. Pour GitHub, gh suffit, et Claude le lance comme n'importe quelle commande. Sentry a aussi sa propre CLI (sentry, décrite sur cli.sentry.dev), donc là aussi tu as le choix. Un serveur MCP distant n'exige rien d'installé sur l'ordinateur.
La revue du capitaine
- Secret hors du dépôt.
git statusne montre pas.env.sentry-build-plugin, et il n'y a pas de jeton dans le diff. - Échantillonnage.
tracesSampleRateen production n'est pas resté à 1. - Test avant la correction. Le test de l'extrait a échoué avant le changement et passe après. Un test qui passe tout de suite ne prouve rien.
- Rien n'est réduit au silence. Cherche
catchdans le projet (Cmd+Shift+F) : chaque nouveaucatchrelance l'erreur ou appelleSentry.captureException. - Les limites rapportent. Chaque
error.tsxet chaqueErrorBoundarycontientcaptureException.
Étape suivante
Demande un commit "Sentry, extrait sans paragraphe et ErrorBoundary autour des applaudissements". Puis : "Ajoute @app/articles/[id]/error.tsx avec un bouton Réessayer via retry et Sentry.captureException dans un useEffect", comme dans la leçon 3_4. Dans l'éditeur ci-dessous t'attend la page de publication avec un faux Sentry : provoque l'erreur de l'extrait, active l'erreur de l'agent "cacher l'erreur dans un try/catch" et compare ce que voit le lecteur et ce que voit la vigie.
Retiens ceci : la vigie ne répare pas le navire, mais sans elle personne ne sait que l'eau envahit déjà la cale.
Code de cette leçon : App.jsx
// Page de publication avec un faux Sentry : extraits, limite d'erreur et erreur de l'agent try/catch
import { Component, useState } from 'react';
const ARTICLES = [
{ id: 'a1', title: "Comment survivre à une tempête en Atlantique", text: "La tempête est arrivée de nuit, et l'équipage dormait après un long quart." },
{ id: 'a2', title: "La carte au trésor introuvable", text: "La carte avait trois croix et aucun trésor." },
{ id: 'a3', title: "Le cuisinier de bord conseille : du biscuit pour six semaines", text: "Le biscuit doit être dur comme le pont, sinon il ne survivra pas au voyage." },
];
const VERSIONS = [
{ key: 'agent', label: "Version avec ! (il y a toujours un paragraphe)" },
{ key: 'trycatch', label: "Erreur de l'agent : cacher l'erreur dans un try/catch" },
{ key: 'fixed', label: "Correction : premier bloc quand il n'y a pas de paragraphe" },
];
function excerpt(article, version) {
if (version === 'trycatch') {
try {
return article.blocks.find((b) => b.type === 'paragraph').text;
} catch {
return '';
}
}
if (version === 'agent') {
return article.blocks.find((b) => b.type === 'paragraph').text;
}
const block = article.blocks.find((b) => b.type === 'paragraph') ?? article.blocks[0];
return block ? block.text : '';
}
// Limite d'erreur comme dans la leçon. Au lieu de Sentry.captureException, elle appelle onReport.
class ErrorBoundary extends Component {
state = { hasError: false };
static getDerivedStateFromError() {
return { hasError: true };
}
componentDidCatch(error, info) {
this.props.onReport(error, info.componentStack);
}
render() {
if (this.state.hasError) return this.props.fallback;
return this.props.children;
}
}
function ArticleList({ articles, version }) {
return (
<ul className="space-y-3">
{articles.map((article) => {
const lead = excerpt(article, version);
return (
<li key={article.id}>
<p className="font-semibold">{article.title}</p>
{lead ? (
<p className="text-gray-700">{lead}</p>
) : (
<p className="italic text-amber-700">(extrait vide)</p>
)}
</li>
);
})}
</ul>
);
}
export default function App() {
const [maryQuote, setMaryQuote] = useState(false);
const [version, setVersion] = useState('agent');
const [reports, setReports] = useState([]);
const [attempt, setAttempt] = useState(0);
const articles = ARTICLES.map((a) => ({
id: a.id,
title: a.title,
blocks: [{ type: a.id === 'a3' && maryQuote ? 'quote' : 'paragraph', text: a.text }],
}));
function report(error, componentStack) {
const match = /at (\w+)/.exec(componentStack || '');
setReports((list) =>
[{ n: list.length ? list[0].n + 1 : 1, name: error.name, message: error.message, component: match ? match[1] : '?' }, ...list].slice(0, 3),
);
}
return (
<div className="min-h-screen bg-gray-50 p-4 text-gray-900">
<div className="mx-auto max-w-xl space-y-4 rounded-xl bg-white p-4 shadow-sm">
<header>
<h1 className="text-2xl font-bold">Chroniques du Cap et la Cambuse</h1>
<p className="text-sm text-gray-500">Page de publication : titres avec extraits</p>
</header>
<ErrorBoundary
key={attempt + '-' + version + '-' + maryQuote}
onReport={report}
fallback={
<div role="alert" className="rounded bg-red-50 p-3 text-red-800">
Cette page a perdu le cap. Le lecteur voit ce message à la place de la liste.
</div>
}
>
<ArticleList articles={articles} version={version} />
</ErrorBoundary>
</div>
<div className="mx-auto mt-3 max-w-xl space-y-2 rounded-xl bg-gray-900 p-4 text-sm text-white">
<label className="flex items-center gap-2">
<input type="checkbox" checked={maryQuote} onChange={(e) => {
setMaryQuote(e.target.checked);
setReports([]);
}} />
Mary transforme l'unique paragraphe du texte a3 en citation
</label>
<fieldset className="space-y-1">
<legend className="font-semibold">Fonction excerpt</legend>
{VERSIONS.map((v) => (
<label key={v.key} className="flex items-center gap-2">
<input type="radio" name="version" checked={version === v.key} onChange={() => {
setVersion(v.key);
setReports([]);
}} />
{v.label}
</label>
))}
</fieldset>
<button type="button" onClick={() => setAttempt((n) => n + 1)} className="rounded bg-gray-700 px-3 py-1">
Actualiser la page
</button>
</div>
<div className="mx-auto mt-3 max-w-xl space-y-2 rounded-xl bg-white p-4 text-sm shadow-sm">
<p className="font-semibold">Faux Sentry : {reports.length ? 'alarme !' : 'silence'}</p>
{reports.length === 0 && (
<p className="text-gray-500">Aucun signalement. Le silence ne veut pas dire que tout fonctionne : vérifie les extraits ci-dessus.</p>
)}
<ul className="space-y-1">
{reports.map((r) => (
<li key={r.n} className="rounded bg-red-50 p-2 text-red-900">
#{r.n} {r.name}: {r.message} (composant : {r.component})
</li>
))}
</ul>
</div>
</div>
);
}Tu as repéré une erreur dans cette leçon ?
Teste tes connaissances
Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.
1. L'assistant Sentry te connecte dans le navigateur, pose des questions et enregistre un jeton pour envoyer les cartes source. Comment le lances-tu ?
2. Dans quelle méthode d'un ErrorBoundary de type classe envoies-tu le rapport à Sentry ?
Tâches pratiques dans le jeu
- Éditeur de code
Error Boundary avec envoi de rapports à Sentry
- Tri vertical
Ordonne ce qui se passe dans un ErrorBoundary de type classe quand un composant à l'intérieur lève une erreur pendant le rendu :