Tanımadığınız layihəni necə anlamaq olar

IDE-də layihənin qovluğunu ilk dəfə açırsınız: iç-içə qurulmuş onlarla qovluq, tanış olmayan adlar və özünüzün yazdığınız bir dənə də fayl yoxdur. Dəyişikliklər etməli olacaqsınız: əvvəl səhifələrdə kiçik düzəlişlər, sonra isə yeni oyunların əlavə edilməsi. Başlamazdan əvvəl lazım olan faylların harada olduğunu və layihədə hansı qaydaların qüvvədə olduğunu anlamaq lazımdır.

Lazım olan yeri tapmaq ümidi ilə qovluqları bir-bir açmağa başlamaq asandır. Əvvəlcə layihənin ümumi quruluşunu və qaydalarını anlamaq daha faydalıdır. Bu biliklər həm kiçik düzəliş zamanı, həm də yeni oyun əlavə edəndə işə yarayacaq: fayllara ad seçmək, onlar üçün yer tapmaq və nəticəni Claude Code ilə yoxlamaq lazım gələcək.

Əvvəlcə layihəyə giriş nöqtəsini tapın

IDE panelində fayl ağacına baxın və layihənin kökündə README.md faylını tapın. Bu, proqram üçün deyil, insanlar üçün yazılan adi mətn faylıdır: adətən burada layihənin nə olduğu və necə işə salındığı qısa izah olunur. Düzdür, bəzən faylda yalnız layihənin adı və özünüzün hər şeyi başa düşəcəyinizə dair ümid olur. Adamlar tənbəldir, README isə öz-özünə yazılmır :)

README-dən adətən üç şeyi öyrənmək olur: layihənin təyinatını, onu işə salma qaydasını və daha ətraflı təlimatlara keçidləri - məsələn, arxitektura və ya kod tərtibatı qaydaları barədə ayrıca faylı. Səhifədə kiçik düzəliş üçün ümumi mənzərəni anlamağa bu qədər məlumat kifayətdir.

README olmaya və ya koddan geri qala bilər. Onu başlanğıc nöqtəsi sayın: əmrlər və qovluqlar barədə məlumatı layihə faylları ilə tutuşdurmaq lazımdır. Təsvir bir quruluşdan danışır, fayl ağacı isə başqa quruluş göstərirsə, bunu yoxlanmalı sual kimi qeyd edin.

Qovluq ağacı nə deyir

Tədris nümunəsi götürək: oyun vitrini, xal hesablanması və nəticələr cədvəli olan kiçik brauzer portalı. Onun ağacının bir hissəsi belə görünür:

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

Hələ bir sətir kod oxumadan da ağac bəzi şeylərdən xəbər verir:

Qovluğun adı istiqamət verir, amma təsdiq sayılmır. src/leaderboard.js adına görə lazım olan fayla oxşayır; indi onu oxuyub harada qoşulduğunu tapmaq lazımdır. Yuxarıdakı cədvəl hələ təsdiqlənməli olan ehtimal edilən rolları göstərir. Xüsusən də tests/ qovluğunun olması yoxlamaların necə işə salındığı barədə hələ heç nə demir.

Mənbə kodunu ondan yaradılan və ya kənardan quraşdırılan fayllardan ayırmaq da vacibdir. dist/ adətən build aləti tərəfindən src/ məzmunu əsasında yaradılır, üçüncü tərəf asılılıqlarının qovluğu isə (nümunədə olmasa da, çox vaxt node_modules/ adlanır) komandanızdakı insanlar tərəfindən yazılmayıb. Oxumağa bunlardan başlamaq demək olar ki, həmişə mənasızdır: oradakı dəyişiklik növbəti build zamanı itəcək, ya da birbaşa redaktə etmədiyiniz başqasının koduna aid olacaq. Paket menecerləri, asılılıqların quraşdırılması və lockfile formatı isə ayrıca mövzudur, bura daxil deyil.

Bir məqam da var: nümunədəki qovluq dəsti standart deyil. Başqa layihədə səhifələr public/, mənbə faylları isə app/ qovluğunda ola bilər. Axtarış məntiqi dəyişməyəcək, yalnız adlar fərqli olacaq.

Layihə ilə iş qaydaları

