Jak se zorientovat v neznámém projektu

V IDE otevíráte složku projektu, kterou vidíte poprvé: desítky vnořených složek, neznámé názvy a ani jeden soubor, který byste napsali vy. Čekají vás úpravy: nejprve drobné změny stránek, později přidání nových her. Než začnete, potřebujete zjistit, kde jsou potřebné soubory a jaká pravidla v projektu platí.

Člověk snadno začne otevírat složky jednu po druhé a doufá, že narazí na správné místo. Užitečnější je nejprve pochopit celkovou strukturu a pravidla projektu. Hodí se při drobné úpravě i později, až budete chtít přidat novou hru: bude třeba zvolit názvy souborů, najít pro ně místo a spolu s Claude Code ověřit výsledek.

Nejprve najděte, kde začít

Začněte stromem souborů v panelu IDE a v kořenové složce projektu najděte README.md. Je to obyčejný textový soubor, který někdo napsal pro lidi, ne pro program. Obvykle stručně vysvětluje, co je to za projekt a jak ho spustit. Někdy v něm ale najdete jen název projektu a naději, že na všechno přijdete sami. Lidé jsou líní a README se samo nenapíše :)

Z README se nejčastěji dozvíte tři věci: k čemu projekt slouží, jak ho spustit a kde najdete podrobnější pokyny - třeba samostatný soubor o architektuře nebo pravidlech formátování kódu. Pro drobnou úpravu stránky to většinou stačí k pochopení celkového obrazu.

README může chybět nebo nemusí odpovídat aktuálnímu kódu. Berte ho jako výchozí bod: informace o příkazech a složkách ověřte v souborech projektu. Pokud popis slibuje jednu strukturu a strom ukazuje jinou, poznamenejte si to jako otázku k ověření.

Co prozradí strom složek

Vezměme si cvičný příklad: malý herní portál v prohlížeči s katalogem her, připisováním bodů a tabulkou výsledků. Část jeho stromu vypadá takto:

project/
├── README.md
├── package.json
├── vite.config.js
├── pages/
│   └── leaderboard.html
├── src/
│   ├── leaderboard.js
│   └── reward-flow.js
├── assets/
├── tests/
└── dist/

I bez přečtení jediného řádku kódu vám strom něco napoví:

Název složky je vodítko, ne potvrzení. Soubor src/leaderboard.js podle názvu vypadá jako ten správný; teď si ho přečtěte a najděte, kde se načítá. Tabulka výše popisuje očekávané role složek, které je ještě třeba ověřit. Samotná přítomnost tests/ například zatím nic neříká o tom, jak se kontroly spouštějí.

Je také dobré rozlišovat zdrojový kód od toho, co z něj vzniklo nebo bylo přidáno zvenčí. dist/ se obvykle vytváří nástrojem pro sestavení z obsahu src/. Složku externích závislostí (často se jmenuje node_modules/, v našem příkladu ale chybí) zase nenapsali lidé z vašeho týmu. Začínat čtením těchto souborů většinou nemá smysl: změna se při příštím sestavení ztratí, nebo se týká cizího kódu, který přímo neupravujete. Správci balíčků, instalace závislostí a formát lockfile jsou samostatné téma, které sem nepatří.

A ještě jedna věc: uspořádání složek v příkladu není standard. V jiném projektu mohou být stránky v public/ a zdrojové soubory v app/. Způsob hledání zůstane stejný, změní se jen názvy.

Pravidla práce s projektem

Předpokládejme, že už víte, k čemu složky slouží. Než přidáte soubory, zjistěte, jak se v projektu běžně pracuje. V jednom projektu jsou všechny stránky ve společné složce, v jiném má každá hra vlastní skripty a obrázky. Obojí může fungovat dobře. Problém nastane, když novou hru uspořádáte podle třetího principu a nikde nevysvětlíte proč.

Hledejte dohodnutá pravidla přes odkazy v README. Soubor CONTRIBUTING.md, pokud existuje, obvykle vysvětluje, jak přispívat do projektu. Dokumentace může obsahovat pravidla pro umístění souborů a CLAUDE.md zase pokyny pro agenta. Samostatná složka může mít vlastní README s podrobnostmi o svém obsahu. Nepočítejte s tím, že každý projekt obsahuje všechny tyto soubory: někdy se několik důležitých pravidel vejde do kořenového README.

