Claude Code ile proje: CLAUDE.md, subagent’lar ve Git

Bu derste Claude Code’a projenizin kurallarını CLAUDE.md dosyasıyla kalıcı olarak öğretmeyi, işi yardımcı ajanlara (subagent) devretmeyi ve Git ile değişiklikleri güvenle kaydetmeyi öğreneceksiniz. Böylece her oturumda aynı şeyleri baştan anlatmak zorunda kalmazsınız.

Not: Claude Code için ücretli bir erişim gerekir (Claude aboneliği, Claude Console hesabı ya da desteklenen bir bulut sağlayıcısı). Kurulum bir önceki derste anlatıldı.

Aklınıza bir soru mu takıldı?

Sorunuzu ya da aradığınız konuyu yazın Ders bul

Bu derste neler öğreneceksiniz?

• CLAUDE.md dosyasının ne olduğunu, nereye konduğunu ve nasıl kısa tutulduğunu.
• Subagent’ın ne olduğunu ve bir tanesini nasıl tanımlayacağınızı.
• Claude Code ile Git’te değişiklik görmeyi, dal açmayı ve commit atmayı.

CLAUDE.md: projenin kalıcı notları

Anthropic’in belgesine göre CLAUDE.md, Claude Code’a kalıcı talimat veren bir Markdown dosyasıdır, yani sade bir metin dosyasıdır. Claude her oturumun başında onu okur. Dosya bir kural motoru değil, bağlam olarak yüklenir; bu yüzden uyulması garanti değildir. Kesinlikle her seferinde olması gereken işler için belge “hook” denen ayrı bir düzeneği öneriyor.

Dosyanın konumu, kimin göreceğini belirler:

• ~/.claude/CLAUDE.md: yalnızca siz, tüm projelerinizde.
• ./CLAUDE.md ya da ./.claude/CLAUDE.md: proje için; ekiple kaynak kontrolü üzerinden paylaşılır.
• ./CLAUDE.local.md: yalnızca siz, yalnızca bu projede. Belge bu dosyayı .gitignore’a eklemenizi söylüyor.

Başlamak için oturumda /init yazın. Claude projeyi inceler ve derleme komutlarını, test talimatlarını, kuralları içeren bir başlangıç dosyası üretir. Dosya zaten varsa üzerine yazmaz, iyileştirme önerir. Yüklenen dosyaları görmek için /memory kullanın.

İyi bir CLAUDE.md için belgenin önerileri şöyle:

• Her dosyayı yaklaşık 200 satırın altında tutun. Uzun dosyada kurallara uyma düşer.
• Doğrulanabilir yazın. “Düzgün biçimlendir” yerine “2 boşluk girinti kullan” gibi.
• Yalnızca Claude’un koddan çıkaramayacağı bilgileri yazın: komutlar, kurallar, ekip kararları.
• Çelişen kurallardan kaçının; Claude birini rastgele seçebilir.

# Komutlar
- Testleri çalıştırmak için: npm test

# Kurallar
- Site metinleri Türkçe yazılır, sade ve kısa cümlelerle.
- Telefon ve adres gibi kişisel veriler dosyalara yazılmaz.

# Dikkat
- Yayınlanmış duyuru dosyaları arşiv klasöründedir, değiştirilmez.

Yukarıdaki dosya yalnızca bir örnektir; içeriğini kendi projenize göre değiştirin.

Subagent: yardımcı ajanlar

Belgeye göre subagent, belirli bir iş türü için uzmanlaşmış bir yapay zekâ yardımcısıdır. Kendi bağlam penceresi, kendi talimatı, kendi araç izinleri vardır. Arama sonuçları ya da günlükler gibi ana konuşmanızı dolduracak işleri ayrı yürütür ve size yalnızca özeti döndürür. Claude Code’da Explore (hızlı, salt okunur arama), Plan ve general-purpose adlı hazır subagent’lar da bulunur.

