Tanımadığınız Bir Projeyi Anlamak

IDE'de, daha önce hiç görmediğiniz bir proje klasörünü açıyorsunuz: iç içe geçmiş onlarca klasör, tanımadığınız adlar ve sizin yazdığınız tek bir dosya bile yok. Değişiklik yapmanız gerekecek: önce sayfalarda küçük düzenlemeler, ardından yeni oyun eklemeleri. Başlamadan önce gerekli dosyaların nerede olduğunu ve projede hangi kuralların geçerli olduğunu anlamanız gerekir.

Aradığınız yere denk gelme umuduyla klasörleri sırayla açmaya başlamak kolaydır. Önce projenin genel yapısını ve kurallarını anlamak daha yararlı. Bunlar hem küçük bir düzenlemede hem de daha sonra yeni bir oyun eklemek istediğinizde işinize yarar: dosyalara ad vermeniz, onları uygun yere koymanız ve sonucu Claude Code ile kontrol etmeniz gerekecek.

Önce projeye giriş noktasını bulun

IDE panelindeki dosya ağacından başlayın ve proje kökünde README.md dosyasını bulun. Bu, program için değil insan için yazılmış sıradan bir metin dosyasıdır: genellikle projenin ne olduğunu ve nasıl çalıştırılacağını kısaca açıklar. Gerçi bazen içinde yalnızca projenin adı ve gerisini kendiniz çözeceğiniz umudu vardır. İnsanlar tembel; README kendi kendini yazmıyor :)

README'den genellikle üç şey öğrenebilirsiniz: projenin amacı, nasıl çalıştırılacağı ve daha ayrıntılı yönergelerin bağlantıları - örneğin mimariyi veya kod biçimlendirme kurallarını anlatan ayrı bir dosya. Küçük bir sayfa düzenlemesi için genel tabloyu görmeye bu kadarı yeter.

README bulunmayabilir ya da kodun gerisinde kalmış olabilir. Onu başlangıç noktası sayın; komutlar ve klasörlerle ilgili bilgileri proje dosyalarıyla karşılaştırın. Açıklama başka, dosya ağacı başka bir yapı gösteriyorsa bunu kontrol edilmesi gereken bir soru olarak not edin.

Klasör ağacı neler anlatır?

Bir eğitim örneği düşünelim: oyun vitrini, puan kazanma ve sonuç tablosu olan küçük bir tarayıcı portalı. Dosya ağacının bir bölümü şöyle görünüyor:

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

Henüz tek satır kod okumadan bile dosya ağacı bazı ipuçları verir:

Klasör adı bir ipucudur, doğrulama değil. src/leaderboard.js adıyla aradığınız dosyaya benziyor; şimdi onu okuyup sayfaya nerede dahil edildiğini bulmanız gerekir. Yukarıdaki tablo klasörlerin henüz doğrulanması gereken olası rollerini anlatıyor. Özellikle tests/ klasörünün varlığı, kontrollerin nasıl çalıştırılacağını tek başına açıklamaz.

Kaynak kodu, bu kodun ürettiği veya dışarıdan kurulan dosyalardan ayırmak da önemli. dist/ genellikle src/ içeriğinden derleme aracıyla oluşturulur. Üçüncü taraf bağımlılıkların klasörünü (örneğin node_modules/; örnekte bulunmuyor) ekibinizdeki kişiler yazmamıştır. Bunları okumaya başlamak çoğu zaman anlamsızdır: oradaki bir değişiklik sonraki derlemede kaybolur ya da doğrudan düzenlemediğiniz başka birine ait koda dokunur. Paket yöneticileri, bağımlılık kurulumu ve lockfile biçimi ayrı bir konu; burada ele almıyoruz.

Bir de şu var: örnekteki klasörler standart değildir. Başka bir projede sayfalar public/, kaynak kod ise app/ içinde olabilir. Arama mantığı aynı kalır, yalnızca adlar değişir.

Projeyle çalışma kuralları

