Claude Code ile Üretim Yaparken Benim İçin En Önemli Şey Ne?

Kod yazma biçimi değişiyor

Kod yazma biçimimizin değiştiğini düşünüyorum. Eskiden bütün kodu satır satır yazmak sürecin merkezindeydi. Bir buton eklemek için bile sözdizimini hatırlamak, dokümantasyonu açmak, küçük hataları tek tek ayıklamak gerekiyordu. Bu işin bir kısmı hâlâ duruyor, ama ağırlık merkezi kaydı.

Şimdi ne istediğini doğru tarif etmek, sistemin nasıl çalıştığını anlamak ve çıkan sonucu kontrol etmek daha önemli hale geliyor. Claude Code gibi komut satırında çalışan, projedeki dosyaları okuyup düzenleyebilen araçlar bu kaymayı çok görünür kılıyor. Araç dosyaları gezebiliyor, değişiklik önerebiliyor, komut çalıştırabiliyor. Ama neyin değişmesi gerektiğine, hangi kararın projeye uyduğuna ve sonucun gerçekten doğru olup olmadığına karar veren hâlâ sizsiniz.

Bu yazıda, böyle bir araçla web sitesi geliştirirken benim için neyin kritik olduğunu, hangi alışkanlıkların işe yaradığını ve hangi hataların sık yapıldığını toparlıyorum. Bu bir araç tanıtımı değil; çalışma yöntemi üzerine bir yazı. Araç değişse de yöntemin büyük kısmı geçerli kalıyor.

Benim için kritik olanlar

Claude Code gibi araçlarda benim için kritik olan şey, sadece bir prompt yazmak değil. Üç adımı birbirinden ayırarak düşünüyorum.

• Önce projenin yapısını anlamak.
• Sonra neyin değişmesi gerektiğini net tarif etmek.
• Sonrasında ortaya çıkan kodu test etmek.

Yani AI'ye “site yap” demek ile bir sistemi birlikte geliştirmek aynı şey değil. Birincisinde sonuç büyük ölçüde şansa kalıyor; ikincisinde ise her adımın bir sebebi ve bir kontrol noktası var. Aşağıda bu üç adımı tek tek açıyorum.

Önce projeyi anlamak

Bir araca iş vermeden önce projenin kendi içinde nasıl organize olduğunu bilmeniz gerekiyor. Hangi klasörde sayfalar duruyor, ortak stiller nerede, içerik nereden geliyor, derleme (build) adımı ne üretiyor, yayına giden dosyalar hangileri? Bu sorulara cevabınız yoksa aracın verdiği cevabı değerlendiremezsiniz; sadece kabul edersiniz ya da reddedersiniz, ikisi de kör karar olur.

Pratikte şu soruları kendime sorarım:

• Bu değişiklik hangi dosyaları ilgilendiriyor, hangilerine dokunmamalı?
• Aynı şey projede zaten başka bir yerde yapılmış mı? Yeni bir yapı kurmak yerine var olanı kullanmak daha tutarlı olmaz mı?
• Bu değişiklik derleme çıktısını, yani yayına giden dosyaları nasıl etkiler?
• Geri almak gerekirse nasıl alırım?

Son soru özellikle önemli. Sürüm kontrolü (Git gibi) kullanmak, araçla çalışırken neredeyse zorunlu bir güvenlik ağı. Her anlamlı adımdan önce temiz bir noktanız varsa, aracın yaptığı büyük bir değişikliği beğenmediğinizde dönebilirsiniz. Sürüm kontrolü olmadan, “biraz önce çalışıyordu” cümlesi çok pahalıya mal olur.

Proje yapısını anlamanın bir yan faydası daha var: araca verdiğiniz bağlam iyileşir. “Ana sayfadaki kart bileşeninin gölgesini azalt” demek ile “bir şeyler yap, daha hafif görünsün” demek arasında dağlar kadar fark var. İlki, aracın doğru dosyayı bulmasını ve doğru satırı değiştirmesini kolaylaştırır. İkincisi tahmine dayalı bir değişikliğe kapı açar.

Değişikliği net tarif etmek

