Čo mám vo svojom AGENTS.md a čo som z neho vyhodil

Pravidlá, ktoré si nechávam

Do súboru dávam veci, ktoré agent z kódu nevyčíta. Ako s ním chcem komunikovať, čo smie urobiť sám a kde má zastaviť. Pár skutočných riadkov z mojich súborov:

Explain everything like he is 17. Be concise, human and easily understandable.

Toto platí pre všetko, čo mi agent píše. Nie je to o detskom jazyku. Je to o tom, aby som odpoveď pochopil na prvé prečítanie.

Decide reversible and low-stakes things yourself and say what you chose in one line.

Hneď pod tým je zoznam vecí, pri ktorých sa pýtať musí: správy a e-maily iným ľuďom, peniaze, mazanie dát bez zálohy, verejný web a produkčné databázy. Všetko ostatné, teda názvy súborov, commit do vlastnej vetvy alebo reštart servera, si rozhodne sám.

E-mail má ešte vlastnú bránu. Agent najprv pripraví koncept, ukáže mi príjemcov, predmet aj celé telo a odošle ho až po mojej samostatnej správe s jednou presnou vetou. Súhlas napísaný rovno v zadaní nestačí.

End every finished deliverable with one clickable link.

K odkazu pridá jeden riadok stavu: či je to hotové, kde to beží a čím to overil. Nemusím sa dopytovať, kde to je a či je to už nasadené.

Potom mám tri pracovné režimy, ktoré prepínam jedným slovom v zadaní. Pri „RÝCHLO“ agent robí najmenšiu nutnú zmenu, sám ju commitne a pushne. Pri „DEEP“ hľadá príčinu a púšťa všetky relevantné kontroly. „IBA DIAGNOSTIKA“ znamená, že len číta a nesmie nič meniť ani posielať. Keď nenapíšem nič, platí rýchly režim.

A potom drobnosti, ktoré mi agent kazil opakovane. Napríklad že macOS nemá príkaz timeout, alebo že v zsh sa v podmienke porovnáva jedným =. Sú to dva riadky a agent na nich už nepadá.

Pravidlá pre zdieľané priečinky

V koreni PACTu má najväčšiu váhu časť o tom, čo je osobné a čo firemné. Firemné priečinky sú v zdieľanom Dropboxe, kam zapisujú aj kolegovia, takže tam platí:

Sdílené vrstvy jsou append-only.

Agent v nich nič cudzie neprepisuje ani nemaže. Nový obsah pridá vedľa a o nahradení sa najprv dohodneme. Druhé pravidlo hovorí, že nástroje, ktoré držia môj systém pokope, ležia len v osobnej časti. Keby boli vo firemnej, ktokoľvek by mi ich mohol omylom prepísať.

Tretie pravidlo je kratšie, ale ušetrilo najviac otázok:

Na zapsanou věc se znovu neptej.

Trvalé rozhodnutia, napríklad tykanie alebo vykanie, jazyk či názvy, mám v jednom súbore s rozhodnutiami. Agent si ho prečíta pred písaním. Vzniklo to v októbri, keď som si prešiel posledných 30 dní práce a agenti sa ma pýtali stále na to isté. Rozhodnutia ležali vo worklogoch alebo v pamäti, ktorú videl iba Claude. Codex o nich nevedel.

Riadky, ktoré som vyhodil

Tabuľky príkazov. Z tých 446 riadkov ostalo 71, z CLAUDE.md 32. Zostal kontext projektu, bezpečnostné hranice a odkazy na dokumentáciu, kde príkazy naozaj žijú. Pôvodné súbory som celé archivoval a pridal kontrolu, ktorá súbor nad 150 riadkov alebo s tabuľkou príkazov odmietne.

História zmien. Desať projektových AGENTS.md malo vlastnú sekciu „Changelog“, niektoré so 44 riadkami. Agent ju čítal pri každej návšteve projektu, hoci na prácu nepotrebuje vedieť, čo sa zmenilo pred tromi mesiacmi. Pôvodcom bol jeden môj skill, ktorý agentom kázal changelog do AGENTS.md písať. Opravil som skill a história sa presunula do worklogu projektu.

Neplatné cesty. Pri tom istom audite vyšlo, že desať riadkov v mojich inštrukciách ukazovalo na súbory, nástroje alebo premenné, ktoré už neexistovali. Agent sa nimi poctivo riadil a hľadal niečo, čo tam nebolo. Najhorší bol príkaz na zápis do worklogu projektu. Keď som ho spustil v koreni PACTu, zapísal by do globálneho worklogu.

Zoznam, kto čo robí. Na konci októbra mal koreňový AGENTS.md v PACTe 199 riadkov. Sekciu o tom, ktorý agent alebo skill vlastní akú úlohu, som presunul do samostatného súboru, ktorý agent otvorí, až keď to potrebuje. Súbor klesol na 151 riadkov. Spolu s ďalšími úpravami v ten istý deň klesol štart novej session z približne 57 tisíc tokenov na 50,5 tisíca.

Pravidlo, ktoré sa obrátilo proti mne

Jedno pravidlo som nevyhodil, ale do večera som ho musel prepísať. Chcel som šetriť, tak som si pridal podagenta s lacnejším modelom na prácu v prehliadači a do AGENTS.md pravidlo, kedy ho použiť.

Podagent však nemal prístup k môjmu Chromu. Hlavná session to vyriešila po svojom a spustila si vlastné okno prehliadača, čo mám inde v pravidlách výslovne zakázané. Dnes tam stojí opak: prehliadač beží vždy v hlavnej session. Keď chcem lacnejší model, otvorím novú session priamo s ním.

Ako držím AGENTS.md krátky

1. Pridávam len to, čo agent nevyčíta sám. Štruktúra projektu sa dá zistiť z priečinkov, moje hranice nie.
2. Pred novým riadkom si odhadnem cenu. Celý súbor sa načíta pri každej požiadavke, takže aj pár viet navyše platím stále dookola.
3. Podrobnosti dávam do vedľajších súborov. V AGENTS.md ostane jedna veta, kedy ich má agent otvoriť.
4. Históriu píšem do worklogu, nie do pravidiel. Pravidlá majú hovoriť, čo platí dnes.
5. Raz za čas pustím audit. Hľadám zastarané cesty, duplicity a pravidlá, ktoré si odporujú. Pôvodné verzie pred úpravou vždy zálohujem.

Ako súbor založiť a čím sa líši CLAUDE.md od AGENTS.md, sme rozpísali na blogu Aibility.