Claude Code'a Giriş: Kurulum, İlk Session ve Agentic Loop'u Anlamak

Sürüm notu: Bu yazı Claude Code 2.1.325'i (13 Kasım 2026) anlatır; kurulum, giriş ve komut bilgileri 15 Kasım 2026'da code.claude.com/docs'taki Advanced setup, Quickstart, Authentication ve How Claude Code works sayfalarından kontrol edilmiştir. Bu yazıda resmî belgelerden yararlanılmıştır. Komutlar Windows 11 ve PowerShell için verilmiştir; Claude Code haftada birkaç sürüm çıkardığı için ekranındaki ayrıntılar biraz farklı olabilir.

Önce Tahmin Et

Emre, sitedeki serilerin ortak örnek uygulaması Bookstore'da (bir online kitapçı) çalışan bir backend developer. Bir akşam evde Claude Code'u kurdu, kendi Pro hesabıyla giriş yaptı ve ertesi sabah şirket laptop'ında aynı hesapla Bookstore repo'sunu açtı. İlk prompt'u iddialıydı: "Ordering module'ünü baştan CQRS'e (Command Query Responsibility Segregation; okuma ve yazma modelini ayıran yaklaşım) çevir." Claude Code yarım saat boyunca onlarca dosyayı değiştirdi ve sonunda "testler geçiyor" dedi. Emre testleri kendisi çalıştırmadan değişiklikleri commit'ledi. Laptop'ta Git for Windows kurulu değildi.

Tahminin ne? Bu üç karardan hangisi en pahalıya patlar: kişisel hesapla şirket repo'suna girmek mi, ilk iş olarak dev bir refactor istemek mi, yoksa "testler geçiyor" cümlesini doğrulamadan kabul etmek mi? Ve Git for Windows olmayan bir makinede Claude Code komutları hangi shell'de çalıştırır? İlk sorunun cevabı giriş bölümünde, ikincisininki kurulum bölümünde.

Bu seri Claude Code'u kurulumdan ekip kullanımına kadar anlatıyor: CLAUDE.md ve memory, permission mode'ları, plan mode, skill'ler, subagent'lar, hook'lar, MCP (Model Context Protocol; agent'ların dış araç ve veri kaynaklarına bağlandığı açık protokol) server'ları, paralel session'lar, CI, plugin'ler, Agent SDK ve maliyet. Araçtan bağımsız AI destekli geliştirme pratiği AI Destekli Geliştirme serisinde, Claude'un web ve masaüstü uygulamaları Claude ile Çalışmak serisinde, aynı işin Copilot karşılığı da GitHub Copilot serisinde anlatıldı. Burada yalnız Claude Code'a özgü olanı göreceğiz ve gerektiğinde o serilere döneceğiz.

Claude Code Nedir?

Resmî belgeler Claude Code'u codebase'i okuyan, dosya düzenleyen, komut çalıştıran ve geliştirme araçlarınla birleşen agentic bir coding aracı olarak tanımlıyor. Kilit kelime "agentic". Editörde imlecin olduğu yere öneri getiren inline completion'dan farklı olarak Claude Code bir hedef alır, o hedef için hangi dosyaları okuyacağına, hangi komutu çalıştıracağına ve sonucu nasıl doğrulayacağına kendisi karar verir. Bir bug için ilgili dosyaları arar, birden fazla dosyada koordineli değişiklik yapar, testleri çalıştırır ve istersen commit atar.

Belgelerde sık geçen bir terim de harness. Modelin kendisi yalnız metin üretir; onu dosya okuyan ve komut çalıştıran bir agent'a çeviren şey, tool'ları sağlayan ve modelin gördüğü context'i yöneten katmandır. Claude Code tam olarak bu katman. Terminalde, Visual Studio Code (VS Code) ve JetBrains eklentilerinde, Claude Desktop'taki Code sekmesinde ve claude.ai/code'daki cloud session'larda aynı motor çalışıyor; bu yüzden repo'daki CLAUDE.md, ayarlar ve MCP server'ları tüm yüzeylerde geçerli.

GitHub Copilot serisini okuduysan benzerlikleri hemen göreceksin: Copilot'ın IDE'deki agent'ı ve Copilot CLI de aynı döngüyle çalışıyor. Fark daha çok çıkış noktasında. Copilot editörden ve GitHub.com'dan başlayıp terminale geldi; Claude Code terminalden başladı ve IDE'ye, masaüstüne, web'e yayıldı. Bu yüzden bu seride ağırlık terminalde olacak, diğer yüzeyleri dokuzuncu yazıda toplu olarak ele alacağız.

