Claude Code'u gerçekte nasıl kullanıyorum: brief'ten canlıya bir ajansın akışı

Claude Code'u bir sohbet robotu gibi kullanmıyoruz, bir icra kolu gibi kullanıyoruz. Akış hep aynı sırayla işliyor: önce brief okunuyor ve kapsam bir sohbette netleşiyor, sonra o kapsamdan tek, net bir görev çıkarılıp Claude Code'a veriliyor, iş bitince gerçek bir build ve typecheck komutu koşuyor, sonuç geçerse pull request açılıyor. Kararı hep insan veriyor, icrayı agent yapıyor, aradaki sınırı da bir doğrulama komutu çiziyor.

Özet

Beş adım: brief, plan, görev, doğrulama, deploy. Plan aşaması bir sohbette geçiyor ve kapsamı insan onaylıyor. Göreve dönüşen kısım Claude Code'a tek seferde, dar tanımlı olarak veriliyor; geniş "şunu hallet" talimatları değil. Her görev bir CLAUDE.md dosyasını okuyarak başlıyor, o dosya projenin değişmez kurallarını taşıyor. Build ve typecheck geçmeden hiçbir şey birleşmiyor; bu kural istisnasız. Ödeme, migration, sır yönetimi gibi geri dönüşü zor işler agent'a asla tek başına bırakılmıyor. Bu yazının kendisi de aynı akıştan geçti, aşağıda gerçek bir örneği var.

Her proje aynı üç adımla başlıyor: brief, plan, görev

Bir müşteri briefi neredeyse hiçbir zaman doğrudan bir agent görevine dönüşmüyor. Önce bir sohbette plana dönüşüyor: hangi sayfa, hangi entegrasyon, hangi kısıt, hangi stack. Bu adımda Claude Code henüz devrede değil, kararı veren insan. Plan netleştikten sonra ondan tek, dar tanımlı bir görev çıkarılıyor: "checkout sayfasına şu ödeme sağlayıcısını ekle, şu iki testi geçir" gibi somut, sınırları belli bir iş. Kapsamı geniş tutmak agent'ı değil, kontrolü kaybettiriyor: "sitenin ödeme akışını düzelt" gibi belirsiz bir görev, agent'ın kendi kararıyla kapsam genişletmesine kapı açıyor. Dar görev, dar diff, dar diff de kolay inceleme demek.

CLAUDE.md: Claude Code'un her oturumda okuduğu tek dosya

Her müşteri projesinin kök dizininde bir CLAUDE.md var ve Claude Code her oturuma bu dosyayı okuyarak başlıyor. İçinde üç şey duruyor: stack'in değişmezleri (hangi framework, hangi veritabanı, hangi deploy hedefi), yasaklar (bu projede kullanılmayacak kütüphaneler, atlanmayacak adımlar) ve doğrulama kuralı (hangi komut geçmeden hiçbir şey birleşmez). Örneğin bir projede "Next.js dışına çıkma, WooCommerce müşteri talebi olmadan önerilmez" satırı duruyorsa, bu satır agent'ın bir önceki projeden alışkanlıkla farklı bir stack önermesini daha ilk turda engelliyor. Dosya kısa tutuluyor bilerek: uzun, genel geçer bir kural listesi okunmuyor, birkaç satırlık, o projeye özel, gerçekten çarpan kurallar okunuyor.

Hangi karar insanda kalıyor, hangi iş agent'a gidiyor

Ayrım net: geri dönüşü kolay olan her şey agent'a gidiyor, geri dönüşü zor veya müşteriyi doğrudan etkileyen her şey insanda kalıyor.

Bu tablo sabit değil, projeye göre kayıyor. Yeni ve az test kapsamı olan bir depoda agent'a bırakılan iş daralıyor, üzerinde uzun süredir çalışılan ve testi güçlü bir depoda genişliyor. Ama üç satır hiç kaymıyor: ödeme, migration ve sır yönetimi her zaman insanda kalıyor, depo ne kadar olgun olursa olsun.

Doğrulama olmadan hiçbir şey birleşmiyor: build ve typecheck kapısı

Bir görev "bitti" denmeden önce gerçek bir komut çalışıyor: framework'ün kendi build komutu ve bir typecheck komutu. İkisi de geçmeden PR açılmıyor, "çalışması lazım" bir kabul kriteri değil. Bu kural agent'ın kendi çıktısına güvenmemesi için var; Claude Code kodu yazdıktan sonra kendi yazdığı kodu, tıpkı bir insan geliştiricinin yapması gerektiği gibi, gerçek bir komutla test ediyor. Aynı disiplin riskli komutlardan önce de işliyor: silme, sıfırlama veya branch değiştirme gibi geri dönüşü zor bir git komutundan önce çalışma dizininin durumu kontrol ediliyor, üstüne yazılabilecek bir şey varsa önce kenara alınıyor. Doğrulamayı atlamak zaman kazandırıyormuş gibi görünüyor, ama kazandırdığı zaman, bir sonraki oturumda "neden bozuldu" diye geriye dönüp aramakla telafi ediliyor.