Fərz edək ki, qovluqların təyinatını anladınız. Fayl əlavə etməzdən əvvəl burada necə işləməyin qəbul olunduğunu öyrənin. Bir layihədə bütün səhifələr ümumi qovluqda saxlanılır, digərində isə hər oyun öz skriptləri və şəkilləri ilə birlikdə yerləşir. Hər iki üsul rahat ola bilər. Yeni oyunu üçüncü bir üsulla quranda və bu qərarın səbəbi heç yerdə izah olunmayanda problemlər başlayır.

README-dəki keçidlərdən layihənin razılaşmalarını axtarın. CONTRIBUTING.md faylı varsa, adətən dəyişikliklərin necə edilməli olduğunu izah edir. Sənədlərdə faylların yerləşdirilməsi qaydaları, CLAUDE.md faylında isə agent üçün təlimatlar ola bilər. Ayrıca qovluğun içindəkiləri dəqiqləşdirən öz README-si də ola bilər. Hər layihədə bunların hamısının olacağını gözləməyin: bəzən lazım olan bir neçə qayda kök README-də olur.

İlk düzəliş üçün hansı mənbə fayllarını dəyişməyin mümkün olduğunu, onları necə adlandırıb yerləşdirməyi, layihəni necə işə salmağı və nəticəni necə yoxlamağı öyrənmək kifayətdir. Təlimat build nəticəsini redaktə etməyi qadağan edirsə, mənbə faylını tapın. Səhifə əlavə edəndə təsviri yeniləməyi tələb edirsə, bunu elə əvvəldən tapşırığa daxil edin.

Yazılı qayda yoxdursa, iki-üç oxşar nümunəyə baxın. Yeni oyun üçün sənədlərin təsadüfi qovluğunu yox, qonşu oyunları öyrənmək daha faydalıdır. Faylların oxşar yerləşdirilməsini nümunə götürmək olar, amma bir köhnə fayl bütün layihənin belə qurulduğunu hələ sübut etmir.

Daha xoşagəlməz vəziyyət də olur: README səhifələri pages/ qovluğuna yönləndirir, amma son oyunlar başqa yerdədir. Bu zaman layihə sahibinə konkret sual verin: "Təlimatda pages/ göstərilib, amma iki yeni oyun games/ qovluğundadır. Növbətini hara əlavə edim?" Bəyəndiyiniz variantı səssizcə seçməyin və vahidlik xatirinə bütün ağacı köçürməyin.

Fayl və qovluqların adlandırılması

Adlandırma adlarla bağlı razılaşmadır. Yaxşı ad faylı ağacda tapmağa və açmadan əvvəl təyinatını anlamağa kömək edir. Portalımızda leaderboard.html nəticələr cədvəli olduğunu bildirir, page2.html isə yalnız hansısa sıra nömrəsini deyir.

Adın həm mənası, həm də forması var. Məna "burada nə var?" sualına cavab verir, forma isə hərflərin registrini və söz ayırıcılarını müəyyənləşdirir. Məsələn, gündəlik mükafatlar səhifəsini bir neçə cür adlandırmaq olar:

Bunlar yazılış variantlarıdır, reytinq deyil. Layihənin səhifələri defislə adlandırılıbsa, yeni səhifəyə də eyni üslubda ad verin. Bununla belə, müxtəlif fayl qruplarının fərqli razılaşmaları ola bilər: HTML səhifələrinə oxşasın deyə tanış README.md adını kiçik hərflərə çevirmək lazım deyil. Alətlərin gözlədiyi adlar da olduğu kimi saxlanılır.

Fərz edək ki, portalın adi faylları üçün kebab-case formatında ingiliscə sözlərdən istifadə etməyə razılaşmısınız. Onda snake-preview.png adı img3.png-dən aydındır: bu, Snake oyununun önizləmə şəklidir. game-icons/ qovluğunun adı məzmunu stuff/-dan daha yaxşı izah edir. leaderboard-final-new.html adı növbəti düzəlişdən sonra tez köhnələcək; işlək səhifə üçün təyinatına uyğun, davamlı ad seçin.

Hər anlayış üçün bir termin seçin. Layihədə oyunlar games adlanırsa, həmin qrup üçün plays qovluğunun yaranması oxucunu bunların arasında fərq olub-olmadığını araşdırmağa məcbur edəcək. Layihə razılaşmalarında belə qısaltma yoxdursa, sözləri ldrbrd/ kimi tapmacaya çevirməyin.

