Jak vést rozsáhlý úkol: kontext a ověřitelné etapy

Rozsáhlý úkol obvykle začíná požadavkem, který zní rozumně. "Vytvoř katalog lokalizací: seznam, vyhledávání v něm, filtr podle země a slušný vzhled." Za hodinu před sebou máte stránku, na které je seznam hotový jen napůl, vyhledávání nefunguje ve všech polích, vzhled se už dvakrát změnil a konverzace narostla tak, že už není jasné, co je ověřený výsledek a co jen slib, který cestou zazněl.

Jednou z možných příčin je, že úkol nebyl rozdělen na části s jasným výsledkem. Chyby v kódu to sice nevylučuje, ale snáz se hledají, když je jasné, co má fungovat právě teď. Podíváme se, jak rozdělit rozsáhlou práci na ověřitelné etapy, jaké informace dát agentovi pro aktuální etapu a co si poznamenat, abyste se k úkolu mohli vrátit zítra - ve stejné nebo nové konverzaci - a nemuseli vše znovu skládat z paměti.

Takto má katalog vypadat: seznam s vyhledáváním a v každém řádku kód lokalizace, jazyk, země, měna a doména. Mějte tuhle maketu na paměti - v praktické části poslouží jako vzor stylu, nejen jako obrázek.

Rozsáhlý úkol a dlouhá konverzace

Dlouhý úkol se může zaseknout ještě před první chybou v kódu: postup ztrácí strukturu. Kontext se rozrůstá, hypotézy se míchají s přijatými rozhodnutími a k vyhledávání se nenápadně přidá předělávání vzhledu. Kontextové okno má své limity, ale hlavní problém je jinde - přestává být jasné, co právě děláte a co už je hotové.

TASK_SPEC stanovuje cíl, hranice a způsob ověření celého úkolu. Práci podle tohoto zadání pak rozdělíte na ověřitelné etapy - milestones. Každá má výsledek a hranice: například přidat vyhledávání a zachovat data i vzhled. Claude tak může pracovat k věci a vy vidíte, v jaké fázi úkol je.

Pokud úkol ještě není jasný, první etapou může být průzkum: přečíst dva nebo tři klíčové soubory, popsat možnosti řešení a rizika a potom upřesnit zadání i následující etapy.

Každou etapu zakončete kontrolami a krátkým shrnutím (summary): co je hotové, jak jste to ověřili a co bude dál. Pokud projekt spravujete v Gitu, ukládejte ověřené změny do malého commitu. Shrnutí uchovává rozhodnutí, commit verzi kódu; dohromady vám pomohou ověřit výsledek a po přestávce navázat.

Co se počítá jako etapa

Milestone, neboli milník, je bod, ve kterém má úkol průběžný výsledek, který lze ověřit. Práci vedoucí k takovému bodu budeme dál nazývat etapou.

Etapa má tři nezbytné části:

• výsledek - co přesně začne fungovat;
• hranice - na co tentokrát nesaháte;
• ověření - na co se podíváte, abyste měli jistotu.

Rozdíl je vidět na formulacích. "Zapracovat na vyhledávání" nemá jasný konec: pracovat můžete donekonečna a kdokoli může rozhodnout, kdy je "hotovo". "Vyhledávání najde řádek podle kódu lokalizace a prázdný dotaz vrátí celý seznam" už konec má a v prohlížeči ho uvidíte za půl minuty.

Neexistuje univerzální limit na čas ani počet souborů. Na velikosti ale záleží: pokud se v etapě míchá několik nezávislých změn a výsledek nedokážete ověřit v jednom přehledném průchodu, zmenšete ji. Vodítkem je nejbližší užitečný výsledek, který lze samostatně získat a ověřit.

Rozdělte výsledek na funkční části

Vezměme si výukový katalog lokalizací. Záznamy mají stejná pole jako v maketě výše: kód lokalizace, jazyk, země, měna a doména. Pro jednoduchost je hotové pole přímo v souboru app.js, který se načítá v index.html. Stránka data nestahuje samostatným požadavkem, takže ji můžete otevřít v prohlížeči bez serveru. Tady je samotná sada:

[
  { "code": "en-US", "language": "English", "country": "United States", "currency": "USD", "tld": ".us" },
  { "code": "de-DE", "language": "German", "country": "Germany", "currency": "EUR", "tld": ".de" },
  { "code": "fr-CA", "language": "French", "country": "Canada", "currency": "CAD", "tld": ".ca" },
  { "code": "ja-JP", "language": "Japanese", "country": "Japan", "currency": "JPY", "tld": ".jp" }
]

Celé zadání zní: seznam, vyhledávání a filtr podle země. "Slušný vzhled" z úvodu nedostane samostatnou etapu: základní vzhled stránka získá spolu se seznamem v M1 a do "odložených" patří jen nové úpravy vzhledu, tedy změna motivu. Rozdělme požadavek do tří etap.

Nejdřív potřebujeme funkční seznam: na něm se dobře ověřuje filtrování záznamů. Vyhledávání a filtr lze přidávat v různém pořadí; tady jsme zvolili vyhledávání a v M3 ověříme, že fungují společně. Šipka mezi etapami znamená, že předchozí výsledek už byl ověřen. Zelené M3 označuje etapu, po které je celý požadavek splněný.

Práci tedy dělíme podle výsledku. Každá etapa zahrnuje čtení kódu, úpravy a ověření. Plán "nejdřív celé HTML, potom celé JS a všechno ověřit až nakonec" odkládá kontrolu chování na úplný závěr. Hotové značkování může být užitečný průběžný výsledek, ale ještě neukazuje, jestli vyhledávání funguje.

Mějte na paměti, že agent sám tíhne právě k takovému plánu po vrstvách: nejdřív celé značkování, pak veškerá logika. Říkají to i lidé, kteří s AI agenty pracují často, například Matt Pocock ve workshopu o svém postupu - takový plán se objeví, i když výslovně požádáte o rozdělení podle výsledku. U etap navržených agentem proto ověřte jednu věc: můžete na konci každé něco otevřít a vidět, že to funguje?

A tři etapy jsou tady příklad, ne pravidlo. Někdy jsou dvě, jindy šest.

Dejte kontext pro aktuální etapu

Jakmile vyberete etapu, agent potřebuje informace právě k ní, ne celý projekt. Zadání pro M2 ve výukovém katalogu může vypadat takto:

Přidáváme vyhledávání do seznamu lokalizací.
Seznam čtyř záznamů už funguje. Zachovej jeho pole i vzhled,
obsah původního pole neměň. Přidej jen prvky potřebné pro vyhledávání.

Přečti @index.html a @app.js.

Požadavky:
- vyhledávací pole nad seznamem;
- vyhledávání podle kódu lokalizace a názvu jazyka;
- dotazy de-DE a German najdou záznam de-DE;
- po dotazu zzz nezůstane v seznamu žádný řádek;
- prázdný dotaz zobrazí celý seznam.

Filtr podle země tentokrát nepřidávej.
Pokud potřebuješ další soubor, pojmenuj ho a přečti.
Nejdřív uveď výsledek a hranice etapy, soubory zatím neměň.

Pokud vám navržené hranice vyhovují, požádejte agenta v další zprávě, aby provedl M2 a vypsal kontroly v prohlížeči. Zároveň ho požádejte, aby oddělil, co ověřil sám a co ještě budete muset ověřit vy.

Cesty v příkladu jsou jen zástupné, vaše soubory budou jiné. Pokud práce vyžaduje zdroj, který v zadání není, agent ho má pojmenovat a přečíst: odhadovat obsah souboru podle názvu je špatný nápad a neměli byste ho o to žádat.

Vzhled je tu samostatný druh informací a právě v této etapě ho zachováváme. Někdy je to naopak: vzhled patří k výsledku etapy, třeba když stránka vzniká poprvé. Slovy ho přesně nepopsáte - požadavek "udělej to hezké" neobsahuje nic ověřitelného a rozhodnutí zůstává na agentovi. V takovém případě přiložte vzor: maketu, snímek obrazovky nebo malý soubor s barvami a názvy tříd.

