Claude Code + GitHub: Struktura 8 složek, kterou používáme na každém projektu

Claude Code + GitHub: Struktura 8 složek, kterou používáme na každém projektu

Většina projektů s Claude Code začíná skvěle. Vytvoříte čistý soubor CLAUDE.md, napíšete pár jasných instrukcí a AI agent odvádí přesně to, co po něm chcete.

Pak ale projekt začne růst. Pravidla, doménové znalosti, stav relace i definice agentů se postupně nasypou do toho jediného souboru. Claude se najednou začne chovat nekonzistentně. A ve chvíli, kdy projekt převezme jiný člen týmu, musí agentovi začít vysvětlovat všechno od nuly.

Tohle není problém kvality promptů. Je to problém architektury souborů.

V Ninjabotu stavíme AI nástroje a automatizace tak, aby firmám šetřily čas a přinášely skutečný výkon. Abychom eliminovali chybovost a zajistili, že AI agent podává stejný výkon první i devadesátý den, přešli nahodile vytvořené soubory na systém.

Jedno rozhodnutí, které zastaví „driftování“ odpovědí

Pokud chcete zamezit tomu, aby AI postupně ztrácela kontext nebo měnila své chování, musíte od sebe striktně oddělit tři věci:

1. Co Claude ví
2. Jak se má chovat
3. Kde se právě nachází v daném procesu

Když smícháte stav, kontext a pravidla do jednoho souboru, LLM model při každém spuštění re-interpretuje všechno znova.

Základem námi používané architektury je rozdělení do 8 složek v adresáři .claude/

(který leží přímo v kořenu projektu vedle souboru CLAUDE.md).

Tři hlavní pilíře tvoří:

• rules/ (Jak se má chovat?)
• Tady sídlí kódovací styl, tonalita značky a standardy kvality. Tyto věci se mění pomalu. Z commitujte je do Git repozitáře a aplikujte plošně.
• context/ (Co má vědět?)
• Definice cílového publika, taxonomie témat nebo schválené datové zdroje. Tato složka říká agentovi fakta o světě, nikoli to, jak má jednat.
• memory/ (Kde v procesu se nachází?)
• Čistě stavový prostor v čase spuštění – aktuální fáze pipeline a co se právě dokončilo. Je to jediná složka, která se mění mezi spuštěními. Vždy ji přidejte do .gitignore.

Na tento základ se pak podle potřeby vrství dalších 5 složek: schemas/
commands/
agents/
skills/
protocols/

‍Oddělení prvních tří ale vyřeší 90 % problémů s konzistencí.

Jak tato architektura funguje v praxi

Samotný soubor CLAUDE.md slouží výhradně jako rozcestník. Pokud se vám jeho obsah nevejde na obrazovku notebooku bez skrolování, je příliš dlouhý.

1. Vytvoříte Claude Project a v nastavení připojíte váš GitHub repozitář.
2. Claude Code během aktivní relace aktualizuje lokální repozitář a manuální úpravy jdou mezi relacemi přímo do Gitu.
3. Protože má každý člen týmu propojený svůj Claude Project se stejným repozitářem, zastřešuje celou firmu jeden sdílený „mozek“.

Nezapomeňte v kořenu .claude/ vytvořit soubor settings.jsonpro definici oprávnění (jaké nástroje a cesty může agent používat) a settings.env.json, abyste si omylem neprotlačili vývojářské chování do produkce.

‍

🔄 Jak to technicky propojit s GitHubem?

Propojení s GitHubem funguje tak, že veškerou strukturu složek .claude/ i soubor CLAUDE.md nahrajete do svého GitHub repozitáře, který následně v rozhraní Claude připojíte k vašemu Claude Project (přes Project Settings -> Attach Repository). Repozitář se tím stane jediným sdíleným „mozkem“ celého týmu: vývojáři při práci s Claude Code v terminálu provádějí lokální úpravy a klasicky je verzují přes Git (git commit a push), zatímco ostatním členům týmu stačí stáhnout nejnovější kód (git pull) nebo v rozhraní Claude kliknout na tlačítko „Sync“, čímž zajistíte, že AI agent i všichni vývojáři pracují vždy se stejně aktuálními pravidly a kontextem.

4 nejčastější chyby při implementaci

Při čištění a nastavování AI vývojů u klientů vídáme stále stejné chyby:

1. Míchání pravidel a kontextu: Lidé často dávají uživatelské persony do složky rules/, protože jim to připadá jako instrukce. Není. Než tam soubor dáte, ptejte se: Říká to agentovi, jak jednat, nebo co má vědět? Pokud je to znalost, patří do context/.
2. Považování složky memory/ za databázi: Složka memory/ slouží pouze pro zjištění pozice v procesu. Pokud má informace přežít restart relace, přesuňte ji do context/.
3. Přeplňování CLAUDE.md: Přidání podsložek nepomůže, pokud v kořenovém CLAUDE.md stále držíte 400 řádků instrukcí. Používejte ho jako rozcestník, ne jako odkladiště.
4. Zapomínání na synchronizaci: Tým pushne změnu do repozitáře (nový kontext nebo úpravu pravidla), ale nikdo v nastavení Claude Project nestiskne „Sync“. Agent pak funguje podle starých dat. Udělejte ze synchronizace běžný návyk.

Nástroje, které se vyplatí propojit

• Claude Code: Na začátku relace perfektně načte strukturu a zvládá slash příkazy.
• Cursor: Pokud kombinujete Cursor a Claude Code, ujistěte se, že váš soubor .cursorrules není v rozporu se složkami v .claude/.
• Obsidian (+ Git plugin): Vynikající pro udržování složky context/ v lidsky čitelné podobě. Netradiční nebo netechničtí členové týmu tak mohou upravovat podklady k projektu, aniž by museli otevírat terminál.

Přestaňte dělat operativu, začněte využívat systém

Analytici z Gartneru předpovídají, že do roku 2027 selže téměř 40 % projektů zaměřených na AI agenty. Důvodem ale nebývá selhání technologie. Týmy většinou vypustí agenty do světa dříve, než vůbec zdokumentují své interní procesy – a nelze automatizovat workflow, které neexistuje.

Oddělení informací, pravidel a stavu je nejrychlejší cesta k tomu, jak z AI agentů udělat stabilního a spolehlivého člena týmu.

Chcete nasadit funkční AI automatizace a prodejní nástroje bez zbytečného chybování?

Můžeme se potkat na bezplatné schůzce.

‍

‍