Claude Code Kullanım Biçimi: Planlama ve Uygulamanın Ayrılması

• Yapay zeka kodlama araçlarının kullanım biçimini kökten yeniden düzenleyerek, kod yazmadan önce mutlaka açık bir plan inceleme aşamasından geçen bir iş akışı sunuyor
• Temel ilke, “plan onaylanmadan Claude'a kod yazdırma”; bu sayede yapısal kontrol ve verimli token kullanımı sağlanıyor
• Tüm süreç, Research → Plan → Annotation → Todo List → Implementation → Feedback döngüsel yapısıyla ilerliyor
• Her aşamada markdown belgeleri (research.md, plan.md) etrafında iş birliği yapılıyor; notlar ve düzeltme süreci tekrar edilerek olgunluk artırılıyor
• Bu yaklaşım, yapay zekanın uygulama gücü ile insanın muhakeme gücünü ayırıp yeniden birleştirerek, karmaşık sistemlerde bile istikrarlı ve tutarlı sonuçlar elde etmeye odaklanıyor

---

Genel iş akışı özeti

• Yaklaşık 9 ay boyunca Claude Code'u ana geliştirme aracı olarak kullanırken, yaygın olan “prompt gir → kod üret → tekrar düzelt” yaklaşımı yerine planlama ve uygulamayı ayıran sistematik bir süreç kuruldu
• Claude kod yazmadan önce, mutlaka yazar tarafından incelenip onaylanmış plan belgesine (plan.md) dayanarak hareket etmesi sağlanıyor
• Bu yaklaşım, gereksiz deneme-yanılmayı azaltıyor, mimari karar yetkisini koruyor ve token kullanımına kıyasla kaliteyi en üst düzeye çıkarıyor

Faz 1: Research

• Tüm işler derinlemesine bir kod tabanı analiziyle başlıyor
  • Claude'dan belirli klasörleri veya işlevleri “derinlemesine okuyup” analiz etmesi isteniyor
  • Sonuçların mutlaka research.md dosyasına yazılması sağlanıyor
• Bu belge, Claude'un anlama düzeyini doğrulayan bir inceleme yüzeyi (review surface) görevi görüyor; yanlış anlama varsa bu aşamada düzeltiliyor
• Hatalı araştırma, hatalı plan ve uygulamaya yol açtığı için, maliyeti en yüksek başarısızlık nedeni daha baştan engelleniyor
• Örneğin cache katmanını göz ardı etme, ORM kurallarını yansıtmama veya yinelenen mantık üretme gibi sorunlar önleniyor

Faz 2: Planning

• Araştırma incelendikten sonra Claude'dan ayrıntılı bir uygulama planı (plan.md) yazması isteniyor
  • Gerçek kod parçacıkları, değiştirilecek dosya yolları ve trade-off'lar da buna dahil ediliyor
  • Yerleşik plan modu yerine, doğrudan yönetilebilen markdown dosyaları kullanılıyor
• Açık kaynaklı bir referans uygulama (reference implementation) birlikte verildiğinde, Claude'un plan kalitesi belirgin biçimde yükseliyor
• Plan belgesinin kendisinden daha önemli olan şey, sonrasındaki Annotation döngüsü

Annotation Döngüsü

• Yazar, plan.md dosyasını açıp doğrudan satır içi notlar ekliyor
  • Yanlış varsayımları düzeltme, yaklaşımı reddetme, alan bilgisi ekleme vb.
  • Örneğin: “Bu bir PATCH olmalı”, “cache gereksiz”, “visibility alanı liste düzeyine taşınmalı”
• Ardından Claude'a “notları yansıtacak şekilde belgeyi güncelle ama henüz uygulama yapma” talimatı veriliyor
• Bu not-ekleme ve güncelleme döngüsü 1 ila 6 kez tekrarlanıyor ve “don't implement yet” komutuyla erken uygulamanın önüne geçiliyor
• Markdown belgeleri, etkileşimli talimatlardan daha net ve yapısal olan paylaşılabilir bir durum (state) gibi çalışıyor
• Tekrarlar sayesinde genel plan, gerçek sisteme tam oturan bir spesifikasyona dönüşüyor

Todo List oluşturma

• Uygulamadan önce Claude'dan ayrıntılı bir görev listesi (todo list) eklemesi isteniyor
  • Her aşamadaki alt görevler de dahil edilerek ilerleme izleniyor
  • Claude tamamlanan maddeleri işaretlediği için, uzun oturumlarda bile durum takibi kolaylaşıyor

Faz 3: Implementation

• Tüm kararlar netleştikten sonra, standartlaştırılmış bir prompt ile uygulama başlatılıyor
  • “Tüm görevler tamamlanana kadar durma”, “gereksiz yorum yok”, “any/unknown tipleri yasak”, “sürekli type-check yap” gibi talimatlar veriliyor
• Bu komut, planı olduğu gibi uygulayan mekanik bir aşama; yaratıcı muhakeme kısmı zaten daha önce tamamlanmış oluyor
• Plansız doğrudan uygulamaya geçildiğinde kod, yanlış varsayımlar üzerine kurulduğu için “don't implement yet” kuralı temel güvenlik mekanizması oluyor

Uygulama Sırasında Geri Bildirim

• Uygulama sırasında yazar denetleyici rolüne geçiyor
  • Geri bildirimler kısa ve net veriliyor: “bu fonksiyon eksik”, “admin uygulamasına taşı” gibi
  • Frontend düzenlemelerinde “daha geniş”, “2px boşluk” gibi kısa talimatlar veya ekran görüntüleri kullanılıyor
• Mevcut kod referansları sık kullanılarak tutarlı bir UI/UX korunuyor
• Yanlış yöne gidildiğinde git revert yapıp kapsamı daraltarak yeniden denemek, kademeli düzeltmelerden daha etkili oluyor

Direksiyonda Kalmak

• Claude'a tam özerklik verilmiyor; son kararı her zaman insan veriyor
• Claude'un önerilerinden bazıları seçiliyor, bazıları değiştiriliyor, siliniyor veya teknik tercihler yeniden tanımlanıyor
  • Örneğin: “birincide Promise.all kullan”, “dördüncü ve beşinciyi yok say”
  • “indirme özelliğini kaldır”, “fonksiyon imzasını değiştirme”, “belirli kütüphane metodunu kullan” gibi
• Claude mekanik uygulamayı, insan ise muhakeme ve öncelik belirlemeyi üstleniyor

Tek Uzun Oturumlar

• Araştırmadan uygulamaya kadar her şey tek bir uzun oturumda kesintisiz yürütülüyor
  • Oturum boyunca Claude sürekli bağlam biriktiriyor ve auto-compaction ile yeterli bağlam korunuyor
  • plan.md, oturum boyunca tam biçimiyle korunuyor ve her an başvurulabiliyor

Temel özet

• “Derinlemesine oku, planı yaz, notlarla rafine et ve ardından tek seferde uygula.”
• Karmaşık prompt'lara veya sistem talimatlarına ihtiyaç duymadan, düşünme (Thinking) ile yazmayı (Typing) ayıran disiplinli bir süreçle yüksek kalite sağlanıyor
• Research bilgisiz değişiklikleri engelliyor, Plan hatalı değişiklikleri önlüyor, Annotation ise insan muhakemesini sürece enjekte ediyor
• Nihai uygulama, tüm kararlar netleştikten sonra otomatikleştirilmiş bir prosedür olarak yürütülüyor ve verimli bir iş birliği yapısı tamamlanıyor

[naka98]

Ben de benzer sorunları sürekli yaşıyorum. Yalnızca sohbet tabanlı şekilde yapay zeka ile işbirliği yapınca iş kırılım yapısı (WBS), ilerleme durumu ve karar kayıtları bulanıklaşıyor.

[pcj9024]

Plan dosyasını doğrudan repoya koyup o planı çalıştırarak ortaya çıkan uygulama değişikliklerini kaydettirdiğinizde, bağlamın epey iyi korunduğunu gördüm.

[geekbini]

Bu içerik yalnızca Claude ile sınırlı değil; genel olarak diğer CLI tabanlı yapay zeka hizmetlerine de uygulanabilir gibi görünüyor.

[GN⁺]

Hacker News görüşleri

• Asıl mesele gerçekten de “plan yapıp yapmamak” değil, model kodda somutlaşmadan önce varsayımları görünür kılmak
  LLM’ler sözdiziminden çok mimari ya da kısıtlar gibi görünmeyen kabuller yüzünden başarısız oluyor. Bu yüzden belgelenmiş bir plan, bu kabulleri debug edebileceğiniz bir yüzey sağlıyor

  • Bu açıdan alt ajan yapısı çok yardımcı oluyor. Birini planlama, birini uygulama, bir diğerini inceleme için görevlendirince roller netleşiyor. Blue team/red team tarzında da yapılabilir. Sonuçta mesele, LLM’in daha net talimatlarla doğru akıl yürütmesine yardımcı olmak
  • Tüm kullanım senaryosu akışını yönergelere eklerseniz, modelin saçma sapan davranışlar sergilemesini engelleyebilirsiniz
  • Ama bu varsayımları görünür kılma eyleminin kendisi bile modelin davranışını değiştirebilir. Tıpkı tek bir printf() satırı ekleyince Heisenbug’ın ortadan kaybolması gibi
  • Neredeyse hiç sözdizimi hatası olmuyor mu? Benim deneyimim öyle değil. Küçük bir Rust projesine S3 backend eklemeye çalışırken Claude API halüsinasyon döngüsüne girdi ve 30 dakikada 20 doları yaktı. Üstelik mesele sadece basit bir sözdizimi sorunuydu
  • Bu yazıyı yoksa ChatGPT ile mi yazdınız?