Bu yazının kendisi de aynı akıştan geçti

Teoride kalmasın diye: bu yazı da yukarıda anlatılan akışın bir örneği. Bir öneri kuyruğunda bekleyen brief onaylandı, kapsam ve başlık netti; oradan taslağın planı çıkarıldı ve prova amaçlı bir kontrolden geçirildi. Aşağıdaki panel, o kontrolün bu oturumda gerçekte döndürdüğü sonucu gösteriyor; uydurma bir örnek değil, bu yazının kendi planı üstünde çalıştırıldı.

Sonuç geçmeseydi taslak yazılmadan önce başlık ve bölüm sırası değişecekti, geçtiği için taslağa geçildi. Aynı kontrol, bu yazının bitmiş hali üzerinde bir kez daha, yayına almadan hemen önce tekrar çalıştırılıyor. Bu, "yapay zekayla yazı üretmek" ile "yapay zekayı doğrulama disipliniyle çalıştırmak" arasındaki farkın küçük ama somut bir örneği.

Bu akış nerede çalışmıyor

Bu disiplin her işte gerekli değil. Kimsenin dokunmayacağı, tek seferlik küçük bir script için brief-plan-görev-doğrulama zincirini kurmak zaman kaybı; scripti yaz, çalıştır, bitir. Zincirin asıl değeri, çıktıyı bir müşterinin kullanacağı, bir ekip arkadaşının okuyacağı veya bir sistemin gözetimsiz çalıştıracağı anda ortaya çıkıyor. Ayrıca bu akış CLAUDE.md'siz bir depoda zayıflıyor: proje kuralları yazılı değilse agent bir önceki projenin alışkanlığını taşıyabiliyor, bu da ilk PR'da fark edilmesi gereken, tasarım hatası değil süreç hatası. Ve hiçbir doğrulama komutu, kapsam kararını insandan alamaz; build geçmesi, o özelliğin doğru özellik olduğu anlamına gelmiyor, sadece yazılanın çalıştığı anlamına geliyor.

Sık sorulan sorular

Her görevi Claude Code'a mı devrediyorsunuz?
Hayır. Kapsam kararı, tasarım kararı ve ödeme/migration gibi geri dönüşü zor işler insanda kalıyor. Devredilen kısım, kararı netleşmiş, sınırları belli, doğrulanabilir görevler.

CLAUDE.md dosyası olmadan da çalışır mı?
Çalışır ama daha zayıf çalışır. Dosya olmadan agent, o projeye özel yasakları ve tercihleri bilmez; her seferinde aynı hatırlatmayı sohbette tekrar etmek gerekir. Dosya, o tekrarı bir kere yazıp her oturumda otomatik okutmanın yolu.

Build veya typecheck geçmezse ne oluyor?
PR açılmıyor. Hata mesajı agent'a geri veriliyor, agent kendi yazdığı kodu o hataya göre düzeltiyor, komut tekrar çalışıyor. Bu döngü, komut gerçekten geçene kadar sürüyor.

Bu akış kod bilmeyen biri için de anlamlı mı?
Akışın kendisi teknik, ama sonucu teknik olmayan biri için de görünür: her PR'ın açıklaması var, her görevin bir doğrulama kaydı var. Devralınan bir projede bu kaydın hiç olmaması, üzerinde çalışılırken hiçbir şeyin test edilmediğinin ilk işareti.

Bu disiplini kurmak uzun mu sürüyor?
Bir CLAUDE.md dosyası yazmak ve build/typecheck komutlarını netleştirmek bir öğleden sonra işi. Asıl zaman, ilk birkaç görevde kuralları netleştirmeye gidiyor; ondan sonrası tekrar eden bir kalıp.

Devraldığımız projelerde en çok eksik olan da genelde bu: kod çalışıyor ama hangi görevin nasıl doğrulandığına dair hiçbir iz yok. Cursor, Claude Code ve Windsurf'ü karşılaştırdığımız yazıda araç seçimini, geliştirici arama rehberinde bu izin hiç olmadığı bir projeyi devralırken nelere bakılacağını ayrı ayrı ele aldık; burada anlatılan akış olmadan devralınan bir proje genelde yapay zeka projesi tamamlama işimizin ilk haftasında yeniden kuruluyor.