Claude Code ile Gerçek Projede Çalışmak: Explore → Plan → Code → Commit

Claude Code Nedir, Sohbet Botundan Farkı Ne?

Claude Code, terminalde (ve VS Code, JetBrains, masaüstü uygulaması ya da web üzerinde) çalışan bir agentic kodlama aracı. Kod parçası yapıştırıp cevap beklediğiniz bir sohbet penceresinden farkı şu: dosyalarınızı kendisi okuyor, komut çalıştırıyor, değişiklik yapıyor ve sonucu kontrol ediyor.

Bunu mümkün kılan şey agentic döngü: model bir adım planlar, bir araç çağırır (dosya oku, komut çalıştır, düzenle), sonucu görür ve bir sonraki adıma karar verir. Ne kadar ileri gidebileceğini ise izinler belirler. Hangi komutları sormadan çalıştırabileceğine siz karar verirsiniz.

Explore → Plan → Code → Commit

Claude Academy'deki Claude Code 101 kursunun omurgası bu dört adımlık akış. Kendi projelerimde de en çok fark yaratan alışkanlık bu oldu.

1. Explore: Önce kodu okut

Doğrudan "şu özelliği ekle" demek yerine, ilgili kodu önce okutun. Örneğin bu sitede sertifikalar sayfasını eklerken ilk iş header'ın nav linklerini nereden aldığına, mevcut bir sayfanın (yasal sayfalar) hangi layout bileşenlerini kullandığına ve sitemap'in nasıl üretildiğine baktırdım. Böylece yeni sayfa, sıfırdan bir tasarım yerine mevcut LegalPageShell bileşenini kullandı.

> Header'daki menü linkleri nereden geliyor? Yeni bir sayfa eklersem
  sitemap'e de girmesi için neyi değiştirmem gerekir? Henüz kod yazma.

2. Plan: Plan Mode ile önce yol haritası

Plan Mode'da Claude dosyaları okuyabilir ama değiştiremez. Size bir plan sunar, onaylamadan hiçbir şey yazmaz. Birden fazla dosyaya dokunacak işlerde yanlış yöne giden bir uygulamayı en başta yakalamanın en ucuz yolu bu.

• Hangi dosyalar değişecek?
• Yeni bir veri dosyası mı, mevcut yapıya ekleme mi?
• Neyi bilerek yapmıyoruz?

3. Code: Küçük, doğrulanabilir adımlar

Plan onaylandıktan sonra uygulama başlar. Burada önemli olan, Claude'un yaptığı işi kendisinin doğrulayabilmesi: tip kontrolü (tsc --noEmit), lint, testler ya da tarayıcıda sayfayı açıp bakmak. "Bitti" demeden önce bir doğrulama adımı istemek, hatalı kodun size ulaşmasını büyük ölçüde azaltır.

4. Commit: Son söz sizde

Değişiklikleri diff üzerinden gözden geçirip commit etmek size kalmalı. Claude commit mesajını yazabilir, ama neyin neden değiştiğini anladığınızdan emin olun. Agentic araçlarda en büyük risk, anlamadığınız bir kodun ana dala girmesi.

Kurulum ve Çalışma Modları

Claude Code'u terminalde, VS Code ve JetBrains eklentileriyle, Claude masaüstü uygulamasında ya da web'de kullanabilirsiniz. Hangi ortamda olursanız olun, onay davranışı üç moddan biridir:

Context Yönetimi: Uzun Oturumları Hızlı Tutmak

Claude'un her oturumda bir context window'u var: okuduğu dosyalar, komut çıktıları ve konuşmanın tamamı burada birikir. Dolmaya yaklaştıkça hem yavaşlar hem de odak dağılır. Üç komut işinizi görür:

• /context: context'in neyle dolduğunu gösterir.
• /compact: konuşmayı özetleyip yer açar; aynı işe devam ederken kullanın.
• /clear: sıfırdan başlar; ilgisiz yeni bir işe geçerken kullanın.

