AI kontextové soubory v repozitáři: CLAUDE.md, AGENTS.md a server

AI asistent pro programování otevřený v repozitáři zná kód a nic jiného. Neví, na jakém portu server poslouchá, že restart přežije jen jeden adresář, že tu není root ani systemd, ani že push nasadí novou verzi během pár sekund. Tak hádá a hádá podle výchozích hodnot z tutoriálů: port 3000, localhost, Dockerfile, o který nikdo nestál, heslo vložené přímo do konfiguračního souboru. Řešením je obyčejný soubor Markdown v repozitáři, který si asistent přečte, než se do práce pustí - CLAUDE.md pro Claude Code, AGENTS.md pro Codex, Cursor a čím dál delší seznam dalších nástrojů. Na aplikačních serverech RE:NODE propojených s GitHubem vám ten soubor umí napsat panel: na záložce GitHub zapněte Keep AI context in the repository a panel otevře pull request, který přidá .renode/server.md a krátký označený blok do CLAUDE.md a AGENTS.md. Přečtete si ho, sloučíte ho a od té chvíle asistent ví, jak server běží, aniž by mu to někdo musel vkládat ručně.

Tento článek pokrývá obě poloviny: co kontextový soubor je a jak napsat dobrý na jakémkoli hostingu, a také přesně co panel zapisuje, co vynechává a jak do toho vstupuje pre-flight kontrola.

Co je AI kontextový soubor#

Kontextový soubor jsou pokyny pro agenta uložené vedle kódu. Když agentní nástroj zahájí v repozitáři relaci, hledá v kořeni (a občas i v podadresářích) soubor se známým názvem, přečte ho a bere ho jako trvalé pokyny pro celou relaci. Není to konfigurace v pravém slova smyslu - nic ho neparsuje - je to text a seznamy, které model čte stejně jako váš prompt, jen je napíšete jednou.

Patří do něj to, co by nový kolega potřeboval vědět hned první den a jinak by se musel ptát:

• jak projekt nainstalovat, sestavit, otestovat a spustit, jako přesné příkazy;
• kde co leží a které adresáře jsou generované a nesmí se upravovat;
• konvence, které z kódu nejsou zřejmé - pojmenování, zacházení s chybami, která knihovna vyhrává, když by se hodily dvě;
• prostředí, ve kterém kód skutečně běží, a jeho limity;
• věci, které se nikdy nesmí stát: tajné údaje v commitech, úpravy převzatého kódu, force push.

Poslední dvě položky bývají v kontextových souborech nejchudší a právě tam vzniká nejvíc škod. Asistent, který nezná prostředí nasazení, píše kód pro notebook. Kód pro notebook poslouchá na 127.0.0.1, ukládá nahrané soubory do /tmp a počítá s tím, že si může pomocí apt install doinstalovat, co potřebuje. Na kontejnerovém hostingu všechno tohle selže, a to potichu. Obecné způsoby selhání agentů při práci na serverech jsme rozebrali v článku AI coding agents for server and DevOps work; kontextový soubor je nejlevnější pojistka proti chybám typu „špatné prostředí“.

Který nástroj čte který soubor#

Jednotný standard zatím neexistuje a názvy souborů jsou trochu chaos. Užitečné shrnutí k závěru roku 2026:

AGENTS.md je nejblíž společnému formátu: obyčejný soubor Markdown bez povinné struktury, který se několik výrobců dohodlo číst. CLAUDE.md je název, který pro stejný nápad používá Claude Code; čte také soubory CLAUDE.md v podadresářích, když v nich pracuje, a osobní soubor ve vašem domovském adresáři. Podpora v nástrojích se rychle mění, takže pokud na některém záleží, ověřte si v jeho dokumentaci, které názvy aktuálně vyhledává.