Kendi subagent’ınızı iki yolla oluşturabilirsiniz: Claude’dan istemek ya da dosyayı elle yazmak. Dosya Markdown biçimindedir ve en üstünde iki zorunlu alan bulunur: name (benzersiz ad) ve description (Claude’un bunu ne zaman devreye alacağı). tools ve model isteğe bağlıdır. Dosyayı .claude/agents/ klasörüne koyarsanız yalnızca o projede, ~/.claude/agents/ klasörüne koyarsanız tüm projelerinizde geçerli olur. Belgedeki örnek dosya:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Kullanmak için adını söylemeniz yeterli: Use the code-improver agent to suggest improvements in this project. Claude ayrıca isteğinize ve her subagent’ın description alanına bakarak kendisi de devredebilir. /agents komutunun davranışı sürüme göre değişiyor; yeni sürümlerde Claude’a sormayı ya da dosyaları elle düzenlemeyi hatırlatıyor, eski sürümlerde bir sihirbaz açıyor.

Claude Code ile Git

Git, projenin geçmişini saklayan sürüm kayıt sistemidir. Belgeye göre Claude Code Git işlemlerini konuşma diliyle yapabilir. Quickstart sayfasındaki örnek istekler:

• what files have I changed?: hangi dosyaları değiştirdiğinizi gösterir.
• commit my changes with a descriptive message: değişiklikleri açıklayıcı bir mesajla kaydeder.
• create a new branch called feature/quickstart: yeni bir dal açar. Dal, ana çalışmayı bozmadan denemek için ayrı bir koldur.
• show me the last 5 commits: son beş kaydı listeler.
• help me resolve merge conflicts: birleştirme çakışmalarında yardım eder.

Aynı anda iki işi birbirine karıştırmadan yürütmek için belge claude --worktree feature-auth komutunu gösteriyor. Her worktree kendi dalında ayrı bir çalışma kopyasıdır; depoda en az bir commit olmalıdır. Önceki konuşmanıza dönmek için claude --continue (en son konuşma) ya da claude --resume (listeden seçim) kullanın.

Adım adım uygulama

1. Deneme klasörünüzde claude ile oturumu açın.
2. Git kullanmıyorsanız Claude’dan klasörü Git deposu yapmasını isteyin ve ilk commit’i attırın.
3. /init yazıp oluşan CLAUDE.md’yi okuyun.
4. Gereksiz ya da yanlış satırları silin, kendi kurallarınızı ekleyin; 200 satırı geçmeyin.
5. /memory ile dosyanın yüklendiğini doğrulayın.
6. Örnek komutla bir subagent oluşturup adıyla çağırın.
7. Yeni bir dal açtırıp küçük bir değişiklik yaptırın.
8. Değişiklikleri what files have I changed? ile gözden geçirip commit ettirin.

Kontrol listesi

• CLAUDE.md kısa ve doğrulanabilir kurallardan oluşuyor.
• Dosyada parola, anahtar ya da kişisel veri yok.
• Subagent’ın tools alanını gerekenle sınırladım.
• Commit atmadan önce değişiklikleri okudum.
• Çalışmamı ana dalda değil, ayrı bir dalda denedim.

Sık yapılan hatalar

• Çok uzun CLAUDE.md: Her satır her işte Claude’un dikkatinden pay alır. Koddan anlaşılan şeyleri yazmayın.
• Belirsiz kurallar: “Düzenli ol” gibi cümleler denetlenemez.
• CLAUDE.md’ye sır yazmak: Proje dosyası ekiple paylaşılabilir. Parola, API anahtarı ve kişisel veri koymayın; kişisel veri için KVKK’yı unutmayın.
• Subagent’a gereğinden fazla yetki vermek: tools alanını boş bırakırsanız tüm araçlar devralınır. Salt okuma yeterliyse öyle sınırlayın.
• Güvenmeden commit atmak: Claude’un yazdığı commit mesajını ve değişiklikleri kontrol edin.

Kendinizi deneyin

Videoyla izleyin

Video: Claude (İngilizce). Türkçe altyazı için YouTube’da altyazı ayarını açabilirsiniz.

Kaynaklar

• Memory – Claude Code Docs (İngilizce)
• Create custom subagents – Claude Code Docs (İngilizce)
• Quickstart – Claude Code Docs (İngilizce)
• Common workflows – Claude Code Docs (İngilizce)
• Best practices for Claude Code – Claude Code Docs (İngilizce)

Son kontrol: 7 Kasım 2026

Kaynak: yzdersleri.com/ders/claude-code-proje/ · Yapay Zeka Dersleri