İçeriğe geç

Claude Code ile ilk projeni nasıl kurarsın?

Hasan Çelik Yayın: Güncelleme: Yazılım & AI 6 dakika okuma

Claude Code terminalde çalışan bir yapay zekâ geliştirme aracıdır. İlk projeyi kurmak için önce hedefi tek cümleyle yazarsın, sonra planı onaylatırsın, ardından küçük adımlarla kod ürettirip her adımı test ettirirsin. Bu döngü gerçek bir örnekle, komutlarıyla ve sık yapılan hatalarıyla anlatılır; örnekler bu sitenin kendi kurulum oturumundan alınmıştır.

Claude Code nedir ve nasıl kurulur?

Claude Code, Anthropic’in terminalde çalışan yapay zekâ geliştirme aracıdır: proje klasörünü okur, plan önerir, onayınla dosya düzenler ve komut çalıştırır. Kurulum tek komuttur; ardından proje klasöründe claude yazarak oturum açarsın. İlk oturumda aracın ne yapacağını değil, senin ne istediğini yazman gerekir; kurulumun geri kalanı bu alışkanlığı oturtmaktır.

Terminal merkezli bir araçla çalışmanın en somut avantajı, kod yazma eylemini editör penceresinden çıkarıp projenin derleyicisi, paket yöneticisi ve test koşucusuyla aynı düzleme taşımasıdır. 2000 yılından bu yana yazılımda mimari kararlar alıyorum; önce .NET ve SQL, sonra Java, Python ve TypeScript ile. Geliştirme araçları metin tamamlama seviyesinden bağlamı anlayan ajan seviyesine evrilirken aradığım temel nitelik hiçbir zaman sihirli şekilde kod yazması olmadı. Aradığım şey, projenin mevcut kurallarını okuyan, dosya ağacını tarayabilen ve yazdığı kodu aynı komut satırında derleyip sınayabilen bir çalışma arkadaşıydı. Claude Code bu boşluğu dolduruyor.

Kurulum için Node.js ortamınızın hazır olması gerekir. Terminalinizi açıp aracı tek bir npm komutuyla sisteminize eklersiniz:

npm install -g @anthropic-ai/claude-code

Kurulum bittikten sonra çalışmak istediğiniz boş bir klasör oluşturup o dizine geçersiniz:

mkdir ilk-projem && cd ilk-projem
git init
claude

İlk kez claude çalıştırdığınızda tarayıcınız açılır ve Anthropic hesabınızla oturum açmanız istenir. Yetkilendirme tamamlandıktan sonra terminalde Claude Code karşılama ekranını görürsünüz. Bu aşamada acele edip araca hemen kod yazdırmaya çalışmak yerine, projenin sınırlarını çizmeye odaklanmalısınız. Yazılım & AI bölümündeki tüm içeriklerde vurguladığım gibi, bir ajana verilecek ilk komut doğrudan kod üretimi değil, bağlamın ve hedefin inşası olmalıdır.

Bu sitenin deposundaki ilk commit 25 Eylül 2026 tarihli bir tasarım spesifikasyonudur; uygulama planları ve ilk kod commit’i (Astro iskeleti) ertesi gün, bu sırayla geldi.

İlk komut ne olmalı: hedefi nasıl yazarsın?

İlk komut, projenin nihai amacını, teknik yığınını ve taviz verilmeyecek kısıtlarını tek bir net paragrafta özetlemelidir. “Bana bir blog sitesi yap” gibi ucu açık ifadeler yerine, hangi çerçevenin kullanılacağını, verilerin nerede saklanacağını ve hangi komutla test edileceğini belirten somut bir çerçeve çizilmelidir. Kısıtları baştan belirtmek, modelin varsayımlarla yanlış kütüphaneler seçmesini ve gereksiz bağımlılıklar yüklemesini engeller.

Örneğin hasancelik.com gibi kişisel bir site kurarken ilk komut şöyle olabilir:

Astro 7 ve TypeScript kullanarak statik bir kişisel site kuracağız. 
Tasarım Tailwind CSS ile yapılacak. İçerik koleksiyonları MDX formatında olacak. 
Sitenin kendi istemci tarafı JavaScript kodu bulunmayacak; yalnızca tek bir küçük tema betiği yer alacak. 
Her değişiklik `pnpm verify` komutuyla (astro check, build, test) doğrulanacak. 
Şimdi bana proje iskeletini kurmak için bir plan öner. Henüz kod yazma.

Bu komuttaki her cümlenin bir görevi vardır:

  1. Teknik yığın: Astro, TypeScript, Tailwind CSS. Model başka bir araç aramaz.
  2. Kısıt: İstemci tarafında ağır JavaScript kütüphaneleri yasak; yalnızca tema betiği var.
  3. Doğrulama kriteri: pnpm verify komutu sıfır hatayla bitecek. Model başarıyı kendi kafasına göre değil, bu komutun çıktısına göre ölçecek.
  4. Fren mekanizması: “Henüz kod yazma, plan öner.” Bu cümle, modelin kontrolsüzce dosya üretmesini önler.

Kısıt belirtmediğinizde yapay zekâ en popüler veya en kolay yolu seçer. Popüler yol çoğu zaman sizin projenizin ihtiyaç duyduğu yalınlıkla uyuşmaz. Projenin mimarı sizsiniz; Claude Code ise verdiğiniz teknik kararları disiplinle uygulayan bir geliştiricidir.

Plan onayı neden zorunlu?