Diyelim ki klasörlerin amacını anladınız. Dosya eklemeden önce burada işlerin nasıl yürütüldüğünü öğrenin. Bir projede tüm sayfalar ortak bir klasörde, diğerinde her oyun kendi script'leri ve görselleriyle birlikte tutulabilir. İki yöntem de işe yarayabilir. Sorun, yeni bir oyun üçüncü bir yaklaşımla düzenlendiğinde ve bunun nedeni hiçbir yerde açıklanmadığında başlar.

README'deki bağlantılardan proje kurallarını arayın. Varsa CONTRIBUTING.md dosyası genellikle değişikliklerin nasıl yapılacağını açıklar. Belgelerde dosya yerleşimiyle ilgili kurallar olabilir, CLAUDE.md ise ajan için talimatlar içerebilir. Ayrı bir klasörün içeriğiyle ilgili açıklamalar içeren kendi README dosyası da olabilir. Her projede bu dosyaların hepsini bulmayı beklemeyin: bazen gereken birkaç kural kök dizindeki README'ye sığar.

İlk düzenleme için hangi kaynak dosyaların değiştirilebileceğini, nasıl adlandırılıp nereye konduğunu, projenin nasıl çalıştırıldığını ve sonucun nasıl kontrol edildiğini öğrenmeniz yeterli. Talimat derleme çıktısını düzenlemeyi yasaklıyorsa kaynak dosyayı bulun. Yeni sayfa eklerken açıklamanın da güncellenmesini istiyorsa bunu göreve baştan ekleyin.

Yazılı bir kural yoksa benzer iki üç örneğe bakın. Yeni bir oyun için komşu oyunları incelemek, rastgele bir belgeler klasörünü açmaktan daha yararlıdır. Bu örneklerde ortak olan yerleştirme biçimini model alabilirsiniz; ancak tek bir eski dosya tüm projenin böyle düzenlendiğini kanıtlamaz.

Daha tatsız bir durum da olabilir: README sayfaları pages/ içine yönlendirirken son oyunlar başka bir yerde duruyordur. Proje sahibine şöyle net bir soru sorun: "Talimatlarda pages/ yazıyor ama iki yeni oyun games/ içine konmuş. Sıradakini nereye ekleyelim?" Sessizce hoşunuza giden seçeneği seçmeyin veya sırf tutarlılık için tüm ağacı taşımayın.

Dosya ve klasör adlandırma kuralları

Adlandırma, isimler üzerinde anlaşmaktır. İyi bir ad, dosya ağacında aradığınız dosyayı bulmanıza ve açmadan önce ne işe yaradığını anlamanıza yardımcı olur. Portalımızda leaderboard.html sonuç tablosunu çağrıştırırken page2.html yalnızca bir sıra numarası söyler.

Bir adın hem anlamı hem de biçimi vardır. Anlamı "burada ne var?" sorusunu yanıtlar; biçimiyse büyük-küçük harf kullanımını ve sözcükleri ayırma yöntemini belirler. Örneğin, günlük ödüller sayfasına birkaç farklı şekilde ad verebilirsiniz:

Bunlar yazım biçimleri, bir sıralama değil. Projedeki sayfalar tireyle adlandırılıyorsa yeni sayfaya da aynı biçimde ad verin. Farklı dosya gruplarının kuralları farklı olabilir: HTML sayfalarıyla benzesin diye alışılmış README.md adını küçük harfe çevirmeyin. Araçların beklediği adları da koruyun.

Portalımızdaki sıradan dosyalar için İngilizce sözcükleri kebab-case biçiminde kullanmaya karar verdiğimizi varsayalım. Bu durumda snake-preview.png, img3.png adından daha açıklayıcıdır: Yılan oyununun önizlemesi olduğunu anlatır. game-icons/ klasörü, içeriği hakkında stuff/ klasöründen daha çok şey söyler. leaderboard-final-new.html adı bir sonraki düzenlemede eskir; kullanımdaki bir sayfaya amacını belirten kalıcı bir ad verin.

