CLAUDE.md Kullanım Kılavuzu: En İyi Uygulamalar ve Prensipler

CLAUDE.md, bir AI ajanını (örneğin Claude) projenizin kod tabanına ve iş akışına sorunsuz bir şekilde entegre etmek için kullanılan, proje‑özel talimatları ve bağlamı tanımlayan bir markdown dosyasıdır.

CLAUDE.md Nedir? Neden Önemlidir?

Yapay zeka destekli kodlama asistanları, özellikle OpenAI ChatGPT integration ve ChatGPT and Telegram integration gibi modern araçlarla geliştiricilerin iş akışını hızlandırıyor. Ancak bu asistanlar, oturum başına “stateless” (durumsuz) bir model olarak çalışır; yani her yeni oturumda kod tabanınız hakkında hiçbir bilgiye sahip değildir. İşte bu noktada CLAUDE.md devreye girer: Ajanı, projenizin mimarisi, teknolojik yığını ve çalışma kurallarıyla “onboard” eder.

Bu makalede, CLAUDE.md’nin temel ilkelerini, en iyi uygulamalarını ve gerçek dünyada nasıl kullanılacağını adım adım inceleyeceğiz. Teknik profesyoneller, geliştiriciler ve pazarlama ekipleri için hazırlanmış bu rehber, AI ajanı dokümantasyonunu optimize ederek zaman ve maliyet tasarrufu sağlamayı hedefliyor.

CLAUDE.md Nedir?

CLAUDE.md, AGENTS.md gibi açık kaynaklı eşdeğerleriyle aynı amaca hizmet eden bir dosyadır. Dosya, her oturumda otomatik olarak ajana enjekte edilen bir system‑reminder içerir ve aşağıdaki üç temel soruya yanıt verir:

• WHAT (Ne?): Projenizin teknoloji yığını, klasör yapısı ve önemli bileşenleri.
• WHY (Neden?): Projenin amacı, iş hedefleri ve kodun hangi problemleri çözdüğü.
• HOW (Nasıl?): Ajanın kodu nasıl derleyeceği, test edeceği ve doğrulayacağı.

Bu bilgiler, ajanın bağlamını oluşturur ve ona doğru kararlar alması için gerekli zemini hazırlar.

Temel İlkeler ve Yönergeler

1. Statik ve Dinamik Bağlamı Ayırın

LLM’ler (Large Language Models) stateless olduğundan, statik bilgiler (örnek: proje yapısı, kullanılan diller) CLAUDE.md’de yer almalı. Dinamik bilgiler (örnek: geçici ortam değişkenleri, anlık test komutları) ise ayrı markdown dosyalarına (ör. running_tests.md) konulmalı ve CLAUDE.md’de sadece referans verilmelidir.

2. “Az, çoktur” Prensibi

Modelin aynı anda işleyebileceği talimat sayısı sınırlıdır. Araştırmalara göre, 150‑200 talimat arasında tutulan bir bağlam, yüksek tutarlılık sağlar. Bu yüzden gereksiz kod stil rehberleri, uzun komut listeleri ve tekrarlayan açıklamalardan kaçının. Örneğin, About UBOS sayfasında yer alan şirket vizyonu gibi bilgiler bir kez yeterlidir.

3. Progressive Disclosure (Aşamalı Açıklama)

Projeniz büyükse, tüm detayları tek bir CLAUDE.md dosyasına sığdırmak zor olur. Bunun yerine, görev‑özel dosyalar oluşturun ve CLAUDE.md’de bu dosyaların bir listesini sunun. Ajan, ihtiyacı olduğunda ilgili dosyayı okuyarak bağlamı genişletebilir. Örnek bir yapı:

agent_docs/
├─ building_the_project.md
├─ running_tests.md
├─ code_conventions.md
└─ service_architecture.md
    

Bu yaklaşım, Workflow automation studio gibi otomasyon araçlarıyla da entegre edilebilir; ajana hangi dosyayı okuması gerektiği sorulup onay alınabilir.

4. Doğrulama ve Geri Bildirim Mekanizmaları

CLAUDE.md, ajanın yaptığı değişiklikleri nasıl test edeceğini de tanımlamalıdır. Örneğin:

• Derleme komutu: bun run build
• Test komutu: npm test -- --watchAll=false
• Tip kontrolü: tsc --noEmit

