Claude Code best practices: üretimde bir yılın süzülmüş kuralları

Claude Code'u bir yıl boyunca gerçek müşteri projelerinde çalıştırdıktan sonra elimizde kalan şey internette dolaşan genel bir tavsiye listesi değil, dört kural: CLAUDE.md'yi kısa ve kapsamı sınırlı tutmak, agent'ın "bitti" demesine değil kendi çalıştırdığın komuta güvenmek, ödeme, migration ve secret işini asla agent'a tek başına bırakmamak, görevi vermeden önce planı yazılı hale getirmek. Her kuralın altında bir neden var: ya bir aksilik ya da ölçülebilir bir kazanım.

Bu yazı, Claude Code'u gerçekte nasıl kullandığımızı anlattığımız yazının kural referansı. O yazı akışı baştan sona anlatıyor, burada sadece kurallar ve her birinin arkasındaki gerekçe var.

Kural 1: CLAUDE.md tek kaynaktır ama her şeyi yazmaz

CLAUDE.md, Claude Code'un her oturumun başında okuduğu tek dosya, dolayısıyla işi gerçekten davranışı değiştiren şeyi taşımak: projenin tek satırlık tanımı, değişmeyen stack, yasaklı araç ve kalıplar, işin hangi sırayla ilerlediği ve hangi iş için hangi uzman agent'ın çağrıldığı. Taşımaması gereken şey bir wiki sayfası gibi okunan herhangi bir şey, hiçbir credential ya da anahtar, haftadan haftaya değişen herhangi bir karar. Bir sayfayı geçen dosya artık tam okunmuyor, bu da bir dosyaya sahip olmanın amacını ortadan kaldırıyor.

Sıfırdan başlıyorsan CLAUDE.md üretici aracımız aynı kapsamda bir başlangıç dosyası çıkarıyor, kendi yapını baştan kurman gerekmiyor.

Kural 2: agent "bitti" demeden önce komutu sen çalıştır

Bir agent'ın build geçti ya da testler geçti demesi bir iddia, bir doğrulama değil. Kural basit ve kesin: build ve typecheck'i gerçekten bir insan, ya da bir insanın kurduğu bir CI adımı çalıştırıp temiz bittiğini görmeden hiçbir şey birleşmiyor. Bu, en çok zaman kaybettiren hata türünü yakalıyor: bir tip tanımını değiştiren, bununla ilişkisiz üç dosyayı bozan ve hepsini başarılı bir değişiklik olarak anlatan bir agent.

Kural 3: ödeme, migration ve secret agent'a asla tek başına bırakılmaz

Çizdiğimiz çizgi zorluk değil geri dönülebilirlik üzerine. Bir migration yazmak, bir refactor taslağı çıkarmak, bir diff'i incelemek agent'ın iyi yaptığı bir iş ve bunu gözetimsiz çalıştırmasına izin veriyoruz. O migration'ı production veritabanında çalıştırmak, canlı bir ödeme akışına dokunmak ya da bir credential'ı değiştirmek her zaman insanı devreye sokan bir iş, çünkü hata türünün geri alma yolu yok. Bu sınır çizilmediğinde ne olduğunun iki gerçek, herkese açık örneği: Cursor'ın ajanının production veritabanını dokuz saniyede silmesi ve Replit'in ajanında görülen aynı hata kalıbı. İkisi de bizim müşterimiz değildi, ama ikisi de bu kuralın bir müşteride test edilmeden önce neden var olduğunun tam nedeni.

Kural 4: görevi vermeden önce planı yazılı hale getir

Yazılı bir plan olmadan agent'a verilen bir görev, ilk turunu işi yapmak için değil ne istediğini anlamaya çalışmak için harcıyor. Düzeltmesi neredeyse ücretsiz: agent bir satır yazmadan önce kısa bir brief, hedef, ilgili dosyalar, "bitti" sayılmanın tanımı. Bu adımı atlamanın asıl maliyeti başarısız bir görev değil, yanlış problemi çözmüş ama gözden geçirmede yakalanması gereken, kulağa makul gelen bir görev.