Aynı kavram için tek bir terim seçin. Projedeki oyunlara games deniyorsa aynı grup için plays adlı bir klasör eklemek, okuyucuyu aralarında fark olup olmadığını düşünmeye iter. Proje kurallarında yoksa sözcükleri ldrbrd/ gibi anlaşılmaz kısaltmalara indirmeyin.

Yazımın doğruluğu da önemli. Dosya adı ve yolu, büyük-küçük harfler dahil birbiriyle uyuşmalı: Snake.png ile snake.png birbirinin yerine kullanılamaz. Hata bir bilgisayarda fark edilmeyip başka bir ortamda ortaya çıkabilir. Örneğimizde küçük harf kullanma kuralı bu tür uyumsuzlukları azaltır.

Klasörlerin iç içe yerleşimi

Adı seçtik. Sıradaki soru dosyanın nereye konacağı. İç içe klasörler oyun sayfaları, tek bir oyunun görselleri veya ortak simgeler gibi anlaşılır gruplar oluşturduğunda yararlıdır. Her yeni düzey, içeriği bulmayı kolaylaştırmalı.

Başka bir durumu düşünelim: portal büyüyor ama tüm dosyalar doğrudan kök dizine atılıyor:

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

Küçük bir örnekte bu yapı hâlâ idare eder. Oyun sayısı yirmiye çıktığında sayfalar, script'ler ve görseller birbirine karışır. Portalımızda pages/, src/ ve assets/ ayrımı zaten var; yeni oyunlar eklerken bunu sürdürmek mantıklı. Eklemelerden sonra olası yapının bir bölümü şöyle görünebilir:

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 sayfaları bir grupta, script'leri başka bir grupta toplanmış. Oyun adı dosyaları birbirine bağlıyor. Görsellerin her oyun için ayrı bir klasörü var; bu yüzden preview.png gibi kısa bir ad yeterli: tam yol önizlemenin hangi oyuna ait olduğunu zaten gösteriyor. Aynı oyunun diğer görselleri için de ayrı klasör işe yarar.

Diğer uçta pages/portal/content/browser/games/arcade/snake/screens/main/index.html gibi bir yol var. Tek bir sayfayı açmak için birçok klasör geçmeniz gerekir ve adların bazıları pek bilgi vermez. Projede ayrı portallar, ekranlar ve kategoriler yoksa böyle bir yapı fayda sağlamadan iş çıkarır.

"En fazla üç klasör derinliği" gibi evrensel bir sınır yok. Her düzeyin neyi bir araya getirdiğini ve bu grubu komşularından ayırmaya yardımcı olup olmadığını değerlendirin. Araç veya proje kuralları nedeniyle tek dosyalı bir klasör gerekebilir. Ama sırf "belki sonra bir şey ekleriz" diye oluşturmak genellikle erkendir.

Yukarıdaki ağaç örneğimizin nasıl gelişebileceğini gösteriyor. Projenizde her oyun zaten kendi klasöründe tutuluyorsa bu yöntemi sürdürün. Yeni bir oyun eklemek, diğerlerini yeniden düzenlemek için tek başına gerekçe değildir.

Ortak ve yerel dosyalar nerede tutulur?

Yılan oyununa bir elma görseli, tüm portala da ortak bir logo eklenmiş olsun. İkisi de görseldir ama farklı biçimde kullanılır. Elma tek bir oyun için gerekir; logo vitrinde, sonuç tablosunda ve oyun sayfalarında görünür.

Tek bir oyuna ait dosya yalnızca o oyunda kullanılır. Bu bölümde bu tür dosyalara yerel diyeceğiz: buradaki yerellik, bilgisayarda ya da sunucuda tutulmasıyla değil, kullanım alanıyla ilgilidir. Ağaç örneğimizde elma görseli assets/games/snake/apple.png yolunda olur. Ortak dosya birkaç bölümün işine yarar; projede böyle bir klasör kullanılıyorsa logo için assets/shared/portal-logo.svg ayrılabilir. shared sözcüğü "ortak" demektir, ancak klasör adı dosyaya kendiliğinden özel bir özellik kazandırmaz.