Kurulum: Windows'ta Hangi Yol?

Belgelere göre Claude Code Windows 10 1809 ve sonrası ile Windows Server 2019 ve sonrasında çalışıyor; en az 4 GB RAM ve x64 ya da arm64 işlemci istiyor, internet bağlantısı şart. Kurulum için yönetici yetkisi gerekmiyor. Önerilen yol, PowerShell'de ya da Komut İstemi'nde (CMD) çalışan native installer:

# PowerShell'de (istem satırı "PS C:\..." ile başlar)
irm https://claude.ai/install.ps1 | iex

# Komut İstemi'nde (CMD) aynı iş
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# Alternatif: WinGet
winget install Anthropic.ClaudeCode

# Kurulumdan sonra YENİ bir terminal penceresinde
claude --version
claude doctor

Belgeler iki yaygın karışıklığı özellikle not ediyor. PowerShell'de CMD komutunu yapıştırırsan The token '&&' is not a valid statement separator hatası alırsın; CMD'de PowerShell komutunu çalıştırırsan 'irm' is not recognized görürsün. Installer ilerleme göstermiyor, bitince yeni bir pencere açman gerekiyor. claude --version sürüm numarasının yanına (Claude Code) yazar; claude bulunamıyorsa kurulum klasörü (native kurulumda %USERPROFILE%\.local\bin) henüz PATH'te değildir. claude doctor ise session açmadan kurulum sağlığını, ayar dosyalarındaki hataları ve son güncelleme denemesinin sonucunu salt okuma olarak gösterir.

Tahmindeki ikinci sorunun cevabı burada. Native Windows'ta Git for Windows kuruluysa Claude Code Bash tool'unu Git Bash üzerinden çalıştırır; kurulu değilse shell komutları için PowerShell tool'unu kullanır. Git for Windows belgelerde opsiyonel ama önerilen olarak geçiyor; Bash tool'u ve arka plan çıktısını izleyen Monitor tool'u Git Bash'e ihtiyaç duyuyor. Bunun pratik sonucu üçüncü yazıda karşımıza çıkacak: Bash(dotnet test *) gibi bir izin kuralı PowerShell tool'unu kapsamıyor, onun için PowerShell(...) kuralı yazmak gerekiyor.

Tablodaki üçüncü yol WSL (Windows Subsystem for Linux; Windows içinde Linux dağıtımı çalıştıran katman). WSL 2 içinde Linux installer'ı çalıştırıp claude'u WSL terminalinden açarsın. Belgelere göre komutları işletim sistemi seviyesinde sınırlayan sandbox native Windows'ta desteklenmiyor, WSL 2'de destekleniyor. Bookstore gibi Visual Studio ve SQL Server ile Windows'ta geliştirilen bir repo için native kurulum doğal tercih; sandbox'ı üçüncü yazıda konuşacağız.

Native kurulum varsayılan olarak latest kanalını izler: her sürüm çıktığı anda gelir. Ekipte herkesin aynı davranışı görmesi önemliyse stable kanalı yaklaşık bir hafta geriden gelir ve ciddi regression içeren sürümleri atlar. Kanalı /config içinden ya da kullanıcı ayar dosyasından (%USERPROFILE%\.claude\settings.json) seçersin; mevcut sürümün altına düşmemek için minimumVersion da verilebilir:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.325"
}

Giriş: Hangi Hesapla?

Claude Code ücretsiz claude.ai planında yok. Pro, Max, Ultra, Team ya da Enterprise aboneliği, faturası kullanım başına kesilen bir Claude Console hesabı ya da Amazon Bedrock, Google Cloud ve Microsoft Foundry gibi bir bulut sağlayıcı gerekiyor. İlk claude çalıştırmasında tarayıcı açılır, girişten sonra terminalde Login successful görürsün. Console hesabıyla ilk girişte Console'da maliyet takibi için "Claude Code" adlı bir workspace otomatik açılıyor. Plan fiyatları ve usage limit'leri Claude ile Çalışmak serisinin ilk yazısında; aynı abonelik Claude uygulamalarıyla Claude Code'u birlikte kapsıyor.

