Claude Code, kökteki CLAUDE.md dosyasını oturum başında context’e alıyor. Bu dosyaya bütün servislerin test kurallarını, kişisel ayarlarınızı ve görev tariflerini eklediğinizde, basit bir değişiklik için bile ilgisiz talimatlar yükleyebilirsiniz. Dosyaları ayırırken hangi içeriğin ne zaman yüklendiğini de belirlemek gerekiyor.

Ben küçük bir projeye başlarken kısa bir CLAUDE.md tercih ederim. İhtiyaç büyüdüğünde dosya kapsamlı kuralları, tekrar kullanılan işleri ve çalıştırma ayarlarını ayrı tanımlarım. Burada aynı ayrımı örnek bir TypeScript projesi üzerinden kuracağız.

CLAUDE.md içinde ne kalmalı?

Projenin amacı, temel test komutları ve bütün kod tabanını ilgilendiren kararlar burada durabilir. Örneğin bağımlılık yönetiminde npm ci kullanılması veya değişen davranış için test eklenmesi genel talimattır. Sadece API katmanına ait hata yanıtı sözleşmesini her frontend işine taşımaya gerek yok.

Resmi belgenin önerisi, her CLAUDE.md dosyasını 200 satırın altında tutmak. Bu bir ürün limiti değil, context kullanımı ve talimatlara uyum için verilen hedef. Sosyal medyadaki farklı satır sayılarını teknik sınır gibi almamak lazım.

Dosyayı @docs/testing.md ile parçalara bölmek okunmasını kolaylaştırabilir. Fakat import edilen içerik de yüklenir, dolayısıyla import tek başına context maliyetini azaltmaz. Yalnız belirli dosyalarda gerekli olan talimatı koşullu rule olarak yazmak daha uygun.

Proje ağacını sorumluluklara göre ayırın

Aşağıdaki yapı bir başlangıç örneği. Mevcut projenizdeki dizinlere göre uyarlayın, henüz kullanmayacağınız agent veya MCP bağlantısı için boş dosyalar açmayın.

Kökteki .mcp.json bağlantı tanımlarını taşır. .claude/settings.json ekiple paylaşılacak ayarlardır; settings.local.json sizin bu projedeki kişisel tercihleriniz içindir. Dosyayı elle oluşturduysanız .gitignore içine .claude/settings.local.json ekleyin. Claude Code’un kendi oluşturduğu dosyaya uyguladığı dışlama davranışına güvenip elle yazdığınız dosyanın da otomatik dışlandığını varsaymayın.

Claude Code örnek projesinin gerçek dosya listesi ve yerel doğrulama sonucu
Bu yazı için oluşturulan örnek dosyalar yerel olarak doğrulandı. Gerçek doğrulama çıktısı görsele dönüştürüldü; Claude Code arayüzü değildir.

Görsel, bu yazı için hazırlanan örnek dosyaların yerel doğrulama çıktısından oluşturuldu; Claude Code arayüzü değildir. Yapının dayanağı resmi settings belgesi.

Rules dosyasının kapsamı nasıl belirlenir?

.claude/rules/api.md içinde YAML frontmatter ile dosya eşleşmesi tanımlayabilirsiniz. Örneğin aşağıdaki kural yalnız src/api altındaki TypeScript dosyalarıyla çalışırken yüklenir.

paths yazmadığınız rule dosyaları koşulsuz yüklenir. Yirmi ayrı dosya açıp hepsini koşulsuz bırakırsanız dosya düzeni iyileşir, yüklenen talimat miktarı kendiliğinden azalmaz. Ben kapsamı dosya türünden çok gerçek sorumluluğa göre seçmeyi öneririm; bütün .ts dosyalarına API kuralı uygulamak gereksiz geniş olur.

Kuralı test ederken eşleşen bir API dosyasıyla başlayın. Sonra frontend dosyası üzerinden aynı kontrolü yapın. Yanlış glob, beklenen talimatın hiç yüklenmemesine veya ilgisiz işlerde devreye girmesine neden olabilir.

Skill ile agent aynı işi mi yapar?

Skill, tekrar kullanacağınız görev tarifini ve destek dosyalarını birlikte tutar. .claude/skills/test-api/SKILL.md için description alanında ne zaman kullanılacağını açık yazabilirsiniz. Kullanıcı başlatmadan çalışmaması gereken işlerde disable-model-invocation: true seçeneği var.