Dvě praktické poznámky. Za prvé, pokud tým používá víc asistentů, potřebujete stejné základní pokyny ve víc než jednom souboru. Držet je ručně shodné dlouho nevydrží; obvyklé řešení je nechat společnou část krátkou a oba soubory odkázat na jeden delší dokument. Za druhé, chatový asistent, třeba ChatGPT v prohlížeči, váš repozitář sám nečte vůbec. Ví jen to, co mu dáte - proto má panel pro tento případ i odkaz ke sdílení, o kterém je řeč na konci.

Co do něj patří a co ne#

Nejlepší kontextové soubory jsou krátké a konkrétní. Model čte každý řádek souboru při každé relaci a dlouhý soubor plný obecných rad ředí těch pár řádků, na kterých záleží. Dobrý test pro každý řádek: spletl by se asistent, který tento soubor nikdy neviděl? Pokud ne, smaž ho. „Piš čistý kód“ tímto testem neprojde. „Server poslouchá na portu z SERVER_PORT, ne na 3000“ projde.

Malá služba v Node by mohla mít tohle:

# Orders API## Commands- Install: npm ci- Test: npm test (needs a local Postgres, see docker-compose.yml)- Start: npm start (runs node dist/server.js; build first with npm run build)## Layout- src/ is the code; dist/ is generated - never edit it.- migrations/ is append-only. Add a new file; never change a merged one.## Rules- Read configuration from environment variables only. See .env.example.- Never commit .env or any key, token or password.- Use the existing logger in src/log.ts, not console.log.

Co do něj nepatří:

• Tajné údaje. Kontextový soubor se commituje, takže cokoli v něm zůstane v historii nadobro. Uveďte název proměnné, nikdy její hodnotu. O tom, kde mají hodnoty žít místo toho, je článek Environment variables and secrets.
• Věci, které se mění při každém nasazení. Aktuální commit, čas posledního nasazení, číslo buildu. Okamžitě zastarají a každý diff z toho bude šumem.
• Věci, které už říká kód. Seznam routes, schéma databáze. Asistent si je přečte sám; jejich opisování do prózy jen vytvoří druhou verzi, která se začne rozcházet.
• Dlouhé tutoriály. Odkažte raději na dokument v repozitáři a nechte asistenta, ať ho otevře, až ho bude potřebovat.

Část, kterou většina lidí vynechává, je server. Napíšou příkazy a konvence a tím skončí, protože server jim připadá jako cizí starost. Přitom právě tuhle část umí doplnit panel, protože panel je jediné místo, které ji zná přesně.

Přepínač AI kontextu na záložce GitHub#

Na aplikačním serveru propojeném s repozitářem na GitHubu je na záložce GitHub přepínač: Keep AI context in the repository (opens a pull request). Dokud ho nezapnete, je vypnutý, a platí vždy jen pro jedno propojení. Pro repozitář, jehož vlastník na něj nekliknul, se nikdy nic neotevře.

Když je zapnutý, GitHub App panelu - ta samá, která obsluhuje nasazování z GitHubu - udělá toto:

1. Vytvoří větev renode/ai-context z hlavy větve, ze které se váš server nasazuje.
2. Přes API GitHubu do ní commitne .renode/server.md a označené bloky v CLAUDE.md a AGENTS.md. Nic se nekloňuje.
3. Otevře pull request z renode/ai-context do vaší větve pro nasazení.
4. Vy ho projdete a sloučíte, nebo zavřete.

Panel nikdy neposílá nic do větve, ze které se server nasazuje. Každý commit jde do vlastní větve renode/ai-context a sloučení je vaše rozhodnutí. Pushe do větví renode/ navíc ignoruje hook nasazení při pushi, takže obnova kontextu server nikdy nerestartuje.

