Cum să vă orientați într-un proiect necunoscut

Deschideți în IDE un folder de proiect pe care îl vedeți pentru prima dată: zeci de foldere imbricate, nume necunoscute și niciun fișier scris de dumneavoastră. Urmează să faceți modificări: mai întâi mici ajustări la pagini, apoi să adăugați jocuri noi. Înainte să începeți, trebuie să aflați unde se găsesc fișierele necesare și ce reguli se aplică proiectului.

E ușor să începeți să deschideți foldere unul după altul, în speranța că veți da peste locul potrivit. Mai util e să înțelegeți mai întâi structura generală și regulile proiectului. Vă vor ajuta atât la o modificare mică, cât și mai târziu, când veți dori să adăugați un joc nou: va trebui să-i alegeți numele fișierelor, să găsiți locul potrivit și să verificați rezultatul împreună cu Claude Code.

Găsiți mai întâi intrarea în proiect

Începeți cu arborele de fișiere din panoul IDE și căutați README.md în rădăcina proiectului. Este un fișier text obișnuit, scris de cineva pentru oameni, nu pentru programe: de regulă, explică pe scurt ce proiect aveți în față și cum îl puteți porni. Uneori, însă, conține doar numele proiectului și speranța că vă veți descurca singuri. Oamenii sunt leneși, iar README nu se scrie singur :)

De obicei, din README puteți afla trei lucruri: scopul proiectului, cum se pornește și linkuri către instrucțiuni mai detaliate - de exemplu, un fișier separat despre arhitectură sau regulile de formatare a codului. Pentru o mică modificare a unei pagini, acestea sunt suficiente ca să înțelegeți imaginea de ansamblu.

README poate să lipsească sau să nu mai corespundă codului. Tratați-l ca pe un punct de plecare: verificați în fișierele proiectului ce spune despre comenzi și foldere. Dacă descrierea promite o structură, iar arborele arată alta, notați diferența ca pe o întrebare de verificat.

Ce vă spune arborele de foldere

Să luăm un exemplu didactic: un mic portal web cu o galerie de jocuri, punctaj și un clasament. O parte din arborele lui arată astfel:

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

Chiar și fără să fi citit o singură linie de cod, arborele oferă deja câteva indicii:

Numele unui folder este un indiciu, nu o confirmare. După nume, src/leaderboard.js pare fișierul potrivit; acum trebuie să-l citiți și să găsiți unde este inclus. Tabelul de mai sus arată rolurile așteptate ale folderelor, care încă trebuie confirmate. În special, simpla existență a folderului tests/ nu spune cum se rulează verificările.

Merită să deosebiți codul sursă de ceea ce a fost generat de el sau instalat din exterior. dist/ este de obicei generat de instrumentul de build pe baza conținutului din src/, iar folderul dependențelor terțe (numit adesea node_modules/, deși lipsește din exemplu) nici măcar nu a fost scris de echipa dumneavoastră. Aproape întotdeauna e inutil să începeți lectura de acolo: modificarea fie va dispărea la următorul build, fie ține de codul altcuiva, pe care nu-l editați direct. Managerii de pachete, instalarea dependențelor și formatul lockfile sunt un subiect separat, care nu intră aici.

Încă ceva: lista de foldere din exemplu nu este un standard. În alt proiect, paginile pot fi în public/, iar sursele în app/. Logica de căutare rămâne aceeași, se schimbă doar numele.

Regulile de lucru cu proiectul

Să presupunem că ați aflat ce rol au folderele. Înainte să adăugați fișiere, merită să vedeți cum se lucrează în acest proiect. Într-un proiect, toate paginile stau într-un folder comun; în altul, fiecare joc este păstrat împreună cu scripturile și imaginile sale. Ambele variante pot fi potrivite. Problemele apar când un joc nou urmează un al treilea principiu, fără ca cineva să explice de ce.

Căutați convențiile urmând linkurile din README. Fișierul CONTRIBUTING.md, dacă există, explică de obicei cum se fac modificările. Documentația poate conține reguli despre amplasarea fișierelor, iar CLAUDE.md poate include instrucțiuni pentru agent. Un folder separat poate avea propriul README, cu detalii despre conținutul lui. Nu vă așteptați să găsiți toate aceste fișiere în fiecare proiect: uneori, câteva reguli utile încap în README-ul din rădăcină.