Tahmindeki ilk sorunun cevabı da burada: Emre'nin en pahalı hatası kişisel hesapla şirket repo'suna girmekti. Refactor geri alınabilir, test yeniden çalıştırılabilir; ama şirket kodu artık şirketin yönetici ayarlarının, veri politikasının ve faturasının dışındaki bir hesaptan modele gitti. Team ve Enterprise planlarında yönetici, organizasyon genelinde ayar dağıtabiliyor ve girişin belirli bir organizasyona ait olmasını zorunlu tutabiliyor; kişisel Pro hesabı bunların hiçbirini kapsamıyor. Şirket repo'sunda şirketin verdiği hesapla çalış.

İki hesabı aynı makinede kullanman gerekiyorsa belgelerin önerisi her hesaba ayrı bir configuration klasörü vermek. CLAUDE_CONFIG_DIR ortam değişkeni ayarları, session geçmişini ve girişi o klasöre taşıyor. PowerShell profiline şöyle bir fonksiyon eklenebilir:

# $PROFILE içine: iş hesabı ayrı bir klasörde dursun
function claude-work {
    $previous = $env:CLAUDE_CONFIG_DIR
    $env:CLAUDE_CONFIG_DIR = Join-Path $HOME ".claude-work"
    try { claude @args } finally { $env:CLAUDE_CONFIG_DIR = $previous }
}

Bir tuzak daha var: kimlik bilgileri bir öncelik sırasıyla seçiliyor. Ortamında ANTHROPIC_API_KEY tanımlıysa ve Claude Code'un sorduğu soruya onay verdiysen, aboneliğin yerine o API key kullanılır ve fatura Console'a yazılır; claude -p ile çalışan non-interactive modda ise key varsa sormadan kullanılır. Hangi kimliğin aktif olduğunu session içinde /status gösterir. Hesap değiştirmek için /login, çıkmak için /logout var. Windows'ta giriş bilgisi %USERPROFILE%\.claude\.credentials.json dosyasında, kullanıcı profilinin erişim haklarıyla korunarak duruyor.

Agentic Loop: Claude Code Bir İşi Nasıl Yapar?

Belgeler döngüyü üç aşamayla anlatıyor: context toplamak, işlem yapmak ve sonucu doğrulamak. Bu aşamalar birbirine karışıyor; Claude her adımda bir tool çağırıyor, sonucu okuyor ve sıradaki adıma o sonuca göre karar veriyor. Codebase hakkında bir soru yalnız ilk aşamayı gerektirebilir, bir bug fix üç aşamayı defalarca dolaşır.