• Claude’un yüzeysel okumaması için “derinlemesine”, “ayrıntılı” gibi kelimeler kullanmak gerektiği söyleniyor ama dürüst olmak gerekirse bunun nedenini sezgisel olarak anlayamıyorum

  • Bunun sebebi attention mekanizması. LLM internetteki her şeyi öğrendi ama “sorunun ayrıntılarına bak” gibi ifadeler içeren yazılar genelde uzman seviyesinde yanıtlar barındırıyor. Bu yüzden böyle kelimeler geçince model o veri tarafına daha fazla ağırlık veriyor. “MIT profesörü gibi davran” türü prompt’ların işe yaramasının nedeni de aynı
  • Ama bu tür açıklamalar batıl inanç gibi geliyor. İstatistiksel olarak doğrulanmış bir dayanak yok ve sanki güneş tanrısına kurban sunmak düzeyinde büyüsel düşünce gibi hissettiriyor. Gerçekten işe yarıyorsa bunun bir optimizasyon problemi olarak kanıtlanabilmesi gerekir ama kimse veri paylaşmıyor
  • Şu anda yazılım geliştirme gerçekten garip bir çağda. Kimse LLM’in neden öyle davrandığını bilmiyor. Sadece prompt’un olasılıkları doğru yönde itmesini umuyoruz. Eskiden deterministik olan bir alandı, şimdi ise AGENTS.md dosyasına anne babanın çocuğuna söyler gibi kalın harflerle komut yazıyoruz
  • Bunları görüp de hâlâ ciddiye alabilmelerine şaşırıyorum. Neredeyse mühendislik için astroloji gibi
  • Modelin gizil uzayını (latent space) bir arazi gibi düşünürseniz anlamak kolaylaşıyor. Prompt, topu belirli bir noktaya bırakmak gibi; kelime seçimi de o topun hangi vadiye yuvarlanacağını belirliyor. “Derinlemesine” gibi ifadeler topun istenen bölgede daha iyi kalmasını sağlıyor. Kusursuz bir açıklama olmayabilir ama böyle düşününce pratikte gerçekten işe yaradı

• Ben üç belge tipi ve iki skill’den oluşan bir yapı kullanıyorum
  Specs projenin statik tasarım belgeleri, Plans LLM’in ürettiği yürütme planları, Working memory dosyaları ise ilerleme durumunu takip ediyor.
  Gemini Pro’nun planner skill’i ile yeni plan oluşturuyor, Codex’in implementer skill’i ile uyguluyorum.
  Böyle olunca context hafif ve odaklı kalıyor, dolayısıyla verim yüksek oluyor. Codex/Gemini’nin 20 dolarlık planıyla bile yeterince hızlı ilerlemek mümkün

  • Ben de benzer bir yaklaşım kullanıyorum. Makalelere dayanarak spec dosyaları oluşturuyor ve Claude ile etkileşerek planı geliştiriyorum. IEEE tarzı sistem mühendisliği belgeleri gibi gereksinim–test–tanım belgelerini yönetiyorum. Claude’a guardrail verirseniz iyi uyuyor. Bana göre Claude, Codex’ten daha uygun
  • Güzel yaklaşım. Ama monorepo’nun yapay zeka çağında daha iyi bir seçim olup olmadığını merak ediyorum. Bizim şirkette Next.js uygulamaları birden fazla repo’ya bölünmüş durumda; tek bir yapıda toplamak daha mı iyi diye düşünüyoruz

• Plan belgesine doğrudan yorum bırakma fikri taze geliyor. Acaba bu yorumları ayrı saklama ya da sonra gözden geçirmek için yönetmenin bir yolu var mı diye merak ediyorum

• Bu yaklaşımda hoşuma gitmeyen birkaç nokta var
  Birincisi, tüm kodu tek seferde üretmeye çalışan big bang yaklaşımı, anlaşılması zor devasa kod yığınları üretiyor. Planı yapıp uygulamayı aşama aşama yürütmek daha iyi olur diye düşünüyorum.
  İkincisi, geri bildirim verirken bilgi tabanını güncellememesi eksik kalıyor. Hata nedenlerini kaydedip bir dahaki sefere tekrar etmemesini sağlamak gerekir.
  Son olarak testlerden hiç bahsedilmiyor. En azından bir miktar test odaklı geliştirme (TDD) içermeli. Yapay zeka destekli geliştirmenin bu metodolojilerle nasıl birleşeceğini görmek ilginç olacak

  • Ben de benzer deneyimler yaşadım. PLAN.md’yi aşamalara bölüyor ve prompt’u dikkatle yazarak sadece ilgili aşamayı uygulatıyorum. Testleri de planın bir parçası yapıyorum ama şimdilik daha çok sonlara doğru ekliyorum

