--- title: Štruktúra priečinkov, ktorá poháňa produkčného AI agenta type: deep-dive level: L2 status: live revision: 1 updated: 2026-05-25 systemVersion: 4.2 authoring: machine-translated tags: [structure, filesystem, organisation] rating: 7.85 ratingAxes: useful 8 · evidence 7 · pull 8 · original 8 · form 9 ratingKind: derived source: reddit r/ClaudeAI --- # Štruktúra priečinkov, ktorá poháňa produkčného AI agenta _Written 2026-05-25 · last verified 2026-05-25 · system v4.2 · live_ **TL;DR** — Usporiadanie súborového systému produkčného agenta po deviatich mesiacoch a približne štyroch refaktoroch, spolu s odôvodnením každého adresára. Model číta cesty a vyberá súbory podľa názvu, takže chaotický strom priečinkov vytvára agenta, ktorý sa odkláňa od cieľa — a to doslova, nie obrazne. *Prehliadka toho, ako som usporiadal súborový systém MIA — výkonnej asistentky založenej na Claude, ktorá je v produkčnej prevádzke približne 9 mesiacov — a prečo si každý adresár zaslúži svoje miesto. Ak sa chystáte postaviť agenta a máte pokušenie „priečinky vyriešiť neskôr", prečítajte si najprv toto.* --- ## Štruktúra priečinkov nie je administratíva. Je to nervový systém. Keď si ľudia predstavujú AI agenta, vidia model, prompty, možno volania nástrojov. Priečinky si nepredstaví takmer nikto. Presne preto väčšina svojpomocne postavených agentov stroskotá okolo druhého mesiaca. Súborový systém agenta je miesto, kde fyzicky žije jeho **identita, pamäť, práca a história**. Neuprataný súborový systém vytvára zmäteného agenta — a to doslova, nie obrazne. Model číta cesty. Model vyberá súbory podľa názvu. Model píše nové súbory na základe vzorov, ktoré vidí v tých starých. Ak je váš strom adresárov chaotický, každý výstup sa o čosi viac vzďaľuje od súdržnosti. Nižšie je usporiadanie, ku ktorému som dospel po deviatich mesiacoch a približne štyroch refaktoroch. Preberte si tie časti, ktoré vám sedia; na princípoch záleží viac než na presných názvoch. --- ## Konvencia číslovania Priečinky majú predponu z dvojciferného čísla: `01_`, `02_`, `09_`, `99_`. Dôvody sú dva: 1. **Poradie triedenia nesie význam.** Všetko, čo začína na `0`, sa nachádza pri vrchu. `99_` klesá na spodok. Najdôležitejšie adresáre sú vizuálne prvé; archívy sú vizuálne posledné. Mozog agenta čítate zhora nadol. 2. **Medzery sú zámerné.** Preskakujem z `04_` na `06_`, z `09_` na `11_`. Medzery sú rezervované miesta na vloženie. Keď sa objaví nová oblasť, zaradí sa bez toho, aby bolo treba premenovať všetko ostatné. Dva priečinky zámerne vynechávajú predponu: `Inbox/` a `Outbox/`. Sú prevádzkové, nie štrukturálne. Nachádzajú sa nad číslovanou sadou, pretože sa s nimi pracuje desiatky krát denne. --- ## `Inbox/` — nespracovaná hromada Všetko, čo sa dostane do sveta agenta, začína tu. Súbory, ktoré má spracovať. Snímky obrazovky. Exporty z iných systémov. PDF súbory, ktoré je potrebné analyzovať. Pravidlo: **v Inboxe nič nezostáva.** Vyhradená spracovateľská rutina triedi, presmerúva a maže. Ak Inbox nie je prázdny dlhšie ako deň, systém zlyháva. Predstavte si to ako skutočný fyzický zásobník na doručenú poštu. Zmyslom zásobníka je, že sa vyprázdňuje. --- ## `Outbox/` — čo agent vyprodukoval pre vás Každý súbor, ktorý agent kdekoľvek v strome zapíše, sem súčasne dostane kópiu. Keď otvorím `Outbox/`, vidím presne to, čo bolo vygenerované počas tejto relácie — bez prehrabávania sa dvanástimi podadresármi. Znie to nadbytočne. Nie je. Bez toho sa otázka „čo agent dnes urobil?" mení na pátranie. S tým je odpoveď na jeden klik. `Outbox` sa vymaže počas ďalšieho behu spracovania Inboxu. Je to zobrazovacia plocha, nie úložisko. --- ## `.auto-memory/` — aktívna pamäť Jednoznačne najdôležitejší adresár v systéme. V predvolenom nastavení skrytý, pretože by ste ho nemali upravovať ručne. Obsahuje pracovnú pamäť agenta: preferencie používateľa, pravidlá spätnej väzby, fakty o entitách (ľudia, firmy, obchody), aktívne hypotézy, odkazy na projekty, aktuálny kontext relácie. Zhruba 400 – 500 malých markdown súborov, každý venovaný jedinej téme. **Prečo skrytý?** Pretože je to kritická cesta agenta. Načítava odtiaľto pri každej relácii. Ak otvorím priečinok a začnem ho ručne prerovnávať, súperím s agentom o priorite. Zaobchádzajte s ním ako s databázou, nie ako so zápisníkom. **Prečo toľko malých súborov?** Pretože agent vyhľadáva (grepuje) podľa témy. Jeden monolitický pamäťový súbor sa pre model stáva nečitateľným okolo hranice 50 KB. Veľa malých súborov sa dá ľahšie čiastočne načítať, ľahšie indexovať, ľahšie nechať vypršať. --- ## `01_IDENTITY/` — kým agent je Ústavná vrstva. Meno, rola, pravidlá hlasu, zásobník princípov, vizuálny systém, predvolené správanie. Toto sa mení len zriedka. Keď sa to zmení, mení sa s tým aj všetko nadväzujúce. Držím ho ako priečinok `01_`, pretože každý ďalší priečinok naň nadväzuje. Ak neviete, kým agent je, nemôžete vedieť, ako by mali vyzerať jeho pracovné postupy, čo by si mal pamätať, ani ako by mal reagovať. --- ## `02_MEMORY/` — riadenie, nie dáta Jemný, no zásadný rozdiel: `.auto-memory/` obsahuje *dáta*, `02_MEMORY/` obsahuje *pravidlá o dátach*. V `02_MEMORY/` žije ústava, štartovací protokol, protokol pomenúvania, rozhodovací protokol, štandardy profilov (čo musí obsahovať „profil dodávateľa", čo musí obsahovať „profil zákazníka"), mapa schopností. Agent číta tieto dokumenty, aby vedel, *ako si má pamätať*, *ako pomenúvať nové súbory*, *ako rozhodnúť, čo je vratné*. Bez tohto priečinka je každý zápis do pamäte improvizáciou. --- ## `03_PROJECTS/` — aktívna práca Tu sa odohráva skutočná práca. Členené najprv podľa oblasti cieľa, potom podľa skratky (slug) projektu: ``` 03_PROJECTS/areas/{goal}/{slug}/ ``` Každý projekt má svoj vlastný priečinok so štandardnou kostrou: `README.md`, `TASKS.md`, `CHANGELOG.md`, `BRIEF.md`, plus pracovné súbory. Na vrchu je register projektov, ktorý agent číta, aby vedel, čo je aktívne, čo spí a čo je archivované. Najväčší disciplinárny problém tu: **nedovoľte projektom rozliezť sa mimo svojho priečinka.** Keď pracujete na Projekte X, každý súbor súvisiaci s Projektom X patrí dovnútra adresára Projektu X. Pokušenie odložiť „len jeden PDF" niekam inam je presne to, čo štruktúru zabíja. --- ## `04_PROMPTS/` — knižnica opakovane použiteľných promptov Pomenované, verziované prompty, ktoré si používateľ (alebo agent) môže vyvolať podľa ID. Každý má spúšťaciu frázu, prípad použitia, príklad a záznam o tom, kedy bol naposledy spustený. Toto je vec, ktorú si väčšina ľudí buduje neformálne — vkladaním dobrých promptov do Poznámok a ich následným stratením. Vytvorenie priečinka vynúti tri návyky: pomenúvate si svoje prompty, držíte ich na jednom mieste a viete skontrolovať, ktoré sa skutočne používajú. --- ## `06_KNOWLEDGE/` — výstupy z výskumu Všetko, čo agent *vyprodukuje* prostredníctvom výskumu, žije tu: analýzy trhu, hĺbkové rozbory dodávateľov, audítorské správy, prehľady noviniek, zosúlaďovacie správy. Usporiadané podľa témy, nie podľa dátumu — dátum je metadáta, nie štruktúra. Rozdiel oproti `03_PROJECTS/`: projekt je *práca smerujúca k výsledku*. Znalosti sú *porozumenie, ktoré si agent vybudoval a na ktoré sa môže neskôr odvolať*. Niektorý výskum patrí k projektu (žije v `03_PROJECTS/`). Prierezový výskum žije v `06_KNOWLEDGE/`. --- ## `07_LIBRARY/` — znalosti, ktoré agent NEVYTVORIL Externý materiál, na ktorý sa agent môže odvolávať: knihy zhrnuté do stručných prehľadov, zákony relevantné pre danú oblasť, štatistické správy, periodiká. V mojom prípade viac ako 100 položiek. Knižnica je z pohľadu agenta iba na čítanie. Kuratoruje vstupy. Nevymýšľa ich. Oddelenie `07_LIBRARY/` (externé) od `06_KNOWLEDGE/` (interné) je to, čo bráni agentovi zamieňať si vlastné výstupy s citovanými zdrojmi — kategória halucinácie, ktorá vie poriadne uškodiť, ak jej to dovolíte. --- ## `08_WORKSPACE/YYMMDD/` — denný pracovný priestor Dnešné návrhy, priebežné výstupy, pracovné súbory. Nový dátumovaný priečinok každý deň, keď agent vykoná zmysluplnú prácu. Lacné na vytvorenie, ľahko sa dá spätne pozrieť za týždeň a zistiť, čo sa dialo. Kľúčová vlastnosť: všetko v `08_WORKSPACE/` je **v predvolenom nastavení jednorazové/zahoditeľné**. Ak na tom záleží, povýši sa to do priečinka projektu, priečinka znalostí alebo prevádzkového priečinka. Ak sa to do niekoľkých dní nepovýši, aj to je informácia — znamená to, že to nebolo dôležité. Dátumované podpriečinky tiež znamenajú, že dva výstupy s rovnakým názvom súboru sa nikdy nezrazia. --- ## `09_OPERATIONS/` — štandardné postupy a opakujúce sa procedúry Štandardné prevádzkové postupy, ktorými sa agent riadi. Definície naplánovaných úloh. Dokumentácia exportu zručností. Všetko, čo popisuje, „ako agent opakovane vykonáva tento druh práce". Ak je `02_MEMORY/` ústava, `09_OPERATIONS/` je procedurálny kód. Oddelené preto, lebo ústavy sa menia zriedkavo, zatiaľ čo procedúry sa neustále vyvíjajú. --- ## `11_SESSIONS/` — archív konverzácií Každá konverzácia s agentom sa tu archivuje, usporiadaná podľa dátumu. Prehľadávateľná pomocou fulltextového indexu. Tu sa zodpovedá otázka typu „o čom sme sa pred šiestimi týždňami rozprávali ohľadom X". Za zmienku stoja dve dizajnové rozhodnutia: relácie sa zapisujú iba raz (staré konverzácie sa neupravujú) a sú usporiadané plocho podľa dátumu (`11_SESSIONS/YYMMDD/`), nie vnorene podľa témy. Plochá štruktúra sa dobre škáluje; tematická nie. --- ## `99_ARCHIVE/` — studené úložisko Uzavreté projekty, zastarané zručnosti, vyradené pamäťové súbory. Nemažú sa — presúvajú sa. Dôvod, prečo mať explicitný archív namiesto mazania: agent príležitostne potrebuje odkázať na to, ako niečo *kedysi* fungovalo, alebo zvrátiť vyradenie, ktoré sa ukázalo ako chybné. Disk je lacný. Stratený kontext je drahý. Dôvod, prečo je to `99_`: nech to padne na spodok pri triedení. Vizuálne by to malo pôsobiť ako pivnica. --- ## Dva priečinky, ktoré sa do vzoru nehodia **`00_ASSETS/`** — brandové materiály, logá, šablóny, fonty. Priorita triedenia `00_`, pretože sú príležitostne potrebné a chcete, aby boli nájditeľné, no nie sú súčasťou uvažovacej slučky agenta. Sú to nástroje, nie myšlienky. **`10_DASHBOARDS/`** — generované HTML dashboardy, ktoré si používateľ otvára v prehliadači, aby videl pohľad agenta na rôzne oblasti. Prezentačná vrstva, nie dátová vrstva. Nachádza sa v blízkosti `08_WORKSPACE/`, pretože má tiež formu výstupu, no je oddelená, pretože dashboardy pretrvávajú, zatiaľ čo pracovné súbory nie. --- ## Čo som zámerne NEVYTVORIL ako priečinok - **Žiadne `LOGS/`.** Logy patria dovnútra priečinka veci, ktorá sa loguje (relácie majú svoje vlastné logy, naplánované úlohy majú svoje vlastné logy). Centralizované logy sa stávajú nečitateľnými. - **Žiadne `TEMP/`.** `08_WORKSPACE/` už je dočasným adresárom. Pridanie druhého by rozdrobilo pravidlo o jednorazovosti. - **Žiadne `MISC/` ani `OTHER/`.** Do takýchto priečinkov chodia systémy umierať. Ak niečo nesedí, znamená to, že štruktúra je nesprávna a potrebuje nový domov, nie zbernú škatuľu na haraburdy. --- ## Čo si všimnete počas prvého mesiaca Spoľahlivo sa objavia tri veci: 1. **`Inbox/` pretečie skôr, než bude spracovateľská rutina spoľahlivá.** Rutinu postavte hneď prvý deň. Inak sa inbox zmení na emocionálnu záťaž, nie na prevádzkový front. 2. **`08_WORKSPACE/` sa naplní rýchlejšie, než čakáte.** To je v poriadku. Zmyslom jednorazového pracovného priestoru je, že sa hromadí bez výčitiek svedomia. 3. **Agent sa bude pokúšať zapisovať do koreňového adresára.** Neustále. Musíte zaviesť striktné pravidlo proti tomu a vynucovať ho na úrovni promptu. Bez tohto pravidla sa vaša najvyššia úroveň postupne mení na bažinu zatúlaných súborov. --- ## Hlbší princíp Štruktúra priečinkov je agentovou **fyzickou teóriou samého seba**. Hovorí: toto je moja pamäť, toto je moja práca, toto je moja história, toto je môj referenčný materiál. Každý priečinok je kategória myslenia zhmotnená do podoby. Keď sú kategórie čisté, agent myslí jasne. Keď sa kategórie rozmažú, presne tak isto sa rozmažú aj výstupy agenta. Venujte popoludnie stromu priečinkov skôr, než strávite mesiac nad promptmi. --- *Prehliadka skutočného súborového systému MIA — názvy mierne zovšeobecnené, štruktúra nezmenená. Strom prežil štyri refaktory a je, konečne, nudný. Nudný je cieľ.*