Tugrul Erdem

CLAUDE.md Nasıl Yazılır: Claude Code'u Kurallara Uymaya Zorlamak

February 19, 2026

Originally published on Medium — this is a mirror.

Bu yazı, claude-task-workflow sürecimden esinlenerek ve Claude Code ile geliştirme yaparken bizzat yaşadığım audit-fix döngüsünden çıkmak için kurduğum sistemin bir özeti.

1. Tavsiye Dosyası Değil, "Anayasa"

Çoğu CLAUDE.md rehberi genellikle şu tarz esnek öneriler sunar:

"Performans optimizasyonu için React.memo kullanın."

Bu bir tavsiyedir. AI, bağlam (context) kalabalıklaştığında tavsiyeleri unutabilir veya karmaşık görevler sırasında bunları atlayabilir. Bunun yerine, esneklik payı bırakmayan kesin kurallar (hard constraints) yazmalısınız:

"Dışa aktarılan (exported) her bileşen React.memo ile sarmalanmalıdır. İstisna yoktur. Bu kural ihlal edilirse görev tamamlanmamış sayılır."

Aradaki fark küçük görünse de AI davranışı üzerindeki etkisi büyüktür. Kural ihlali ölçülebilirdir; tavsiye ihlali ise yoruma açıktır. CLAUDE.md içerisindeki her kuralı şu formatta yapılandırmanızı öneririm:

1.1 — React.memo Zorunluluğu

Dışa aktarılan her bileşen React.memo ile sarmalanmalıdır. İstisna yoktur.

// ❌ YASAK (FORBIDDEN)
export function ArtworkCard({ artwork }: ArtworkCardProps) { ... }

// ✅ ZORUNLU (REQUIRED)
export const ArtworkCard = React.memo(function ArtworkCard({
  artwork,
}: ArtworkCardProps) { ... });
ArtworkCard.displayName = 'ArtworkCard';

❌ FORBIDDEN ve ✅ REQUIRED gibi ifadeler, AI için güçlü birer örüntü (pattern) niteliğindedir ve kod üretirken hatalı yapılardan kaçınmasını sağlar.

2. Her Görev Sonunda Self-Audit

Eskiden her özellik geliştirmesinden sonra ayrı bir denetim süreci çalıştırıyordum. Bunun ayrı bir aşama olmaması gerektiğini, denetimin bizzat görevin bir parçası olması gerektiğini geç fark ettim.

CLAUDE.md dosyama bir Self-Audit Checklist bölümü ekledim:

"Her görevden sonra bu listeyi çalıştır. Tüm maddeler ✅ olmadan görev tamamlanmış sayılmaz."

Self-Audit Checklist — Bileşenler (Components)

  • [ ] Yeni bileşenler React.memo ile sarmalandı mı?
  • [ ] displayName tanımlandı mı?
  • [ ] Bileşen içinde fetch veya iş mantığı (business logic) var mı? (Olmamalı)
  • [ ] Fonksiyon prop'ları üst bileşende useCallback ile sarmalandı mı?

Her görevin sonunda AI bu listeyi kendisi tarar ve eksikleri tamamlamadan işi teslim etmez.

3. İş Akışı Sıralaması: PRD'den Koda

Özellik geliştirmeyi rastgele başlatmak yerine, her süreç belirli bir disiplinle yönetilmeli:

1. types/          → Arayüz ve tip tanımlamaları
2. i18n/           → Metin sabitleri
3. events/         → Analitik etkinlik tipleri
4. [Checklist]     → Bu özellik için hangi kurallar geçerli? Listele.
5. hooks/          → İş mantığı (Business logic)
6. components/     → Sadece arayüz (Render)
7. [Self Audit]    → Kontrol listesini çalıştır

AI'yı o anki özellik için geçerli kuralları listelemeye zorlamak, sonraki adımlarda hata yapma payını minimize eder.

4. Nested CLAUDE.md

Tek bir CLAUDE.md dosyasına her şeyi yüklemek, context window'u gereksiz yere şişirir. Arayüz yazarken servis kurallarına, servis yazarken liste performans kurallarına ihtiyacımız yoktur.

Claude Code, dizin hiyerarşisine göre otomatik olarak yüklenen katmanlı (nested) yapıları destekler:

project-root/
├── CLAUDE.md                 ← Global kurallar
│
└── src/
    ├── components/
    │   └── CLAUDE.md         ← Sadece UI yazarken yüklenir
    ├── hooks/
    │   └── CLAUDE.md         ← Hook yazarken yüklenir
    └── services/
        └── CLAUDE.md         ← Servis yazarken yüklenir
  • root/CLAUDE.md → Global kurallar: TypeScript standartları, iş akışı, platform kısıtlamaları.
  • src/components/CLAUDE.md → Sadece render katmanı; React.memo, animasyon izolasyonu ve FlatList kuralları.
  • src/hooks/CLAUDE.md → İş mantığı katmanı; useEffect temizliği, veri yükleme ve sayfalama kuralları.

Claude Code ilgili dizinde bir dosya açtığında kuralları üst üste ekler (stacking): root → src → components. Böylece AI, sadece ihtiyacı olan bilgiyle çalışır.

5. Referans Verme, Doğrudan Tanımla

CLAUDE.md içerisinde "şu dokümana bak" demek genellikle verimsizdir. AI referansı takip etmeyebilir veya dökümanın hangi kısmının o an geçerli olduğuna yanlış karar verebilir. Kural, doğrudan dosya içinde ve kısa bir kod örneğiyle yer almalıdır.

4.1 — Global Mutable State Yasaktır

// ❌ ASLA YAPMAYIN
let hasConfigured = false;

// ✅ Promise Guard Kullanın
let _initPromise: Promise<void> | null = null;
export async function initService(): Promise<void> {
  if (_initPromise) return _initPromise;
  _initPromise = _doInit();
  return _initPromise;
}

6. Yeni Kural Eklemek: Geri Bildirim Döngüsü

Denetim raporunda tekrarlayan bir hata fark ettiğinizde, bunu sadece düzeltip geçmeyin; o hatayı bir kurala dönüştürün:

// ❌ FORBIDDEN
[kötü örnek]

// ✅ REQUIRED
[iyi örnek]

Checklist'e ekle: - [ ] [Kontrol sorusu]

Denetim → Kural → Checklist döngüsü, zamanla projenizin anayasasını teorik bilgilerden değil, bizzat yaşanmış hatalardan inşa etmenizi sağlar.

Sonuç

  • Kurallar tavsiye değil, kısıt (constraint) olmalıdır. AI, "yapmalısın" yerine "yapmazsan bitmedi" yaklaşımını daha iyi kavrar.
  • Bağlam, ilgili dizinde tutulmalıdır (Nested CLAUDE.md).
  • Denetim, sürecin dışında değil, tam merkezinde olmalıdır.

Bu sistem de mükemmel değil; AI bazen kuralları atlayabilir. Ancak "ne zaman hata çıkacak?" belirsizliği yerine "hangi kuralı ihlal etti?" netliğine sahip olmak, geliştirme sürecini çok daha öngörülebilir kılıyor.