Stojí za to připomenout, čím taková formulace není. Věta "filtr tentokrát nepřidávej" je pokyn, ne technická překážka. Určuje směr, ale nic neblokuje, takže výsledek stejně zkontrolujete sami.

Kdy je čas etapu zmenšit

Etapy mají sklon se během práce rozrůstat. Začali jste vyhledáváním, ale cestou se ukázalo, že by bylo dobré změnit strukturu dat, rovnou upravit vzhled a přidat horní navigaci. Znáte to.

U každého nového požadavku se zeptejte, jestli je potřeba pro zvolený výsledek. Nový barevný motiv i navigace počkají, viditelné vyhledávací pole je ale nezbytné. Pokud záznamům chybí údaje, podle kterých se má vyhledávat, nejdřív upřesněte hranice: data lze doplnit v aktuální etapě nebo jejich přípravu vyčlenit do samostatné ověřitelné etapy. Zákaz měnit data nelze během práce potichu zrušit.

Upřesňující zadání může být krátké:

Data, vzhled ani navigaci tentokrát neměň,
zapiš je jako samostatné body na později.
Zůstaneme u vyhledávání podle kódu a jazyka: vstupní pole, shody, prázdný dotaz.

Etapa je hotová, když máte dohodnutý výsledek a provedli jste jeho ověření. Pokud kontrola neprošla, nejdřív vyřešte aktuální etapu; přechod k další by jen přidal nejistotu.

Někdy se etapa nedaří: opravíte agenta, on práci předělá, a znovu je to špatně. Neúspěšné pokusy zůstávají v konverzaci a další pokus už vychází z nich. Dokumentace Claude Code nabízí jednoduché vodítko: pokud jste museli tutéž věc opravit víc než dvakrát, začněte čistou konverzaci se zadáním, do kterého zahrnete vše, co jste zjistili. Například: "přístup se samostatným polem pro vyhledávání nefunguje, rozchází se se zdrojovými daty; vyhledávej přímo v hlavním poli". Takové zadání obvykle funguje lépe než třetí oprava v řadě. A pokud nepomůže ani to, etapa je nejspíš příliš velká a stojí za to ji rozdělit.

Uložte bod, od kterého lze pokračovat

Levá větev vás vrací k úpravám stejné etapy: její výsledek zatím není potvrzený. Pravá vede k zaznamenání stavu a další etapě. Do poznámky zapisujte úspěšné kontroly i to, co zůstalo mimo jejich rozsah.

Ověřili jste výsledek? Zapište stav. Poznámka neslouží k vykazování práce, ale k tomu, abyste za den nebo v jiné konverzaci nemuseli historii dolovat z chatu.

Název souboru je na vás, poslouží i existující pracovní poznámka. Dejme tomu, že se bude jmenovat PROGRESS.md. Níže je výukový příklad po ověření M1; do vlastní poznámky zapisujte jen to, co jste skutečně udělali a pozorovali:

# Katalog lokalizací

## Hotovo
M1: stránka zobrazuje seznam lokalizací z pole v app.js.

## Ověřeno
Otevřel jsem index.html v prohlížeči: 4 záznamy, všech pět polí v každém řádku
odpovídá zdrojovému poli v app.js.

## Neověřeno
Co stránka zobrazí, když je datová sada prázdná.
Tato kontrola nebyla součástí kritérií M1; chování u prázdného pole zatím neznáme.

## Rozhodnutí
Data ukládáme do pole v app.js, samostatné načítání dat neprobíhá.
Při přidání vyhledávání zachováme obsah záznamů i vzhled.

## Zamítnuto
Načítání dat ze samostatného souboru JSON: bez serveru ho prohlížeč
nepřečte a stránka se musí dát otevřít jako soubor.

## Soubory
index.html, app.js

## Zbývající etapy
M2: funguje vyhledávání podle kódu lokalizace nebo názvu jazyka.
Ověření: de-DE a German najdou záznam de-DE;
zzz nenajde žádný záznam; prázdný dotaz zobrazí všechny čtyři.

