Kurs vibe coding z Claude Code · Moduł 12: Klon Medium
Wartownik na maszcie: błędy z produkcji, Sentry i MCP
W tej lekcji11
Po lekcji 11_3 poprosiłeś Claude o zajawki, czyli początek tekstu pod każdym tytułem na stronie publikacji: "Pod tytułami pokaż pierwszy akapit, najwyżej 160 znaków, funkcja excerpt w lib/excerpt.ts". Jeśli jeszcze go nie wydałeś, zrób to teraz. Lint i build przeszły, commit poszedł. Tydzień później Mary Read zmieniła jedyny akapit swojego tekstu w Kambuzie na cytat. Od tej chwili strona /publikacje/kambuz odpowiada każdemu czytelnikowi błędem 500, a Ty nic o tym nie wiesz, bo u Ciebie wszystko działa. Czytelnik nie pisze zgłoszenia, tylko odpływa. Potrzebujesz wartownika na maszcie: usługi, która widzi każdy błąd na produkcji i od razu podnosi alarm.
Czego się nauczysz
- podłączyć Sentry kreatorem i przeczytać w Cursorze każdy plik, który dopisał;
- trzymać token Sentry poza rozmową z Claude i poza repozytorium;
- debugować błąd z produkcji z Claude Code: przyczyna, test, który go odtwarza, dopiero potem poprawka;
- odróżnić
error.tsx,global-error.tsxi własnyErrorBoundary; - podłączyć serwer MCP Sentry i wiedzieć, kiedy wystarczy zwykłe CLI.
Kreator Sentry uruchamiasz sam
Sentry zbiera błędy z aplikacji razem ze śladem stosu, czyli listą funkcji, plików i linii, przez które przeszedł program, zanim upadł. Potrzebujesz własnego konta i projektu w Sentry. Oficjalny przewodnik dla Next.js zaleca kreator (stan na listopad 2026):
npx @sentry/wizard@latest -i nextjsTę komendę wpisujesz sam, w osobnej karcie terminala w Cursorze. Kreator loguje Cię w przeglądarce, pyta o śledzenie wydajności, nagrania sesji i stronę przykładową, a na koniec zapisuje token. Z lekcji 8_5 wiesz, że wynik komendy z ! trafia do rozmowy z Claude, a tu nie ma nic, co Claude musiałby zobaczyć.
Według dokumentacji Sentry kreator zapisuje token w pliku .env.sentry-build-plugin i dopisuje ten plik do .gitignore. Tym tokenem build wysyła do Sentry mapy źródłowe, czyli pliki, które tłumaczą skompilowany kod z powrotem na Twoje pliki i linie. Token to sekret. Inaczej jest z DSN, adresem, pod który SDK wysyła błędy: trafia do przeglądarki każdego czytelnika, więc tajemnicą nie jest. Reguła Read(./.env.*) z lekcji 8_4 obejmuje też plik z tokenem, bo gwiazdka pasuje do każdej nazwy po .env.. Jeśli ten projekt jej jeszcze nie ma, skopiuj reguły do .claude/settings.json przed uruchomieniem kreatora.
Co dopisał kreator
Otwórz panel Source Control w Cursorze i przeczytaj diff plik po pliku, zanim zrobisz commit. Kreator tworzy trzy pliki startowe, bo Next.js uruchamia kod w trzech środowiskach: instrumentation-client.ts dla przeglądarki, sentry.server.config.ts dla Node.js i sentry.edge.config.ts dla środowiska Edge. Plik przeglądarki wygląda tak:
// 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;Kreator wpisuje DSN wprost, a dokumentacja pozwala też na zmienną publiczną NEXT_PUBLIC_SENTRY_DSN. tracesSampleRate mówi, jaką część zapytań Sentry zapisuje jako ślady wydajności. Kreator wpisuje 1, czyli wszystkie, a dokumentacja zaleca zmniejszyć tę wartość na produkcji i pokazuje 0.1. Błędów to nie dotyczy: dla nich osobna opcja sampleRate domyślnie wysyła każdy. Najważniejszy jest jednak 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 ładuje konfigurację właściwą dla środowiska. onRequestError to haczyk Next.js, który według dokumentacji Sentry łapie błędy z Server Components, tras API i middleware, czyli dokładnie taki błąd, jaki wywołała zmiana Mary. Dalej w diffie: app/global-error.tsx z Sentry.captureException w useEffect i next.config.ts owinięty w withSentryConfig z @sentry/nextjs/config, który przy buildzie wysyła mapy.
Pierwszy alarm
Dokumentacja każe sprawdzić instalację na stronie /sentry-example-page od kreatora: przycisk "Throw Sample Error" rzuca błąd w przeglądarce i na serwerze. Potem odtwórz prawdziwy przypadek: w lib/articles.ts zmień typ jedynego bloku tekstu a3 z "paragraph" na "quote", uruchom npm run build && npm start i otwórz /publikacje/kambuz.
Nie mieliśmy konta Sentry, więc DSN wskazał lokalny odbiornik, który udawał Sentry. Dostał zgłoszenie: TypeError: Cannot read properties of undefined (reading 'text'), mechanizm auto.function.nextjs.on_request_error, trasa /publikacje/[slug]. Ramki śladu wskazywały plik _next/server/chunks/ssr/...js, linię 2: tak wygląda ślad bez map źródłowych. W npm run dev ten sam błąd w terminalu wskazał Twój kod:
⨯ TypeError: Cannot read properties of undefined (reading 'text')
at excerpt (lib/excerpt.ts:5:54)
at <unknown> (app/publikacje/[slug]/page.tsx:20:18)Z mapami źródłowymi Sentry pokazuje w śladzie Twoje pliki i linie, dlatego token z kreatora jest wart zachodu.
Polecenie dla Claude Code: najpierw przyczyna
Kolejność znasz z lekcji 2_8 i 4_1: przyczyna, test, który zawodzi, dopiero potem poprawka.
Polecenie dla Claude Code:
Sentry: /publikacje/kambuz zwraca 500, odkąd jedyny akapit tekstu a3
stał się cytatem. Ślad:
TypeError: Cannot read properties of undefined (reading 'text')
at excerpt (lib/excerpt.ts:5:54)
at <unknown> (app/publikacje/[slug]/page.tsx:20:18)
Najpierw opisz przyczynę, nie zmieniaj kodu. Potem dopisz do
lib/excerpt.test.ts test, który odtwarza błąd, uruchom go i pokaż,
że nie przechodzi. Poprawkę napisz dopiero po moim "ok": tekst bez
akapitu dostaje zajawkę z pierwszego bloku, tekst bez bloków pustą.Co napisał Claude: test i poprawka
Przyczyna mieści się w jednym zdaniu: excerpt zakłada, że każdy tekst ma akapit, a znak ! za find(...) obiecuje TypeScriptowi, że coś się znajdzie. Ta obietnica przeszła u nas npm run lint i npx tsc --noEmit. Otwórz w Cursorze lib/excerpt.test.ts:
// lib/excerpt.test.ts
test("wiersz z samych cytatów: zajawka z pierwszego cytatu", () => {
const poem = article([{ id: "q1", type: "quote", text: "Gwiazdy są zegarem." }]);
expect(excerpt(poem)).toBe("Gwiazdy są zegarem.");
});article to pomocnicza funkcja testu, która bierze przykładowy artykuł i podmienia mu bloki. Przed poprawką test oblał z tym samym TypeError co produkcja, więc naprawdę odtwarza błąd. Po Twoim "ok" Claude zmienił funkcję:
// 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;
}?? bierze pierwszy blok dowolnego typu, gdy akapitu nie ma, a pusty artykuł dostaje pustą zajawkę. Oba przypadki to decyzje, które sam podjąłeś w poleceniu, i oba mają test. U nas po poprawce przeszły wszystkie testy.
Typowy błąd agenta: try/catch, który gasi alarm
Zamiast przyczyny agent potrafi uciszyć objaw:
// lib/excerpt.ts (wersja agenta)
try {
const text = article.blocks.find((b) => b.type === "paragraph")!.text;
return text.length > max ? text.slice(0, max - 1).trimEnd() + "…" : text;
} catch {
return "";
}U nas ta wersja przeszła lint i tsc, a strona Kambuza odpowiadała 200 z pustą zajawką. Do Sentry nic by nie dotarło, bo według jego dokumentacji błąd złapany i nie rzucony dalej nigdy tam nie trafia. Prawdę powiedział dopiero test: expected '' to be 'Gwiazdy są zegarem.'. Puste catch to wartownik, który zasnął na maszcie.
Trzy straże: error.tsx, global-error.tsx i ErrorBoundary
Błąd w czasie rysowania strony łapie granica błędu (error boundary): komponent, który zamiast pękniętej części pokazuje tekst zastępczy. Next.js daje dwie gotowe. error.tsx w folderze trasy obejmuje jej stronę i zagnieżdżone layouty. global-error.tsx to ostatnia linia obrony, gdy pęknie layout główny, dlatego ma własne <html> i <body>. Dokumentacja Sentry ostrzega: błąd złapany przez error.tsx nie dociera do Sentry sam, więc każda taka granica woła Sentry.captureException.
Własną granicę stawiasz wokół jednej części strony, żeby jej awaria nie zabrała reszty. Dokumentacja Reacta mówi, że granicę pisze się jako klasę z dwiema metodami: static getDerivedStateFromError zmienia stan, żeby pokazać tekst zastępczy, a componentDidCatch służy do wysłania raportu:
// 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;
}
}Plik zaczyna się od "use client", a Props to fallback i children. Test z komponentem, który rzuca błąd, pokazał u nas kolejność: getDerivedStateFromError ustawia hasError, render rysuje tekst zastępczy, a dopiero potem React woła componentDidCatch. Na stronie artykułu granica obejmuje oklaski, więc ich awaria nie zabiera tekstu:
// app/artykuly/[id]/page.tsx
<ErrorBoundary fallback={<p className="text-sm text-gray-500">Oklaski chwilowo nie działają.</p>}>
<ClapButton articleId={article.id} initial={claps} />
</ErrorBoundary>Dwie granice tej granicy, też z dokumentacji Reacta: nie łapie błędów w obsłudze zdarzeń (na przykład w onClick) ani w kodzie asynchronicznym, a w wersji produkcyjnej błąd złapany w componentDidCatch nie idzie wyżej. Bez captureException Sentry by go nie zobaczył. Next.js od wersji 16.3 ma też catchError z next/error, który dokłada retry i przepuszcza notFound(), ale klasa z Reacta to fundament, który ćwiczysz w zadaniu.
Wartownik w rozmowie: serwer MCP Sentry
Do tej pory kopiowałeś ślad z Sentry do polecenia. MCP (Model Context Protocol) to otwarty standard, przez który Claude Code łączy się z innymi narzędziami: serwer MCP daje Claude narzędzia do czytania i działania w innym systemie. Dokumentacja Claude Code radzi podłączyć serwer właśnie wtedy, gdy łapiesz się na wklejaniu danych z innego narzędzia, na przykład z panelu monitoringu. Strona serwera Sentry (mcp.sentry.dev) wymienia wyszukiwanie błędów, analizę wydajności, triaż problemów, czytanie dokumentacji i zarządzanie projektami. Polecenie wpisujesz w terminalu, w folderze projektu:
claude mcp add --transport http --scope project sentry https://mcp.sentry.dev/mcp/twoja-organizacja/captains-chronicle--transport http to według dokumentacji zalecany sposób łączenia ze zdalnym serwerem. Dwa ostatnie człony adresu zawężają serwer do jednej organizacji i jednego projektu, co strona Sentry zaleca. Zakres decyduje, gdzie trafia konfiguracja: local (domyślny) tylko dla Ciebie i tego projektu w ~/.claude.json, user dla wszystkich Twoich projektów w tym samym pliku, project do pliku .mcp.json w repozytorium, dla całej załogi. Wybierasz project, bo plik zawiera sam adres, bez tokenu. U nas powstał taki .mcp.json:
{
"mcpServers": {
"sentry": {
"type": "http",
"url": "https://mcp.sentry.dev/mcp/twoja-organizacja/captains-chronicle"
}
}
}claude mcp list pokazał przy serwerze ⏸ Pending approval z prośbą o uruchomienie claude: serwer z .mcp.json czeka, aż zatwierdzisz go w sesji, bo sklonowane repozytorium nie może włączyć sobie serwerów samo. W sesji /mcp pokazuje status serwerów, prowadzi przez logowanie OAuth w przeglądarce, pozwala wyłączyć serwer i wyczyścić logowanie. Każdy z załogi loguje się własnym kontem, więc Claude widzi w Sentry tylko to, do czego ma dostęp Twoje konto. Teraz pytasz:
Pobierz z Sentry nierozwiązane błędy z ostatnich 24 godzin. Dla
każdego podaj tytuł, liczbę wystąpień i pliki z naszego repozytorium,
których dotyczy ślad. Niczego nie zmieniaj.Każdy wskazany plik otwierasz w Cursorze i porównujesz z raportem. Komunikaty błędów potrafią zawierać tekst wpisany przez obcych ludzi, a dokumentacja Claude Code ostrzega przed wstrzykiwaniem poleceń przez serwery, które czytają treści z zewnątrz. To dane do przeczytania, nie rozkazy.
Najpierw jednak zapytaj, czy MCP w ogóle jest potrzebny. Dobre praktyki Claude Code mówią: jeśli system ma CLI, to zwykle najprostsza droga, a MCP jest dla systemów bez niego. Do GitHuba wystarczy gh, które Claude uruchamia jak każdą komendę. Sentry ma też własne CLI (sentry, opis na cli.sentry.dev), więc i tu masz wybór. Zdalny serwer MCP nie wymaga instalowania niczego na komputerze.
Przegląd kapitana
- Sekret poza repozytorium.
git statusnie pokazuje.env.sentry-build-plugin, a w diffie nie ma tokenu. - Próbkowanie.
tracesSampleRatena produkcji nie zostało na 1. - Test przed poprawką. Test zajawki oblał przed zmianą i przechodzi po niej. Test, który od razu przechodzi, niczego nie dowodzi.
- Nic nie wyciszone. Wyszukaj w projekcie (Cmd+Shift+F)
catch: każde nowecatchalbo rzuca błąd dalej, albo wołaSentry.captureException. - Granice raportują. Każde
error.tsxi każdyErrorBoundaryzawieracaptureException.
Następny krok
Poproś o commit "Sentry, zajawka bez akapitu i ErrorBoundary przy oklaskach". Potem: "Dodaj @app/artykuly/[id]/error.tsx z przyciskiem Spróbuj ponownie przez retry i z Sentry.captureException w useEffect", jak w lekcji 3_4. W edytorze poniżej czeka strona publikacji z udawanym Sentry: wywołaj błąd zajawki, włącz błąd agenta "ukryj błąd w try/catch" i porównaj, co widzi czytelnik, a co wartownik.
Zapamiętaj: wartownik nie naprawia statku, ale bez niego nikt nie wie, że woda już leje się do ładowni.
Kod do tej lekcji: App.jsx
// Strona publikacji z udawanym Sentry: zajawki, granica błędu i błąd agenta try/catch
import { Component, useState } from 'react';
const ARTICLES = [
{ id: 'a1', title: 'Jak przetrwać sztorm na Atlantyku', text: 'Sztorm przyszedł nocą, a załoga spała po długiej wachcie.' },
{ id: 'a2', title: 'Mapa skarbów, której nie było', text: 'Mapa miała trzy krzyżyki i żadnego skarbu.' },
{ id: 'a3', title: 'Kucharz okrętowy radzi: suchary na sześć tygodni', text: 'Suchar musi być twardy jak pokład, inaczej nie przetrwa rejsu.' },
];
const VERSIONS = [
{ key: 'agent', label: 'Wersja z ! (akapit jest zawsze)' },
{ key: 'trycatch', label: 'Błąd agenta: ukryj błąd w try/catch' },
{ key: 'fixed', label: 'Poprawka: pierwszy blok, gdy nie ma akapitu' },
];
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 : '';
}
// Granica błędu jak w lekcji. Zamiast Sentry.captureException woła 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">(pusta zajawka)</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">Kroniki Przylądka i Kambuz</h1>
<p className="text-sm text-gray-500">Strona publikacji: tytuły z zajawkami</p>
</header>
<ErrorBoundary
key={attempt + '-' + version + '-' + maryQuote}
onReport={report}
fallback={
<div role="alert" className="rounded bg-red-50 p-3 text-red-800">
Ta strona zgubiła kurs. Czytelnik widzi ten komunikat zamiast listy.
</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 zmienia jedyny akapit tekstu a3 na cytat
</label>
<fieldset className="space-y-1">
<legend className="font-semibold">Funkcja 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">
Odśwież stronę
</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">Udawany Sentry: {reports.length ? 'alarm!' : 'cisza'}</p>
{reports.length === 0 && (
<p className="text-gray-500">Brak zgłoszeń. Cisza nie znaczy, że wszystko działa: sprawdź zajawki powyżej.</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} (komponent: {r.component})
</li>
))}
</ul>
</div>
</div>
);
}Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Kreator Sentry loguje Cię w przeglądarce, zadaje pytania i zapisuje token do wysyłania map źródłowych. Jak go uruchamiasz?
2. W której metodzie klasowego ErrorBoundary wysyłasz raport do Sentry?
Zadania praktyczne w grze
- Edytor kodu
Error Boundary z raportowaniem do Sentry
- Układanie w pionie
Uporządkuj, co dzieje się w klasowym ErrorBoundary, gdy komponent w jego środku rzuci błąd podczas rysowania: