Claude Code Plan Modu: Tasarım İncelemesi-Öncelikli Refaktör Döngüleri

Birçok geliştirici Claude Code’u kullanmaya aynı şekilde başlar: bir görev yapıştırır, çalışmasına izin verir ve diffi inceler. Bu küçük değişikliklerde işe yarar, ancak birden fazla dosyaya dokunan işler bozulmaya başlar. 

Claude’un rehbersiz verdiği her karar çoğu zaman doğru olabilir; kulağa iyi geliyor ama birleşik etkisini düşünün: Örneğin, karar başına %80 doğruluk varsayarsanız, 20 karar noktası olan bir özellikte 0.8^20 olasılığınızı yaklaşık %1’e düşürür.

Plan Modu, bir salt-okunur aşama ekleyerek bu hesabı değiştirir. Claude’u kod tabanını okumaya, soruları görünür kılmaya ve tek bir dosyaya dokunulmadan önce sizin inceleyeceğiniz bir plan üretmeye zorlarsınız. 

Bu eğitim, dağınık bir FastAPI blog API üzerinden Explore-Plan-Execute döngüsünü, Ctrl+G ile plan düzenlemeyi ve Agent Teams ile daha büyük refaktörlere ölçeklemeyi içeren iş akışını adım adım gösterir. 

Claude Code en iyi uygulamalar eğitimimiz birleşik hata sorununu daha ayrıntılı ele alır; Claude Code 2.1 rehberi ise kurulumda yardıma ihtiyacınız varsa yükleme ve özellikleri anlatır.

Claude Code’un arkasındaki modellere dair daha fazla bilgi için Claude Sonnet 4.6 ve Opus 4.6 rehberlerimize göz atın ya da Introduction to Claude Models kursumuza katılın.

Claude Code Plan Modu Nedir?

Plan Modu, Claude’u salt-okunur işlemlere kilitler. Dosyaları okuyabilir, kod tabanını arayabilir ve size sorular sorabilir; ancak dosya yazma, kod düzenleme veya kabuk komutları çalıştırma girişimleri reddedilir. Plan Modu açıkken ondan “şu hızlı düzeltmeyi yap” diye isteyin, kıpırdamaz.

Dört şekilde etkinleştirebilirsiniz:

• Giriş alanında Shift+Tab iki kez basmak Normal, Otomatik-Kabul ve Plan Modu arasında geçiş yapar

• /plan komutu Plan Modu’na girer ve siz modu değiştirene kadar sürer

• --permission-mode plan CLI bayrağı yeni bir oturumu Plan Modu’nda başlatır

• permissions.defaultMode altında settings.json girdisi Plan Modu’nu kalıcı varsayılanınız yapar

Claude bir plan üretmeyi bitirdiğinde, sonucu ~/.claude/plans/ dizinine rastgele üretilmiş bir adla (ör. dreamy-orbiting-quokka.md) markdown dosyası olarak kaydeder. 

Bu dosya, gözden geçirilebilir bir sözleşmedir: oturumlar arasında kalır, /clear ve bağlam sıkıştırmasına dayanır ve siz onaylayana kadar hiçbir şey uygulanmaz. Plan dosyasının kendisi kalıcı olsa da, Claude’un zaman zaman bağlam sıkıştırmasından sonra planı yeniden okumasını istemedikçe onu gözden kaçırabileceğini unutmayın.

Planların sürüm kontrolü için projenizin içinde tutulmasını istiyorsanız, settings.json içindeki plansDirectory değerini ./plans gibi projeye göreli bir yola ayarlayın.

Projeye göreli planlar, ~/.claude/plans/ dizininin destekleyemeyeceği iş akışlarını açar:

• Birileri kod yazmaya başlamadan önce plan diff’lerini çekme isteklerinde inceleyin
• Bağlam sıkıştırmasına bel bağlamadan açıklamaları oturumlar arasında ileriye taşıyın
• Markdown dosyasını, ekip üyelerinin doğrudan düzenlediği yaşayan bir şartname olarak ele alın

Uzun soluklu refaktörler veya çok oturumlu işler için, sürüm kontrollü bir plan dosyası size tek başına Ctrl+G’den daha fazla kontrol sağlar.

Bir Claude Code Explore-Plan-Execute İş Akışını Uygulama

Üç aşamanın birlikte nasıl çalıştığını görmek için bir fastapi-blog-api deposunu refaktör edeceğiz. Test içermiyor ve her biri fazlasını yapan üç dosyası var: 

• main.py: tüm rotalar, satır içi yetkilendirme kontrolleri, sabit kodlanmış yapılandırma, e-posta gönderimi

• models.py: ORM modelleri, Pydantic şemaları, sorgu fonksiyonları, tohum verisi

• utils.py: parola karma, JWT belirteçleri, S3 yüklemeleri, markdown işleme, önbellekleme, hız sınırlama, CSV dışa aktarma

Aşama 1: Her şeyden önce bağlam toplayın

Görevi Plan Modu’nda başlatın (önce GitHub reposunu yerele klonlayın). Açılış istemi Claude’a ne istediğinizi söylemeli ve ilgili dosyaları okumasını istemelidir:

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.Altyapı:

Claude, kod tabanı araştırmasını salt-okunur araçlarla sınırlı yerleşik bir alt aracıya devreder. Üç dosyanın hepsini okudu, aralarındaki içe aktarmaları izledi ve belirsizlikleri görünür kılmak için AskUserQuestion kullandı. 

Sorular birkaç üst düzey kararı kapsıyordu:

• Mimari derinlik (düz router’lar mı tam hizmet katmanları mı)
• Sabit kodlu yapılandırmanın nasıl ele alınacağı
• Kullanılmayan yardımcı fonksiyonların kaldırılıp kaldırılmayacağı
• Hangi test çerçevesinin kullanılacağı

Bu sorular önemlidir. Yalnızca mimari sorusu bile insan girdisi olmadan yazı tura olurdu. Claude, eğitim verilerinde en sık gördüğü kalıba varsayılan olarak yönelir; FastAPI için bu genellikle düz bir router yapısıdır. Burada “servis katmanı kullan” demek, daha sonra baştan refaktörün tüm bir turunu kurtardı.

Hedef mimarinize uyan bir referans projeniz varsa, isteminize bağlantısını ekleyin. Claude, soyut açıklamalardansa çalışır bir örnekten yararlanabildiğinde daha iyi planlar üretir.

Herhangi bir planı kabul etmeden önce kontrol etmeniz gereken bir şey: Claude’un soruları belirli fonksiyonlara ve satır düzeyindeki ayrıntılara atıfta bulunuyor mu, yoksa yalnızca dosya adlarına mı? “Kimlik doğrulama sistemi”nden bahsedip de hiç verify_jwt_token ya da main.py’deki middleware zincirinden söz etmiyorsa, dosyaları okumak yerine göz gezdirmiştir. 2. Aşamaya geçmeden önce daha dikkatli okumasını isteyin.

Aşama 2: Planı üretin ve düzenleyin

Claude’un sorularını yanıtladıktan sonra planı otomatik olarak üretir. Ayrı bir isteme gerek yoktur. Plan ~/.claude/plans/ dizinine kaydedilir ve şunları içerir: 

• Bağlam özeti
• Hedef dizin yapısı
• Adım adım uygulama sırası
• Refaktörün çalıştığını doğrulamak için komutlarla doğrulama bölümü

Nasıl ilerleyeceğinizi seçmeden önce planı varsayılan metin düzenleyicinizde açmak için Ctrl+G tuşlarına basın ($EDITOR ile ayarlanır). Alternatif olarak, etkin plan dosyasını doğrudan açmak için /plan open komutunu kullanın.

Plan Modu bu adımda kendini amorti eder. Adımlara satır içi notlarla açıklama ekleyebilir, katılmadığınız adımları silebilir, işlemleri yeniden sıralayabilir ve kaydedebilirsiniz. Terminale döndüğünüzde Claude tüm düzenlemeleri alır.

Blog API planı için açıklamalar şöyle görünebilir:

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.pyAltyapı:

Karmaşık planlarda tek bir Ctrl+G turu yeterli olmayabilir. Açıklama ekleyin, geri dönün, Claude’a “planda tüm açıklamaları ele al, henüz uygulama yapma” deyin, gözden geçirilmiş sürümü inceleyin ve tekrar Ctrl+G yapın. Her açıklama turu, aksi halde yanlış uygulama kararına dönüşecek belirsizliği ortadan kaldırır.

Sözleşme doğru göründüğünde Claude birkaç seçenek sunar: 

1. Planda çalış ve bağlamı temizle (oturum bayatlamaya başladığında iyi), 
2. Temizlemeden çalış (konuşma geçmişini korumak için) veya 
3. Plan hakkında sohbet etmeye devam et. 

