Ako sa zorientovať v neznámom projekte

Otvárate v IDE priečinok projektu, ktorý vidíte prvýkrát: niekoľko desiatok vnorených priečinkov, neznáme názvy, ani jeden súbor, ktorý ste písali vy. Čakajú vás úpravy: najprv drobné zmeny stránok, potom pridávanie nových hier. Skôr než začnete, treba zistiť, kde ležia potrebné súbory a aké pravidlá v projekte platia.

Láka začať otvárať priečinky jeden za druhým v nádeji, že narazíte na správne miesto. Užitočnejšie je najprv pochopiť celkovú štruktúru a pravidlá projektu. Hodia sa pri drobnej úprave aj neskôr, keď budete chcieť pridať novú hru: bude treba vybrať názvy súborov, nájsť im miesto a overiť výsledok spolu s Claude Code.

Najprv nájdite vstup do projektu

Začnite stromom súborov v paneli IDE a v koreňovom priečinku projektu nájdite README.md. Je to obyčajný textový súbor, ktorý niekto napísal pre človeka, nie pre program: zvyčajne stručne vysvetľuje, o aký projekt ide a ako ho spustiť. Niekedy je však vnútri len názov projektu a nádej, že si zvyšok zistíte sami. Ľudia sú leniví a README sa samo nenapíše :)

Z README sa najčastejšie dozviete tri veci: na čo projekt slúži, ako ho spustiť a kde hľadať podrobnejšie pokyny - napríklad samostatný súbor o architektúre alebo o pravidlách formátovania kódu. Pri drobnej úprave stránky to na pochopenie celkového obrazu stačí.

README môže chýbať alebo zaostávať za kódom. Berte ho ako východiskový bod: údaje o príkazoch a priečinkoch treba overiť v súboroch projektu. Ak popis sľubuje jednu štruktúru a strom ukazuje inú, poznačte si to ako otázku na overenie.

Čo prezradí strom priečinkov

Vezmime si učebný príklad: malý portál v prehliadači s katalógom hier, pripisovaním bodov a tabuľkou výsledkov. Časť jeho stromu vyzerá takto:

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

Ešte pred prečítaním jediného riadku kódu vám strom niečo napovie:

Názov priečinka je vodítko, nie potvrdenie. Súbor src/leaderboard.js vyzerá podľa mena ako ten správny; teraz ho treba prečítať a nájsť miesto, kde sa pripája. Tabuľka vyššie opisuje očakávané úlohy priečinkov, ktoré ešte treba potvrdiť. Samotná prítomnosť tests/ napríklad zatiaľ nič nehovorí o tom, ako sa kontroly spúšťajú.

Oplatí sa tiež oddeliť zdrojový kód od toho, čo z neho vzniklo alebo čo bolo nainštalované zvonku. dist/ zvyčajne generuje nástroj na zostavenie z obsahu src/ a priečinok cudzích závislostí (často sa volá node_modules/, hoci v príklade chýba) vôbec nenapísali ľudia z vášho tímu. Začínať čítanie práve nimi je takmer vždy zbytočné: úprava sa tam buď stratí pri ďalšom zostavení, alebo sa týka cudzieho kódu, ktorý neupravujete priamo. Správcovia balíkov, inštalácia závislostí a formát lockfile sú samostatná téma, sem nepatria.

A ešte jedno: sada priečinkov z príkladu nie je štandard. V inom projekte môžu byť stránky v public/ a zdrojáky v app/. Logika hľadania zostane rovnaká, zmenia sa len názvy.

Pravidlá práce s projektom

Povedzme, že v úlohách priečinkov sa už vyznáte. Skôr než pridáte súbory, oplatí sa zistiť, ako je tu zvykom pracovať. V jednom projekte ležia všetky stránky v spoločnom priečinku, v inom má každá hra svoje skripty a obrázky pri sebe. Oba varianty môžu byť pohodlné. Problémy sa začínajú vtedy, keď novú hru niekto usporiada podľa tretej zásady a nikde k tomu nie je vysvetlenie.

Dohody hľadajte cez odkazy z README. Súbor CONTRIBUTING.md, ak existuje, zvyčajne vysvetľuje, ako robiť zmeny. V dokumentácii môžu byť pravidlá umiestňovania súborov a v CLAUDE.md pokyny pre agenta. Niektorý priečinok má občas vlastné README s upresneniami k svojmu obsahu. Netreba očakávať celú túto sadu v každom projekte: niekedy sa niekoľko potrebných pravidiel zmestí do koreňového README.