Pro první úpravu stačí zjistit, které zdrojové soubory smíte měnit, jak je pojmenovávat a kam je ukládat, jak projekt spustit a jak ověřit výsledek. Pokud pokyny zakazují upravovat výsledek sestavení, najděte zdrojový soubor. Pokud při přidání stránky požadují aktualizaci popisu, zahrňte to rovnou do úkolu.

Pokud žádná písemná pravidla nenajdete, prohlédněte si dva nebo tři podobné příklady. Pro novou hru je užitečnější prozkoumat sousední hry než náhodnou složku s dokumentací. Stejný způsob ukládání souborů můžete použít jako vzor, ale jediný starý soubor ještě nedokazuje, že tak funguje celý projekt.

Někdy je to ještě složitější: README říká, že stránky patří do pages/, ale poslední hry jsou jinde. V takovém případě se vlastníka projektu zeptejte konkrétně: "V pokynech je uvedeno pages/, ale dvě nové hry jsou v games/. Kam mám přidat další?" Nevybírejte potichu variantu, která se vám líbí, ani nepřesouvejte celý strom jen kvůli jednotnosti.

Pravidla pojmenování souborů a složek

Pojmenování je dohoda o názvech. Dobré jméno vám pomůže najít správný soubor ve stromu a ještě před otevřením pochopit, k čemu slouží. V našem portálu leaderboard.html napovídá, že jde o tabulku výsledků, zatímco page2.html prozradí jen něčí pořadové číslo.

Název má význam a podobu. Význam odpovídá na otázku "co tu najdu?" a podoba určuje velikost písmen a oddělovače slov. Například stránku s denními odměnami lze pojmenovat několika způsoby:

Jde o různé způsoby zápisu, ne o žebříček. Pokud jsou stránky projektu pojmenované s pomlčkami, pojmenujte stejně i novou stránku. Různé skupiny souborů se ale mohou řídit různými pravidly: zavedený název README.md neměňte na malá písmena jen proto, aby vypadal jako HTML stránky. Zachovejte také názvy, které očekávají nástroje.

Předpokládejme, že jsme se pro běžné soubory našeho portálu dohodli na anglických slovech ve stylu kebab-case. Pak je snake-preview.png srozumitelnější než img3.png: jde o náhled hry Snake. Složka game-icons/ prozradí víc než stuff/. Název leaderboard-final-new.html rychle zastará, jakmile přijde další úprava; pracovní stránce raději nechte stabilní název podle jejího účelu.

Pro jednu věc používejte jeden termín. Pokud se hry v projektu označují jako games, složka plays pro stejnou skupinu přiměje čtenáře zjišťovat, jestli mezi nimi není rozdíl. Nezkracujte slova na hádanky typu ldrbrd/, pokud takovou zkratku pravidla projektu neznají.

Důležitý je i přesný zápis. Název souboru a jeho cesta se musí shodovat včetně velikosti písmen: Snake.png a snake.png nejsou zaměnitelné. Na jednom počítači může chyba zůstat skrytá a projevit se až v jiném prostředí. V našem příkladu dohoda o malých písmenech omezuje podobné nesrovnalosti.

Pravidla vnoření složek

Název máme. Další otázka zní: kam soubor uložit? Vnořená složka dává smysl, když sdružuje jasně vymezenou skupinu: stránky her, obrázky jedné hry nebo společné ikony. Každá další úroveň by měla usnadnit hledání.

Představme si jinou možnost: portál se rozrůstá, ale všechny soubory se ukládají přímo do kořenové složky:

project/
├── README.md
├── package.json
├── snake.html
├── tetris.html
├── leaderboard.html
├── snake.js
├── tetris.js
├── snake-preview.png
└── tetris-preview.png

V malém příkladu se ještě vyznáte. Až bude her dvacet, stránky, skripty a obrázky si začnou překážet. Náš portál už rozděluje soubory do složek pages/, src/ a assets/, takže při přidávání her dává smysl v tom pokračovat. Tady je část možné struktury po takovém rozšíření:

project/
├── pages/
│   ├── leaderboard.html
│   └── games/
│       ├── snake.html
│       └── tetris.html
├── src/
│   ├── leaderboard.js
│   └── games/
│       ├── snake.js
│       └── tetris.js
└── assets/
    └── games/
        ├── snake/
        │   └── preview.png
        └── tetris/
            └── preview.png