Tool'lar beş grupta toplanıyor: dosya işlemleri (okuma, düzenleme, oluşturma), arama (dosya adı pattern'i ve regex ile içerik araması), çalıştırma (shell komutu, test, git), web (arama ve doküman çekme) ve code intelligence (düzenlemeden sonra tip hatalarını görmek; bunun için ayrı plugin gerekiyor). Bunlara subagent başlatmak ve sana soru sormak gibi koordinasyon tool'ları ekleniyor. Claude Code'u bir dizinde açtığında Claude o dizindeki ve altındaki dosyalara, terminalde senin çalıştırabildiğin her komuta, git durumuna (branch, commit edilmemiş değişiklikler, son commit'ler), CLAUDE.md dosyalarına ve kendi tuttuğu auto memory notlarına erişiyor.

Sen de döngünün içindesin. Esc çalışan tool çağrısını keser ve Claude yeni talimatını bekler. Claude çalışırken bir düzeltme yazıp Enter'a basarsan mesajın queue'ya alınır; Claude elindeki tool çağrıları bitince aynı turda okur ve yönünü değiştirir. Dosya düzenlemeleri de geri alınabilir: Claude bir dosyayı düzenlemeden önce mevcut hâlinin kopyasını alıyor ve boş prompt'ta Esc'e iki kez basmak geri alma menüsünü açıyor. Checkpoint'lerin ayrıntısı dördüncü yazıda; şimdilik bilmen gereken, veritabanı, push ya da deploy gibi dış etkilerin geri alınamadığı.

Her session temiz bir context window ile başlar; önceki session'ın konuşması yeni session'a taşınmaz. Kalıcı olması gereken bilgi CLAUDE.md'ye ya da auto memory'ye gider; ikinci yazının konusu bu. Context dolmaya yaklaşınca Claude Code konuşmayı kendiliğinden kısaltıp bir özet çıkarır, ama bu sırada konuşmanın başında verdiğin ayrıntılı talimatlar kaybolabilir. Context'te neyin yer kapladığını /context komutu gösteriyor.

İlk Session: Bookstore'u Tanımak

Repo'nun kök klasöründe bir terminal açıp claude yazdığında prompt'un üstünde sürüm, aktif model ve çalışma dizini görünür. Bookstore'un yapısı tanıdık: src/ altında Bookstore.Api ve Bookstore.Contracts, tests/ altında test projeleri, web/bookstore-web altında Angular uygulaması ve SQL Server veritabanı. İlk iş değişiklik istemek değil, Claude'un repo'yu nasıl okuduğunu görmek:

Explain how this solution is layered: list the projects under src/ and tests/,
what each one depends on, and where the Catalog endpoints are registered.
Then explain the route structure of the Angular app in web/bookstore-web.
Name the files you used for each claim. Do not change any file.

Son iki cümle önemli. "Hangi dosyaya dayandığını yaz" demek cevabı doğrulanabilir yapar: Claude Program.cs'teki endpoint kayıtlarından ya da Angular'ın route tanımlarından söz ediyorsa o dosyaları açıp bakabilirsin. "Hiçbir dosyayı değiştirme" de keşif aşamasında yanlışlıkla bir düzenlemenin araya girmesini önler; bunu prompt yerine permission mode ile garanti altına almayı dördüncü yazıda plan mode ile göreceğiz. Belgelerin önerisi de aynı: Claude'a ne yapacağını adım adım dikte etmek yerine hedefi ve bağlamı ver, hangi dosyayı okuyacağına kendisi karar versin.

İlk Değişiklik: BookDto'ya PublishedYear Eklemek

Emre'nin ikinci hatası ilk iş olarak dev bir refactor istemekti. İlk değişiklik küçük, sınırları belli ve testle doğrulanabilir olmalı. Böylece hem Claude'un repo'da nasıl çalıştığını hem de kendi review alışkanlığını küçük bir diff üzerinde görürsün:

Add a nullable int property PublishedYear to BookDto in src/Bookstore.Contracts.
Map it from the Book entity in the Catalog endpoints and update the existing
tests in tests/Bookstore.Api.Tests. If Book has no publication year column,
stop and ask me instead of adding a migration.
Run dotnet test when you are done and show me the test summary.

Bu prompt'ta üç şey var: ne değişecek (tek bir property ve mapping'i), nerede değişecek (iki proje ve test projesi) ve nerede durulacak (veritabanı şeması gerekiyorsa sorması). Durma koşulu küçük görünür ama önemli: Claude bir migration eklemeye karar verirse değişiklik tek bir property'den veritabanı şemasına büyür, review'un da ona göre büyür.

Claude çalışırken her düzenlemede ve her komutta sana sorup sormayacağı permission mode'a bağlı. 2.1.283'ten beri terminal ve VS Code'da etkileşimli session'ların varsayılan modu Auto: ayrı bir classifier model riskli işlemleri engelliyor, gerisi sormadan çalışıyor. Shift+Tab ile Manual, Accept edits ve Plan arasında geçiş yaparsın. İlk session'larda Manual moda geçip her düzenlemeyi tek tek onaylamak, aracın nasıl çalıştığını görmenin iyi bir yolu. Ayrıntılar üçüncü yazıda.

Claude "testler geçiyor" dediğinde iş bitmiş sayılmaz; Emre'nin üçüncü hatası buydu. Claude'un gösterdiği test özetine bak ama kararı kendi koşunla ver: değişen dosyaları /diff ile ya da kendi terminalinde git diff ile oku, sonra testleri sen çalıştır:

git diff --stat
git diff src/Bookstore.Contracts
dotnet test