M3: filtr podle země funguje společně s vyhledáváním.
Ověření: Canada + French ponechají fr-CA;
Canada + German vrátí prázdný seznam;
zrušení obou podmínek vrátí čtyři záznamy.

## Další krok
Provést M2. Filtr podle země zatím nepřidávat.

Klíčová je tu část "Ověřeno". Záznam "všechno funguje" za týden nic neřekne, ale "otevřel jsem stránku v prohlížeči, 4 záznamy, pole odpovídají" ano. Samostatná část pro neověřené věci je důležitá právě proto, že si ten rozdíl zítra už nevybavíte.

Část "Zamítnuto" může vypadat zbytečně, protože obsahuje něco, co v projektu není. V nové konverzaci ale agent o předchozích pokusech nic neví a může znovu poctivě navrhnout stejný postup. Jeden řádek s důvodem ušetří celé kolo.

Poznámku můžete svěřit agentovi, ale porovnejte ji s aktuálními soubory a výsledky kontrol. Může vycházet z historie konverzace, kde jsou plány vedle skutečně provedených kroků. U pozorování v prohlížeči uveďte, kdo ho provedl; nepřipisujte agentovi kontrolu, kterou nespustil.

Dvě omezení. Průběžný stav úkolu nepatří do CLAUDE.md - tam jsou trvalá pravidla projektu, ne to, na čem právě pracujete. A poznámka neukládá verzi kódu: je to text o stavu, ne kopie souborů.

Pokračujte s potřebnými informacemi

Hranice etapy je vhodným místem k rozhodnutí, v jaké konverzaci pokračovat. Otázka je jednoduchá: pomáhá současná konverzace dalšímu kroku, nebo už překáží?

Pokud pomáhá, pokračujte v ní, nic zvláštního není potřeba. Neexistuje pravidlo "vyčistit konverzaci po každé etapě" ani procentní hranice, po jejímž překročení byste údajně měli začít znovu.

Pokud nevíte, kolik místa zabírá historie, spusťte /context a podívejte se na využití okna. Porovnejte ho s postupem práce: které dlouhé výstupy a diskuse ještě potřebuje další etapa? Příkaz pomůže odhadnout objem, ale to, které informace jsou užitečné, určujete vy.

Pokud se nahromadil nesouvisející obsah a rozhodli jste se začít čistou konverzaci, nejdřív uložte poznámku. Příkaz /clear zahájí novou konverzaci: předchozí historie se nepředává do jejího pracovního kontextu, zdrojové soubory zůstávají na disku a projektové instrukce se dál načítají. Stará konverzace se tím neodstraní navždy: k uložené konverzaci se můžete vrátit pomocí /resume. Pro pokračování v nové relaci je ale lepší potřebná rozhodnutí předat výslovně.

Obě šipky se sbíhají před pokračováním práce. Poznámka předává rozhodnutí a výsledky kontrol, soubory ukazují aktuální kód. Agent si přečte oba zdroje a shrne stav; vy jeho odpověď ověříte, než mu zadáte M2.

Začátek nové konverzace je docela běžný:

Přečti @PROGRESS.md, @index.html a @app.js.
Vlastními slovy řekni, co už je hotové a ověřené a co zbývá.
Soubory zatím neměň.

Odpověď si pozorně přečtěte. Pokud agent označil za hotové něco, co jste neudělali, porovnejte jeho slova s poznámkou, soubory a výsledky kontrol. Příčinou může být nepřesný záznam, zastaralý kód nebo chyba samotného agenta. Nesoulad vyřešte před dalšími úpravami: čistá konverzace sama o sobě neopraví chybné zadání ani nezaručí správné pochopení.

Projděte si celý katalog

Rozbor je u konce. Teď si stejný katalog vytvoříte sami: od prázdné složky až po ověřené M2 a bod, od kterého lze pokračovat. Čtyři kroky kopírují pořadí článku. U každého si nejdřív sestavte vlastní prompt a naši variantu si otevřete jako druhý názor: cílem je rozhodnout, jaké informace agent potřebuje, ne opsat jednu větu.