Aynı ayrım stiller ve script'ler için de geçerlidir. Yılan'ın oyun alanının görünümü o oyuna, ortak üst bölümün görünümüyse tüm portala aittir. Dosyanın konumuna karar verirken onu şu anda kimin kullandığını sorun. İleride tekrar kullanılır diye her şeyi şimdiden ortak klasöre taşımayın.

Tersine, tek bir logoyu her oyunun klasörüne kopyalamak da kullanışsızdır: değiştirirken tüm kopyaları bulmanız gerekir. Gerçekten ortak bir kaynaktan söz ediyorsak tek dosyaya başvurmak daha iyi. Farklı oyunlardaki benzer iki görsel ise bağımsız kalabilir; görünüşlerinin benzemesi her zaman birlikte değiştirilecekleri anlamına gelmez.

Şemada ortak logoya üç ok, elma görselineyse yalnızca bir ok yöneliyor. Bu nedenle logoyu değiştirdikten sonra üç sayfayı da, elmayı değiştirdikten sonra Yılan'ı kontrol edin. Düzenleme öncesinde Claude Code'dan kaynağa hangi dosyaların başvurduğunu bulmasını istemek yararlı olabilir: gerçek bağlantılar klasör adından anlaşılandan daha fazla olabilir.

Taşıma ve yeniden adlandırma sırasında neleri kontrol etmeli?

Bir dosyanın adını saniyeler içinde değiştirebilirsiniz; ancak eski adı bağlantılarda ve ayarlarda geçiyor olabilir. Taşıma, dosyanın diğerlerine göre konumunu da değiştirir. Bu yüzden dosya ağacını düzenlemek de sayfa içeriğini değiştirmek gibi bir proje değişikliğidir.

Taşıma için ayrı bir örnek ele alalım: pages/snake.html sayfası pages/games/snake.html konumuna taşınıyor. Script, src/games/snake.js konumunda kalıyor. Bu örnekte göreli yol, HTML sayfasının konumuna göre hesaplanıyor. Taşıdıktan sonra bağlantıyı değiştirmeniz gerekir:

<!-- pages/snake.html içinde taşımadan önce -->
<script src="../src/games/snake.js" type="module"></script>

<!-- pages/games/snake.html içinde taşıdıktan sonra -->
<script src="../../src/games/snake.js" type="module"></script>

../ parçalarının her biri yolu bir klasör yukarı taşır. Artık games/ içinden önce pages/ klasörüne, ardından kök dizine çıkıp ancak oradan src/ içine geçmeniz gerekir. Script değişmedi ama eski yolu artık geçersiz.

Ters yönde giden bağlantılar da var: vitrindeki oyun kartı hâlâ sayfanın eski adresine yönlendirebilir. Taşımadan önce proje genelinde eski yolun geçtiği yerleri bulun. Taşıdıktan sonra gerekli bağlantıları, script referanslarını, derleme ayarlarını ve belgelerdeki örnekleri güncelleyin. Yeniden adlandırılan bir script için import ifadelerini, yani diğer script'lerin onu dahil ettiği satırları da kontrol edin.

IDE bazı bağlantıları otomatik güncelleyebilir, ancak sonucu yine de gözden geçirin. Her yol tek bir dizge olarak yazılmayabilir: bazen adres klasör ve dosya adlarından birleştirilir. Eski adı aramak bağımlılıkları bulmaya, ilgili senaryoyu çalıştırmaksa gözden kaçanları fark etmeye yardımcı olur.

Yaptığınız değişikliği nasıl kontrol edersiniz?

Önce proje belgelerinde çalıştırma, derleme ve kontrol komutlarını bulun. Projede package.json varsa talimatı içindeki scripts bölümüyle karşılaştırın. Komut adları projeye göre değişir; tests/ klasörünün varlığı hangi komutun çalıştırılacağını tek başına göstermez. Talimat yoksa bildiğiniz bir komutu tahmin ederek kullanmak yerine kontrol yöntemini sorun.