Biriktirdiğiniz bağlama göre seçin. Uzun bir oturumun derinlerindeyseniz, temizlemek Claude’a uygulama için taze bir pencere verir.

Aşama 3: Onaylanan planı uygulayın

Bir çalışma seçeneği belirleyin ve Claude adım adım uygulamaya başlasın. Her adımı işler ve manuel müdahale gerektiğinde (ör. terminalde etkileşimli kimlik doğrulama) ya da tüm plan tamamlandığında durur.

Sapmalara dikkat edin. Plan, önce kimlik doğrulamayı kendi modülüne çıkarmayı söylüyor olabilir; ancak Claude, bir kestirme gördüğü için rotaları ve kimlik doğrulama mantığını aynı anda çekmeye başlayabilir. Bu tür bir hamle, bazı içe aktarmaların eski konumu, bazılarının yeni konumu işaret ettiği yarım göçmüş bir kod tabanıyla sonuçlanır. 

Diğer sapma sinyalleri: 

• Geçerli adımda belirtilmeyen bir dosyayı düzenlemek
• Planın açık bıraktığı bir mimari kararı sessizce vermek
• Planın ayrı tuttuğu iki adımı birleştirmek

Sapma olduğunda, Shift+Tab ile Plan Modu’na geri dönün. Claude mevcut dosya durumunu okur, kalan adımlar için gözden geçirilmiş bir plan üretir ve devam etmeden önce siz bunu incelersiniz. Bu bir acil durum önlemi değil. Çoğu çok dosyalı refaktör bitmeden önce 2-3 plan revizyonundan geçer.

Tek bir oturuma sığmayan refaktörlerde, işi tek büyük bir plan yerine art arda gelen planlara bölün. Kimlik doğrulamayı kendi planı altında bitirin, ardından taze bir oturum ve rota bölme için bir planla başlayın. 

/rename ile her oturumu etiketleyin (örn. "blog-api-auth-extraction"), böylece /resume ile kaldığınız yerden devam edebilirsiniz. Daha küçük planlar bağlam penceresini odaklı tutar ve aşamalar arasında doğal bir kontrol noktası sağlar.

Claude Code Plan Modu için Pratik Stratejiler

Artık tüm süreci bir kez tamamladığımıza göre, Plan Modu’ndan en iyi şekilde yararlandığınızdan emin olmak için birkaç en iyi uygulamaya bakalım.

Plan Modu ne zaman kullanılmalı (ve ne zaman atlanmalı)

Her görev bir plan gerektirmez. Tek satırlık düzeltmeler, yazım hataları ve yalıtılmış fonksiyon güncellemeleri, planlama yükü olmadan daha hızlıdır. Bir dosya genelinde bir değişkenin adını değiştirme gibi mekanik değişiklikler için de aynı şey geçerlidir.

İyi bir sezgi: Değişiklik üç veya daha fazla dosyaya dokunuyorsa ya da tüm değişikliği tek bir cümleyle tarif edemiyorsanız önce plan yapın. Üç dosya, birleşik hataların can sıkmaya başladığı eşiğe yakındır; çünkü her dosya, Claude’un doğru yapması gereken kendi karar kümesini ekler.

Plan Modu’ndan her zaman fayda gören görevler:

• Dosyalar arasında kod taşıyan veya paylaşılan arabirimleri yeniden adlandıran refaktörler
• Mevcut modüllere dokunan yeni özellikler
• Kırıcı API değişiklikleri olan bağımlılık yükseltmeleri
• Kod tabanının belirli bir durumu nasıl ele aldığına emin olmadığınız her görev
• Claude ile bir yaklaşıma risksiz şekilde yineleme yapmak istediğiniz beyin fırtınası oturumları

Size pahalıya patlamadan zayıf planları tespit etmek

Yapılandırılmış görünen bir plan her zaman iyi değildir. Mevcut Claude Code sürümlerinde, hayali dosya referansları ve muğlak “gerektiği gibi güncelle” adımları nadirdir. Daha olası sorun, tüm uygulama adımlarını başa koyup en sona “test ekle” iliştiren bir planla karşılaşmaktır.

Bu şekilde yapılandırılan planlar, beklediğinizden kötü sonuç verir. Uygulama sırasında testler olmadan Claude, oturum ortasında kendi işini doğrulamanın bir yoluna sahip değildir. Blog API refaktöründe, “Adım 1-6: tüm modülleri çıkar, Adım 7: testleri yaz” diyen bir plan, geri bildirim döngüsü olmadan altı adım kod demektir. 

