Většina lidí, kteří Claude Code používají první týdny, narazí na čtyři typické chyby. Agent ignoruje konvence projektu, opakuje stejné hloupé chyby, někdy řekne „hotovo”, když není hotovo, a postupem času začne pohlcovat víc tvojí pozornosti, než kolik práce ti šetří. Frustruje to. A obvykle to není problém modelu.
Začátkem roku 2026 začal Mitchell Hashimoto, autor Terraformu, na svém blogu psát o disciplíně, kterou si pro sebe pojmenoval harness engineering. Centrální myšlenka: prostředí, ve kterém agent pracuje — jeho nástroje, pravidla, kontext, oprávnění — má na výsledek často větší vliv než samotný model. Když agent něco kazí, většinou stačí upravit prostředí, ne čekat na lepší model. Tato myšlenka se za pár měsíců stala dominantní disciplínou kolem programátorských agentů a vibecoding.cz se na ni v chystané třídílné sérii podívá podrobně.
Než se ale do série pustíme, tady je pět praktických věcí, které můžete v Claude Code udělat dnes večer. Každá z nich ti zlepší výsledky bez nutnosti studovat teorii. Článek je psaný tak, aby ho mohl použít kdokoli — vibe coder, který programovat v klasickém smyslu neumí, i zkušený vývojář s desetiletími praxe. Pro každý krok ukážu snadnou verzi, kterou zvládne každý, a kde to dává smysl, dovětek pro pokročilejší.
1. Jak pořádně napsatCLAUDE.md
CLAUDE.md v kořeni projektu je první soubor, který si Claude Code přečte. Lidé ho ale často píší jako dokumentaci nebo style guide — „používáme camelCase”, „používáme tyto knihovny”, „máme rádi funkcionální komponenty”. To se může zdát logické, ale agentovi to moc nepomáhá.
CLAUDE.md by měl být krátký (ve skutečnosti deset až dvacet pět řádků, mnou tolerované maximum je 50 řádků), věcnýa obsahovat pravidla, která jsi přidal kvůli konkrétní zkušenosti, ne pravidla, která zní rozumně obecně. Lépe vypadá takto:
# Project context
Aplikace pro správu klientských zakázek.
Cíl: dashboard s filtrovatelným seznamem a detail zakázky.
# Build & run
- Pro spuštění: pnpm dev
- Pro testy: pnpm test
- Před uložením spusť pnpm lint
# Codebase
- Server Components ve výchozím stavu
- shadcn/ui pro komponenty
# Don't / Nedělat
- Nepřidávej nové závislosti bez ptaní
- Neupravuj components/ui/
- Když si nejsi jistý, zeptej se a počkej
To je celé. Žádné odstavce filozofie kódování, žádné dlouhé výčty knihoven. Každá řádka má za sebou důvod, proč tam je — buď je to věc, kterou agent jinak nezná, nebo věc, kterou opakovaně dělal špatně.
Poslední řádka v sekci Don’t je nejdůležitější. „Když si nejsi jistý, zeptej se a počkej” je univerzální záchranná brzda, kterou by měl mít každý projekt. Bez ní má agent tendenci tipovat — a tipovat špatně. S ní dostává explicitní povolení vrátit ti rozhodnutí.
Pokud jsi zkušený vývojář: pravidla, která lze vynutit linterem nebo CI, do CLAUDE.md nepatří. Patří do linteru a CI. „Před commitem proběhne eslint” a „kód musí projít typecheckem” jsou pravidla, která vynutíš mechanicky přes Hooks, ne promptem. Druhý díl série se tomuto rozdílu věnuje podrobně. V CLAUDE.md nechej jen to, co lint vynutit neumí — architektonická rozhodnutí, kontext projektu, věci, které musí agent vědět před psaním kódu.
2. Nech agenta zapisovat dokumentaci a rozhodnutí průběžně
Když agent stavbu projektu dělá za tebe, vzniká (zprvu) neviditelný problém: kód roste rychleji než tvoje pochopení toho, co v něm je. Po týdnu máš funkční aplikaci se třiceti soubory, kterou agent napsal, ale ty ji v hlavě nemáš. Když přijde čas na změnu, agent musí kód číst znovu od nuly. Když narazíš na chybu, agent neví, proč byl daný kód napsán tak, jak byl. Analýzou ze zdrojáků se pálí čas a tokeny.
Řešení je jednoduché: nech agenta, aby si při psaní kódu rovnou psal dokumentaci. Konkrétně do adresáře docs/ v projektu, jako Markdown soubory. To není dokumentace pro tebe v klasickém smyslu — je to paměť pro budoucího agenta, kterému dáš v dalším sezení úkol.
V CLAUDE.md k tomu přidej pravidlo:
# Documentation
- Pro každou novou významnou funkcionalitu vytvoř soubor v docs/features/
- Pro každé architektonické rozhodnutí (volba knihovny, vzor) zapiš zápis do docs/decisions/
- Dokumentace popisuje PROČ, ne CO. Co dělá kód, vidím v kódu.
- Při změně chování aktualizuj relevantní soubor v docs/
Po měsíci práce má agent v docs/decisions/ zápisy typu „zvolili jsme tuto knihovnu, protože je menší a má lepší tree-shaking”. Když v dalším sezení agent přemýšlí, jestli ji změnit, narazí na zápis a ví, proč byla volba původní. Bez zápisu by ji zlepšil zpět na alternativu, která je v jeho trénovacích datech dominantnější. To samé platí pro funkcionalitu — soubor docs/features/order-validation.md popisuje, jak validace funguje a proč. Agent v dalším sezení chápe systém jako celek, ne jen kus kódu, který právě píše.
Pokud chceš jít dál: ctěte pravidlo žádný kód bez zápisu rozhodnutí. Tohle je vyšší disciplína, kterou si někteří vývojáři osvojují, a má smysl pro projekty, kde počítáš s dlouhodobou údržbou. Pravidlo zní: každá změna kódu má v docs/log/ (nebo podobném adresáři) zápis o tom, na jaký požadavek byla provedena a proč. Ne každá řádka — to by bylo přehnané — ale každá změna, která mění chování nebo strukturu.
V CLAUDE.md to vypadá takto:
# Change log
- Před každou změnou, která mění chování nebo strukturu kódu, zapiš stručný záznam do docs/log/
- Záznam obsahuje: datum, soubor, popis změny, na jaký požadavek reaguje, zdroj požadavku
- Žádná úprava kódu bez zápisu rozhodnutí
Po několika měsících máš v docs/log/ linii rozhodnutí, která ti řekne co se kdy stalo a proč. Když přijde reklamace, audit, nebo otázka „kde se to vzalo”, máš odpověď. Když agent řeší úkol „zoptimalizuj tuhle funkci”, narazí na záznam „tato funkce byla přepsána ze zjednodušené verze, protože původní řešení padalo na okrajových případech X a Y”. Regrese se nestane, protože agent kontext má.
Pokud jsi zkušený vývojář: struktura docs/decisions/ má v komunitě ustálený formát — Architecture Decision Records(ADR). Pro docs/log/ existuje analogie v podobě Changelog konvencí (Keep a Changelog). Pokud chceš jít touto cestou, agent ti je dokáže psát ve standardním tvaru. Drobnost, která dělá rozdíl: dokumentaci a záznamy aktualizuj při změně, ne na konci. Agentovi to musíš explicitně zadat v CLAUDE.md (poslední řádka výše). Bez toho zápisy napíše jednou a pak je zapomene, čímž ztrácí na hodnotě.
3. Řekni agentovi, podle čeho poznáš, že je hotový
Druhá nejčastější chyba je dát agentovi úkol slovy a doufat, že odhadne, kdy je hotovo. Místo „přidej validaci do formuláře” zkus:
Přidej validaci do formuláře pro vytvoření zakázky.
Hotovo když:
- Formulář ukáže chybovou hlášku, když je jméno klienta prázdné
- Formulář ukáže chybovou hlášku, když je email ve špatném formátu
- Formulář ukáže chybovou hlášku, když je datum v minulosti
- Když je všechno v pořádku, zakázka se uloží a zobrazí potvrzení
Mimo rozsah:
- Stylování chybových hlášek (vyřešíme později)
- Kontrola, jestli email už existuje v databázi (jiný úkol)
Tři věci, které tato struktura dělá. Za prvé říká, co je uvnitř úkolu pozorovatelně. Ne „funguje to”, ale „uvidíš tohle a tohle”. Za druhé říká, co je mimo rozsah. Bez toho má agent tendenci úkol rozšiřovat a „zlepšovat” věci, které jsi nechtěl řešit. Za třetí dává agentovi něco, co si může sám ověřit, místo aby čekal, až ty řekneš „OK”.
Tohle nemusíš psát do samostatného souboru. Pro jednotlivé úkoly stačí, když to napíšeš přímo do promptu. Pro větší úkoly, na kterých budeš pracovat víc dní, si to napiš do souboru SPRINT.md v kořeni projektu. V CLAUDE.md pak přidej řádku „před začátkem úkolu vždy přečti SPRINT.md, pokud existuje” — tím dáš agentovi explicitní pokyn, aby se na soubor podíval na začátku každého sezení.
Pokud pracuješ s testy: přidej do Hotovo když konkrétní testovací příkaz, který agent může spustit a získat strojově ověřitelnou odpověď. „pnpm test src/components/order-form proběhne bez chyby” je silnější verifikace než „formulář ukáže chybovou hlášku”, protože agent nemusí důvěřovat sám sobě — má nezávislý ukazatel. Pokročilejší formou této disciplíny je sprint contract, který používá například Anthropic — agent a evaluátor se před začátkem práce dohodnou, co znamená hotovo. K tomu se vrátíme v dílu 2.
4. Když agent udělá chybu, neopravuj jen ten řádek
Toto je nejdůležitější bod celého článku. Když agent udělá hloupou chybu — odstraní část kódu, kterou jsi nechtěl mazat, použije knihovnu, kterou v projektu nepoužíváš, vloží něco do nesprávné složky — většina lidí řekne „ne, takhle ne” a buď to opraví ručně, nebo dá agentovi další prompt: „nech to tam”, „použij jinou knihovnu”.
Tohle je retry, ne oprava. Agent stejnou chybu udělá za týden znovu, protože v jeho kontextu pro to nic nestojí v cestě.
Místo toho otevři CLAUDE.md a přidej řádku, která tu chybu pojmenovává a zakazuje. Konkrétně:
# Don't
- Nemazej kód, ani když si myslíš, že nepatří k úkolu. Pokud si nejsi jistý, zeptej se.
- Pro datum používej knihovnu date-fns, ne moment.js.
- Komponenty patří do src/components/, ne do src/ui/.
Po měsíci práce máš v CLAUDE.md deset až patnáct takových řádek. Každá z nich kóduje jednu konkrétní zkušenost — jednu chybu, kterou agent v tvém projektu udělal a kterou už neudělá, protože ji čte při každém startu. Tento drobný ratchet — krok za krokem nahoru, nikdy dolů — je centrální disciplínou celé série, na kterou navazujeme.
V angličtině ratchet je rohatka — mechanická součástka, která umožňuje pohyb pouze jedním směrem a v opačném směru zaskočí. Pohyb je jen jedním směrem: pravidla přibývají, neubývají (s výjimkou disciplinovaného mazání po upgradu modelu, ale to je jiný cyklus). Tvoje znalost se kumuluje, agent ji dědí. Proto se tento příměr v komunitě používá.
Princip platí napříč všemi typy chyb, které agent dělá. Některé jsou technické (špatná knihovna), některé jsou organizační (špatné umístění souboru), některé jsou hodnotové (agent ti přepisuje něco, co jsi explicitně chtěl zachovat). Pro každou z nich existuje jedna řádka v CLAUDE.md, která ji v dalším běhu zablokuje.
Pokud jsi zkušený vývojář: některé chyby jsou tak vážné nebo tak časté, že textový zákaz v CLAUDE.md nestačí. Agent ho prostě přečte a stejně udělá chybu, protože v rozhodujícím okamžiku má kontext plný jiných věcí. Pro tyto případy máš silnější vrstvu — pre-commit hook, ESLint pravidlo, CI gate. Mechanické vynucení, kde commit nebo build prostě neprojde, je vždy silnější než textová instrukce. Druhý a třetí díl série se této hierarchii věnuje podrobně. Pravidlo zní: pokud stejná chyba přežije tři až čtyři opakovaná pravidla v CLAUDE.md, je čas ji posunout na úroveň mechanického vynucení.
5. Nepřidávej MCP servery hned. Pravděpodobně je nepotřebuješ
Claude Code přijde s nástroji, které pro většinu úkolů stačí: čtení a zápis souborů, prohlížení obsahu projektu, spouštění příkazů, práce s gitem. To je dost na to, abys s ním postavil aplikaci od nuly. MCP servery jsou rozšíření — externí konektory pro systémy, které Claude Code v základu neumí: Linear, Jira, databáze přes specializované rozhraní, Stripe API.
Komunita kolem Claude Code dnes diskutuje hodně o MCP, takže je lákavé nainstalovat patnáct serverů hned na začátku „pro jistotu”. Tomu se vyhni. Každý MCP server, který přidáš:
- Zabírá místo v kontextovém okně agenta (jeho definice se načítají do paměti, kterou agent potřebuje pro tvůj úkol, není to moc, ale zbytečné to je)
- Přidává komplexitu, kterou musíš ladit, když něco selže
- Často duplikuje něco, co Claude Code už umí jednodušeji
Pravidlo: přidej MCP server teprve, když pozoruješ, že agent opakovaně obchází nějaký externí systém kostrbatým způsobem. Když pravidelně řeší něco, co by jeden konkrétní server vyřešil v jednom kroku, je čas. Před tím není. Snad jedinou výjimkou může být Context7 pro aktuální definice API, ale pokud nepociťujete problém s tím, že by Claude Code používal zastaralé API, asi si zatím poradil …
To samé platí pro skills, hooks, sub-agenty a další pokročilé vrstvy harness, o kterých možná slyšíš. Začni s tím, co Claude Code má v základu, pozoruj, kde to nestačí, a teprve pak přidávej. Hashimotův princip — „každá komponenta musí mít konkrétní historii toho, proč ji potřebuješ” — platí napříč celou disciplínou.
Co dál
Těchto pět věcí ti zlepší práci v Claude Code během prvního dne. Jsou to relativně jednoduché a přitom ve skutečnosti velmi silné postupy.
Pokud chceš jít hlouběji — pochopit, co je harness engineering jako disciplína, jak fungují jeho jednotlivé části a jak postavit harness pro produkční nasazení na rozsáhlém projektu, pak mám dobrou zprávu. Připravili jsme několikadílný seriál, kde se do harness ponoříme.
První díl řeší, co je harness a kdy tato disciplína vznikla. Druhý díl prochází anatomií harness: devět komponent, tři pilíře, pět principů. Třetí díl je praktický průvodce stavbou harness pro tvůj projekt — od založení po stálou údržbu. Budeme je publikovat průběžně.
Pokud máš vlastní zkušenost s Claude Code — co se ti osvědčilo, co tě překvapilo, co bys udělal jinak — napiš mi. Vibecoding.cz je o praxi, ne o teorii.