• Bu iş akışı aslında Anthropic’in Claude Code için önerdiği standart yöntem. Ama dezavantajı şu: plan mükemmel değilse en baştan başlamak gerekebiliyor.
  Bu yüzden ben tasarım → plan → uygulama sürecini birden fazla batch’e bölüyorum. 1.500 satırdan kısa plan parçalarına ayırınca karmaşıklığı yönetmek daha kolay oluyor.
  30 bin LOC’lik uygulamam için 100 bin satırlık planım var. Bunu tek seferde üretmek imkânsız

  • Benim de deneyimim aynı. O yüzden planları daha küçük parçalara ayırıyor ve commit’leri özellik bazlı branch’lerle yönetiyorum. Yapay zeka sayesinde geliştirme alışkanlıklarım hatta daha iyi hale geldi
  • Aslında “radikal biçimde farklı” denilen iş akışının sadece varsayılan Plan modu olması biraz komik
  • Ben de aşamalı yürütmenin doğru cevap olduğunu düşünüyorum. Devasa projeyi tek seferde bitirmek hâlâ sadece bir fantezi
  • Plan kusursuz olmak zorunda değil. Yapay zekanın değiştirdiği kısmı geri alıp önceki aşamadan yeniden yineleyebilirsiniz. Önemli olan küçük ölçekli değişikliklerle karmaşıklığı düşürmek
  • 100 bin satırlık plan neredeyse bir milyon kelime eder. Sadece okumak bile 66 saat sürer. Pratikte mümkün değil

• Ben plan.md yerine çalıştırılabilir iskelet ve doğrulama döngüsü merkezli çalışıyorum
  Kolibri Tickets adlı gerçek bir ödeme sistemini yapay zekayla birlikte kurdum. Buradaki esas mesele modelin hızlı kod yazması değil, doğrulama döngüsünü tasarlamak

  • Başta çalışır durumdaki iskeleti korumak
  • Her seferinde yalnızca ince bir dikey dilim eklemek
  • Testler, tipler, state machine’ler gibi doğrulanabilir çıktıları zorunlu kılmak
  • Refactoring’i gündelik hale getirmek
    Böyle yapınca “hız yanılsaması” değil, gerçekten daha hızlı deploy etmek mümkün oluyor. Plan belgesi paylaşılan durumu korumanın bir yolu; doğrulanabilir harness ise başka bir yolu
  • Ben de kodun ucuzladığı bu çağda %100 test kapsamını hedefliyorum. Python’da static typing, Playwright testleri, mutation testing bile ekliyorum. Artık ajan 1 saatlik döngüler çalıştırıp neredeyse düzeltme gerektirmeyen kod çıkarıyor

• Ben Claude Code’u ders hazırlığı için kullanıyorum
  Quarto ile ders notları yazıyorum, sonra Claude bunları Slidev slaytlarına dönüştürüyor. Sonrasında slaytlara “bunu iki slayda böl”, “buraya görsel ekle” gibi yorumlar ekleyerek geri bildirim veriyorum.
  Bu tür yorum tabanlı geri bildirim çok güçlü. Token mesafesi ve bağlamı koruma açısından ciddi fayda sağlıyor

  • Quarto zaten kendi başına PowerPoint, PDF, HTML gibi farklı formatları destekliyor; o zaman neden Slidev kullanıyorsunuz diye merak ettim. Claude’a Quarto belgesini yeniden üretmesini söylemek yeterli olmaz mı?
  • Geri bildirimi satır içi yorumlar olarak mı bırakıyorsunuz? Mesela # bu kısmı X olarak değiştir gibi?
  • O Claude skill’ini açık kaynak olarak yayımlayıp yayımlamadığınızı merak ediyorum

• Amazon’un Kiro, Google’ın Antigravity, GitHub’ın Spec Kit, OpenSpec gibi araçları zaten bu tür özellikler sunuyor

• Yapay zeka destekli kodlamadaki en pahalı başarısızlık sözdizimi hatası değil, kısmen çalışsa da tüm sistemi bozan bir uygulama
  Bu yüzden ben başta brief.md ekleyip problem tanımını, hedef metrikleri ve özelliğin ne zaman durdurulacağını açıkça yazıyorum. Böylece iş hedefleri ile teknik uygulama arasındaki uyumsuzluğun maliyetini azaltmak mümkün