Bir yıl boyunca bu kurallar gerçekte neyi önledi

Yukarıda bağlantısı olan hiçbir olay kendi işimizde yaşanmadı, ve asıl nokta da bu: kuralı bir müşterinin production veritabanında test edilmeden önce, bir yazıda yazılı hale getirmek. Bir agent'ın canlı veriyi sildiği ya da bozduğu her kamuya açık örnekte kalıp aynı: agent'ın geri dönüşü olmayan bir şeye kalıcı erişimi vardı ve bir prompt ile o eylem arasında hiçbir insan kontrol noktası yoktu. Kural 3 tam olarak bu kontrol noktasını, agent'ın küçük görevlerdeki geçmiş performansı ne kadar iyi olursa olsun yerinde tutmak için var.

Bu liste ne zaman yetmiyor

Bu dört kural, ekibin CLAUDE.md'yi gerçekten okuduğunu varsayıyor, kimse açmıyorsa kağıt üstünde bir kural, pratikte değil. Tek bir dosya da belli bir repo büyüklüğünü geçince ölçeklenmeyi bırakıyor, büyük bir monorepo her şeyi tek dosyada toplamak yerine paket başına bölünmüş dosyalar istiyor. Ve bunların hiçbiri gerçekten yeni bir karar için insan mimari incelemesinin yerini tutmuyor, yeni bir servis, bir şema değişikliği, yeni bir üçüncü taraf bağımlılığı, bunlar hâlâ "derleniyor mu" için optimize etmeyen bir insanı gerektiriyor. Bu kurallar özellikle Claude Code için yazıldı; ekibin başka bir agent kullanıyorsa ilkeler taşınır ama dosya formatı ve tetikleyiciler değişir, mekaniğin gerçekte nerede farklılaştığını Cursor Claude Code Windsurf karşılaştırmamızda görebilirsin.

Ekibiniz bu dört kuralın hiçbirinin olmadığı bir kod tabanını devraldıysa gördüğümüz tablo tanıdık: demoda çalışan bir uygulama, hiç var olmamış ya da hiç okunmamış bir CLAUDE.md ve soruyu zorlayan bir production olayı. Yapay zeka projesi tamamlama hizmetimiz tam bu devir noktası için var.

Projeniz tam bu noktaya geldiyse yapay zeka projesi tamamlama hizmetimize bakabilirsiniz.

Sık sorulan sorular

CLAUDE.md dosyası gerçekte nerede durmalı?
Repo kökünde .claude/CLAUDE.md olarak. Claude Code bu repoda her oturumun başında dosyayı otomatik okuyor, ek bir ayar gerekmiyor.

Bu kurallar başka bir coding agent kullanıyorsak da geçerli mi?
İlkeler evet: güvenmeden önce doğrula, geri dönüşü olmayan işi delege etme, prompt'tan önce planla. Dosya formatı ve tam tetikleyiciler agent'a göre değişiyor.

Planı ben mi yazmalıyım, yoksa agent önce taslak çıkarsın mı daha iyi?
İkisi de olur, gereken şey bir insanın iş başlamadan önce son planı gözden geçirip onaylaması, her kelimeyi insanın yazmış olması değil.

Force-push gerçekten hiç kabul edilebilir değil mi?
Kendine ait, paylaşılmayan bir feature branch'te, bilerek yaptığında nadiren olur. Paylaşılan bir branch'te hayır, başkalarının üzerine iş kurduğu bir history'yi yeniden yazmanın temiz bir geri dönüşü yok.

Bu kurallar küçük, solo bir proje için de önemli mi?
Ödeme, migration ve secret kuralı ölçekle küçülmüyor. Solo bir projenin veritabanı, gittiğinde büyük bir ekibinki kadar geri dönüşsüz.