Daha güçlü bir plan, test odaklı geliştirme (TDD) kullanır ve testi uygulamayla iç içe geçirir: auth/ için fonksiyonları çıkarmadan önce testleri yazın, geçtiklerini doğrulayın, ardından rotaları çıkarmadan önce posts/ için testleri yazın. Her geçen test, refaktörün yolunda olduğuna dair Claude’a net bir sinyal verir. 

Projenizin CLAUDE.md dosyasına TDD kuralları eklemek, Claude’un varsayılan olarak test adımlarını dahil etmesini sağlar. Claude Code Hooks, plan uygulamasını onaylamadan önce plan kalitesini kontrol eden doğrulama betiklerini çalıştırarak bu tür zorlamayı otomatikleştirebilir.

Büyük refaktörleri Agent Teams ile ölçeklendirme

Yedi veya daha fazla dosyaya dokunan planlar, uygulama sırasında bağlam penceresi dolduğu için kalite kaybetmeye başlar. Blog API refaktörü, rotalar, modeller, servisler, yapılandırma, testler ve yeni dizin yapısını saydığınızda bu eşiğe ulaşır.

Agent Teams, bu tür işleri birden çok Claude Code oturumuna dağıtan deneysel bir özelliktir. Bir oturum ekip lideri olarak hareket ederken ekip arkadaşlarının her biri bağımsız bir bağlam penceresine sahip olur. 

Blog API için üç ekip arkadaşına bölebilirsiniz: biri rota çıkarımıyla, biri veritabanı ve model katmanıyla, biri de test kapsamıyla ilgilenir. Lider görevleri atar, ekip arkadaşları talep edip tamamlar ve “modülleri çıkar”a bağlı “içe aktarmaları güncelle” gibi engelli görevler, bağımlılıklar tamamlandığında otomatik olarak açılır. 

Aynı ayrım depolar arasında da çalışır: API’niz paylaşılan bir kütüphaneye bağlıysa, bir ekip arkadaşı kütüphaneyi refaktör ederken diğeri API’nin onu kullanımını güncelleyebilir.

Plan Modu için en iyi kurulum, ekip arkadaşları için plan onayı gerektirmektir. Lidere şunu söyleyin: “Blog API refaktörü için üç ekip arkadaşı oluştur. Değişiklik yapmadan önce plan onayı iste.” 

1. Her ekip arkadaşı salt-okunur modda plan yapar
2. Lider inceler ve geri bildirimle onaylar veya reddeder
3. Yalnızca onaylanan planlar uygulanır

Liderin yargısını ölçütlerle şekillendirebilirsiniz: “yalnızca test kapsamı içeren planları onayla” veya “veritabanı şemasını doğrudan değiştiren planları reddet.” Agent Teams’i settings.json dosyanızın env bloğuna "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" ekleyerek etkinleştirin.

Deneysel bayrak olmadan daha basit paralelleştirme için, git worktree’leri farklı dallarda ayrı Plan Modu oturumları yürütmenizi sağlar; her biri kendi planını bağımsız olarak işler.

Uzun süren bir oturum bağlam sıkıştırmasına uğrarsa, ekip arkadaşlarının sapmayı önlemek için plan dosyalarını açıkça yeniden açıp yeniden okumalarını sağlayın.

Claude Code eklentileri eğitimi, çok aşamalı işi yönetmek için ek kalıpları kapsar.

Sonuç

Plan Modu’nun değeri tek bir şeye dayanır: uygulamadan önce gözden geçirme. Eklediğiniz her açıklama turu, Claude’un tahmin etmek yerine sorduğu her soru, aksi halde yanlış çıkacak bir kararı ortadan kaldırır. 

Bir sonraki çok dosyalı değişikliğinizle başlayın, Claude’u önce plan yapmaya zorlayın ve yazma izni vermeden önce planı Ctrl+G ile düzenleyin. CLAUDE.md yapılandırması, bağlam yönetimi ve kancaya dayalı korkuluklar için en iyi uygulamalar eğitimi bu noktadan devam eder. 

Daha geniş bir AI destekli kodlama perspektifi için, temel kavramları öğreten ve GitHub Copilot, Windsurf veya Replit gibi benzer araçlarda uygulamalı deneyim sunan AI for Software Engineering yetkinlik yolumuzu incelemenizi öneririm.