İyi bir istek genellikle dört parçadan oluşur: neyi değiştirmek istiyorsunuz, nerede, hangi kurala uyarak ve bittiğinde nasıl anlayacaksınız. Bunu bir şablon gibi görmeyin, bir düşünme sırası olarak görün.

Belirsiz bir istek şöyle olur: “Blog sayfasını daha iyi yap.” Net bir istek ise şuna benzer: “Blog yazı sayfasında başlık altındaki meta satırı mobilde iki satıra taşıyor; küçük ekranlarda tek satırda kalacak şekilde boşlukları azalt, masaüstü görünümüne dokunma.” İkinci istekte sorun, konum, sınır ve beklenen sonuç var.

Net tarifin birkaç pratik kuralı var:

• Tek seferde tek konu. Aynı istekte hem navigasyonu hem form doğrulamasını hem de renk paletini değiştirmeyin. Hata çıktığında hangisinin sebep olduğunu ayırt edemezsiniz.
• Sınırları söyleyin. “Şu dosyaya dokunma”, “mevcut sınıf adlarını koru”, “yeni bağımlılık ekleme” gibi kısıtlar, aracın alanını daraltır ve beklenmedik yan etkileri azaltır.
• Başarı ölçütünü yazın. “Derleme hatasız bitsin”, “sayfa 375 piksel genişlikte yatay kaydırma çıkarmasın”, “mevcut bağlantılar bozulmasın” gibi doğrulanabilir cümleler iyi çalışır.
• Önce planı isteyin. Büyük bir değişiklikte aracın önce ne yapacağını anlatmasını isteyip onaydan sonra uygulatmak, yanlış yöne giden bir işi erkenden yakalamanızı sağlar.

Bu son madde bence en az kullanılan ama en çok işe yarayan yöntemlerden biri. Plan aşamasında bir yanlış anlama varsa, kod yazılmadan düzeltirsiniz. Kod yazıldıktan sonra düzeltmek hem daha uzun sürer hem de aracın bir önceki yaklaşıma yapışmasına yol açabilir.

Küçük, net ve test edilebilir adımlar

Küçük, net ve test edilebilir adımlar, büyük ve belirsiz isteklerden her zaman daha iyi sonuç veriyor. Bu cümle tek başına bir çalışma felsefesi.

Neden böyle? Çünkü büyük bir istek, aracı pek çok varsayım yapmaya zorluyor. Her varsayım küçük bir ihtimalle yanlış olabilir ve bu ihtimaller çarpılarak büyüyor. Küçük bir adımda varsayım sayısı az, sonucu kontrol etmek de kolay. Bir adımı doğrulayıp ilerlemek, sonunda büyük bir yığını tek seferde çözmeye çalışmaktan hem daha güvenli hem de çoğu zaman daha hızlı.

Basit bir örnek senaryo düşünelim. Diyelim ki bir sitede blog yazılarını markdown dosyalarından üretiyorsunuz ve etiket sayfaları eklemek istiyorsunuz. Tek bir istekte “etiket sistemi kur” demek yerine adımları bölebilirsiniz:

1. Mevcut yazı verisinde etiketlerin nasıl tutulduğunu araca okutup özetletin ve kendi anladığınızla karşılaştırın.

2. Etiketlerin listelenmesi için veri tarafını ekletin, çıktıyı kontrol edin.

3. Tek bir etiket sayfası şablonu oluşturtun, tarayıcıda bakın.

4. Yazı sayfalarından bu etiket sayfalarına bağlantı verdirin, bağlantıları tek tek tıklayarak test edin.

5. Site haritasına ve başlık/açıklama alanlarına etkisini kontrol edin.

Bu senaryo varsayımsal, ama ritmi gösteriyor: her adım küçük, her adımın bir doğrulaması var. Bir adımda sorun çıkarsa nerede çıktığını biliyorsunuz.

Teknik çalışma ortağı

Ben bunu daha çok teknik bir çalışma ortağı gibi düşünmeye başladım. Kendi sitem bunun iyi bir örneği: bir şeyin neden çalışmadığını birlikte inceliyoruz, ben hedefi ve görsel kararı veriyorum, araç uygulamayı hızlandırıyor, sonra sonucu tarayıcıda ben de kontrol ediyorum.