Yazılışın dəqiqliyi də vacibdir. Böyük-kiçik hərflər də daxil olmaqla faylın adı və yolu eyni olmalıdır: Snake.png və snake.png adlarını bir-birini əvəz edən saymaq olmaz. Səhv bir kompüterdə görünməyib başqa mühitdə üzə çıxa bilər. Nümunəmizdə kiçik hərflərdən istifadə razılaşması belə uyğunsuzluqları azaldır.

Qovluqların iç-içə quruluşu

Ad seçildi. Növbəti sual faylı hara yerləşdirməkdir. İç-içə qovluq aydın bir qrupu birləşdirəndə faydalıdır: oyun səhifələri, bir oyunun şəkilləri, ortaq ikonlar. Hər yeni səviyyə məzmunu tapmağa kömək etməlidir.

Alternativ vəziyyəti təsəvvür edin: portal böyüyür, bütün fayllar isə birbaşa kök qovluğa yığılır:

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

Kiçik nümunədə hələ baş çıxarmaq mümkündür. Oyunların sayı iyirmiyə çatanda səhifələr, skriptlər və şəkillər bir-birinə qarışacaq. Portalımız artıq pages/, src/ və assets/ qovluqlarına bölünüb, buna görə yeni oyunlar əlavə edəndə bu bölgünü davam etdirmək məntiqlidir. Belə əlavədən sonra mümkün quruluşun bir hissəsi belə görünə bilər:

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

Oyun səhifələri bir qrupda, onların skriptləri isə başqa qrupda toplanıb. Oyunun adı faylları bir-biri ilə əlaqələndirir. Şəkillər konkret oyunun qovluğundadır, ona görə qısa preview.png adı kifayətdir: tam yol önizləmə şəklinin hansı oyuna aid olduğunu göstərir. Ayrıca qovluq həmin oyunun başqa şəkilləri üçün də yararlı olacaq.

Əks ifrat variant pages/portal/content/browser/games/arcade/snake/screens/main/index.html kimi yoldur. Bir səhifəyə çatmaq üçün çox səviyyə keçmək lazım gəlir, adların bir hissəsi isə demək olar ki, heç nə əlavə etmir. Layihədə ayrıca portallar, ekranlar və kateqoriyalar yoxdursa, belə quruluş faydasız iş yaradır.

"Üç qovluqdan dərinə getməmək" kimi universal hədd yoxdur. Hər səviyyənin mənasını yoxlayın: o nəyi birləşdirir və bu qrupu qonşu qruplardan ayırmağa kömək edirmi? Bəzən alət və ya layihə qaydalarına görə bir fayllıq qovluq lazım olur. Amma "bəlkə sonra burada nəsə yaranar" deyə qovluq yaratmaq adətən tezdir.

Yuxarıdakı ağac nümunəmizin inkişafını göstərir. Layihənizdə hər oyun artıq bütövlükdə öz qovluğunda saxlanılırsa, bu üsulu davam etdirin. Təkcə yeni oyunun əlavə olunması qalan quruluşu dəyişmək üçün səbəb deyil.

Ortaq və lokal faylları harada saxlamaq olar

Snake oyunu üçün alma şəkli, bütün portal üçün isə ortaq loqo əlavə edilib. Hər iki fayl şəkildir, amma fərqli məqsədlə istifadə olunur. Alma yalnız bir oyuna lazımdır, loqo isə vitrində, nəticələr cədvəlində və oyun səhifələrində göstərilir.

Bir oyuna aid fayl yalnız həmin oyunda istifadə olunur. Bu bölmədə belə faylları lokal adlandırırıq: söhbət kompüterdə və ya serverdə saxlanmasından yox, istifadə sahəsindən gedir. Ağacımızın bu variantında alma şəkli assets/games/snake/apple.png yolunda olacaq. Ortaq fayl bir neçə hissəyə lazımdır; layihədə belə qovluq qəbul edilibsə, loqo üçün assets/shared/portal-logo.svg yolu ayrıla bilər. shared sözü "ortaq" deməkdir, amma qovluğun adı fayla öz-özlüyündə heç bir xüsusi xassə vermir.