Krok 1. Plán bez kódu

Projekt ještě neexistuje a první, co vás napadne, je požádat "vytvoř katalog". Soubory by se pak objevily dřív než rozhodnutí o nich. Cíl tohoto kroku je opačný: získat plán a nevytvořit žádný soubor. Než začnete psát, promyslete si čtyři věci:

• jak zabránit agentovi, aby se hned pustil do psaní kódu;
• jaké informace dát místo souborů, které ještě neexistují;
• jaká technická omezení uvést, aby nepřibyl zbytečný nástroj;
• o jaký výstup požádat, když zatím není co vytvářet.

Naše varianta:

Chci výukový katalog lokalizací: seznam záznamů, vyhledávání v něm
a filtr podle země. Projekt zatím nemám.

Stránka se musí otevřít v prohlížeči jako soubor, bez serveru a sestavení:
jen index.html, styles.css a app.js. Záznam má pole kód lokalizace (en-US),
jazyk, země, měna a doména.

Nejdřív připrav plán:
- uveď cíl, hranice a způsob ověření celého úkolu;
- rozděl práci do tří etap;
- u každé popiš výsledek a to, co uvidím při ověření;
- řekni, jaké informace ode mě potřebuješ;
- vypiš soubory, které bys vytvořil.

Zatím žádné soubory nevytvářej.

Porovnejte navržené etapy s tabulkou M1-M3 výše; jiné pořadí je v pořádku. Pokud agent rozdělil práci na "nejdřív celé HTML, potom celé JS", požádejte ho, aby plán upravil tak, aby stránka po každé etapě něco uměla. A pokud etapa nemá pojmenované pozorovatelné chování, upřesněte zadání hned: před prvním řádkem kódu vás to stojí jednu zprávu.

Krok 2. Jen M1 a hned se vzorem

Rozsah je úzký: stránka ukazuje čtyři záznamy, nic víc. Žádné vyhledávání ani filtr. Vzhled ale odložit nelze - stránka se objevuje poprvé a nějak vypadat musí. Proto přiložte vzor: do složky projektu uložte mockup.html, statické značkování bez JavaScriptu, jen barvy a názvy tříd.