Diff'te beklediğin şeyler: BookDto'da yeni bir property, Catalog tarafında tek bir mapping satırı, test projesinde bu alanı doğrulayan bir assertion. Beklemediğin her şey (başka bir DTO'da (Data Transfer Object; katmanlar arasında veri taşıyan class) değişiklik, yeni bir paket, silinmiş bir test) review'da sorulacak bir soru. Commit'i de sen at ya da Claude'a "commit my changes with a descriptive message" de; ama mesajı ve kapsamı okumadan onaylama.

Günlük Komutlar ve Diğer Yüzeyler

Belgelerdeki temel komutlar iki gruba ayrılıyor: terminalden Claude Code'u başlatanlar ve session içinde / ile yazılanlar.

Prompt'ta yalnız / yazmak o an kullanabildiğin komutları ve skill'leri listeler; Tab tamamlar, yukarı ok önceki prompt'ları getirir. Terminal dışındaki yüzeyler de aynı motoru kullanıyor: VS Code eklentisi diff'leri editörde gösteriyor, JetBrains eklentisi CLI'nin kurulu olmasını istiyor, Claude Desktop'taki Code sekmesi CLI kurmadan paralel session'lar açabiliyor, claude.ai/code ise işi Anthropic'in yönettiği bulut ortamında çalıştırıyor. Slack'ten iş devretmek ve telefondan takip etmek de mümkün. Bunların hepsi dokuzuncu yazıda.

Üretimde Dikkat

Ekipte sürüm farkı sürpriz yaratır. Biri latest kanalda, diğeri üç haftadır güncellenmeyen bir WinGet kurulumundaysa aynı ayar iki makinede farklı davranabilir. Ekip için stable kanalı ve minimumVersion iyi bir başlangıç; Team ve Enterprise'da yönetici sürüm aralığını managed settings ile zorunlu tutabiliyor. WinGet kullanıyorsan winget upgrade'i takvime koy.

Ortam değişkenlerine dikkat et. Bir başka iş için shell profiline eklenmiş ANTHROPIC_API_KEY, Claude Code'un aboneliğin yerine Console faturasını kullanmasına yol açabilir. Hesabın, organizasyonun ve aktif kimliğin doğru olduğunu ilk session'da /status ile kontrol et.

Claude Code'u repo'nun kökünde aç. Ev klasöründe ya da birden fazla repo'yu kapsayan bir üst klasörde açtığın session, gereğinden geniş bir dosya alanına erişir ve proje ayarlarını doğru yerden okumaz. Kurumsal proxy arkasındaysan ağ ayarlarını belgelerin network configuration sayfasından yap; kurulum ya da giriş takılırsa ilk adım claude doctor.

Sık Düşülen Tuzaklar

İlk iş olarak büyük refactor istemek. Aracı ve repo'yu tanımadan otuz dosyalık bir diff review edilemez. İlk hafta küçük, testle doğrulanan işler seç.

"Testler geçiyor" cümlesini kanıt saymak. Claude'un raporu bir iddia; kanıt senin terminalindeki test çıktısı ve okuduğun diff.

Yanlış hesapla girmek. Kişisel abonelikle şirket kodu, şirket hesabıyla kişisel deneme projeleri; ikisi de sonradan açıklaması zor durumlar. CLAUDE_CONFIG_DIR ile hesapları ayır.

Kurulum komutunu yanlış shell'de çalıştırmak. PowerShell komutu CMD'de, CMD komutu PowerShell'de çalışmaz; hata mesajı hangisinde olduğunu söylüyor.

Git for Windows olmadan Bash kuralları yazmak. Claude o makinede PowerShell tool'unu kullanıyorsa Bash(...) izinleri hiçbir şeyi eşlemez. Hangi shell'in kullanıldığını bil, kuralları ona göre yaz.

Küçük Bir Deneme

★☆☆ Claude Code'u native installer ile kur, yeni bir terminalde claude --version ve claude doctor çıktısına bak. Bir session açıp /status ile hangi hesap ve hangi kimlik bilgisiyle çalıştığını not et.

★★☆ Kendi repo'nda "katmanları açıkla, dayandığın dosyaları yaz, hiçbir dosyayı değiştirme" prompt'unu çalıştır. Cevaptaki her iddia için gösterilen dosyayı aç ve doğru olup olmadığını işaretle. Kaç iddia doğrulandı?

★★★ Küçük bir DTO değişikliğini durma koşuluyla birlikte iste. Önce Manual modda her düzenlemeyi tek tek onaylayarak, sonra git stash ile geri alıp Auto modda tekrarla. İki koşuda diff'ler ve senin müdahale sayın ne kadar farklıydı?

Claude Code her session'a temiz bir context'le başlıyor; Bookstore'un build komutlarını, katman kurallarını ve "migration dosyalarına elle dokunma" gibi yasaklarını her seferinde yeniden anlatmak istemiyorsan onları bir yere yazman gerekiyor. İkinci yazıda CLAUDE.md katmanlarını, .claude/rules/ ile path'e özel kuralları ve Claude'un kendi tuttuğu auto memory'yi göreceğiz.