Eyni fərq stillərə və skriptlərə də aiddir. Snake oyun sahəsinin dizaynı həmin oyuna, ümumi başlığın dizaynı isə bütün portala aiddir. Yer seçərkən fayldan hazırda kimin istifadə etdiyini soruşun. Gələcəkdə təkrar istifadə oluna bilər deyə hər şeyi qabaqcadan ortaq qovluğa çıxarmağa ehtiyac yoxdur.

Əksinə, eyni loqonu hər oyunun qovluğuna köçürmək əlverişsizdir: onu dəyişəndə bütün nüsxələri tapmaq lazım gələcək. Bu, həqiqətən ortaq resursdursa, bir fayla istinad etmək daha yaxşıdır. Müxtəlif oyunların bir-birinə oxşayan iki şəkli isə müstəqil qala bilər: zahiri oxşarlıq onların həmişə birlikdə dəyişdiriləcəyi demək deyil.

Sxemdə ümumi loqoya üç ox, alma şəklinə isə yalnız bir ox gedir. Buna görə loqonu dəyişdikdən sonra hər üç səhifəyə, alma şəklini dəyişdikdən sonra isə Snake səhifəsinə baxın. Düzəlişdən əvvəl Claude Code-dan hansı faylların resursa istinad etdiyini tapmağı istəmək faydalıdır: faktiki əlaqələr qovluğun adından görünəndən çox ola bilər.

Köçürmə və ad dəyişərkən nəyi yoxlamaq lazımdır

Faylın adını bir saniyədə dəyişmək olar, amma əvvəlki adı keçidlərdə və parametrlərdə artıq yazılmış ola bilər. Köçürmə onun digər fayllara nəzərən yerini də dəyişir. Buna görə ağacı səliqəyə salmaq da səhifənin məzmununu dəyişmək kimi layihə düzəlişidir.

Köçürmə ilə bağlı ayrıca nümunəyə baxaq: pages/snake.html səhifəsi pages/games/snake.html yoluna köçürülüb. Skript əvvəlki yerdə, src/games/snake.js faylındadır. Bu nümunədə nisbi yol HTML səhifəsinin ünvanına görə hesablanır. Köçürmədən sonra qoşulma yolunu dəyişmək lazımdır:

<!-- Köçürülməzdən əvvəl pages/snake.html faylında -->
<script src="../src/games/snake.js" type="module"></script>

<!-- Köçürüləndən sonra pages/games/snake.html faylında -->
<script src="../../src/games/snake.js" type="module"></script>

../ fraqmentlərinin hər biri yolu bir qovluq yuxarı qaldırır. İndi games/ qovluğundan pages/-ə, sonra kök qovluğa çıxmaq və yalnız oradan src/-ə keçmək lazımdır. Skriptin özü dəyişməyib, amma ona gedən köhnə yol artıq yanlışdır.

Əks istiqamətdə keçidlər də var: vitrindəki oyun kartı hələ də səhifənin köhnə ünvanına apara bilər. Köçürmədən əvvəl layihədə köhnə yolun çəkildiyi yerləri tapın. Köçürdükdən sonra lazım olan keçidləri, qoşulmaları, build parametrlərini və sənədlərdəki nümunələri yeniləyin. Adı dəyişdirilən skript üçün importları da yoxlayın - başqa skriptlərin onu qoşduğu qeydləri.

IDE bəzi keçidləri avtomatik yeniləyə bilər, amma nəticəyə yenə də baxmaq lazımdır. Hər yol bir sətirdə yazılmır: bəzən ünvan qovluq və fayl adlarından yığılır. Buna görə köhnə adı axtarmaq asılılıqları tapmağa, lazımi ssenarini işə salmaq isə gözdən qaçanları üzə çıxarmağa kömək edir.

Düzəlişin nəticəsini necə yoxlamaq olar

Əvvəl layihə sənədlərində işə salma, build və yoxlama əmrlərini tapın. Layihədə package.json varsa, təlimatı onun scripts bölməsi ilə tutuşdurun. Əmr adları layihədən asılıdır; tests/ qovluğunun olması nəyin başladılmalı olduğunu öz-özünə göstərmir. Təlimat yoxdursa, tanış əmri kor-koranə işlətmək əvəzinə yoxlama üsulunu dəqiqləşdirin.

