Agentní vývoj / Kontextové okno

Nejčastějším omylem je brát kontextové okno jako úložiště – čím víc do něj nasypu, tím víc agent ví.

Je to přesně naopak. S rostoucí délkou historie kvalita odpovědí klesá, protože se v ní ředí to podstatné – pro tento jev se ujal termín context rot. Deset tisíc řádků logu ze selhaného buildu, obsah čtyř souborů, které se ukázaly jako slepá ulička, tři neúspěšné pokusy o opravu. To nejsou informace, ale šum. Model pak musí vaše zadání hledat mezi balastem a snáz přehlédne, na čem skutečně záleží.

Kontextové okno je pracovní plocha, nikoli archiv. Podstatné jsou proto dvě otázky. Co na ni vědomě pokládat? A co z ní průběžně odklízet?

A každou informaci, která na ní leží, platíte dvakrát – spálenými tokeny za požadavek a pozorností modelu. Místo na ploše je omezené, správa kontextu proto není technická drobnost, ale ekonomické rozhodnutí.

Kam psát instrukce

Agent umí spustit kompilaci, ale neví, že se v tomto projektu sbt nespouští z terminálu, že se nikde nepoužívá try/catch a že se po každé změně volá scalafmt. Netuší ani, že nesnášíte tříodstavcové úvody u odpovědí na otázky typu ano/ne. Tyhle znalosti mu musíte dodat vy.

Vlastní instrukce lze agentovi předat na třech místech. Každé se hodí pro jiný typ pokynů a liší se tím, kdy se jeho obsah do kontextu dostane.

Systémový prompt

První možností je systémový prompt – sada instrukcí, kterou harness posílá modelu s každým požadavkem. Neurčuje konkrétní úkol, ale způsob práce agenta: jakým tónem odpovídá, jak zachází s nástroji a kdy se má raději zeptat, než aby hádal.

Oficiální CLI harnessy svůj systémový prompt upravit nedovolují, agnostické ho naopak dávají k dispozici. Konkrétní podoba se liší podle nástroje, možnosti jsou ale většinou dvě – buď výchozí prompt celý nahradíte svým, nebo ho jen rozšíříte o vlastní text.

Patří sem to, co nezávisí na projektu – že chcete odpověď bez tříodstavcového úvodu, že se nikdy necommituje bez vyzvání nebo že dotaz „wdyt“ je pozvání k diskusi, ne pokyn k editaci souborů.

Úplná náhrada je ale ve většině případů špatný nápad. Výchozí systémový prompt kromě chování obsahuje také instrukce pro práci s nástroji, například přesný formát pro editaci souborů. Spolu s promptem je zahodíte a agent pak může selhávat i při základních operacích.

Projektové instrukce

Systémový prompt popisuje agenta, projektové instrukce popisují repozitář. Název souboru závisí na nástroji: řada harnessů používá AGENTS.md, Claude Code nativně čte jen CLAUDE.md (AGENTS.md se do něj dá přesměrovat odkazem @AGENTS.md). Soubor bývá v kořeni repozitáře a jeho obsah se na začátku relace načte do kontextu. Patří do něj to, co platí vždy a pro každého, kdo v repozitáři pracuje.

## Build

- ALWAYS use Metals MCP tools instead of sbt for compiling and
  running tests: `compile-file` / `compile-module` / `compile-full`
  to compile, `test` to run test suites (Weaver Test, ScalaTest,
  etc.)

## Code style

- Scala 3 brace-less syntax
- Never try/catch - use `Try`, `Either`, etc.
- `Either.cond(condition, right, left)` over `if/then/else`
- Descriptive names, no abbreviations (`fingerprint` not `fp`,
  `fieldSchema` not `fs`)

Všimněte si, že každé pravidlo je konkrétní a ověřitelné. Obecné poučky typu write readable code je plýtvání tokeny, protože z něj agent nic neodvodí. Naproti tomu fingerprint not fp je konkrétní pokyn, kterého se agent může držet.

Zásadní je zároveň stručnost. Obsah souboru zůstává v kontextu po celou relaci, proto sem nepatří návody pro výjimečné situace. Několik řádků navíc ničemu nevadí – problémem jsou dlouhé seznamy, ve kterých se důležitá pravidla začnou ztrácet.

Instrukce doporučuji psát v angličtině. Modely jsou na ni trénované, drží se jí spolehlivěji a stejný pokyn zabere méně tokenů než v češtině.

Skills

Pro obsáhlejší postupy je vhodnější mechanismus skills. Skill je markdownový soubor s návodem pro konkrétní typ úlohy a krátkým popisem, podle kterého agent pozná, kdy ho použít. V kontextu zůstává trvale jen tento popis – celý návod agent načte teprve ve chvíli, kdy na odpovídající úlohu narazí. Tomuto principu se říká progresivní odkrývání (progressive disclosure).

---
name: weaver-test
description: Conventions for writing tests with Weaver Test
  (weaver-cats) in Scala. Use when writing or reviewing
  Weaver test suites, assertions, or `expect` usage.
---

# Weaver Test

Write assertions with `expect.same` and combine them using `List(...).combineAll`...

Díky tomu do skillů můžete přesunout podrobné materiály, které by projektové instrukce zbytečně prodlužovaly: kompletní konvence pro Cats Effect, pravidla pro práci s Resource, checklist pro code review nebo popis firemního review procesu.

Hranici mezi systémovým promptem a projektovými instrukcemi určuje jejich vlastník. Systémový prompt je váš a typicky ho držíte mimo repozitář, projektové instrukce jsou jeho součástí a platí i pro kolegy. O přesunu do skillu rozhoduje frekvence: co agent potřebuje u většiny úkolů, patří do projektových instrukcí, postup pro výjimečnou situaci do skillu.

Jak plochu uklízet

Instrukce nastavíte jednou. Zbytek plochy se zaplňuje sám. Odklízet ho můžete třemi způsoby a každý se hodí pro jinou situaci.

Komprese (compaction) starou historii sumarizuje. Je nejpohodlnější, protože se spouští sama, a zároveň nejméně přesná – co se do sumáře nevešlo, zmizí z dalšího kontextu a vy nevíte, co to bylo.

Větvení vrátí konverzaci do bodu před chybným rozhodnutím a slepou větev z dalšího kontextu odstraní. Je levné i přesné, harness vám sám nabídne seznam bodů návratu. Hodí se i na experimenty – zkusíte jednu cestu a pokud nikam nevede, celou ji zahodíte.

Subagent deleguje dílčí úkol na samostatnou instanci s vlastním kontextem, která do hlavní konverzace vrátí jen výsledek. Typickým příkladem je prohledávání rozsáhlého repozitáře, kde vás zajímá odpověď, ne cesta k ní. Subagentovi navíc můžete pro jednodušší úkoly nastavit levnější model. Nevýhodou je izolace – nevidí hlavní konverzaci, takže zadání musí být úplné, jinak vrátí odpověď na jinou otázku.

Sám dávám přednost větvení, když si chci něco jen vyzkoušet a pak pokračovat, jako by se to nestalo. Subagenty používám pro ohraničené úkoly, u kterých mě zajímá jen výsledek – například spouštění sbt tasků nebo vyhledávání na GitHubu. Kompresi beru jako poslední možnost, ne jako strategii.

Závěr

Model i harness se dají vyměnit, kontext skládáte vždy vy. A přesnost odpovědi klesá s každou informací, která na ploše nemusela být.

Příklady subagentů a skillů, které používám, jsou k dispozici na githubu.