Kurs vibe coding z Claude Code · Moduł 12: Klon Medium

Edytor kroniki: plan, bloki i autozapis

9 min czytania
W tej lekcji9

Ahoj! Kapitan prowadzi dziennik od lat, ale kartki mokną, a wpisy z rejsów giną w skrzyni. Załoga chce czytać jego opowieści w sieci, więc w tej lokacji budujesz Captain's Chronicle, klon Medium, czyli platformy do długich tekstów. Zaczynasz od edytora, bo kronika to nie wpis na kilka zdań. Ma tytuł, akapity, śródtytuły i cytaty, a kapitan pisze ją godzinami. Jeśli karta przeglądarki zamknie się po godzinie pisania, tekst nie może przepaść.

Czego się nauczysz

  • zamówić dużą funkcję w trybie planowania i sprawdzić plan, zanim powstanie kod;
  • przeczytać w Cursorze typy bloków i funkcje, które zmieniają listę bez zgadywania;
  • znaleźć autozapis, który nigdy nie zapisuje, i udowodnić poprawkę testem z udawanym zegarem;
  • pilnować nowych zależności jedną linią w CLAUDE.md.

Nowy port: projekt captains-chronicle

Kronika to osobna aplikacja, więc zakładasz ją poleceniem z lekcji 1_2, zmieniając tylko nazwę. Porównaj komendę z tą, zanim klikniesz Yes:

npx create-next-app@latest captains-chronicle --ts --eslint --tailwind --app --no-src-dir --no-cache-components --agents-md --no-agent-feedback --use-npm

Dalej znana pętla: sesja claude w folderze captains-chronicle, CLAUDE.md z importem @AGENTS.md (lekcja 1_7), Vitest z poprawką @types/node z lekcji 4_1 i pierwszy commit. Do sekcji konwencji w CLAUDE.md dopisz jedną linię, bo edytor tekstu to miejsce, w którym agent chętnie sięga po gotową paczkę:

- Nowe zależności tylko po mojej zgodzie: zapytaj, zanim dopiszesz paczkę do package.json.

Gotowy edytor z npm to setki linii cudzego kodu, własny format zapisu i aktualizacje, których nie planowałeś. Bywa dobrym wyborem, ale to ma być Twoja decyzja, a nie skutek uboczny jednego polecenia.

Polecenie dla Claude Code

Artykuł to lista bloków: akapit, nagłówek albo cytat. Każdy blok ma identyfikator, typ i tekst. Krok dotknie typów, funkcji, komponentu, strony i hooka, czyli funkcji Reacta z własnym stanem, więc zaczynasz od planu, jak w lekcji 1_6. W trybie planowania Claude czyta projekt i pisze plan, ale nie zmienia plików, dopóki go nie zatwierdzisz. Na końcu stoi kryterium ukończenia z lekcji 10_1.

Polecenie dla Claude Code:

/plan Dodaj do Captain's Chronicle edytor artykułów na stronie /pisz.
Artykuł to lista bloków: paragraph, heading, quote; blok ma id, typ
i tekst. Typy w types/article.ts, funkcje bloków w lib/blocks.ts,
komponent components/ArticleEditor.tsx. Nad tytułem czas czytania
(200 słów na minutę). Autozapis szkicu do localStorage co 30 sekund,
także wtedy, gdy piszę bez przerwy. Bez nowych paczek. Zaproponuj
podział na pliki i kolejność kroków, jeszcze bez kodu.
Będzie gotowe, gdy testy Vitest pokażą: pusty artykuł to 0 minut,
nowy blok trafia za wskazany blok, autozapis zapisuje po 30 sekundach
ciągłego pisania. Potem npm run lint, npx tsc --noEmit i npm run build.

W planie sprawdź dwie rzeczy: skąd blok dostaje identyfikator i co restartuje zegar autozapisu. Jeśli plan o tym milczy, naciśnij Ctrl+G, który otwiera plan w edytorze, i dopisz to, albo wybierz "No, keep planning" i dopytaj. Gdy plan pasuje, wybierz "Yes, manually approve edits": każdą edycję zobaczysz przed zapisaniem.

Co napisał Claude: typy bloków

Otwórz w Cursorze types/article.ts. Typ bloku to jedna z trzech nazw, więc literówka w rodzaju "qoute" nie przejdzie przez kompilator:

// types/article.ts
export type BlockType = "paragraph" | "heading" | "quote";

export interface ArticleBlock {
  id: string;
  type: BlockType;
  text: string;
}

