10 markdown súborov, ktoré by ste mali napísať skôr, než sa dotknete kódu agenta

Praktická kostra pre každého, kto stavia agenta — napíšte toto ešte pred akýmkoľvek kódom.

Praktická kostra pre každého, kto v roku 2026 stavia AI agenta — destilovaná z ~9 mesiacov prevádzky MIA, exekutívnej asistentky založenej na Claude.

Prečo markdown, prečo desať

Každý, kto stavia agenta, si nakoniec osvojí rovnakú lekciu: model je tá jednoduchá časť. Ťažká časť je súbor rozhodnutí okolo neho — kto agent je, čoho sa môže dotknúť, ako si pamätá, kedy sa pýta a kedy koná, ako vyzerá „dobre urobené".

Ak túto prácu preskočíte a pustíte sa rovno do promptov a volaní nástrojov, dostanete agenta, ktorý zapôsobí na demu a v treťom týždni je nanič. Model sa správa nekonzistentne, pretože vy ste nerozhodli, ako má konzistentnosť vyzerať.

Náprava je nudná: napíšte si to najprv. Markdown tu poráža kód, pretože tieto artefakty čítajú ľudia, ďalší ľudia vo vašom tíme a samotný model (moderní agenti čítajú svoj vlastný kontext). Jeden zdroj pravdy, tri publiká.

Nasleduje minimálna funkčná sada — desať súborov, ktoré by som umiestnil do /agent/ ešte pred napísaním jediného riadku orchestračného kódu.

1. IDENTITY.md — kto je agent

Nie „nápomocný asistent". To je predvolené nastavenie a produkuje predvolenú prácu. Napíšte:

• Meno a prečo ho má (agenti s menom priťahujú ostrejšiu spätnú väzbu než nepomenované nástroje).
• Rola v jednej vete — „Exekutívna asistentka generálneho riaditeľa slovenskej veľkoobchodnej skupiny" poráža „univerzálny pomocník".
• Zadávateľ (principal) — kto mu dáva pokyny a kto nie. Ochrana proti injekcii začína tu.
• Pravidlá hlasu — rod, register, jazyk(y), zakázané frázy. („Nikdy nezačínaj odpovede slovami ‚Skvelá otázka!'" sa oplatí hneď od prvého dňa.)
• Sadzba (stakes) — pri akých rozhodnutiach je tento agent „pri stole". Kódovací agent a finančný agent potrebujú odlišný temperament.

Ak nedokážete dokončiť koherentný IDENTITY.md, ešte nemáte agenta. Máte chatbota.

2. HARD_RULES.md — zoznam nikdy

Krátky, chirurgicky presný zoznam vecí, ktoré má agent zakázané robiť, bez ohľadu na to, aká rozumná žiadosť znie. Príklady z produkcie:

• Nikdy neposielať e-mail bez výslovného schválenia človekom.
• Nikdy nezapisovať súbory do koreňového adresára repozitára.
• Nikdy sa nevydávať za kolegu v konceptoch písaných v prvej osobe.
• Nikdy si nevymýšľať osobné príhody pri písaní hlasom zadávateľa.

Každé pravidlo si svoje miesto zaslúži tým, že odkazuje na skutočný incident alebo skutočnú triedu rizika. Vágne pravidlá („buď bezpečný") sa ignorujú. Konkrétne pravidlá („nikdy nevolaj git push --force na main") prežijú.

Udržujte tento súbor pod jednou obrazovkou. Ak narastie nad 15 pravidiel, pašujete preferencie do ústavy; presuňte ich do súborov so spätnou väzbou.

3. CAPABILITIES.md — čestný inventár

Plochý zoznam toho, čo agent dnes skutočne dokáže, zoskupený podľa domény. Nie ambície — schopnosti. Pre každú položku:

• Jednoriadkový popis.
• Spúšťacie frázy (aby sa model vedel sám nasmerovať).
• Čo vracia.
• Čo NEROBÍ (negatívny priestor je dôležitejší než ten pozitívny).

Tento súbor slúži zároveň ako vaša cestovná mapa. Rozdiel medzi tým, čo si používatelia žiadajú, a tým, čo obsahuje inventár, je váš backlog.

4. TOOLS.md — každý nástroj, každý spúšťač

Pre každý nástroj, ktorý agent môže volať:

• Názov a jednoriadkový účel.
• Kedy ho použiť (matica spúšťačov).
• Kedy ho NEPOUŽIŤ (zlyhaniu, ktorému chcete predísť).
• Nákladový profil — spotreba tokenov, latencia, vedľajšie účinky, vratnosť.
• Úroveň oprávnenia — automaticky schválené vs. so zapojením človeka.

Stĺpec s vratnosťou je ten, ktorý väčšina tvorcov vynechá a potom to ľutuje. Čítanie súboru je vratné. Odoslanie e-mailu nie. Zaobchádzajte s nimi v prompte odlišne a systém s nimi bude odlišne zaobchádzať aj v praxi.

5. ROUTING.md — rozhodovací strom

Keď agent dostane žiadosť, čo urobí ako prvé? Tento súbor na túto otázku odpovedá vývojovým diagramom v prozaickej podobe:

Request arrives
├── Trivial / read-only? → handle directly
├── Matches a specialist sub-agent trigger? → delegate
├── Multi-domain? → fan out to multiple sub-agents in parallel
├── Reversible and <€1K impact? → execute, report after
└── Irreversible OR >€1K OR ≥5 steps → plan-first, wait for approval

Presné prahové hodnoty patria vám. Existencia explicitných prahových hodnôt patrí každému serióznemu agentovi. „Použi úsudok" nie je smerovacia politika.

6. MEMORY.md — čo si pamätať, kde a ako dlho

Tri otázky, konkrétne zodpovedané:

• Čo sa oplatí ukladať naprieč reláciami? Preferencie používateľa, opravy, stav projektu, fakty o entitách. Nie: pominuteľné detaily úloh, veci odvoditeľné z kódu alebo git histórie.
• Kde to žije? Adresárová štruktúra s jedným súborom na tému plus index. Vyhnite sa jednému obrovskému súboru pamäte — stane sa z neho cintorín.
• Ako to zaniká? Niektoré spomienky sú trvalé (rola používateľa). Niektoré sú sezónne (priority aktuálneho kvartálu). Niektoré zastarajú v priebehu dní (stav obchodu). Označte typ.

Najväčšia chyba pri pamäti je hromadenie. Druhá najväčšia je považovať pamäť za autoritatívnu vtedy, keď sa svet už posunul ďalej. Zabudujte overovanie priamo do cesty čítania: „pamäť hovorí, že X existuje" nie je to isté ako „X existuje teraz".

7. WORKFLOWS.md — pomenované postupy

Pre každú opakujúcu sa úlohu napíšte postup raz a pomenujte ho. „Ranný prehľad", „návrh ponuky pre zákazníka", „spracovanie doručenej pošty", „týždenná revízia". Každá položka obsahuje:

• Spúšťač — čo používateľ povie, aby ho vyvolal.
• Vstupy — čo agent číta pred spustením.
• Kroky — samotný postup, očíslovaný.
• Výstup — formát súboru, umiestnenie, kto dostane upozornenie.
• Režim zlyhania — čo robiť, keď sa krok zablokuje.

Toto sú „zručnosti", „príkazy" alebo „playbooky" vášho systému. Ich pomenovaním sa jednorazové konverzácie menia na opakovane použiteľné aktíva a získate niečo merateľné: ako často sa jednotlivé workflow vyvolávajú, ako často sa čisto dokončia.

8. OUTPUTS.md — zmluva o odpovedi

Každý agent produkuje text. Takmer žiadny tím sa vopred nezhodne na tom, ako má tento text vyzerať. Potom strávia mesiace „smrťou tisícich opráv".

Zmluvu si vybavte vopred:

• Predvolená dĺžka podľa typu žiadosti (faktická otázka je jedna veta, strategický prehľad je štruktúrovaná správa).
• Poradie sekcií (nadpis, odpoveď, podporné odkazy, ďalšie kroky — vždy v tomto poradí).
• Vizuálne konvencie — sémantika emoji, pravidlá tučného/kurzívneho písma, používanie blokov kódu.
• Čo sa nikdy neobjaví — pochvalné úvody, vatové vyhýbavé formulácie, „Dúfam, že to pomôže".
• Správanie na konci ťahu — ponúka agent vždy ďalšie kroky? Niekedy? Nikdy?

Konzistentný hlas nie je estetická preferencia. Je to spôsob, akým si používatelia vytvárajú funkčný mentálny model toho, čo agent urobí ďalej.

9. FEEDBACK_LOG.md — plocha na učenie

Jediný súbor v systéme s najväčším pákovým efektom — a ten, na ktorý väčšina ľudí zabúda vytvoriť.

Zakaždým, keď používateľ agenta opraví („na konci nezhŕňaj"), potvrdí neevidentnú voľbu („áno, ten zlúčený PR bol správny") alebo zmení preferenciu, pridá sa sem záznam. Formát:

- Rule: <what to do or not do>
  Why: <the reason the user gave>
  How to apply: <when this kicks in>
  Added: <date>

Agent tento súbor číta na začiatku každej relácie. Opravy sa kumulujú. Bez tohto súboru mesiace dookola riešite tých istých päť chýb.

Ukladajte aj pozitívnu spätnú väzbu, nielen opravy. Ak logujete iba zlyhania, agent sa posúva smerom k prehnanej opatrnosti.

10. EVALUATION.md — ako viete, že to funguje

Posledný a najnepríjemnejší bod. Vopred si definujte, ako vyzerá úspech:

• Tvrdé metriky — miera dokončenia úloh, čas do prvého užitočného výstupu, miera eskalácie, počet halucinačných incidentov na 100 výstupov.
• Mäkké metriky — dôvera používateľa (nechajú ho bežať bez dozoru?), miera prekvapení (dobrých aj zlých), miera osvojenia funkcií pre jednotlivé workflow.
• Anti-metriky — veci, ktoré vyzerajú dobre, no v skutočnosti znamenajú, že agent bezpečne zlyháva. („Kladie veľa spresňujúcich otázok" môže znamenať dôkladnosť alebo paralýzu — o čo ide?)
• Frekvencia revízií — týždenná sebareflexia, mesačná retrospektíva, štvrťročný audit.

Ak neviete opísať, ako vyzerá zlý týždeň, nedokážete rozpoznať, keď práve taký prežívate.

Čo si všimnete v druhom týždni

Po nasadení v1 sa spoľahlivo objavia tri vzorce:

1. HARD_RULES.md rastie rýchlejšie, než čakáte. Každé „tesne unikol" pridá pravidlo. Odolajte pokušeniu ich zjemňovať; konkrétnosť je celý zmysel.
2. MEMORY.md sa súčasne zväčšuje a stáva menej užitočným. Naplánujte si prečistenie. Zastaraná pamäť je horšia než žiadna pamäť, pretože model jej dôveruje.
3. FEEDBACK_LOG.md je miesto, kde agent skutočne žije. Identita vám povie, kým je v prvý deň. Spätná väzba vám povie, kým je v deväťdesiaty deň.

Poznámka k tomu, čo v zozname nie je

Žiadny súbor pre prompty, žiadny súbor pre implementácie nástrojov, žiadny súbor pre orchestračnú slučku. Tie nadväzujú až na týchto desať. Ak sú tých desať súborov úprimných a konkrétnych, prompty sa napíšu takmer samy a orchestrácia je väčšinou len inštalatérska práca.

Ak je týchto desať súborov vágnych, nezachráni vás žiadne, hoci aj to najdômyselnejšie promptovanie.

Začnite tam.

Napísané priamo z terénu MIA (exekutívnej asistentky založenej na Claude) — 9 mesiacov v produkcii, ~500 súborov s pamäťou, ~50 workflow, jeden zadávateľ, nula ľútosti nad tým, že sme markdown napísali ako prvý.

[10 markdown súborov, ktoré by ste mali napísať skôr, než sa dotknete kódu agenta](https://stillvalid.dev/sk/playbooks/ten-markdown-files) — stillvalid, SV-4482 (playbook, verified 2026-05-25)