Stránky her jsou pohromadě v jedné skupině a jejich skripty v jiné. Název hry soubory propojuje. Obrázky mají složku konkrétní hry, takže stačí krátký název preview.png: úplná cesta už vysvětluje, které hře náhled patří. Samostatná složka se bude hodit i pro další obrázky téže hry.

Opačným extrémem je cesta jako pages/portal/content/browser/games/arcade/snake/screens/main/index.html. K otevření jedné stránky musíte projít mnoha úrovněmi a část názvů skoro nic nepřidává. Pokud projekt nemá samostatné portály, obrazovky a kategorie, taková struktura přidělává práci bez užitku.

Neexistuje univerzální hranice "nejvýš tři úrovně složek". U každé úrovně ověřte její smysl: co sdružuje a jestli pomáhá odlišit tuto skupinu od sousedních? Složka s jediným souborem může být někdy nutná kvůli nástroji nebo pravidlům projektu. Vytvářet ji jen proto, že "se sem třeba někdy něco přidá", je ale obvykle předčasné.

Strom výše ukazuje, jak se náš příklad může rozvíjet. Pokud jsou ve vašem projektu všechny soubory každé hry už v její vlastní složce, pokračujte stejným způsobem. Nová hra sama o sobě není důvodem předělávat ty ostatní.

Kde ukládat společné a lokální soubory

Hra Snake dostala obrázek jablka a celý portál společné logo. Oba soubory jsou obrázky, ale používají se jinak. Jablko potřebuje jedna hra, logo se zobrazuje v katalogu, tabulce výsledků i na stránkách her.

Soubor jedné hry používá jen tato hra. V této části takovým souborům říkáme lokální: jde o oblast použití, ne o uložení v počítači nebo na serveru. V naší variantě stromu bude obrázek jablka v assets/games/snake/apple.png. Společný soubor potřebuje několik částí projektu; pro logo lze vyhradit assets/shared/portal-logo.svg, pokud se taková složka v projektu používá. Slovo shared znamená "společný", ale samotný název složky souboru žádné zvláštní vlastnosti nedává.

Stejné rozlišení se hodí u stylů a skriptů. Vzhled herního pole hry Snake patří jí, vzhled společné hlavičky celému portálu. Při výběru umístění se ptejte, kdo soubor používá teď. Není třeba předem přesouvat všechno do společné složky pro případ budoucího opětovného použití.

A naopak: kopírovat jedno logo do složky každé hry je nepohodlné. Při výměně byste museli najít všechny kopie. Pokud jde opravdu o jeden společný zdroj, odkazujte na jediný soubor. Dva podobné obrázky různých her ale mohou zůstat nezávislé: podobný vzhled ještě neznamená, že se budou vždy měnit společně.

Ve schématu vedou ke společnému logu tři šipky, k obrázku jablka jen jedna. Po výměně loga proto zkontrolujte všechny tři stránky, po výměně jablka jen hru Snake. Před úpravou požádejte Claude Code, aby našel soubory odkazující na daný zdroj: skutečných vazeb může být víc, než napovídá název složky.

Co zkontrolovat při přesunu a přejmenování

Soubor můžete přejmenovat za sekundu, ale jeho původní název už může být uvedený v odkazech a nastavení. Přesun navíc mění jeho umístění vůči ostatním souborům. Uspořádání stromu je tedy změna projektu stejně jako úprava obsahu stránky.

Vezměme si samostatný příklad přesunu: stránka pages/snake.html se přesunula do pages/games/snake.html. Skript zůstal na místě v src/games/snake.js. V tomto příkladu se relativní cesta počítá od umístění HTML stránky. Po přesunu je potřeba upravit načítání skriptu:

<!-- Před přesunem: pages/snake.html -->
<script src="../src/games/snake.js" type="module"></script>

<!-- Po přesunu: pages/games/snake.html -->
<script src="../../src/games/snake.js" type="module"></script>

Každý úsek ../ posune cestu o jednu složku výš. Teď je třeba z games/ přejít do pages/, pak do kořenové složky a teprve odtud do src/. Samotný skript se nezměnil, ale jeho původní cesta už neplatí.

Existují i odkazy opačným směrem: karta hry v katalogu může pořád vést na starou adresu stránky. Před přesunem najděte v projektu všechny zmínky o původní cestě. Po přesunu aktualizujte potřebné odkazy, načítání skriptů, nastavení sestavení i příklady v dokumentaci. U přejmenovaného skriptu zkontrolujte také importy - zápisy, kterými ho načítají jiné skripty.

