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

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.