<style>
  body   { background:#0f172a; color:#e2e8f0; font-family:system-ui, sans-serif; padding:24px }
  .search{ width:100%; margin-bottom:12px; padding:10px 14px; border-radius:10px;
           background:#1e293b; color:#e2e8f0; border:1px solid #334155 }
  table  { width:100%; border-collapse:collapse }
  th, td { padding:10px 12px; text-align:left; border-bottom:1px solid #334155 }
  th     { color:#8b98b1; font-size:13px }
  .code  { font-family:ui-monospace, monospace; font-weight:700; color:#818cf8 }
</style>

<input class="search" placeholder="Search by code or language">
<table>
  <tr><th>Code</th><th>Language</th><th>Country</th><th>Currency</th><th>TLD</th></tr>
  <!-- ukázkový řádek; skutečné řádky vykresluje app.js -->
  <tr><td class="code">en-US</td><td>English</td><td>United States</td><td>USD</td><td>.us</td></tr>
</table>

Vyhledávací pole je ve vzoru už nakreslené, ale v M1 ho na stránku nepřenášejte: prázdné pole, které nic nedělá, se těžko ověřuje. Jeho styl je ve třídě .search a bude se hodit v M2.

Ještě jedna věc: data musíte agentovi předat výslovně. Bez nich si vymyslí vlastní sadu a kontroly z tabulky - čtyři řádky, de-DE, Canada - přestanou souhlasit. Teď prompt: promyslete, jak agenta udržet v jedné etapě, co po něm chtít před úpravami a jak výsledek ověříte.

Provádíme jen M1: stránka zobrazuje seznam lokalizací
z pole v app.js. Vyhledávání ani filtr tentokrát nepřidávej,
vyhledávací pole ze vzoru zatím také ne.

Data tvoří toto pole čtyř záznamů, jeho obsah neměň:
[vložte pole z článku]

Vzhled převezmi z @mockup.html: použij jeho barvy a názvy tříd,
žádné nové nevymýšlej.

Nejdřív ukaž plán souborů a řekni, kde se zastavíš.
Dokud plán nepotvrdím, žádné soubory nevytvářej.
Po úpravách mi řekni, co mám otevřít a s čím výsledek porovnat.

Po M1 se zastav, bez mého svolení nepokračuj k M2.

Pokud se plán rozrostl, nepotvrzujte ho a nejdřív etapu zmenšete na jediný ověřitelný výsledek. Pokud je plán v pořádku, povolte úpravy, pak otevřete stránku a porovnejte čtyři řádky s polem. Základní vzhled je od této chvíle daný: dál se zachovává a úplná změna motivu zůstává odloženým bodem.

Krok 3. M2 a poctivá poznámka

Prompt pro M2 už jsme probrali v části "Dejte kontext pro aktuální etapu" - vraťte se k němu a doplňte své cesty. V rozboru jsou dva soubory, vy už po M1 máte tři: k index.html a app.js přibyl styles.css, uveďte ho také. A doplňte jednu větu: vzhled teď zachováváme, nenavrhujeme nový.

Vzhled je už určený v M1 podle @mockup.html - zachovej ho,
vyhledávací pole naformátuj třídou .search z tohoto souboru.

Agent uvedl správné hranice - povolte úpravy. Pokud se pustil do filtru nebo struktury dat, vyjasněte to před začátkem práce. Jakmile projdou všechny tři kontroly vyhledávání, zaznamenejte stav do PROGRESS.md podle výše uvedeného vzoru, tentokrát už po M2 a se seznamem vašich souborů.

A ověřte, že vaše poznámka obstojí. Představte si, že místo části "Ověřeno" obsahuje větu "skoro všechno hotovo, zbývá maličkost". Za týden už nic neřekne. Doplňte ji tak, aby se podle ní dalo pokračovat: co přesně jste otevřeli a viděli, co zůstalo mimo kontroly a jaký je další krok. Třeba: "M2: dotazy de-DE a German najdou de-DE, zzz nenajde nic, prázdný dotaz vrátí čtyři záznamy", "chování u prázdné datové sady jsem neověřil", "další krok - M3, filtr podle země".

Krok 4. Pokračujte v čisté konverzaci

Poslední krok ověřuje poznámku, ne kód. Začněte novou konverzaci, požádejte agenta o shrnutí stavu podle PROGRESS.md a aktuálních souborů - všech tří, včetně styles.css - a pak jeho shrnutí porovnejte s tím, co jste skutečně udělali. Pokud agent označil za hotové něco, co jste neověřili, je poznámka nejspíš příliš obecná. Pomůže ji upravit, ne začínat další konverzaci. Porovnejte ji ale i se soubory: příčina může být v kódu nebo v chybě samotného agenta. Pokud vše souhlasí, máte ověřené M1, ověřené M2 a bod, od kterého začne M3.

Jak přejít k další etapě

Celý postup lze shrnout do několika kroků:

1. vyberte nejbližší výsledek, který lze ověřit;
2. dejte agentovi zdroje pro tuto etapu a pojmenujte hranice;
3. proveďte aktuální etapu; nové požadavky si zapište zvlášť;
4. proveďte dohodnutou kontrolu; v našem příkladu ověřte chování stránky v prohlížeči;
5. zaznamenejte stav: hotovo, ověřeno, neověřeno, co bylo zamítnuto a další krok;
6. rozhodněte, zda pokračovat v této konverzaci, nebo začít novou.

Jedna etapa neznamená jednu zprávu. Může jich být tři nebo patnáct, a to je v pořádku. Počet etap se nerovná počtu konverzací: několik sousedních etap může bez problému proběhnout v jedné konverzaci, zatímco jedna náročná někdy zabere dvě.

Na každém kroku ale dokážete odpovědět, co už funguje a jak jste to ověřili. U rozsáhlého úkolu je to nejspíš to nejdůležitější.