Pentru prima modificare, e suficient să aflați ce fișiere sursă puteți schimba, cum sunt numite și amplasate aici, cum se pornește proiectul și cum se verifică rezultatul. Dacă instrucțiunile interzic editarea rezultatului de build, găsiți sursa. Dacă cer actualizarea descrierii la adăugarea unei pagini, includeți asta în sarcină de la început.

Când nu există o regulă scrisă, uitați-vă la două-trei exemple asemănătoare. Pentru un joc nou, jocurile vecine sunt mai relevante decât un folder oarecare cu documentație. Puteți lua drept model felul în care sunt amplasate fișierele, dar un singur fișier vechi nu dovedește că întregul proiect este organizat la fel.

Uneori situația e și mai neplăcută: README indică folderul pages/, dar jocurile cele mai noi sunt în altă parte. Aici ajută o întrebare concretă pentru responsabilul proiectului: "Instrucțiunile indică pages/, dar două jocuri noi sunt în games/. Unde să-l adaug pe următorul?" Nu alegeți în tăcere varianta preferată și nici nu mutați tot arborele doar ca să fie uniform.

Reguli de denumire pentru fișiere și foldere

Denumirea este o convenție despre cum numim lucrurile. Un nume bun vă ajută să găsiți fișierul potrivit în arbore și să-i înțelegeți rolul înainte să-l deschideți. În portalul nostru, leaderboard.html sugerează că este un clasament, pe când page2.html spune doar că cineva i-a dat un număr de ordine.

Un nume are sens și formă. Sensul răspunde la întrebarea "ce se află aici?", iar forma stabilește literele mari și mici și separatorii dintre cuvinte. De exemplu, pagina cu recompense zilnice poate fi numită în mai multe feluri:

Acestea sunt moduri de scriere, nu o ierarhie. Dacă paginile proiectului folosesc cratime, dați și paginii noi un nume în același stil. Totuși, grupuri diferite de fișiere pot avea convenții diferite: numele consacrat README.md nu trebuie transformat în litere mici doar ca să semene cu paginile HTML. Păstrați și numele așteptate de instrumente.

Să presupunem că, pentru fișierele obișnuite din portalul nostru, s-a convenit să folosim cuvinte englezești în kebab-case. Atunci snake-preview.png e mai clar decât img3.png: este imaginea de previzualizare pentru Snake. Folderul game-icons/ spune mai multe despre conținut decât stuff/. Numele leaderboard-final-new.html se învechește imediat după următoarea modificare; pentru o pagină folosită în proiect, e mai bine un nume stabil, bazat pe rolul ei.

Alegeți un singur termen pentru aceeași entitate. Dacă jocurile din proiect se numesc games, apariția folderului plays pentru același grup îl va face pe cititor să se întrebe dacă există vreo diferență între ele. Nu scurtați cuvintele până devin ghicitori, de exemplu ldrbrd/, decât dacă prescurtarea face parte din convențiile proiectului.

Contează și scrierea exactă. Numele fișierului și calea către el trebuie să corespundă, inclusiv la majuscule și minuscule: nu presupuneți că Snake.png și snake.png sunt interschimbabile. Greșeala poate trece neobservată pe un calculator și apărea în alt mediu. În exemplul nostru, convenția de a folosi litere mici reduce astfel de neconcordanțe.

Reguli pentru imbricarea folderelor

Numele e ales. Următoarea întrebare este unde să puneți fișierul. Un folder imbricat e util când grupează ceva ușor de identificat: pagini de jocuri, imaginile unui joc, pictograme comune. Fiecare nivel nou ar trebui să vă ajute să găsiți conținutul.

Să ne imaginăm o variantă alternativă: portalul crește, iar toate fișierele sunt puse direct în rădăcină:

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

Într-un exemplu mic, încă vă puteți descurca. Când vor fi douăzeci de jocuri, paginile, scripturile și imaginile vor începe să se încurce unele cu altele. Portalul nostru separă deja conținutul în pages/, src/ și assets/, așa că are sens să păstrăm această organizare când adăugăm jocuri. Iată un fragment de structură posibilă după adăugare:

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

Paginile jocurilor sunt grupate separat de scripturile lor. Numele jocului leagă fișierele între ele. Imaginile au câte un folder pentru fiecare joc, așa că numele scurt preview.png este suficient: calea completă arată deja pentru ce joc este previzualizarea. Folderul separat va fi util și pentru alte imagini ale aceluiași joc.