Plan onayı, geliştirici ile model arasındaki mutabakat zeminidir ve yanlış yönde ilerleyen yüzlerce satır kodu çöpe atmaktan çok daha ucuzdur. Claude Code plan modundayken dosyalarda değişiklik yapmaz; yalnızca atacağı adımları, oluşturacağı dosyaları ve çalıştıracağı komutları listeler. Bu aşamada mimariyi gözden geçirmek, gereksiz karmaşıklığı budamak ve test yaklaşımını netleştirmek geliştiricinin asli görevidir.

Claude Code varsayılan olarak planlama yeteneğine sahiptir. Karmaşık bir istek aldığında veya siz açıkça plan istediğinizde bir düşünme sürecine girer ve adım adım bir yol haritası sunar. Bu yol haritası terminalinizde görüntülendiğinde önünüzde üç seçenek vardır:

  • Onaylamak: Plan beklentinize tam uyuyorsa onay verip ilk adımın uygulanmasını başlatırsınız.
  • Düzeltme istemek: Plana itiraz edip üçüncü adımda harici bir paket kurmak yerine yerel bir yardımcı fonksiyon yazalım diyebilirsiniz.
  • Reddetmek: Yaklaşım tamamen yanlışsa planı iptal edip bağlamı yeniden tanımlarsınız.

Yazılım geliştirme tecrübem bana şunu öğretti: Üretim ortamında çalışan sistemlerde zamanın çoğu kod yazmaya değil, yanlış yazılmış kodu temizlemeye ve hatalı mimarileri düzeltmeye harcanır. Plan onayını zorunlu tutmak, bu zaman kaybını azaltır. Plan aşamasında yapılan iki dakikalık bir yönlendirme, ileride saatlerce sürecek bir yeniden yazım zahmetini önler.

Küçük adımlar ve test döngüsü nasıl işler?

Claude Code ile çalışırken en verimli tempo, her adımı tek bir göreve odaklamak ve her adımdan sonra otomatik testleri çalıştırmaktır. Bir kerede hem veri şemasını hem arayüzü hem de bülten servisini kurmasını istemek yerine; önce şemayı tanımlatıp test ettirmek, ardından sonraki bileşene geçmek gerekir. Küçük adımlar hata payını daraltır ve geriye dönüp sorun aramayı kolaylaştırır.

Bu döngüyü dört temel halkadan oluşan bir zincir olarak düşünebilirsiniz:

  1. Tek bir görev tanımla: Örneğin, içerik koleksiyonları için Zod şemasını src/content.config.ts dosyasına yaz.
  2. Uygulamayı izle: Claude Code dosyayı oluşturur veya düzenler, diff’i size gösterir.
  3. Testi çalıştır: Claude Code’a hemen test komutunu koşturun: pnpm test veya pnpm check.
  4. Git ile sabitle: Test yeşil yandığı anda temiz bir commit atın: git commit -m "feat(content): içerik şeması tanımlandı".
// Küçük adım örneği: Minimal ve doğrulanabilir bir şema tanımı
import { defineCollection, z } from 'astro:content';

export const yazilar = defineCollection({
  schema: z.object({
    title: z.string().max(70),
    pubDate: z.date(),
    shortAnswer: z.string().min(50).max(300),
  }),
});

Eğer test kırmızıya dönerse, Claude Code hatayı terminal çıktısından doğrudan okur. Ona bu hatayı düzelt demeniz yeterlidir. Hatanın kapsamı tek bir dosya ve tek bir işlevle sınırlı olduğu için model sorunu birkaç saniye içinde çözer. Büyük adımlarda ise birden fazla hata birbirine karışır ve bağlam penceresi gereksiz loglarla dolar.

En sık yapılan üç hata nedir?

Claude Code kullanırken karşılaşılan en yaygın üç hata; bağlamı devasa dosya yığınlarıyla doldurmak, test yazmadan yalnızca üretime odaklanmak ve talimatları sözlü bırakıp kalıcı kurallara dönüştürmemektir. Bu üç hata, başlangıçta hızlı ilerleniyor gibi görünse de birkaç oturum sonra aracın tutarsızlaşmasına ve projenin kontrolünün kaybolmasına neden olur.

İlk hata, projeyle ilgisiz yüzlerce dosyayı bağlama dahil etmektir. Bir klasörde gereksiz yere binlerce satırlık dokümanı veya derleme çıktılarını tutarsanız, modelin dikkat penceresi dağılır. İkinci hata, test otomasyonunu ertelemektir. Testi olmayan bir projede yapay zekâ bir yeri düzeltirken diğer yeri bozabilir ve bunu fark edemezsiniz. Üçüncü hata ise oturum boyunca modele sürekli aynı kuralları sözlü olarak hatırlatmaktır. Her oturumda Türkçe yaz, girintiyi iki boşluk yap, şu paketi kullanma demek yerine bu kuralları projenin kökündeki talimat dosyasına yazmalısınız.

Yapay zekâ araçları birer orkestra şefi değil, sizin şefliğinizde çalan virtüözlerdir. Baget sizde olduğu sürece sonuç tutarlı, öngörülebilir ve temiz olur.

Kaynaklar

Anahtar çıkarımlar

  • Önce hedef ve kısıtlar yazılır, kod sonra gelir.
  • Plan onayı olmadan üretim başlamaz.
  • Her adımda test; büyük değişiklik tek seferde yapılmaz.

Sık sorulan sorular

Claude Code ücretsiz mi?

Hayır. Claude Code ücretli bir Claude aboneliği ya da API kredisiyle çalışır; küçük projeler için aylık plan çoğu zaman yeterlidir ve maliyet kullanımla ölçeklenir. Plan adları ve fiyatlar sık değiştiği için kurulumdan önce Anthropic'in güncel fiyat sayfasına bakın.

Birlikte Çalışalım Projeler