Pratik kural: bir görev bitti ve başka bir konuya geçiyorsanız /clear. Önceki işin kalıntıları yeni işte kafa karıştırır.

CLAUDE.md: Projenin Kalıcı Hafızası

Her oturum sıfırdan başlar; Claude dünkü konuşmayı hatırlamaz. Projeye özgü kuralları her seferinde tekrar anlatmak yerine kök dizine bir CLAUDE.md koyarsınız ve her oturumun başında otomatik okunur.

# CLAUDE.md

- Next.js 16 kullanıyoruz; eski API'ler için node_modules/next/dist/docs'a bak.
- Yeni sayfalar src/app/(frontend) altına; mevcut layout bileşenlerini kullan.
- Commit etmeden önce: npx tsc --noEmit && npm run lint
- Görseller public/ altında WebP olarak; site statik export ile yayınlanıyor.

İyi bir CLAUDE.md kısa olur ve koddan çıkarılamayan bilgiyi taşır: neden böyle yaptığımız, hangi tuzaklara düştüğümüz, hangi komutların doğrulama için çalıştırılacağı.

Subagent'lar: İşi Böl, Context'i Temiz Tut

Bir subagent, kendi context'iyle çalışan ve ana oturuma sadece sonucu döndüren yardımcı bir ajandır. "Bu kod tabanında X'i kullanan tüm yerleri bul" gibi çok dosya okumayı gerektiren bir arama ana context'i doldurur. Aynı işi bir subagent yaparsa ana oturuma yalnızca bulduğu dosya listesi gelir.

Kod review, test yazma veya doküman tarama gibi tekrar eden işler için kendi subagent'larınızı tanımlayabilirsiniz.

Skills, MCP ve Hook'lar

• Skills: Sık tekrarladığınız bir iş akışını (örneğin "yeni blog yazısı ekle") talimatlar ve yardımcı dosyalarla paketler. Claude ilgili işte bunu kendisi yükler.
• MCP (Model Context Protocol): Claude'u dış sistemlere bağlar: issue takip araçları, veritabanları, tasarım araçları, iç dokümanlar.
• Hook'lar: Belirli olaylarda her zaman çalışan komutlardır. Modelin hatırlamasına güvenmek yerine kuralı garantiye alırsınız.

Hook'lar özellikle değerli, çünkü deterministik. Örneğin her dosya düzenlemesinden sonra formatlayıcıyı çalıştırmak:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ]
  }
}

Hook, çağrılan aracın bilgisini stdin'den JSON olarak alır; burada jq ile düzenlenen dosyanın yolunu çekip Prettier'a veriyoruz. Aynı mekanizmayla tehlikeli komutları engelleyebilir ya da uzun bir iş bittiğinde bildirim alabilirsiniz.

Sık Yapılan Hatalar

• Keşif yapmadan kod istemek: Claude projenizdeki mevcut bileşeni bilmezse yenisini yazar.
• Doğrulama istememek: "Tip kontrolünü ve lint'i çalıştır, sonra bitti de" demek küçük bir cümle ama büyük fark yaratır.
• Tek oturumda her şeyi yapmak: İlgisiz işler arasında /clear kullanmamak context'i kirletir.
• Diff okumadan commit: Hız kazandırır, ama ana dala anlamadığınız kod girer.

Sonuç

Claude Code'u verimli kullanmanın sırrı daha iyi prompt yazmaktan çok, iyi bir mühendislik sürecini ona da uygulamak: önce anla, sonra planla, küçük adımlarla uygula, doğrula ve gözden geçirerek commit et. CLAUDE.md, subagent'lar ve hook'lar bu süreci her oturumda tekrarlanabilir hale getiriyor.

Bu yazıdaki iş akışı, Claude Academy'deki Claude Code 101 kursundan ve bu siteyi geliştirirken edindiğim deneyimden derlendi.