Bu iş bölümünü netleştirmek önemli. Hedefi, tasarım yönünü, “bu sayfa nasıl hissettirmeli” sorusunu ben belirliyorum; çünkü bunlar benim işimin ve markamın parçası. Aracın güçlü olduğu yer ise tekrarlı, mekanik ya da araştırma gerektiren işler: bir hatanın sebebini dosyalar arasında aramak, aynı değişikliği birçok yerde tutarlı yapmak, bir yapılandırma seçeneğini hatırlatmak.

Hata ayıklama (debugging) tarafında bu ortaklık özellikle değerli. Bir sorunu anlatırken kullandığım kalıp genelde şu: ne bekliyordum, ne oldu, hangi adımlarla tekrar ediliyor, konsolda ya da derleme çıktısında hangi mesaj var. Bu dört bilgi verildiğinde araç, tahmin etmek yerine somut bir şeyin üzerinde çalışabiliyor. “Çalışmıyor” demek ile hata mesajını ve beklenen davranışı yapıştırmak arasındaki fark, çoğu zaman tek seferde çözülen ile saatlerce dönen bir iş arasındaki fark.

Test etmeden bitti demek

Araç kod yazdı, derleme geçti. Bu, işin bittiği anlamına gelmiyor. Derleme geçmesi yalnızca kodun söz dizimsel olarak geçerli olduğunu söyler; sayfanın doğru göründüğünü, bağlantıların çalıştığını, mobilde bozulmadığını söylemez.

Benim kontrol alışkanlığım şöyle:

• Sayfayı gerçekten tarayıcıda açmak, yalnızca kod farkına (diff) bakmakla yetinmemek.
• Dar bir ekran genişliğinde, örneğin telefon boyutunda, yatay taşma olup olmadığına bakmak.
• Tıklanabilir her şeyi bir kez tıklamak: menüler, bağlantılar, düğmeler.
• Tarayıcı konsolunda hata ya da uyarı çıkıp çıkmadığına bakmak.
• Değişikliğin dokunmaması gereken sayfaları etkileyip etkilemediğini birkaç sayfada kontrol etmek.
• Yayına gidecek çıktıyı (build sonrası dosyalar) bir kez açıp bakmak; geliştirme ortamında çalışan şey üretimde farklı davranabilir.

Bu listenin çoğu beş dakikalık işler. Ama atlandığında, yayına çıkmış bir sayfada kırık bir bağlantı ya da bozuk bir mobil görünüm olarak geri dönüyor. Kontrol konusuna daha geniş bakan AI ile üretirken neden güvenmemek gerekiyor yazımda farklı alanlardan örnekler topladım.

Sık yapılan hatalar

Araçla çalışırken gördüğüm ve kaçınmaya çalıştığım hataları şöyle sıralayabilirim:

• Aşırı geniş istek. “Bütün siteyi yeniden tasarla” gibi istekler, kontrol edilemez büyüklükte bir fark (diff) üretir. Gözden geçirilemeyen değişiklik, kabul edilmemesi gereken değişikliktir.
• Çıktıyı okumadan kabul etmek. Araç bir dosyayı baştan yazdığında ya da gereksiz bir bağımlılık eklediğinde bunu fark etmek için farkı okumak gerekir.
• Hata mesajını paylaşmamak. Aracın tahmin yürütmesine sebep olur; tahmin ise gerçek sebebi kaçırabilir.
• Çalışan kodu gereksiz yere “iyileştirtmek”. Sorunsuz çalışan bir bölümü temizlik amacıyla yeniden yazdırmak, görünmeyen yan etkiler doğurabilir. Bozuk olmayan şeye dokunmamak çoğu zaman en iyisi.
• Gizli bilgileri paylaşmak. Anahtarlar, parolalar ve erişim bilgileri; projede ya da istekte açık metin olarak durmamalı. Bunların ayrı bir yapılandırmada ve sürüm kontrolü dışında tutulması genel bir güvenlik pratiği.
• Bir hatayı iki kez aynı yöntemle düzeltmeye çalışmak. Araç aynı çözümü tekrar üretiyorsa sorun sizin tarifinizdedir; yeni bilgi ekleyin ya da problemi başka bir açıdan anlatın.
• Performansı unutmak. Kod işlevsel olarak doğru olup sayfayı ağırlaştırabilir. Özellikle 3D içerik taşıyan sitelerde bu önemli; bu konuyu 3D web sitesinde tasarım ile performans dengesi yazısında ele aldım.