Na prvú úpravu stačí zistiť, ktoré zdrojové súbory smiete meniť, ako ich tu pomenúvajú a umiestňujú, ako projekt spustiť a ako overiť výsledok. Ak pokyny zakazujú upravovať výsledok zostavenia, nájdite zdroj. Ak žiadajú aktualizovať popis pri pridaní stránky, zahrňte to do úlohy hneď.

Keď písomné pravidlo chýba, pozrite sa na dva-tri podobné príklady. Pri novej hre je užitočnejšie preskúmať susedné hry než náhodný priečinok s dokumentáciou. Zhodný spôsob umiestňovania súborov môžete brať ako vzor, ale jeden starý súbor ešte nedokazuje, že tak funguje celý projekt.

Býva to aj nepríjemnejšie: README posiela stránky do pages/, ale posledné hry ležia inde. Tu pomôže konkrétna otázka vlastníkovi projektu: "V pokynoch je uvedené pages/, ale dve nové hry sú v games/. Kam mám pridať ďalšiu?" Nemá zmysel potichu si vybrať variant, ktorý sa vám páči, ani presúvať celý strom kvôli jednotnosti.

Pravidlá pomenúvania súborov a priečinkov

Pomenúvanie je dohoda o názvoch. Dobré meno pomáha nájsť potrebný súbor v strome a pochopiť jeho účel ešte pred otvorením. V našom portáli leaderboard.html napovedá, že ide o tabuľku výsledkov, kým page2.html prezrádza len niečie poradové číslo.

Názov má zmysel a formu. Zmysel odpovedá na otázku "čo tu je?" a forma určuje veľkosť písmen a oddeľovače slov. Napríklad stránku denných odmien možno nazvať niekoľkými spôsobmi:

Toto sú varianty zápisu, nie rebríček. Ak sú slová v názvoch stránok projektu oddelené pomlčkou, nová stránka dostane meno v tom istom štýle. Rôzne skupiny súborov pritom môžu mať rôzne dohody: zabehnutý názov README.md netreba meniť na malé písmená len kvôli podobnosti s HTML stránkami. Zachovávajú sa aj názvy, ktoré očakávajú nástroje.

Predpokladajme, že pre bežné súbory nášho portálu sa dohodlo používať anglické slová v kebab-case. Potom je snake-preview.png zrozumiteľnejší než img3.png: ide o náhľad hry Snake. Priečinok game-icons/ hovorí o obsahu viac než stuff/. Meno leaderboard-final-new.html rýchlo zastará po ďalšej úprave; pre pracovnú stránku je lepšie nechať stabilný názov podľa účelu.

Vyberte si jeden termín pre jednu vec. Ak sa hry v projekte volajú games, priečinok plays pre tú istú skupinu prinúti čitateľa zisťovať, či je medzi nimi rozdiel. Neskracujte slová na hádanky typu ldrbrd/, ak taká skratka nie je súčasťou dohôd projektu.

Dôležitá je aj presnosť zápisu. Meno súboru a cesta k nemu sa musia zhodovať vrátane veľkosti písmen: Snake.png a snake.png nemožno považovať za zameniteľné. Chyba môže zostať nepovšimnutá na jednom počítači a prejaviť sa v inom prostredí. V našom príklade dohoda o malých písmenách znižuje počet takýchto nezhôd.

Pravidlá vnorenia priečinkov

Meno je vybrané. Ďalšia otázka znie - kam súbor uložiť. Vnorený priečinok je užitočný, keď združuje zrozumiteľnú skupinu: stránky hier, obrázky jednej hry, spoločné ikony. Každá nová úroveň by mala pomáhať nájsť obsah.

Predstavme si alternatívny variant: portál rastie a všetky súbory sa ukladajú priamo do koreňa:

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

V malom príklade sa ešte dá zorientovať. Keď hier bude dvadsať, stránky, skripty a obrázky si začnú prekážať. Náš portál už má rozdelenie na pages/, src/ a assets/, preto pri pridávaní hier dáva zmysel v ňom pokračovať. Tu je fragment možnej štruktúry po takomto pridaní:

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 hier sú spolu v jednej skupine, ich skripty v druhej. Názov hry spája súbory medzi sebou. Obrázky majú priečinok konkrétnej hry, takže krátke meno preview.png stačí: úplná cesta už vysvetľuje, čí je to náhľad. Samostatný priečinok sa zíde aj pre ďalšie obrázky tej istej hry.