IDE může část odkazů aktualizovat automaticky, ale výsledek si stejně projděte. Ne každá cesta je zapsaná jako jeden řetězec: někdy se adresa skládá z názvu složky a souboru. Hledáním původního názvu proto najdete závislosti a spuštěním příslušného scénáře zase odhalíte ty přehlédnuté.

Jak ověřit výsledek úpravy

Nejprve v dokumentaci projektu najděte příkazy pro spuštění, sestavení a kontroly. Pokud jde o projekt s package.json, porovnejte pokyny s jeho sekcí scripts. Názvy příkazů se liší podle projektu; samotná složka tests/ vám neřekne, co spustit. Pokud pokyny chybí, zjistěte, jak kontrolu provést, místo abyste naslepo použili známý příkaz.

Další kontrola závisí na provedené změně. Po přesunu stránky hry Snake ji otevřete přes kartu v katalogu: ověříte tak navigaci i načtení samotné hry. Zkontrolujte, že se zobrazily obrázky a hra se spustila. Po změně společného loga se podívejte také na tabulku výsledků a další stránku hry.

Úspěšné sestavení je užitečné, ale tyto kroky nenahradí: odkaz na starou adresu může zůstat i v sestaveném projektu. Zapište si, co se vám podařilo ověřit a co zatím ne. Například: "Sestavení proběhlo, hra Snake se otevřela z katalogu a spustila se; zobrazení na úzké obrazovce jsem neověřil."

Nakonec si projděte seznam změněných souborů. Při přidání jedné hry se očekávají její soubory a úprava katalogu. Přejmenované složky jiných her nebo hromadné přepsání obrázků vyžadují vysvětlení. Tahle kontrola zabere méně času než pozdější hledání nečekané chyby.

Jak předat pravidla Claude Code

Požadavek "přidej hru pečlivě" nechává agentovi příliš mnoho rozhodnutí. Lepší je popsat úkol a požádat ho, aby nejprve prozkoumal dohodnutá pravidla. Cesta k nové hře by měla odpovídat uspořádání projektu, ne náhodné preferenci agenta.

Ověřená pravidla, která mají platit dlouhodobě, můžete zapsat do CLAUDE.md. V našem cvičném portálu by takový úryvek mohl vypadat třeba takto:

## Soubory a složky
- Běžné soubory a složky pojmenováváme anglicky ve stylu kebab-case.
  Zavedené názvy README.md a CLAUDE.md zachováváme.
- Stránky her jsou v pages/games/, skripty her v src/games/.
- Zdroje jedné hry jsou v assets/games/<game-name>/.
- Společné obrázky portálu jsou v assets/shared/.
- Při přesunu nebo přejmenování aktualizujeme odkazy na soubor
  a relativní cesty uvnitř něj.

## Kontrola
- Příkazy ke spuštění a ověření přebíráme z README.md.
- Novou hru otevíráme z katalogu a kontrolujeme její spuštění.
- Po změně společného zdroje kontrolujeme stránky, které ho používají.

Tohle je příklad dohodnutých pravidel, ne univerzální šablona stromu. Než podobný blok zapíšete do svého projektu, ověřte cesty a příkazy podle skutečných souborů. Pokud agent účel složky jen odhadl, požádejte ho o zdůvodnění; nedělejte z odhadu trvalý pokyn.

Úkol na přidání hry by teď mohl znít třeba takto:

Přidej do portálu hru memory-match podle přiloženého popisu.
Přečti README.md, CLAUDE.md a pokyny ve složkách, kterých se úkol týká.
Podívej se, jak jsou umístěné soubory dvou existujících her.
Navrhni názvy a cesty pro novou stránku, skript a obrázky.
Uveď, který soubor katalogu je třeba změnit a jak ověřit výsledek.
Pokud jsou pokyny v rozporu s uspořádáním projektu, zeptej se.
Nejprve ukaž plán a počkej na schválení, potom proveď změny.

Už v plánu můžete posoudit konkrétní rozhodnutí: kam hra přijde, které soubory budou společné a jestli práce nezasáhne sousední stránky. Po úpravě požádejte agenta o seznam změněných souborů a provedených kontrol. Snáz tak porovnáte výsledek s tím, co jste schválili.