Stavový řádek pod přepínačem říká, jak to vypadá: vypnuto, pracuje se na tom, čeká se na oprávnění, otevřený pull request proti vaší větvi, aktuální, poslední pull request zavřen bez sloučení, nebo chyba. Každé odmítnutí od GitHubu - limit požadavků, chráněná větev, archivovaný repozitář, chybějící oprávnění - se objeví jako jeden z těchto řádků, ne jako chybová stránka. Obecný postup, jak vůbec repozitář propojit, je v průvodci nasazováním.

Co panel do repozitáře zapisuje#

Dva druhy obsahu s různým vlastnictvím.

Blok v CLAUDE.md a AGENTS.md

V CLAUDE.md a AGENTS.md panelu patří jen text mezi dvěma HTML komentáři, <!-- renode:start --> a <!-- renode:end -->. Pokud soubor neexistuje, vytvoří se a obsahuje jen ten blok. Pokud existuje bez značek, blok se přidá na konec. Pokud značky má, nahradí se jen to, co je mezi nimi. Všechno, co jste napsali mimo ně, přežije bajt po bajtu, takže vaše vlastní příkazy a konvence stojí nad částí panelu nebo pod ní, aniž by se jich cokoli dotklo. HTML komentáře se na GitHubu nevykreslují, takže značky jsou při čtení souboru tam neviditelné.

Blok je záměrně krátký - hrstka pravidel, jejichž porušení rozbije nasazení, a odkaz na úplný soubor. Pro server Node.js s nasazením při pushi vypadá zhruba takhle:

<!-- renode:start -->## Renode serverThis repository is deployed to a Renode server (Node.js) from the mainbranch. Read .renode/server.md before changing how it builds, starts orconnects to anything.- Listen on 0.0.0.0 on the port in the SERVER_PORT environment variable.  No other port is reachable from outside.- Only /home/container persists. No root, no apt, no systemd, no Docker.- The panel starts it in a fixed order. Keep the entry file and start  script it expects.- Never commit secrets. They go in a .env uploaded through the Files tab,  or in Startup variables, and are read from the environment.- A push to main redeploys and restarts the server within seconds.- Fix the code, not the startup command or the Docker image.<!-- renode:end -->

Přesné znění závisí na serveru: název runtime, větev, počet kroků startu a to, zda je zapnuté nasazení při pushi. Když je vypnuté, řádek o pushi místo toho říká asistentovi, aby po pushi server restartoval z panelu.

Soubor o serveru

.renode/server.md patří celý panelu, říká to v komentáři nahoře a přepíše se pokaždé, když se změní nastavení serveru. Vlastní poznámky patří do CLAUDE.md nebo AGENTS.md, mimo značky, ne sem. Má tyto sekce:

Pořadí startu je nejužitečnější část a ta, kterou ručně nepíše nikdo. Asistent dotázaný „proč se moje aplikace nespustí“ si přečte, že server nainstaluje závislosti a pak spustí konkrétní příkaz, a vyjde z toho, místo aby si vymýšlel Procfile. Ze stejného důvodu je důležitá sekce s limity: když asistent ví, že proces je při dosažení stropu paměti ukončen bez chybové zprávy - konzole prostě přestane odpovídat - z záhadného pádu se stane zjevná diagnóza. Node memory limits explained tohle rozebírá podrobně.

Co soubor záměrně vynechává: nasazený commit a jeho čas. Jejich zahrnutí by z každého pushe udělalo aktualizaci pull requestu, což je přesně ten šum, který nechcete.

Veřejné a soukromé repozitáře#

Panel se při každém zápisu ptá GitHubu, zda je repozitář soukromý, a cokoli jiného než výslovné „soukromý“ bere jako veřejný. Oba druhy dostanou jiné soubory.

Tajné hodnoty se nezapisují nikdy, do žádného z obou druhů. Proměnná označená jako tajná se objeví jako zástupný text, který říká, že je nastavená na serveru a nezobrazuje se, a hesla databází se nezahrnují vůbec - soubor říká, že heslo je na záložce Databases a patří do .env. Obě verze také procházejí stejným redaktorem, který používají ostatní AI funkce panelu a který vymaže cokoli ve tvaru klíče nebo tokenu i známá tajemství samotného serveru. Popisujeme to jako záchytnou síť, ne jako slib: zachytí to, na co byla postavená, a pull request byste si přesto měli přečíst, než ho sloučíte, stejně jako každý jiný.

Jak nálezy pre-flight kontroly vstupují do kontextu#

Záložka GitHub také spouští pre-flight kontrolu: přečte repozitář - jeden výpis stromu a pár malých souborů, nikdy ne klon - a vypíše, co se při startu serveru rozbije, od nejhoršího, každou věc s opravou k vložení. Hledá chybějící startovací skript nebo vstupní soubor, poslech na portu 3000 nebo na localhost místo na portu serveru na 0.0.0.0, framework, který se nikdy nesestaví (třeba chybí .next), verzi runtime připíchnutou v .nvmrc nebo go.mod, požadavky Pythonu a vstupní soubor, hlavní balíček Go, startovací úlohy Bun a Deno, soubor index na webovém hostingu a commitnutý .env, který se hlásí jménem a nikdy se neotvírá.

Když je přepínač AI kontextu zapnutý, tyto nálezy se dostanou do .renode/server.md pod Pre-flight check, uvozené větou „What the panel found when it read this repository. Fix every FAIL first.“ Každý nález je jeden řádek, označený úrovní velkými písmeny, následovaný popisem a opravou:

## Pre-flight checkWhat the panel found when it read this repository. Fix every FAIL first.- [FAIL] No start script and no entry file - The server runs npm run start,  and package.json has no start script. ... Fix: Add "start": "node <your  main file>" to the scripts in package.json.

Tohle je část, která mění chování asistenta. Bez ní otevřete Claude Code nebo Cursor, napíšete „nasazení je rozbité, oprav to“ a asistent začne hádat. S ní asistent otevře repozitář, přečte kontextový soubor a najde seznam konkrétních závad s už napsanými opravami. První krok je pak obvykle procházet ten seznam odshora. Diagnózu udělal panel, úpravu udělá asistent a diff zkontrolujete vy.

Uzavírá se tím i smyčka. Opravíte FAIL, pushnete a další obnova repozitář přečte znovu. Nález zmizí, obsah souboru se změní a otevřený pull request dostane nový commit bez něj. Čistý repozitář nakonec nemá sekci Pre-flight check vůbec.

Udržování aktuálnosti#

Kontext se obnovuje, ne generuje nahodile. Úloha na pozadí běží každých deset minut a všimne si, když se změní proměnné, porty, databáze nebo domény; uložení nastavení na záložce GitHub také zařadí obnovu do fronty, nejvýš jednu na propojení za deset minut. Pokaždé se obsah zahashuje, a pokud hash odpovídá poslednímu, nezapíše se nic. Server, který se nemění, nevytváří žádné commity.

Co se stane s pull requestem, závisí na jeho stavu:

• Otevřený: dostane nový commit v renode/ai-context se změnami.
• Sloučený: nový pull request se otevře, jen když se obsah liší od toho, co je ve vaší větvi.
• Zavřený bez sloučení: stav to oznámí a nový se otevře, jen když se obsah znovu změní.

Update now čekání přeskočí a obnovu spustí okamžitě - hodí se po schválení oprávnění App nebo hned po změně nastavení, kterou chcete mít v souboru ještě dnes.

Propojení sleduje nastavení nasazení serveru. Přepnutí větve pro nasazení zavře pull request a otevře nový proti nové větvi. Přepnutí na jiný repozitář funkci vypne, protože souhlas s pull requesty v jednom repozitáři není souhlas s nimi v jiném. Odpojení ji vypne také. Když přepínač vypnete sami, otevřený pull request se zavře s komentářem a větev renode/ai-context se smaže. Nikdy se nedotkne toho, co jste už sloučili: soubory ve vašem repozitáři zůstanou, dokud je neodstraníte.

Řešení potíží#

Stav říká, že se čeká na oprávnění. GitHub App nemá ve vaší instalaci udělený zápis do Contents a Pull requests. Následujte odkaz na záložce do nastavení instalace, přijměte nová oprávnění a stiskněte Update now. Dokud to neuděláte, panel nezapíše nic.

Hlásí, že repozitář nešlo aktualizovat. Přečtěte si stavový řádek a důvod, který s ním přichází. Nejčastější: repozitář je archivovaný (GitHub odmítá veškeré zápisy), narazili jste na limit požadavků GitHubu (počkejte a stiskněte Update now), nebo na renode/* dopadá pravidlo ochrany větví. Ochrana hlavní větve nevadí - panel tam nikdy nezapisuje - ale zástupné pravidlo, které odpovídá i renode/ai-context, ji zablokuje.

Můj CLAUDE.md má počáteční značku, ale žádnou koncovou. Panel odmítá hádat, kde jeho blok končí, a nezapíše nic. Obvykle se to stane po ruční úpravě nebo špatném sloučení. Smažte osamocenou značku nebo doplňte chybějící a stiskněte Update now.

Asistent se pořád naváže na port 3000. Zkontrolujte, že pull request byl sloučen do větve, kterou máte načtenou. Soubory fungují, až když jsou v pracovní kopii, kterou asistent otevírá. Pak ověřte, že nástroj čte soubor, o kterém si myslíte - Claude Code čte CLAUDE.md, Codex a Cursor čtou AGENTS.md. Některé nástroje čtou kontext jen na začátku relace, takže zahajte novou.

Nechci, aby panel sahal do CLAUDE.md vůbec. Zavřete pull request nebo vypněte přepínač. Pokud chcete informace bez pull requestu, panel „Work on this server with AI“ na záložce Console vám dá odkaz se stejným kontextem serveru, který můžete předat asistentovi přímo.

FAQ#

Posílá panel někdy něco do mé hlavní větve?

Ne. Každý zápis jde do renode/ai-context a do vaší větve se dostane jen přes pull request, který sloučíte vy. Kód, který přesouvá větve, odmítne jakoukoli větev mimo renode/ a pushe do těchto větví nikdy nespustí nasazení.

Restartuje sloučení pull requestu můj server?

Pokud je zapnuté nasazení při pushi, sloučení vloží do větve pro nasazení nový commit, takže ano, nasadí se a restartuje jako při každém jiném pushi. Samotné kontextové soubory na tom, jak kód běží, nic nemění.

Mohu generované soubory upravovat?

CLAUDE.md a AGENTS.md upravujte volně mimo značky; panel ten text nechává na pokoji. Neupravujte .renode/server.md ani text mezi značkami - další obnova je přepíše. Změňte raději nastavení serveru a soubor ho bude následovat.

Funguje to s ChatGPT?

Ne přes repozitář. ChatGPT v prohlížeči soubory z vašeho GitHubu sám nečte. Pro chatového asistenta použijte tlačítko Connect AI na záložce Console, které vytvoří odkaz ke sdílení s kontextem serveru, jejž vložíte do konverzace. Claude Code, Cursor, Copilot a Codex jsou nástroje, které soubory z repozitáře přebírají samy.

Je moje heslo k databázi v souboru?

Ne, ani ve veřejném, ani v soukromém repozitáři. Soukromý repozitář dostane název databáze, host, port a uživatele s poznámkou, že heslo je na záložce Databases a patří do .env. Veřejný dostane jen počet připojených databází.

Co když můj repozitář není s žádným serverem propojený?

Pak panel nemá co popisovat a přepínač se nenabízí. CLAUDE.md a AGENTS.md můžete stále napsat ručně podle rad výše - nejvíc péče vyžaduje sekce o serveru.