Bu komutları doğrudan CLAUDE.md’ye eklemek yerine, UBOS templates for quick start içinde bir scripts.md dosyası oluşturup referans vermek daha sürdürülebilir bir yöntemdir.

En İyi Uygulamalar

A. Kısa ve Odaklı Tutun

İdeal bir CLAUDE.md dosyası 60‑80 satır arasında olmalıdır. Örnek bir giriş bölümü:

# CLAUDE.md – Proje Onboarding
## WHAT
- Monorepo içinde 3 mikroservis: auth, payments, analytics.
- Tech stack: Node.js (v18), Bun, TypeScript, Prisma.
## WHY
- Kullanıcı kimlik doğrulama ve ödeme iş akışlarını otomatize etmek.
## HOW
- `bun install` → `bun run dev` → `npm test`.
    

B. Bağlamı Güncel Tutun

Proje yapısı değiştiğinde CLAUDE.md’yi güncellemek kritik bir adımdır. Otomatik güncellemeler için Web app editor on UBOS kullanarak CI/CD pipeline’ınıza bir adım ekleyebilirsiniz. Böylece her yeni sürümde dosya otomatik olarak revize edilir.

C. Linter ve Formatter’ı Ayrı Tutun

Kod stil kurallarını CLAUDE.md’ye eklemek, modelin bağlamını gereksiz yere şişirir. Bunun yerine, UBOS partner program kapsamında bir linter (ör. Biome) ve otomatik formatlayıcı kurun. Ajan, git diff üzerinden sadece hatalı dosyaları alır ve düzeltir.

D. Otomatik Oluşturulmuş Dosyalardan Kaçının

UBOS platformu, Telegram integration on UBOS gibi entegrasyonlar için CLAUDE.md şablonları sunar. Ancak bu şablonlar genellikle “genel” talimatlar içerir ve projenize özgü bağlamı yansıtmaz. Kendi dosyanızı elle oluşturmak, yüksek etki ve düşük hata oranı sağlar.

E. Çoklu Dil ve Çevrim İçi Çözüm

Uluslararası ekiplerde, CLAUDE.md’nin birden fazla dilde (ör. İngilizce + Türkçe) bulunması faydalıdır. ElevenLabs AI voice integration sayesinde, dosyanın içeriği sesli olarak da sunulabilir; bu da yeni ekip üyelerinin hızlı onboarding’ini destekler.

F. Gerçek Zamanlı Geri Bildirim Döngüsü

CLAUDE.md’nin etkisini ölçmek için AI marketing agents gibi izleme araçlarıyla “başarı metriği” tanımlayın: ör. “Ajana verilen talimatların %90’ı doğru uygulanıyor mu?”. Bu metrik, dosyanın revizyon sıklığını belirlemenize yardımcı olur.

Sonuç ve Öneriler

CLAUDE.md, AI ajanlarını projenizin kalbinde “görünür” kılan kritik bir köprüdür. Doğru yapılandırıldığında, aşağıdaki faydaları sağlar:

• Yeni bir oturumda bile ajanın kod tabanını anında “okuması”.
• Talimat çakışmalarını ve bağlam aşırı yüklemesini önleyerek daha tutarlı sonuçlar.
• Geliştirici verimliliğini %30‑40 artırma potansiyeli.
• CI/CD süreçlerine entegrasyon sayesinde sürekli güncel dokümantasyon.

Özetle, az talimat, net bağlam, aşamalı açıklama prensiplerini benimseyin ve CLAUDE.md’yi UBOS pricing plans içinde sunulan Enterprise AI platform by UBOS ile otomatikleştirin. Böylece hem teknik ekipleriniz hem de pazarlama ekipleriniz, AI ajanlarından maksimum verim alır.

Unutmayın, CLAUDE.md sadece bir dosya değil, AI‑first geliştirme kültürünüzün temel taşıdır. Doğru bir başlangıç, uzun vadeli başarıyı garantiler.

Görsel ve Ek Kaynaklar

Aşağıdaki görsel, UBOS ekosisteminde CLAUDE.md’nin nasıl bir konumda olduğunu gösterir:

İlgili diğer kaynaklar:

• UBOS solutions for SMBs
• UBOS for startups
• UBOS portfolio examples
• AI SEO Analyzer
• AI Article Copywriter

Orijinal makale ve daha fazla teknik detay için orijinal kaynağa göz atabilirsiniz.