Sonraki kontrol, yaptığınız değişikliğe bağlıdır. Yılan sayfasını taşıdıktan sonra vitrindeki kartından açın; böylece hem bağlantıyı hem de oyunun yüklenmesini kontrol edersiniz. Görsellerin göründüğünden ve oyunun çalıştığından emin olun. Ortak logoyu değiştirdiyseniz sonuç tablosuna ve başka bir oyun sayfasına da bakın.

Derlemenin başarılı olması yararlıdır ama bu adımların yerini tutmaz: eski adrese giden bağlantı derlenmiş projede de kalmış olabilir. Neleri kontrol ettiğinizi ve nelerin henüz kontrol edilmediğini not edin. Örneğin: "Derleme başarılı, Yılan vitrinden açılıyor ve çalışıyor; dar ekrandaki görünüm kontrol edilmedi".

Son olarak değişen dosyaların listesini gözden geçirin. Tek bir oyun eklediyseniz onun dosyaları ve vitrindeki bir düzenleme beklenir. Başka oyun klasörlerinin yeniden adlandırılması veya görsellerin topluca üzerine yazılması açıklama gerektirir. Bu gözden geçirme, sonradan beklenmedik bir hatayı aramaktan daha kısa sürer.

Kuralları Claude Code'a nasıl aktarabilirsiniz?

"Oyunu düzgünce ekle" isteği ajana çok fazla karar bırakır. Görevi açıkça belirtip önce proje kurallarını incelemesini istemek daha yararlı. Yeni oyunun yolu, ajanın rastgele tercihine değil projenin yapısına uymalı.

Kalıcı ve doğrulanmış kuralları CLAUDE.md dosyasına yazabilirsiniz. Eğitim portalımız için bir bölüm şöyle görünebilir:

## Dosyalar ve klasörler
- Sıradan dosya ve klasörlere kebab-case biçiminde İngilizce ad ver.
  README.md ve CLAUDE.md gibi kabul edilmiş adları koru.
- Oyun sayfaları pages/games/, oyun script'leri src/games/ içinde bulunur.
- Tek bir oyunun kaynakları assets/games/<game-name>/ içinde bulunur.
- Portalın ortak görselleri assets/shared/ içinde bulunur.
- Taşıma veya yeniden adlandırma sırasında dosya bağlantılarını
  ve içindeki göreli yolları güncelle.

## Kontrol
- Çalıştırma ve kontrol komutlarını README.md dosyasından al.
- Yeni oyunu vitrinden açıp çalıştığını kontrol et.
- Ortak bir kaynak değiştiğinde onu kullanan sayfaları kontrol et.

Bu, üzerinde anlaşılmış kurallara bir örnektir; her proje için geçerli bir ağaç şablonu değildir. Benzer bir bölümü kendi dosyanıza eklemeden önce yolları ve komutları gerçek dosyalarla karşılaştırın. Ajan bir klasörün amacını yalnızca tahmin ettiyse dayanağını göstermesini isteyin; tahmini kalıcı bir talimata dönüştürmeyin.

Şimdi bir oyun ekleme görevi şöyle yazılabilir:

Ekli açıklamaya göre portala memory-match oyununu ekle.
README.md, CLAUDE.md ve görevin dokunacağı klasörlerin talimatlarını oku.
Var olan iki oyunun dosyalarının nasıl yerleştirildiğine bak.
Yeni sayfa, script ve görseller için adlar ve yollar öner.
Vitrinde hangi dosyayı değiştirmek gerektiğini ve sonucu nasıl kontrol edeceğini belirt.
Talimatlar projenin mevcut yapısıyla çelişiyorsa soru sor.
Önce planı göster, onay bekle ve sonra değişiklikleri yap.

Plan, oyunun nereye konacağını, hangi dosyaların ortak olacağını ve çalışmanın komşu sayfaları etkileyip etkilemeyeceğini somut olarak değerlendirmeye yardımcı olur. Düzenlemeden sonra değişen dosyaları ve yapılan kontrolleri listelemesini isteyin. Böylece sonucu üzerinde anlaştığınız planla karşılaştırmanız kolaylaşır.