runtime

projects/ai/artifacts/agent-to-human-tools.md

@@ -0,0 +1,43 @@
+# Převod agent-nástrojů na nástroje pro člověka
+
+Ověřený postup. Když AI agent napsal nástroj (runbook, skripty) původně
+**pro sebe**, nejde ho přímočaře zjednodušit pro lidské použití.
+
+## Proč opačný postup nefunguje
+
+- Model nevidí hranici, kde končí pro člověka použitelná složitost —
+  „zjednoduš to" produkuje kosmetické úpravy, ne redesign.
+- Existující podoba psaná pro agenta (hromada parametrů, dlouhé runbooky)
+  model **ukotvuje** — upravuje, co vidí, místo aby navrhl jiné rozhraní.
+- Plan mode u designu rozhraní nestačí: plánuje implementaci, ne podobu
+  rozhraní. Tu musí určit člověk.
+
+## Princip
+
+**Rozhraní navrhuje člověk, model implementuje.** LLM je nejsilnější v
+dokódování těla funkce se zadaným podpisem — přebírání designu je jeho slabá
+stránka.
+
+## Postup
+
+1. **Existující agent-runbook ani skripty nepoužívat jako základ** — jen jako
+   zdroj doménových faktů (co nástroj umí, jaké scénáře existují, jak se čeká
+   na konec testu). Strukturu ne. Začít v čistém adresáři.
+2. **Tabulka scénář → příkaz** — člověk ručně napíše, co kdy spouští.
+   To je celý human-runbook; žádný postup kroků.
+3. **Kostry skriptů píše člověk** — param block, komentáře po sekcích,
+   protokol čekání na dokončení (např. čekat na exit procesu, žádný polling).
+   Složitost je tím rozhodnutá předem.
+4. **Model jen dokódovává těla** — zadání: „dokóduj těla, parametry
+   a strukturu neměň, nic nepřidávej.“ Review pak kontroluje jen implementaci,
+   ne design.
+
+## Pravidla pro zadání
+
+- Složitost zadávat **čísly, ne adjektivy**: max počet parametrů na skript,
+  max počet kroků, jeden skript = jeden scénář. Model na numerické limity
+  reaguje spolehlivě; na „simple" ne.
+- Negativní omezení („žádné extra parametry") prosadit **v kódu kostry,
+  ne v promptu** — když param block má 3 parametry, model 15 nedoplní.
+- Agent-runbook pro sebe si nechat vedle — převod „agent-runbook →
+  human-runbook" je cesta, kde se to pořád láme. Nejsou to stejný dokument.