Opačný extrém je cesta typu pages/portal/content/browser/games/arcade/snake/screens/main/index.html. Na otvorenie jednej stránky treba prejsť cez veľa úrovní a časť názvov takmer nič nepridáva. Ak v projekte nie sú samostatné portály, obrazovky a kategórie, takáto štruktúra vytvára prácu bez úžitku.

Univerzálny limit "nie hlbšie ako tri priečinky" neexistuje. Overujte zmysel každej úrovne: čo zoskupuje a či pomáha odlíšiť túto skupinu od susedných? Priečinok s jedným súborom je niekedy potrebný podľa pravidiel nástroja alebo projektu. Ale vytvárať ho len preto, že "možno sa sem neskôr niečo pridá", je zvyčajne predčasné.

Strom vyššie znázorňuje vývoj nášho príkladu. Ak je vo vašom projekte každá hra už celá uložená vo vlastnom priečinku, pokračujte týmto spôsobom. Nová hra sama osebe nie je dôvod prerábať ostatné.

Kde ukladať spoločné a lokálne súbory

Hra Snake dostala obrázok jablka a celý portál má spoločné logo. Oba súbory sú obrázky, ale používajú sa inak. Jablko potrebuje jedna hra, logo sa zobrazuje v katalógu, v tabuľke výsledkov a na stránkach hier.

Súbor jednej hry sa používa len v tejto hre. V tejto časti takéto súbory nazývame lokálnymi: ide o oblasť použitia, nie o uloženie na počítači alebo na serveri. V našom variante stromu skončí jablko v assets/games/snake/apple.png. Spoločný súbor potrebuje niekoľko častí; pre logo možno vyčleniť assets/shared/portal-logo.svg, ak taký priečinok v projekte prijali. Slovo shared znamená "spoločný", ale samotný názov priečinka súboru nedáva žiadne osobitné vlastnosti.

Rovnaké rozlíšenie sa hodí pri štýloch a skriptoch. Vzhľad herného poľa hry Snake patrí jej, vzhľad spoločnej hlavičky celému portálu. Pri výbere miesta si položte otázku, kto súbor používa teraz. Netreba vopred presúvať všetko do spoločného priečinka pre prípad budúceho opätovného použitia.

A naopak, kopírovať jedno logo do priečinka každej hry je nepohodlné: pri výmene bude treba nájsť všetky kópie. Ak ide naozaj o jeden spoločný zdroj, lepšie je odkazovať na jediný súbor. Dva podobné obrázky rôznych hier môžu zostať nezávislé: vonkajšia podobnosť ešte neznamená, že sa budú vždy meniť spolu.

Na schéme vedú k spoločnému logu tri šípky, k obrázku jablka len jedna. Preto sa po výmene loga oplatí pozrieť na všetky tri stránky, po výmene jablka len na Snake. Pred úpravou je užitočné požiadať Claude Code, aby našiel, ktoré súbory odkazujú na tento zdroj: skutočných väzieb môže byť viac, než je vidieť z názvu priečinka.

Čo overiť pri presune a premenovaní

Súbor sa dá premenovať za sekundu, ale jeho predchádzajúce meno už môže byť zapísané v odkazoch a nastaveniach. Presun navyše mení jeho pozíciu voči ostatným súborom. Preto je upratovanie v strome rovnakou úpravou projektu ako zmena obsahu stránky.

Vezmime si samostatný príklad presunu: stránku pages/snake.html presunuli do pages/games/snake.html. Skript zostal na mieste, v src/games/snake.js. V tomto príklade sa relatívna cesta počíta od adresy HTML stránky. Po presune treba pripojenie zmeniť:

<!-- V pages/snake.html pred presunom -->
<script src="../src/games/snake.js" type="module"></script>

<!-- V pages/games/snake.html po presune -->
<script src="../../src/games/snake.js" type="module"></script>

Každý fragment ../ posúva cestu o jeden priečinok vyššie. Teraz treba z games/ vyjsť do pages/, potom do koreňa a až odtiaľ prejsť do src/. Samotný skript sa nezmenil, ale jeho stará cesta je už nesprávna.

Existujú aj odkazy v opačnom smere: karta hry v katalógu môže stále viesť na starú adresu stránky. Pred presunom nájdite zmienky o pôvodnej ceste v celom projekte. Po presune aktualizujte potrebné odkazy, pripojenia, nastavenia zostavenia a príklady v dokumentácii. Pri premenovanom skripte skontrolujte aj importy - záznamy, cez ktoré ho pripájajú iné skripty.