Sonrakı yoxlama edilən dəyişiklikdən asılıdır. Snake səhifəsini köçürdükdən sonra onu vitrindəki kart vasitəsilə açın: beləliklə həm keçidi, həm də oyunun yüklənməsini yoxlayacaqsınız. Şəkillərin göründüyünə və oyunun işə düşdüyünə əmin olun. Ortaq loqonu dəyişəndə nəticələr cədvəlinə və başqa bir oyun səhifəsinə də baxın.

Build-in uğurla tamamlanması faydalıdır, amma bu addımları əvəz etmir: köhnə ünvana keçid build edilmiş layihədə qala bilər. Nəyi yoxlaya bildiyinizi, nəyin isə hələ yoxlanmadığını qeyd edin. Məsələn: "Build tamamlandı, Snake vitrindən açılır və işə düşür; dar ekranda görünüş yoxlanmayıb".

Sonda dəyişdirilmiş faylların siyahısına baxın. Bir oyun əlavə edilibsə, onun faylları və vitrin düzəlişi gözləniləndir. Başqa oyunların qovluqlarının adını dəyişmək və ya şəkilləri toplu şəkildə yenidən yazmaq izah tələb edir. Bu siyahını nəzərdən keçirmək sonradan gözlənilməz nasazlığı axtarmaqdan az vaxt aparır.

Qaydaları Claude Code-a necə ötürmək olar

"Oyunu səliqəli əlavə et" xahişi agentə həddən artıq çox qərar buraxır. Tapşırığı dəqiq izah edib əvvəlcə layihə razılaşmalarını öyrənməsini istəmək daha faydalıdır. Yeni oyunun yolu agentin təsadüfi seçiminə yox, layihənin quruluşuna uyğun olmalıdır.

Daimi və yoxlanmış qaydaları CLAUDE.md faylına yazmaq olar. Tədris portalımız üçün belə bir hissə bu cür görünə bilər:

## Fayllar və qovluqlar
- Adi fayl və qovluqlara kebab-case formatında ingiliscə adlar veririk.
  README.md və CLAUDE.md kimi qəbul olunmuş adları saxlayırıq.
- Oyun səhifələri pages/games/, oyun skriptləri src/games/ qovluğunda yerləşir.
- Bir oyunun resursları assets/games/<game-name>/ qovluğunda olur.
- Portalın ortaq şəkilləri assets/shared/ qovluğunda saxlanılır.
- Köçürmə və ya ad dəyişmə zamanı fayla olan keçidləri
  və onun daxilindəki nisbi yolları yeniləyirik.

## Yoxlama
- İşə salma və yoxlama əmrlərini README.md-dən götürürük.
- Yeni oyunu vitrindən açıb işə düşdüyünü yoxlayırıq.
- Ortaq resurs dəyişəndən sonra ondan istifadə edən səhifələri yoxlayırıq.

Bu, razılaşdırılmış qayda nümunəsidir, ağac üçün universal şablon deyil. Öz layihənizdə oxşar blok yazmazdan əvvəl yolları və əmrləri real fayllarla tutuşdurun. Agent qovluğun təyinatını yalnız təxmin edibsə, ondan əsaslarını göstərməsini istəyin; ehtimalı daimi təlimata çevirməyin.

İndi oyun əlavə etmək üçün tapşırıq belə səslənə bilər:

Əlavə olunmuş təsvirə əsasən portala memory-match oyunu əlavə et.
README.md, CLAUDE.md və tapşırığın toxunacağı qovluqların təlimatlarını oxu.
Mövcud iki oyunun fayllarının necə yerləşdirildiyinə bax.
Yeni səhifə, skript və şəkillər üçün ad və yollar təklif et.
Vitrinin hansı faylını dəyişmək lazım olduğunu və nəticəni necə yoxlamağı göstər.
Təlimatlar layihənin quruluşu ilə uyğun gəlmirsə, sual ver.
Əvvəlcə planı göstər, razılaşdırılmasını gözlə, sonra dəyişiklik et.

Plan əsasında konkret qərarları əvvəlcədən qiymətləndirmək olar: oyun hara yerləşəcək, hansı fayllar ortaq olacaq, iş qonşu səhifələrə toxunacaqmı. Düzəlişdən sonra dəyişdirilmiş faylları və aparılmış yoxlamaları sadalamağı istəyin. Nəticəni razılaşdırdığınız planla tutuşdurmaq daha asan olacaq.