# Brain System: návod pro AI agenta > Zdroj: https://ongy.cz/pages/ai/brain/ > Autor: Ongy (ongy.cz). Brain System: složka s textovými soubory v každém projektu, kterou si AI agent na začátku přečte a na konci sám doplní. Změny, úkoly, rozhodnutí a poznámka pro příští session. ## Pro agenta Pomoz uživateli postavit vlastní verzi tohohle projektu. Nejdřív se ho zeptej na vybavení a na to, co z požadavků už má. Pak postupuj po krocích a po každém kroku s ním ověř, že funguje, než půjdeš dál. Hodnoty v `` doplň s uživatelem, nikdy si nevymýšlej adresy, hesla ani tokeny. Kód autora není veřejný: tohle je popis řešení, ne repozitář ke stažení. ## Cíl Dlouhodobá paměť projektu pro AI agenta v podobě složky `.brain/` s obyčejnými Markdown soubory: co se udělalo, na čem se pracuje a v jakém stavu, co platí, proč se co rozhodlo a co je na řadě příště. Agent si na začátku session načte jen krátký přehled, během práce paměť sám průběžně doplňuje a na konci jedním příkazem připraví předávku na další session. Autorovy skills ani skripty nejsou veřejné: postav vlastní podle popsaného principu a struktury. ## K čemu to je Každý rozhovor s AI začíná od nuly. Co jsme minule vymysleli, dnes neví. U projektu na měsíce je to průšvih. Brain System je složka textových souborů v projektu. Agent si ji na začátku přečte a ví, kde jsme skončili. Na konci sám zapíše, co udělal a co je na řadě. Řeknu „načti si brain“ a jedeme dál. ## Proč právě takhle Web, tracker na deskovky, domácí server, práce. Samá krátká sezení a každé začínalo stejně: jaký stack, jaká pravidla, co bylo minule. První pokus byl jeden soubor s poznámkami. Rychle přerostl. Chtěl jsem strukturu, kde má každý typ informace své místo, a agenta, který ji udržuje sám. ## Jak to funguje - **Na začátku přečte, kde jsme skončili.** Zkontroluje rozdělanou práci, načte úkoly a poznámku pro tuhle session. - **Každý úkol má životní cyklus.** Otevřený, naplánovaný, v procesu, hotový. Stavy mění agent sám. - **Návody se načítají až podle potřeby.** Sedm malých skills, každý pro jednu činnost. - **Na konci zapíše, co se stalo a co dál.** Jeden příkaz: changelog, úkoly, poznámka pro příště. ## Formát a mechanika - **Formát:** Obyčejný Markdown ve složce `.brain/`, verzovaný spolu s projektem v Gitu. Žádná databáze, žádný plugin. Čitelné pro člověka i pro model. - **Lifecycle úkolů:** OPEN → PLAN → PROCESS → TEST → REVIEW → DONE → ACCEPTED. Jeden číslovaný soubor na úkol. Přechody dělá agent sám, hotové úkoly se archivují. - **Skills a příkazy v Claude Code:** Sedm skills: memory-reader, first-answer, task-lifecycle, changelog-writing, context-files, decision-making, mastery. Načítají se podle situace, ne při startu. Příkazy `/brain-status`, `/brain-update`, `/brain-finish`, `/brain-cleanup`, `/brain-debug`. - **Token efektivita:** v1.0 načítala při každém startu kolem 20 kB pravidel. v2.0 s on-demand skills asi 5 kB, úspora zhruba 85 %. Kvalita výstupu bez rozdílu. ## Více počítačů a agentů Paměť všech projektů žije v jednom soukromém Git repu, projekty do něj odkazují symlinkem. `/brain-finish` změny commitne a pushne, na druhém počítači stačí pull. Pro větší úkoly hlavní agent deleguje sub-agentům (rešerše, dokumentace, testy, analýza gitu) a paměť je jejich společný kontext. Jednoduché věci řeší rovnou sám. ## Jak vypadá začátek session Čistý repo: přehled projektu, aktivní úkoly a otázka, na čem pokračujeme. Rozdělaný repo: agent se zastaví a nabídne dokončit a commitnout, pokračovat v práci, nebo změny odložit. Konec session: `/brain-finish` projde úkoly, zapíše changelog a připraví poznámku pro příště. ## Co budeš potřebovat - AI agent, který umí číst a zapisovat soubory v projektu a spouštět příkazy (autor: Claude Code se skills a vlastními příkazy). Jiný agent viz Přizpůsobení. - Projekt ve složce, ideálně verzovaný v Gitu. - Bash pro stavový skript (na Windows Git Bash nebo WSL) a volitelně `ripgrep` (`rg`) pro rychlé hledání ve stavech úkolů. - Volitelně soukromý Git repozitář pro paměť více projektů a počítačů `` (autor: jeden soukromý repozitář, projekty do něj odkazují symlinkem). - Žádná databáze, server ani plugin navíc. ## Postup ### 1. Struktura složek V kořeni projektu vytvoř `.brain/memory/` a v ní: `tasks/` (aktivní úkoly) s podsložkou `archive/`, `changelog/` (historie po měsících), `context/` (opakovaně použitelné vzory a postupy), `decisions/` (rozhodnutí a jejich důvody), `learned/` (poučení z chyb), `trash/` (měkké mazání místo `rm`). Do kořene `memory/` soubory `NEXT_SESSION_TODO.md` (předávka), `todo-later.md` (odložené nápady) a `rules.md` (pravidla specifická pro projekt). Jedním příkazem: `mkdir -p .brain/memory/{tasks/archive,context,decisions,learned,changelog,trash}`. ### 2. Úkoly se stavem Jeden soubor na úkol s názvem `NNNN-kebab-case-nazev-YYYY-MM.md`, číslo o jedna vyšší než nejvyšší existující (počítej i archiv). Hlavička: nadpis, `**Created:** YYYY-MM-DD`, `**Lifecycle:** OPEN`, `**Priority:** High | Medium | Low`. Sekce `## What` (co a proč), `## Plan` (očíslované kroky), `## How` (poznámky k implementaci) a `## Status Log` (datované řádky). Stav je na jednom řádku v přesném tvaru, aby ho šlo najít grepem. Úkol ve stavu ACCEPTED se přesune do `tasks/archive/YYYY-MM/`. ### 3. Changelog, context, decisions a předávka Changelog: soubor `changelog/YYYY-MM.md`, záznam `## YYYY-MM-DD - Název session` a pod ním krátké odrážky s výsledky, nejnovější nahoře. Context: `context/tema.md` se sekcemi přehled, použití, příklady, na co pozor a odkazy na úkoly. Decisions ve stylu ADR: `decisions/YYYY-MM-tema.md` s datem, stavem (Proposed, Accepted, Superseded), kontextem, zvažovanými možnostmi s plusy a minusy, rozhodnutím, zdůvodněním a důsledky. NEXT_SESSION_TODO: datum, jedna věta o poslední session a zaškrtávací položky `- [ ]` seřazené podle priority, u každé další konkrétní krok. Volitelně `MEMORY.md` jako rejstřík: jeden řádek na soubor, odkaz a krátký popis (autor: u jednoho projektu rejstřík a k němu tematické soubory s hlavičkou name, description, type). ### 4. Pravidla v instrukcích agenta Do trvalých instrukcí agenta (u Claude Code `CLAUDE.md` v projektu nebo globálně) napiš krátce: když existuje `.brain/memory/`, na začátku session ji načti; do paměti zapisuj sám bez ptaní; co patří kam (úkol, changelog, context, decisions, learned); changelog zapisuj výsledky, ne průběh; staré rozhodnutí neupravuj, ale nahraď novým a staré označ jako Superseded; do paměti nikdy nepiš hesla, tokeny ani klíče. Podrobnosti dej do samostatných návodů (krok Skills), ne do těchto instrukcí, ať se nenačítají pokaždé. ### 5. Začátek session Nejdřív `git status`. Když jsou v repozitáři neuložené změny, agent je vypíše, nabídne dokončit a commitnout, pokračovat, nebo odložit, a čeká na odpověď. Když je čisto, spustí stavový skript, který vypíše jen: prvních zhruba 20 řádků changelogu za aktuální měsíc, aktivní úkoly mimo archiv se stavem z řádku `**Lifecycle:**`, počet otevřených `- [ ]` v NEXT_SESSION_TODO a v todo-later. Když `.brain/memory/` chybí, skript skončí nenulovým kódem s radou, jak paměť založit. Obsah jednotlivých souborů agent otevírá až podle toho, na čem se bude pracovat. ### 6. Zápis během práce Agent zapisuje průběžně při událostech, ne až na konci: zadání práce → nový soubor úkolu (OPEN) a řádek v changelogu; hotový průzkum → PLAN; začátek psaní kódu → PROCESS; hotová implementace → TEST; prošlé testy → REVIEW; schválení → DONE; převzetí uživatelem → ACCEPTED a archiv. Milník nebo opravená chyba → odrážka v changelogu. Volba mezi alternativami, která bude platit dlouho → soubor v decisions. Postup, který se bude hodit znovu → soubor v context. Chyba, která stála hodně času → soubor v learned. ### 7. Konec session Jeden příkaz (autor: `/brain-finish`) projde aktivní úkoly a upraví jim stav, zapíše do changelogu souhrn session, přepíše NEXT_SESSION_TODO (dnešní datum, co je rozdělané, první konkrétní krok příště), přesune ACCEPTED úkoly do archivu a vypíše shrnutí. Pokud je `.brain` symlink do sdíleného repozitáře paměti, změny tam commitne, udělá `git pull --rebase` a pushne. ### 8. Skills a příkazy Návody, jak s pamětí zacházet, rozděl do malých skills, každý na jednu činnost: načtení stavu, protokol začátku session, životní cyklus úkolů, psaní changelogu, context soubory, rozhodnutí a jeden velký referenční pro vývoj samotného systému. U Claude Code je to `~/.claude/skills//SKILL.md` s hlavičkou `name` a `description`. Popis začni „Use when…“ a vyjmenuj spouštěcí fráze, protože podle něj agent pozná, kdy skill načíst. Stavový skript přilož do složky skillu. Příkazy pro uživatele (stav, synchronizace po ručních úpravách, konec session, úklid, ladění) jako `~/.claude/commands/.md`. V domovské složce platí pro všechny projekty. ### 9. Více projektů a úklid Pro víc projektů a počítačů založ soukromý repozitář `` se složkami třeba `work/` a `personal/`, paměť projektu přesuň do `/personal/` a v projektu nech jen symlink `.brain`. Skills a příkazy mohou žít ve vlastním repozitáři a do `~/.claude/skills/` a `~/.claude/commands/` je nalinkuje skript, takže změna platí všude po jednom pullu. Jednou za čas úklid: archivovat staré DONE a ACCEPTED úkoly, najít soubory, na které nic neodkazuje, projít zastaralé položky a z todo-later povýšit, co je na řadě. ## Na co si dát pozor - Paměť zapsaná jen na konci session se ztratí, když session skončí jinak než příkazem (zavřený terminál, vyčerpaný kontext, pád). Proto zapisovat průběžně při každém milníku. - Číslo nového úkolu počítané jen z aktivních souborů se po archivaci zopakuje a vzniknou dva úkoly se stejným číslem. Hledat nejvyšší číslo včetně `archive/`. - Stavový skript čte stav a otevřené položky podle přesného zápisu (`**Lifecycle:** PROCESS`, `- [ ]`). Když agent napíše „Status: in progress“ nebo odrážku bez zaškrtávátka, přehled ukáže prázdno, i když práce běží. Formát drž striktně. - NEXT_SESSION_TODO má tendenci přerůst v druhý changelog. Hotové položky přesouvat do changelogu a nechat jen otevřené, jinak se začátek session znovu prodlouží. - Jednorázové poznámky k úkolu v `context/` zaplevelí vzory, které se mají načítat opakovaně. Poznámka patří do souboru úkolu, do context jen to, co se použije znovu. - Paměť je text, který čte model a který se verzuje a pushuje. Hesla, tokeny a klíče do ní nepatří ani omylem v changelogu; zapisuj jen, kde tajemství leží (třeba `.env`), ne jeho hodnotu. - Paměť je nápověda, ne pravda. Než agent podle ní něco změní (cesta, verze, stav služby), musí to ověřit proti skutečnosti, jinak sebevědomě opakuje zastaralý údaj. - Skill s vágním popisem se nikdy nenačte a agent pak zapisuje každý den jinak. Popis musí říkat, kdy skill použít, a obsahovat fráze, které uživatel opravdu píše. ## Jak ověřit, že to funguje - [ ] `ls .brain/memory` ukáže složky tasks, changelog, context, decisions, learned, trash a soubor NEXT_SESSION_TODO.md. - [ ] Stavový skript spuštěný v kořeni projektu skončí s kódem 0 a vypíše čtyři části (changelog, aktivní úkoly, NEXT_SESSION_TODO, todo-later). Ve složce bez `.brain/` skončí nenulovým kódem s radou. - [ ] Nová session a věta „načti si brain“: agent v první odpovědi sám uvede poslední záznam changelogu a první otevřenou položku z NEXT_SESSION_TODO, aniž bys cokoli vysvětloval, a neotevře všechny soubory v `context/`. - [ ] Zadání nové práce: bez ptaní vznikne `tasks/NNNN-...-YYYY-MM.md` s číslem o jedna vyšším než nejvyšší včetně archivu a s `**Lifecycle:** OPEN`. - [ ] Během implementace `grep -r "Lifecycle" .brain/memory/tasks` ukazuje u úkolu postupně PLAN, PROCESS a TEST. - [ ] Po příkazu na konec session: `changelog/YYYY-MM.md` má nahoře záznam s dnešním datem, NEXT_SESSION_TODO má dnešní datum a úkoly ve stavu ACCEPTED jsou v `tasks/archive/YYYY-MM/`. - [ ] Neuložená změna v souboru projektu a nová session: agent vypíše změněné soubory, nabídne tři možnosti a do rozhodnutí nepokračuje. - [ ] `grep -rniE "password|token|api_?key|secret" .brain/` nenajde žádnou hodnotu tajemství, nanejvýš odkaz na místo, kde leží. - [ ] S více počítači: po konci session na prvním a `git pull` na druhém vidí agent na druhém stejnou NEXT_SESSION_TODO. - [ ] Session po týdnu pauzy: k pokračování v práci stačí jedna zpráva, bez ručního vysvětlování stacku a pravidel. ## Přizpůsobení - Jiný agent (Codex, Cursor, Gemini CLI a podobně): pravidla z kroku 4 dej do jeho souboru s instrukcemi (třeba `AGENTS.md`), návody ze skills jako Markdown soubory v `.brain/` a příkazy jako věty typu „proveď postup z `.brain/finish.md`“. Struktura složek zůstává stejná. - Malý nebo krátký projekt: začni s changelogem, NEXT_SESSION_TODO a úkoly. Context a decisions přidej, až se objeví první opakovaný postup nebo rozhodnutí, ale typy informací nemíchej do jednoho souboru. - Tým: paměť nech přímo v repozitáři projektu místo soukromého vaultu, rozhodnutí a context se hodí i lidem. Osobní předávku (NEXT_SESSION_TODO) drž mimo sdílenou větev nebo po jednom souboru na člověka, ať se nepřepisuje. - Windows bez Bashe: stavový skript přepiš do PowerShellu a symlink vytvoř přes `mklink /D` (vyžaduje režim vývojáře nebo práva správce). Git potřebuje `core.symlinks=true`, jinak z odkazu udělá obyčejný soubor. --- Stránka projektu s fotkami a diagramem: https://ongy.cz/pages/ai/brain/