Direksiyon bende

Ama direksiyon hâlâ bende olmalı. Neyi neden değiştirdiğini anlamadığım bir sistemi üretime göndermek istemem. Bunun pratik bir karşılığı var: araç bir şey yaptığında “bu neden böyle yapıldı?” diye sorabiliyorum, cevap aklıma yatmıyorsa kabul etmiyorum. Cevabı anlamadan kabul etmek, bir sonraki hatada elimde ipucu olmaması demek.

Bu yüzden öğrenme tarafını da bırakmıyorum. Üretilen kodu okumak, bilmediğim kavramı not alıp ayrıca araştırmak, küçük deneyler yapmak... Kod öğrenme ve anlama tarafını Codex yazımda anlattım; iki yazı birbirini tamamlıyor: biri üretim sürecinin kontrolü, diğeri bu sürecin içinde kendi anlayışını büyütmek hakkında.

Direksiyonu elde tutmanın bir başka boyutu karar sorumluluğu. Bir siteyi yayına almak, bir müşteriye ya da ziyaretçiye karşı verilmiş bir söz. “Araç öyle yazmıştı” bir mazeret değil. Kimin hangi kararı verdiğini net tutmak, hem kaliteyi hem de güveni korur.

Kişisel siteyle birlikte büyüyen süreç

Bu yöntemin bir güzel yanı da zamanla birikmesi. Her proje, bir sonrakine yön gösteren notlar, kalıplar ve kontrol listeleri bırakıyor. Kendi siteme neden yatırım yaptığımı kişisel web sitemi neden geliştirdiğim yazısında anlatıyorum; siteyi bir deney alanı gibi kullanmak, araçlarla çalışma yöntemimi de olgunlaştırıyor. Ayrıca bu notların kalıcı bir arşive dönüşmesi fikri web sitesini dijital arşive dönüştürmek yazısının konusu.

3D tarafında da benzer bir mantık var: yapay zekâyı nerede kullandığımı ve nerede kullanmadığımı 3D çalışmalarda yapay zekâ kullanımı yazısında anlattım. Orada da kural aynı: hız için kullanıyorum, kalite kararını elimden bırakmıyorum.

Kendi iş akışınıza uyarlamak için kontrol listesi

Aşağıdaki liste, araçla yapılacak bir işe başlarken ve bitirirken göz atabileceğiniz kısa bir çerçeve. Kendi projenize göre uyarlayın.

Başlarken:

• Projenin güncel bir yedeği ya da temiz bir commit'i var mı?
• Değişikliğin amacını tek cümleyle yazabiliyor muyum?
• Dokunulmaması gereken dosyaları ve kuralları belirttim mi?
• Büyük bir iş ise önce plan istedim mi?

Çalışırken:

• Her adımda fark (diff) okunabilir boyutta mı?
• Beklemediğim bir dosya değişti mi, yeni bağımlılık eklendi mi?
• Anlamadığım bir şey var mı? Varsa araca açıklattım mı?

Bitirirken:

• Derleme ve varsa testler hatasız mı?
• Tarayıcıda, masaüstünde ve dar ekranda baktım mı?
• Bağlantılar, formlar, menüler çalışıyor mu?
• Konsolda hata var mı?
• Değişiklik beklemediğim bir sayfayı etkiliyor mu?
• Anlamlı bir mesajla kaydettim mi, geri dönüş noktası hazır mı?

Sık sorulan sorular

Sonuç

Claude Code gibi araçlar üretimi hızlandırıyor, bunda tereddüt yok. Ama hızın değeri yönün doğruluğuna bağlı: projeyi anlamak, değişikliği net tarif etmek ve sonucu test etmek bu yönü belirleyen üç ayak. Küçük adımlar, net sınırlar, gerçek cihazda kontrol ve “neden böyle?” sorusunu sorma alışkanlığı, aracın gücünü kontrol kaybetmeden kullanmanın yolu.

AI hız kazandırıyor. Ama kontrol sende değilse o hız bazen sadece hataya daha hızlı ulaşmak anlamına geliyor.