La cealaltă extremă se află o cale precum pages/portal/content/browser/games/arcade/snake/screens/main/index.html. Ca să deschideți o singură pagină, trebuie să treceți prin multe niveluri, iar unele nume adaugă foarte puține informații. Dacă proiectul nu are portaluri, ecrane și categorii separate, această structură adaugă muncă fără vreun beneficiu.

Nu există o limită universală de tipul "cel mult trei foldere adâncime". Verificați rolul fiecărui nivel: ce grupează și vă ajută să deosebiți grupul de cele vecine? Uneori, regulile instrumentului sau ale proiectului cer un folder cu un singur fișier. Dar, de obicei, e prea devreme să-l creați doar pentru că "poate o să apară ceva aici mai târziu".

Arborele de mai sus arată cum s-ar putea dezvolta exemplul nostru. Dacă în proiectul dumneavoastră fiecare joc este deja păstrat integral în propriul folder, continuați în același fel. Un joc nou nu este, de unul singur, un motiv să reorganizați restul.

Unde păstrați fișierele comune și locale

Jocul Snake are acum o imagine cu un măr, iar întregul portal are un logo comun. Ambele fișiere sunt imagini, dar sunt folosite în moduri diferite. Mărul este necesar unui singur joc, pe când logo-ul apare în galerie, în clasament și pe paginile jocurilor.

Fișierul unui singur joc este folosit doar de acel joc. În această secțiune le numim fișiere locale: ne referim la aria de utilizare, nu la stocarea pe calculator sau pe server. În varianta noastră de arbore, mărul va ajunge în assets/games/snake/apple.png. Un fișier comun este folosit de mai multe părți; pentru logo, puteți crea assets/shared/portal-logo.svg, dacă proiectul a adoptat un astfel de folder. Cuvântul shared înseamnă "comun", dar numele folderului nu conferă fișierului vreo proprietate specială.

Aceeași distincție e utilă și pentru stiluri și scripturi. Stilurile tablei de joc pentru Snake țin de acest joc, iar stilurile antetului comun țin de întregul portal. Când alegeți locul, întrebați-vă cine folosește fișierul acum. Nu e nevoie să mutați totul din timp într-un folder comun, în caz că va fi reutilizat pe viitor.

Și extrema opusă e incomodă: dacă copiați același logo în folderul fiecărui joc, la înlocuire va trebui să găsiți toate copiile. Dacă este într-adevăr o singură resursă comună, e mai bine să faceți referire la un singur fișier. Două imagini asemănătoare, dar pentru jocuri diferite, pot rămâne independente: faptul că seamănă nu înseamnă că vor fi întotdeauna modificate împreună.

În schemă, trei săgeți duc la logo-ul comun și doar una la imaginea mărului. De aceea, după înlocuirea logo-ului, merită să verificați toate cele trei pagini, iar după înlocuirea mărului - jocul Snake. Înainte de modificare, îi puteți cere lui Claude Code să găsească fișierele care fac referire la resursă: legăturile reale pot fi mai numeroase decât sugerează numele folderului.

Ce verificați după mutare și redenumire

Puteți redenumi un fișier într-o secundă, dar numele lui vechi poate fi deja folosit în linkuri și setări. Mutarea schimbă și poziția lui față de celelalte fișiere. Așadar, organizarea arborelui este tot o modificare a proiectului, la fel ca schimbarea conținutului unei pagini.

Să luăm un exemplu separat: pagina pages/snake.html a fost mutată în pages/games/snake.html. Scriptul a rămas la locul lui, în src/games/snake.js. În acest exemplu, calea relativă se calculează pornind de la adresa paginii HTML. După mutare, trebuie schimbată includerea:

<!-- În pages/snake.html înainte de mutare -->
<script src="../src/games/snake.js" type="module"></script>

<!-- În pages/games/snake.html după mutare -->
<script src="../../src/games/snake.js" type="module"></script>

Fiecare segment ../ urcă o treaptă în arbore, adică un folder. Acum trebuie să ieșiți din games/ în pages/, apoi în rădăcină și abia de acolo să intrați în src/. Scriptul nu s-a schimbat, dar calea veche către el nu mai este corectă.

Există și linkuri în direcția opusă: cardul jocului din galerie poate duce în continuare la adresa veche a paginii. Înainte de mutare, căutați în proiect toate referințele la calea veche. După mutare, actualizați linkurile, includerile, setările de build și exemplele din documentație care trebuie schimbate. Dacă ați redenumit un script, verificați și importurile - liniile prin care îl includ alte scripturi.

