Etkili CLAUDE.md Dosyaları Oluşturma

Claude Code ile Yazılım Geliştirme

Dani Zysman

AI Curriculum Manager @ DataCamp

CLAUDE.md En İyi Uygulamaları

/init ile başla, sonra yinele
- Claude hata yaptığında bağlam ekle
- Kural/değer değişikliklerini dahil et
Amaç: Projenle birlikte gelişen yaşayan bir belge

Projede Şu Ana Kadar

music-analytics-api/
  app.py           # Uygulama giriş noktası
  routes.py        # API uç noktaları
  models.py        # Artist/Album modelleri
  analytics.py     # İstatistik fonksiyonları
  middleware.py    # İstek günlüğü
  config.py        # Oturum ayarları
  CLAUDE.md        # <- Proje hafıza dosyası

CLAUDE.md'ye Neler Girer, Neler Girmez

recraft: CLAUDE.md içine ne girer, ne girmez

Kural: Yapışkan nottan uzunsa, yeri değil.

CLAUDE.md Üzerinde Yineleme

> /artists uç noktasına hata yönetimi ekle.

Tamam. /artists için hata yönetimi ekledim (routes.py:9-19):
- Alma ve serileştirmeyi saran try-except bloğu
- Veri deposu başlatılmadıysa AttributeError yakalayıcı
- 500 durumuyla hata detaylarını dönen genel yakalayıcı

return jsonify({'error': f'Failed to retrieve artists: {str(e)}'}), 500

> İstisna detaylarını kullanıcılara gösterme, bu güvenlik riski. İçeride logla 
ve genel bir mesaj döndür. CLAUDE.md'yi güncelle.

/artists içini, hataları içerde loglayıp genel bir 
500 mesajı döndürecek şekilde güncelledim. CLAUDE.md şu kuralla güncellendi: 
yanıtlarda asla istisna detaylarını gösterme.

İyi vs. Şişkin CLAUDE.md

Şişkin (200+ satır)

# Inventory API
Bu, Flask ile oluşturulmuş bir Envanter Yönetimi 
API'sidir...

## Tüm Kaynak Kod
### routes.py
from flask import jsonify...
[dosyanın tamamı yapıştırılmış]

### models.py
[dosyanın tamamı yapıştırılmış]

## API Dokümantasyonu
GET /items döner...

İyi (15 satır)

# Inventory API
Envanter için Flask REST API.

## Komutlar
- Çalıştır: flask run --port 5001
- Test: pytest tests/

## Kurallar
- Tür ipuçlarını (type hints) kullan
- Rotaları ince tut

Dosya Referansları - @ Kullanımı

> @routes.py bu API'nin hangi uç noktaları var?

API Uç Noktaları (6 GET rota)

Sanatçılar
- GET /artists              Tüm sanatçılar
- GET /artists/<id>         ID ile tek sanatçı
- GET /artists/<id>/albums  Bir sanatçının albümleri
Albümler
- GET /albums               Tüm albümler
- GET /stats/albums         Albüm popülerliği istatistikleri
- GET /stats/average-tracks Albüm başına ortalama parça sayısı

Tüm uç noktalar JSON döner.

CLAUDE.md + @ Birlikte

# CLAUDE.md - Music Analytics API
Sanatçılar, albümler ve istatistikler için uç noktalar sağlayan, müzik veri analitiğine yönelik Flask tabanlı bir REST API.
...

## Ana Dosyalar

@routes.py - API uç noktası tanımları
@models.py - Bellek içi depolu Artist ve Album veri modelleri
...

CLAUDE.md kalıcı bağlam verir. Ana dosyalarını Claude'un her zaman bilmesi için @ kullan.

Üç Bağlam Düzeyi

CLAUDE.md bağlamının üç düzeyi

Hangisini Ne Zaman Kullanmalı

CLAUDE.md (proje, paylaşılan)
- Test komutları, kodlama kuralları, proje yapısı
CLAUDE.local.md (proje, kişisel)
- Yerel yollar, API anahtarları, kişisel iş akışı tercihleri
~/.claude/CLAUDE.md (genel, kişisel)
- Tüm projelerde stil tercihlerin
- Hep istediğin varsayılan davranışlar

Bölüm 1 Özeti

/init veCLAUDE.md → Kalıcı proje bağlamı
Shift+Tab veya /plan → Plan modunu aç/kapat
think ... ultrathink → Derin akıl yürütme (5 seviye)

Hadi pratik yapalım!

Claude Code ile Yazılım Geliştirme