Claude Code ile Yeni Bir Proje Kurma Rehberi (Tam Kılavuz)

Bu rehber,  adım adım, Türkçe ve uygulamaya hazır şekilde hazırlanmıştır. Claude Code’u (Anthropic’in yerel AI kodlama ajanı) sıfırdan kurup, profesyonel bir proje yapısına kavuşturacaksınız.

1. Claude Code Nedir ve Neden Kullanmalısınız?

Claude Code, klasik Claude sohbetinden farklı olarak:

• Proje klasörünüzdeki dosyaları okuyabilir
• Kod yazabilir, düzenleyebilir ve çalıştırabilir
• Komut satırı araçlarını kullanabilir
• Kalıcı hafıza (CLAUDE.md) ile projenizi “hatırlar”

Avantajı: Geliştirme hızınızı ciddi oranda artırır. Ancak güvenlik için her zaman “Plan Modu”nu kullanmanızı öneririm.

2. Kurulum (2 Dakikada Tamamlanır)

Önerilen Yöntem: Native Installer (Node.js gerektirmez)

macOS / Linux:

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

Kurulum Sonrası Kontrol:

claude --version

İlk kez çalıştırdığınızda tarayıcıda OAuth ile giriş yapmanız istenir (Claude Pro, Max, Team veya Enterprise aboneliği gereklidir).

Alternatif Yöntemler:

• macOS (Homebrew): brew install –cask claude-code
• Windows (WinGet): winget install Anthropic.ClaudeCode

Not: Eski npm install -g @anthropic-ai/claude-code yöntemi artık deprecated (kullanımı önerilmez). Zaten kuruluysa claude install komutuyla native sürüme geçebilirsiniz.

3. İlk Oturum – Proje Başlatma

1. Proje klasörünüze gidin:
   Bash

   cd /path/to/your-project
2. Claude Code’u başlatın:
   Bash

   claude
3. En önemli ilk adım: /init komutunu çalıştırın.
   • Claude projenizi tarar
   • Dosya yapısını analiz eder
   • Başlangıç CLAUDE.md dosyasını oluşturur

Önerilen İş Akışı (Explore → Plan → Implement → Commit):

• Önce projenizi keşfetmesini isteyin (“Bu projenin mimarisini özetle”)
• Plan Modu’na geçin → Shift + Tab
• Claude’un yapmayı planladığı değişiklikleri inceleyin
• Onay verdikten sonra uygulamaya geçsin

Plan Modu neden bu kadar önemli? Claude’un yapacağı değişiklikleri önceden görmenizi sağlar. Bu, büyük hataları önleyen en güçlü güvenlik mekanizmasıdır.

Yararlı Komutlar:

4. CLAUDE.md Dosyasını Oluşturma (En Kritik Adım)

CLAUDE.md, Claude’un her oturum başında okuduğu kalıcı hafıza dosyasıdır. Bu dosya ne kadar iyi olursa, Claude o kadar doğru ve tutarlı çalışır.

Tavsiye edilen uzunluk: 60-80 satır (daha uzun olursa Claude bazı talimatları önemsemez).

Örnek CLAUDE.md Şablonu (WHY / WHAT / HOW)

Markdown

# Proje: TaskFlow API Node.js tabanlı, modern bir görev yönetim API’si. Kullanıcıların görev oluşturup takip etmesini sağlar. ## Tech Stack - Node.js 20 + TypeScript - Express 4 - PostgreSQL + Prisma ORM - Jest + Supertest (test) - ESLint + Prettier ## Komutlar - `npm run dev` → Geliştirme sunucusunu başlatır (port 3000) - `npm test` → Tüm testleri çalıştırır - `npm run test:watch` → Watch modunda test - `npm run lint` → Kod kalitesini kontrol eder - `npm run build` → Production build alır ## Kurallar - Async/await kullan (raw Promise yerine) - Named export tercih et - Hata yanıtları RFC 7807 formatında olsun

En İyi Uygulamalar:

• Kod stili kurallarını buraya yazmayın → ESLint/Prettier kullansın
• Dosyayı yaşayan bir belge gibi tutun (mimari değişikliklerinde güncelleyin)
• Büyük projelerde @docs/kurallar.md gibi import’lar kullanabilirsiniz

Gelişmiş Özellikler:

• .claude/rules/ klasörü → Konuya özel kurallar
• CLAUDE.local.md → Sadece size özel ayarlar (.gitignore’a otomatik eklenir)
• Auto Memory → ~/.claude/projects/<proje-adı>/memory/ klasöründe otomatik kaydedilir

5. Beceriler (Skills) ile Özel Komutlar Oluşturma

Claude Code’a tekrar eden iş akışlarını öğretebilirsiniz.

Konum: .claude/skills/ klasörü

Örnek: Test Düzeltme Becerisi (fix-tests SKILL.md)

--- name: fix-tests description: Başarısız testleri analiz edip düzeltir allowed-tools: Read, Grep, Bash(npm test *) --- When fixing tests: 1. Test suite'i çalıştır ve hataları tespit et 2. Hatalı test dosyalarını ve test edilen kodu oku 3. Sorunun testte mi yoksa implementasyonda mı olduğunu belirle 4. Minimal değişikliklerle sorunu çöz 5. Testleri tekrar çalıştırarak doğrula Focus on: $ARGUMENTS

Kullanımı:

/fix-tests src/features/auth/

Şu anda 1300+ hazır skill mevcut. İsterseniz plugin registry’lerden yükleyebilirsiniz.

6. MCP Sunucuları ile Harici Araçları Bağlama (Güçlü Özellik)

MCP (Model Context Protocol) sayesinde Claude Code veritabanı sorgulayabilir, güncel API dokümanlarına ulaşabilir, tarayıcı otomasyonu yapabilir.

Kurulum:

Bash

claude mcp add context7 -- npx -y @anthropic-ai/context7-mcp@latest

Veya proje kökünde .mcp.json dosyası oluşturun (takım üyeleriyle paylaşılır).

Yeni proje için önerilen başlangıç (2-3 tane):

• Context7 → Güncel API dokümantasyonu
• Playwright → Tarayıcı otomasyonu ve test
• Database MCP → Veritabanı şemasını doğrudan sorgulama

Önemli Uyarılar:

• Maksimum 5-6 MCP sunucusu önerilir (daha fazlası bağlamı şişirir)
• API anahtarlarını ham metin olarak .mcp.json’e yazmayın → Environment variable kullanın

7. En İyi Uygulamalar ve Güvenlik İpuçları

Arayüz Seçenekleri:

• Terminal → En güçlü ve tam özellikli
• VS Code Extension → Inline öneriler + diff görünümü
• JetBrains desteği de mevcut

8. Takımınızla Paylaşma

CLAUDE.md, .claude/skills/ ve .mcp.json dosyalarını Git’e ekleyin. Takım üyeleri projeyi klonladığında aynı kurulum otomatik olarak gelir.

Tasarımcı, PM veya QA gibi teknik olmayan ekip üyeleri için ise Builder 2.0 gibi araçlar Claude Code bağlamını buluta taşıyarak herkesin aynı proje hafızasına sahip olmasını sağlar.

Hızlı Başlangıç Checklist

• Native installer ile Claude Code’u kur
• Proje klasöründe git init yap
• claude komutunu çalıştır → /init yap
• CLAUDE.md dosyasını WHY/WHAT/HOW formatında doldur
• Plan Modu’nu dene (Shift + Tab)
• Gerekli MCP sunucularını ekle
• .claude/skills/ klasörünü oluştur (opsiyonel ama önerilir)