IDE-ul poate actualiza automat o parte dintre linkuri, dar rezultatul trebuie totuși verificat. Nu orice cale este scrisă pe o singură linie: uneori, adresa este alcătuită din numele folderului și cel al fișierului. De aceea, căutarea numelui vechi vă ajută să găsiți dependențele, iar rularea scenariului relevant poate scoate la iveală ce ați omis.

Cum verificați rezultatul unei modificări

Mai întâi, găsiți în documentația proiectului comenzile de pornire, build și verificare. Dacă proiectul are un package.json, comparați instrucțiunile cu secțiunea scripts din acesta. Numele comenzilor depind de proiect; simpla prezență a folderului tests/ nu vă spune ce trebuie rulat. Dacă nu există instrucțiuni, întrebați cum se face verificarea, în loc să alegeți la întâmplare o comandă cunoscută.

Apoi, verificările depind de modificarea făcută. După mutarea paginii jocului Snake, deschideți-o din cardul din galerie: astfel verificați atât navigarea, cât și încărcarea jocului. Asigurați-vă că imaginile apar și că jocul pornește. Dacă ați modificat logo-ul comun, verificați și clasamentul, precum și încă o pagină de joc.

Un build reușit este util, dar nu înlocuiește aceste verificări: linkul către adresa veche poate rămâne și în proiectul generat. Notați ce ați reușit să verificați și ce nu. De exemplu: "Buildul a trecut, Snake se deschide din galerie și pornește; afișarea pe un ecran îngust nu a fost verificată".

La final, verificați lista fișierelor modificate. Pentru adăugarea unui singur joc, vă așteptați la fișierele lui și la o modificare a galeriei. Folderele redenumite ale altor jocuri sau rescrierea în masă a imaginilor au nevoie de o explicație. Verificarea aceasta durează mai puțin decât căutarea unei defecțiuni neașteptate mai târziu.

Cum îi transmiteți regulile lui Claude Code

O cerere precum "adaugă jocul cu grijă" îi lasă agentului prea multe decizii. E mai util să numiți sarcina și să-i cereți să studieze mai întâi convențiile. Calea jocului nou ar trebui să urmeze organizarea proiectului, nu o preferință întâmplătoare a agentului.

Puteți nota regulile stabile și verificate în CLAUDE.md. Pentru portalul nostru didactic, fragmentul ar putea arăta astfel:

## Fișiere și foldere
- Denumiți fișierele și folderele obișnuite cu termeni englezești în kebab-case.
  Păstrați numele consacrate README.md și CLAUDE.md.
- Paginile jocurilor se află în pages/games/, scripturile lor în src/games/.
- Resursele unui joc se află în assets/games/<game-name>/.
- Imaginile comune ale portalului se află în assets/shared/.
- La mutare sau redenumire, actualizați linkurile către fișier
  și căile relative din interiorul lui.

## Verificare
- Preluați comenzile de pornire și verificare din README.md.
- Deschideți jocul nou din galerie și verificați că pornește.
- După modificarea unei resurse comune, verificați paginile care o folosesc.

Acesta este un exemplu de reguli convenite, nu un șablon universal pentru arbore. Înainte să notați un fragment asemănător pentru proiectul dumneavoastră, verificați căile și comenzile în fișierele reale. Dacă agentul doar a presupus rolul unui folder, cereți-i să vă arate pe ce se bazează; nu transformați presupunerea într-o instrucțiune permanentă.

Acum, sarcina de adăugare a unui joc ar putea suna astfel:

Adaugă în portal jocul memory-match, conform descrierii atașate.
Citește README.md, CLAUDE.md și instrucțiunile folderelor vizate de sarcină.
Vezi cum sunt organizate fișierele pentru două jocuri existente.
Propune nume și căi pentru pagina, scriptul și imaginile jocului nou.
Precizează ce fișier al galeriei trebuie modificat și cum verificăm rezultatul.
Dacă instrucțiunile nu corespund organizării proiectului, pune o întrebare.
Arată mai întâi planul, așteaptă aprobarea, apoi fă modificările.

Planul vă permite deja să evaluați decizii concrete: unde va fi adăugat jocul, ce fișiere vor deveni comune, dacă modificările vor afecta paginile vecine. După editare, cereți-i să enumere fișierele modificate și verificările efectuate. Vă va fi mai ușor să comparați rezultatul cu ce ați aprobat.