Niżej w tym samym pliku stoi Draft, czyli identyfikator, tytuł i lista bloków. Szkic zapisany w przeglądarce dostaje jeszcze datę zapisu:

// types/article.ts
export interface SavedDraft extends Draft {
  savedAt: string; // "2026-11-15T09:30:00.000Z": JSON zamienia Date na napis
}

savedAt jest napisem, bo według MDN JSON.stringify zamienia datę na tekst w formacie ISO, a JSON.parse sam nie zrobi z niego daty. Ten haczyk znasz z lekcji 2_3: typ Date w danych z localStorage kłamie, a TypeScript tego nie wyłapie.

Co napisał Claude: bloki bez zgadywania

Otwórz lib/blocks.ts. Każdy nowy blok dostaje identyfikator od przeglądarki:

// lib/blocks.ts
export function newBlock(type: BlockType = "paragraph"): ArticleBlock {
  return { id: crypto.randomUUID(), type, text: "" };
}

crypto.randomUUID() zwraca losowy identyfikator długości 36 znaków. Dokumentacja Reacta poleca go do danych tworzonych lokalnie jako źródło kluczy listy. MDN dodaje warunek: działa tylko w bezpiecznym kontekście, czyli przez HTTPS albo na localhost. Wstawianie za wskazanym blokiem buduje nową tablicę z trzech kawałków:

// lib/blocks.ts
export function addBlockAfter(blocks: ArticleBlock[], afterId: string, block: ArticleBlock): ArticleBlock[] {
  const index = blocks.findIndex((b) => b.id === afterId);
  if (index === -1) return [...blocks, block];
  return [...blocks.slice(0, index + 1), block, ...blocks.slice(index + 1)];
}

slice kopiuje część listy przed miejscem wstawienia i część za nim, więc stara tablica zostaje nietknięta, a React dostaje nową. Gdy bloku o takim id nie ma, nowy trafia na koniec zamiast przepaść. Czas czytania liczy słowa ze wszystkich bloków:

// lib/blocks.ts
export function readingTime(blocks: ArticleBlock[]): number {
  const words = blocks.flatMap((b) => b.text.split(/\s+/)).filter(Boolean).length;
  return Math.ceil(words / WORDS_PER_MINUTE);
}

split(/\s+/) tnie tekst na spacjach i końcach linii, a filter(Boolean) wyrzuca puste kawałki. Bez tego filtra pusty blok liczy się jako jedno słowo, bo "".split(" ") daje tablicę z jednym pustym napisem, i nowy artykuł pokazuje "1 min czytania". Math.ceil zaokrągla w górę, więc 201 słów to 2 minuty.

Co napisał Claude: edytor

components/ArticleEditor.tsx trzyma stan, więc zaczyna się od dyrektywy z lekcji 2_3:

// components/ArticleEditor.tsx
"use client";

import { useState } from "react";

Dokumentacja Reacta mówi, że 'use client' musi stać na samym początku pliku, nad importami; wyżej wolno tylko komentarzom. Zmiana tekstu jednego bloku wygląda tak:

// components/ArticleEditor.tsx
function updateText(id: string, text: string) {
  setBlocks((prev) => prev.map((b) => (b.id === id ? { ...b, text } : b)));
}

prev => ... to funkcja aktualizująca: dostaje najświeższą listę bloków, a nie tę zapamiętaną przy ostatnim renderze. Dokumentacja Reacta pokazuje różnicę na liczniku: trzy razy setAge(age + 1) w jednej funkcji daje 43, a nie 45, bo każde wywołanie widzi ten sam stary stan. Pole tekstowe bloku ma takie klasy:

// components/ArticleEditor.tsx
className={`w-full resize-none rounded outline-hidden focus:bg-amber-50 ${BLOCK_STYLES[block.type]}`}

outline-hidden to w Tailwindzie 4 następca dawnego outline-none: chowa obwódkę fokusu, ale zostawia ją w trybie wymuszonych kolorów systemu. Dokumentacja Tailwinda zaleca wtedy własny styl fokusu, stąd focus:bg-amber-50. outline-none w wersji 4 ustawia outline-style: none i zabiera obwódkę wszystkim.

Autozapis, który nigdy nie zapisuje

Pierwszy autozapis od agenta wygląda niewinnie. Otwórz hooks/useAutosave.ts:

// hooks/useAutosave.ts (wersja agenta)
useEffect(() => {
  const id = setTimeout(() => {
    setSavedAt(saveDraft(draft).savedAt);
  }, AUTOSAVE_MS);
  return () => clearTimeout(id);
}, [draft]);