Bu örnek /test-api komutuyla çağrılır. test:api her Node.js projesinde bulunan standart komut değildir, bu yüzden tanımını kontrol ediyoruz. Skills belgesi, eski .claude/commands/*.md dosyalarının çalışmayı sürdürdüğünü de söylüyor. Yeni işlerde skills yapısını tercih edebilirsiniz; commands ve skills için iki ayrı zorunlu sistem kurmanız gerekmiyor.

Subagent ise ayrı context içinde verilen görevi yürütür. Örneğin reviewer.md dosyasında name, description ve tools: Read, Grep, Glob tanımlayarak dosya incelemeye odaklı bir ajan hazırlayabilirsiniz. Ona beklenen çıktı biçimini de söyleyin: dosya yolu, bulgu ve gerekçe.

Ayrı context, ayrı kullanım kotası anlamına gelmez. Küçük bir dosyayı incelemek için agent açmak ek maliyet getirebilir. Ben bunu uzun arama çıktısını ana konuşmadan uzak tutmak veya sınırları belli bir inceleme görevi vermek gerektiğinde kullanmayı öneririm.

Talimat ile uygulanan kontrolü ayırın

CLAUDE.md içine gizli dosyaları okuma yazmak davranış talimatıdır. Memory belgesi bunu zorunlu uygulanan yapılandırmadan ayırır. İzin politikaları, uygun PreToolUse hook’ları ve işletim sistemi düzeyindeki kısıtlar ayrıca tasarlanmalıdır.

.claude/hooks/check-edit.py dosyasını oluşturmak hook’u etkinleştirmez. Hook yapılandırmasında olayın, eşleşecek aracın ve çalıştırılacak komutun kaydı gerekir. Script araç girdisini okumalı, desteklenen çıkış kodlarını kullanmalı ve izin verilen işlemle engellenmesi beklenen işlem için ayrı ayrı test edilmelidir.

Örnek hook'un izin verilen ve engellenen dosya yollarında gerçek test çıktısı
Örnek hook script'i üç JSON girdisiyle doğrudan çalıştırıldı. İzin ve ret sonuçları gerçek test çıktılarıdır; tam Claude Code oturumu değildir.

Görseldeki kontrol, örnek script’in doğrudan çalıştırılmasıdır; tam Claude Code oturumu veya güvenlik sertifikasyonu değildir. Olay ve çıkış kodlarının kaynağı hooks belgesidir.

MCP tarafında da aynı dikkat gerekiyor. .mcp.json içine HTTP sunucusu eklerken type: http ve gerçek sunucu adresini belirtin. Kimlik bilgisini dosyaya gömmeyin, desteklenen ortam değişkeni genişletmesini kullanın. MCP belgesindeki proje kapsamı ve onay davranışını bağlantıyı paylaşmadan önce kontrol edin.

Aşağıdaki JSON yalnız yerel bir geliştirme sunucusunun yapılandırma örneği. Bu adresin çalışması için kendi MCP sunucunuzun belirtilen portta ve yolda dinliyor olması gerekir.

Dosyayı repoya eklemek sunucuyu kurmaz, başlatmaz veya erişim yetkisi vermez. Başka bir geliştirici aynı dosyayı aldığında adres kendi bilgisayarını gösterir. Takım bağlantısı için ortak bir endpoint gerekiyorsa kimlik doğrulamasını ve erişim kapsamını ayrıca tanımlayın. JSON’un geçerli olmasıyla bağlantının gerçekten kullanılabilir olması farklı kontrollerdir.

İlk değişikliği mevcut dosyanızda yapın

  • Her oturumda gerekli talimatları CLAUDE.md içinde bırakın.
  • API’ye özel kuralı dar bir paths eşleşmesiyle taşıyın.
  • Paylaşılacak ayarlarla kişisel ayarların Git durumunu kontrol edin.
  • Hook eklediyseniz hem izin hem ret sonucunu doğrulayın.

Skill sistemi yazısındaki görev tariflerini bu yapıya eklerken her dosyanın gerçekten ne zaman yüklendiğine bakın. Bir sonraki oturumda aynı API değişikliğini tekrar denemek, yeni klasör ağacını seyretmekten daha yararlı bir kontrol olacaktır. Sorularınız olursa yorumlarda buluşalım.

Diğer yazılara da göz atabilirsiniz

Yorum Bırakın