IDE môže časť odkazov aktualizovať automaticky, ale výsledok si aj tak treba pozrieť. Nie každá cesta je zapísaná vcelku: niekedy sa adresa skladá z názvu priečinka a názvu súboru. Preto hľadanie starého mena pomáha nájsť závislosti a spustenie potrebného scenára pomáha všimnúť si tie, ktoré ste vynechali.

Ako overiť výsledok úpravy

Najprv nájdite v dokumentácii projektu príkazy na spustenie, zostavenie a kontroly. Ak ide o projekt s package.json, porovnajte pokyny s jeho sekciou scripts. Názvy príkazov závisia od projektu; samotná prítomnosť priečinka tests/ nenapovedá, čo presne spustiť. Ak pokyny chýbajú, spýtajte sa na spôsob overenia, namiesto toho, aby ste naslepo použili známy príkaz.

Ďalej overenie závisí od vykonanej zmeny. Po presune stránky Snake ju otvorte cez kartu v katalógu: tak overíte aj prechod, aj načítanie samotnej hry. Uistite sa, že sa objavili obrázky a hra sa spúšťa. Pri zmene spoločného loga sa pozrite aj na tabuľku výsledkov a ešte jednu hernú stránku.

Úspešné zostavenie je užitočné, ale tieto kroky nenahradí: odkaz na starú adresu môže zostať aj v zostavenom projekte. Zapíšte si, čo sa podarilo overiť a čo zatiaľ nie. Napríklad: "Zostavenie prešlo, Snake sa otvára z katalógu a spúšťa sa; zobrazenie na úzkej obrazovke sa neoverovalo."

Napokon si prezrite zoznam zmenených súborov. Pri pridaní jednej hry sa očakávajú jej súbory a úprava katalógu. Premenované priečinky iných hier alebo hromadné prepísanie obrázkov si vyžadujú vysvetlenie. Táto obhliadka zaberie menej času než neskoršie hľadanie neočakávanej poruchy.

Ako odovzdať pravidlá Claude Code

Žiadosť "pridaj hru poriadne" necháva agentovi príliš veľa rozhodnutí. Užitočnejšie je pomenovať úlohu a požiadať ho, aby si najprv naštudoval dohody. Cesta k novej hre by mala vychádzať z usporiadania projektu, nie z náhodnej preferencie agenta.

Trvalé, overené pravidlá možno zapísať do CLAUDE.md. Pre náš učebný portál by fragment mohol vyzerať takto:

## Súbory a priečinky
- Bežné súbory a priečinky pomenúvame anglickými slovami v kebab-case.
  Zavedené názvy README.md a CLAUDE.md zachovávame.
- Stránky hier sú v pages/games/, skripty hier v src/games/.
- Zdroje jednej hry sú v assets/games/<game-name>/.
- Spoločné obrázky portálu sú v assets/shared/.
- Pri presune alebo premenovaní aktualizujeme odkazy na súbor
  a relatívne cesty vnútri neho.

## Kontrola
- Príkazy na spustenie a overenie berieme z README.md.
- Novú hru otvárame z katalógu a overujeme jej spustenie.
- Po zmene spoločného zdroja overujeme stránky, ktoré ho používajú.

Toto je príklad dohodnutých pravidiel, nie univerzálna šablóna stromu. Skôr než si zapíšete podobný blok u seba, overte cesty a príkazy podľa skutočných súborov. Ak agent len predpokladal účel priečinka, požiadajte ho, aby ukázal dôvody; nemeňte domnienku na trvalý pokyn.

Teraz môže úloha na pridanie hry znieť takto:

Treba pridať do portálu hru memory-match podľa priloženého popisu.
Prečítaj README.md, CLAUDE.md a pokyny priečinkov, ktorých sa úloha dotkne.
Pozri sa, ako sú umiestnené súbory dvoch existujúcich hier.
Navrhni názvy a cesty pre novú stránku, skript a obrázky.
Uveď, ktorý súbor katalógu treba zmeniť a ako overiť výsledok.
Ak sa pokyny rozchádzajú s usporiadaním projektu, opýtaj sa.
Najprv ukáž plán, počkaj na schválenie, potom rob úpravy.

V pláne už možno posúdiť konkrétne rozhodnutia: kam hra pribudne, ktoré súbory sa stanú spoločnými, či práca nezasiahne susedné stránky. Po úprave požiadajte o zoznam zmenených súborov a vykonaných kontrol. Ľahšie tak porovnáte výsledok s tým, na čom ste sa dohodli.