Każdy klawisz zmienia draft, więc React sprząta stary zegar i nastawia nowy na pełne 30 sekund. To debounce z lekcji 3_5: dobry dla wyszukiwarki, która czeka na ciszę, i zły dla autozapisu, bo przy ciągłym pisaniu cisza nie nadchodzi. U nas ta wersja przeszła lint i tsc. Złapał ją dopiero test z udawanym zegarem, w którym funkcja draft(text) buduje szkic z jednym blokiem:

// hooks/useAutosave.test.ts
test("zapisuje po 30 s, choć kapitan pisze bez przerwy", () => {
  const { rerender } = renderHook(({ d }) => useAutosave(d), { initialProps: { d: draft("A") } });
  let text = "A";
  for (let second = 1; second <= 31; second++) {
    text += "h";
    rerender({ d: draft(text) });
    act(() => vi.advanceTimersByTime(1000));
  }
  expect(loadDrafts()).toHaveLength(1);
  expect(loadDrafts()[0].blocks[0].text).toBe("A" + "h".repeat(30));
});

vi.useFakeTimers() w beforeEach podmienia zegary, a vi.advanceTimersByTime(1000) według dokumentacji Vitest uruchamia każdy zegar, którego czas minął w ciągu podanych milisekund. Pętla to 31 sekund pisania, litera co sekundę. Wersja agenta oblała z komunikatem expected [] to have a length of 1 but got +0. Kusząca "poprawka", czyli setInterval z pustą tablicą zależności, oblała drugą linię komunikatem zaczynającym się od expected 'A' to be 'Ahhh: zegar zapamiętał szkic z pierwszego renderu, a lint dał tylko ostrzeżenie react-hooks/exhaustive-deps. Przeszła ta wersja:

// hooks/useAutosave.ts
const saveIfChanged = useEffectEvent(() => {
  const json = JSON.stringify(draft);
  if (json === lastSaved.current) return;
  lastSaved.current = json;
  setSavedAt(saveDraft(draft).savedAt);
});

useEffect(() => {
  const id = setInterval(() => saveIfChanged(), AUTOSAVE_MS);
  return () => clearInterval(id);
}, []);

useEffectEvent to hook Reacta na logikę, która ma widzieć najnowsze propsy i stan, ale nie ma restartować efektu. Dokumentacja pokazuje go właśnie z setInterval. Zegar rusza raz, a co 30 sekund zapisuje aktualny szkic, jeśli zmienił się od ostatniego zapisu; lastSaved to useRef z tekstem poprzedniego zapisu. localStorage pojawia się tylko w tym zegarze, nigdy w trakcie rysowania, bo przy renderze na serwerze go nie ma.

Przegląd kapitana

  1. Identyfikatory. Wyszukaj w projekcie (Cmd+Shift+F) Date.now. Agent lubi id: Date.now().toString(): u nas pięć wywołań w jednej pętli dało pięć razy ten sam numer. Dwa bloki z jednym id funkcja updateText zmienia naraz.
  2. Aktualizacje funkcyjne. Każde setBlocks( w edytorze ma w środku prev =>.
  3. Pusta kronika. Nowy artykuł pokazuje "0 min czytania", nie "1 min".
  4. Dyrektywa. Gdy Claude wstawi "use client" pod importami, build kończy się błędem The "use client" directive must be placed before other expressions.
  5. Zależności. W panelu Source Control otwórz package.json. Paczka edytora dopisana bez pytania łamie zasadę z CLAUDE.md: zapytaj Claude, po co mu ona, albo cofnij ją przez /rewind z lekcji 0_6.

Ostatni dowód zbierasz w przeglądarce: npm run dev, strona /pisz, pisz bez przerwy, a po pół minucie pod tytułem pojawi się "zapisano o" z godziną. U nas tak było, a w localStorage leżał szkic z savedAt jako napisem.

Następny krok

Gdy testy i przeglądarka się zgadzają, poproś o commit "Edytor blokowy z autozapisem". Potem małe polecenie, znowu z planem: "Enter na końcu bloku tworzy pod nim nowy akapit. Najpierw plan." Lista zapisanych szkiców, która czyta localStorage wzorcem z lekcji 2_3, czeka w zadaniu praktycznym. W edytorze poniżej jest edytor w miniaturze z udawanym zegarem: pisz bez przerwy i przełącz wersję agenta, a zobaczysz, jak jej odliczanie co chwilę wraca do 30.

Zapamiętaj: kapitan nie wbija desek bez planu okrętu, a dziennik pokładowy ma zapisywać się w trakcie sztormu, a nie dopiero wtedy, gdy wiatr ucichnie.

Kod do tej lekcji: App.jsx
// Edytor kroniki w miniaturze: bloki, czas czytania i autozapis z udawanym zegarem
import { useEffect, useReducer } from 'react';

const AUTOSAVE_S = 30;
const WORDS_PER_MINUTE = 200;
const LABELS = { paragraph: 'Akapit', heading: 'Nagłówek', quote: 'Cytat' };
const STYLES = {
  paragraph: 'text-base',
  heading: 'text-xl font-bold',
  quote: 'border-l-4 border-gray-300 pl-3 italic',
};

let nextId = 1;
function newBlock(type = 'paragraph') {
  return { id: 'b' + nextId++, type, text: '' };
}

function addBlockAfter(blocks, afterId, block) {
  const index = blocks.findIndex((b) => b.id === afterId);
  if (index === -1) return [...blocks, block];
  return [...blocks.slice(0, index + 1), block, ...blocks.slice(index + 1)];
}

function countWords(blocks) {
  return blocks.flatMap((b) => b.text.split(/\s+/)).filter(Boolean).length;
}

function readingTime(blocks) {
  return Math.ceil(countWords(blocks) / WORDS_PER_MINUTE);
}

function formatClock(s) {
  return Math.floor(s / 60) + ':' + String(s % 60).padStart(2, '0');
}

const initialState = {
  title: '',
  blocks: [newBlock()],
  now: 0, // sekundy udawanego zegara
  lastChange: null, // sekunda ostatniej zmiany tekstu
  savedJson: null,
  saves: [],
  agentBug: false,
  typing: false,
};

function snapshot(state) {
  return JSON.stringify({ title: state.title, blocks: state.blocks });
}

function changeText(state, blocks, title) {
  return { ...state, blocks, title, lastChange: state.now };
}

// Reducer zawsze widzi najnowszy stan, więc zegar nie zapamiętuje starego szkicu
function reducer(state, action) {
  switch (action.type) {
    case 'title':
      return changeText(state, state.blocks, action.value);
    case 'text':
      return changeText(state, state.blocks.map((b) => (b.id === action.id ? { ...b, text: action.value } : b)), state.title);
    case 'type':
      return changeText(state, state.blocks.map((b) => (b.id === action.id ? { ...b, type: action.value } : b)), state.title);
    case 'add':
      return changeText(state, addBlockAfter(state.blocks, action.id, newBlock()), state.title);
    case 'agentBug':
      return { ...state, agentBug: action.value };
    case 'typing':
      return { ...state, typing: action.value };
    case 'tick': {
      let next = { ...state, now: state.now + 1 };
      if (state.typing) {
        const last = next.blocks[next.blocks.length - 1];
        next = changeText(next, next.blocks.map((b) => (b.id === last.id ? { ...b, text: b.text + (b.text ? ' ' : '') + 'fala' } : b)), next.title);
      }
      const changed = next.lastChange !== null && snapshot(next) !== next.savedJson;
      // Wersja agenta: zegar od ostatniego klawisza (debounce). Poprawka: co 30 s od startu.
      const due = next.agentBug ? next.now - next.lastChange >= AUTOSAVE_S : next.now % AUTOSAVE_S === 0;
      if (changed && due) {
        return {
          ...next,
          savedJson: snapshot(next),
          saves: [{ at: next.now, words: countWords(next.blocks) }, ...next.saves].slice(0, 4),
        };
      }
      return next;
    }
    default:
      return state;
  }
}

export default function App() {
  const [state, dispatch] = useReducer(reducer, initialState);
  const [fast, setFast] = useReducer((v) => !v, false);

  useEffect(() => {
    const id = setInterval(() => dispatch({ type: 'tick' }), fast ? 200 : 1000);
    return () => clearInterval(id);
  }, [fast]);

  const minutes = readingTime(state.blocks);
  const secondsLeft = state.agentBug
    ? state.lastChange === null
      ? AUTOSAVE_S
      : AUTOSAVE_S - (state.now - state.lastChange)
    : AUTOSAVE_S - (state.now % AUTOSAVE_S);

  return (
    <div className="min-h-screen bg-gray-50 p-4 text-gray-900">
      <div className="mx-auto max-w-xl space-y-3 rounded-xl bg-white p-4 shadow-sm">
        <p className="text-sm text-gray-500">{minutes} min czytania · {countWords(state.blocks)} słów</p>
        <input
          aria-label="Tytuł"
          value={state.title}
          onChange={(e) => dispatch({ type: 'title', value: e.target.value })}
          placeholder="Tytuł kroniki"
          className="w-full rounded text-2xl font-bold outline-hidden focus:bg-amber-50"
        />
        {state.blocks.map((block) => (
          <div key={block.id} className="space-y-1">
            <div className="flex gap-2 text-sm">
              <select
                aria-label="Typ bloku"
                value={block.type}
                onChange={(e) => dispatch({ type: 'type', id: block.id, value: e.target.value })}
                className="rounded border border-gray-300 px-1"
              >
                {Object.entries(LABELS).map(([type, label]) => (
                  <option key={type} value={type}>{label}</option>
                ))}
              </select>
              <button type="button" onClick={() => dispatch({ type: 'add', id: block.id })} className="text-gray-600">
                + blok
              </button>
            </div>
            <textarea
              aria-label={LABELS[block.type]}
              value={block.text}
              onChange={(e) => dispatch({ type: 'text', id: block.id, value: e.target.value })}
              rows={block.type === 'heading' ? 1 : 2}
              placeholder="Pisz tutaj..."
              className={'w-full resize-none rounded outline-hidden focus:bg-amber-50 ' + STYLES[block.type]}
            />
          </div>
        ))}
      </div>

      <div className="mx-auto mt-3 max-w-xl space-y-2 rounded-xl bg-gray-900 p-4 text-sm text-white">
        <p>Udawany zegar: <strong>{formatClock(state.now)}</strong></p>
        <p>
          Następny zapis za: <strong>{secondsLeft} s</strong>{' '}
          ({state.agentBug ? 'wersja agenta: liczy od ostatniego klawisza' : 'poprawka: co 30 s od startu'})
        </p>
        <p>
          Ostatni zapis:{' '}
          {state.saves.length ? formatClock(state.saves[0].at) + ' (' + state.saves[0].words + ' słów)' : 'jeszcze nic nie zapisano'}
        </p>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={state.typing} onChange={(e) => dispatch({ type: 'typing', value: e.target.checked })} />
          Kapitan pisze bez przerwy (słowo co sekundę)
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={state.agentBug} onChange={(e) => dispatch({ type: 'agentBug', value: e.target.checked })} />
          Błąd agenta: setTimeout z [draft] w zależnościach
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={fast} onChange={setFast} />
          Szybki zegar (5 razy szybciej)
        </label>
      </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. 1. Dlaczego newBlock w edytorze kroniki daje blokowi id z crypto.randomUUID(), a nie z Date.now().toString()?

  2. 2. Dlaczego w typie SavedDraft pole savedAt ma typ string, a nie Date?

To 2 z 6 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować liczenie słów jednego bloku, w którym pusty blok daje 0 słów:

  • Układanie w poziomie

    Ułóż w jednej linii zmianę tekstu bloku przez funkcję aktualizującą:

  • Układanie w pionie

    Uporządkuj pracę nad edytorem kroniki w trybie planowania:

  • Edytor kodu

    Rich text editor component

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować zwrot tablicy z nowym blokiem wstawionym za blokiem o numerze index:

  • Układanie w poziomie

    Ułóż w jednej linii start zegara, który co 30 sekund woła zapis aktualnego szkicu:

  • Edytor kodu

    Draft system interface

  • Układanie w pionie

    Wersja agenta ma setTimeout w useEffect z zależnością [draft]. Uporządkuj, co się dzieje, gdy kapitan pisze bez przerwy:

  1. PytanieIdentyfikatory bloków
  2. PytanieData zapisu szkicu jako napis
  3. Kliknij w kolejnościSłowa bez pustych kawałków
  4. Ułóż w kolejnościZmiana tekstu jednego bloku
  5. Ułóż w kolejnościEdytor przez tryb planowania
  6. Zadanie z kodemPraktyka: Article editor
  7. PytanieCzas czytania pustej kroniki
  8. PytanieNowa paczka w diffie
  9. Kliknij w kolejnościWstawienie za wskazanym blokiem
  10. Ułóż w kolejnościZegar autozapisu
  11. Zadanie z kodemPraktyka: Draft management
  12. PytanieMiejsce dyrektywy use client
  13. Ułóż w kolejnościDlaczego autozapis agenta milczy
  14. PytanieAutozapis, który przeszedł test

Przydatne artykuły