Claude Kod Kılavuzu: Geliştiriciler İçin Tam Başlangıç Rehberi

Anthropic'in güçlü yapay zeka destekli kodlama asistanı Claude Code'a derinlemesine dalıyorsanız, net bir referansa sahip olmak çok önemlidir. Bu Claude Code Hızlı Başvuru Rehberi, kurulum, iş akışları, yapılandırma ve gelişmiş ipuçlarını kapsayan pratik, başlangıç seviyesi dostu bir rehber isteyen geliştiriciler için hazırlanmıştır. Sonunda, Claude Code'u yerel ortamınızda veya CI/CD süreçlerinizin bir parçası olarak kullanırken kendinizi daha güvende hissedeceksiniz.

Claude Code Nedir?

Claude Code, Anthropic tarafından geliştirilen CLI tabanlı bir yapay zeka kodlama aracıdır. Geliştiricilerin Claude'un gelişmiş modellerini kullanarak kod üretmelerine, yeniden düzenlemelerine, test etmelerine ve belgelemelerine olanak tanır. Claude Code, basit bir sohbet arayüzünden ziyade bir yapay zeka IDE'si gibi davranır: depo yapınızı anlar, yapılandırma dosyalarında tanımlanan koruyucu önlemleri uygular, bash komutlarını çalıştırabilir ve Git iş akışlarıyla entegre olur.

Claude Code Yükleme:

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

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

# NPM:
npm install -g @anthropic-ai/claude-code

# Homebrew:
brew install --cask claude-code

Claude Code Kullanmaya Başlama:

cd your-project
claude

Claude Code'un Temel Bileşenleri — Hızlı Başvuru Rehberiniz

Claude Code'u kullanmaya başlarken bilmek isteyeceğiniz temel yapı taşları ve özellikler şunlardır:

1. CLAUDE.md — Ajan Manifestosu

• CLAUDE.md dosyası, ajanınızın "anayasasıdır": Claude'un deponuzda nasıl davranacağını tanımlar.
• Onu onaylanmış araçları, yaygın iş akışlarını ve kısıtlamaları belgelemek için kullanın.
• En iyi uygulama: Kısa tutun, ana koruyucu önlemlere odaklanın ve çok büyük dokümanlar eklemekten kaçının.

# MyProject CLAUDE.md

## Project Overview  
This is a Node.js + Express REST API for a task management application.  

## Technology Stack  
- Backend: Node.js (ES6), Express  
- Database: PostgreSQL  
- Testing: Jest  
- Linting & Style: ESLint, Prettier

## Development Commands  
- `npm install` — Install dependencies  
- `npm run dev` — Start development server  
- `npm run test` — Run all tests  
- `npm run lint` — Run linter  

## Coding Standards  
- Use 2-space indentation.  
- Always use `async / await` instead of `.then()` chains.  
- Functions must have JSDoc comments.  
- Prefer composition over inheritance.

## Git Workflow  
- Feature branches must follow this pattern: `feature/FOO`  
- Use `git rebase` instead of `merge` for updating branches.  
- When committing: write descriptive commit messages that follow the Conventional Commits format.

## File Structure Guidance  
- `src/` — Your main application code  
- `tests/` — Test files  
- `scripts/` — Utility or setup scripts  
- `migrations/` — Database migrations  

## Known Issues / Workarounds  
- `db.connect()` sometimes times out; in that case, retry twice.  
- For large JSON payloads, use streaming to avoid memory issues.

## Memory / Style Preferences  
- Always ask for clarification if the request is ambiguous.  
- Do not generate new `.md` files unless explicitly instructed.  
- Include a `co-authored-by Claude` line in generated commits.

2. Bağlam Yönetimi

a. Mevcut Claude oturumunuzun token kullanımını incelemek için /context kullanın.

b. Bağlamı yeniden başlatma veya küçültme komutları:

• /clear + /catchup: Tüm konuşmayı temizler ve ardından bir commit'ten veya daldan dosyaları yeniden yükler.
• Bir "Belgele ve Temizle" akışı: Claude'un planını bir Markdown dosyasına dökmesini, belleği temizlemesini ve ardından o dosyadan yeniden yüklemesini sağlayın.

3. Slash Komutları

• Slash komutları, önceden tanımlanmış istemlere kısayollardır.
• Örnekler:

• Slash komutlarını minimal ve odaklı tutun; her görev için onlara güvenmeyin.

4. Plan Modu

• Karmaşık görevlere başlarken planlama modunu kullanın. Claude, kod yazmadan önce bir plan taslağı çıkaracaktır.
• Daha sonra Claude'dan yürütmesini istemeden önce bu planı gözden geçirebilir, düzenleyebilir veya onaylayabilirsiniz.
• Büyük özellik çalışmaları, yeniden düzenleme veya mimari değişiklikler için idealdir.

5. Alt Ajanlar ve Görev Delege Etme

• Claude Code, ana ajanın "klonlarına" işin bazı kısımlarını delege etmenizi sağlayan alt ajanları destekler.
• Shrivu, katı özelleşmiş alt ajanlar yerine Task(...) aracılığıyla ana ajanın klonlar oluşturduğu bir "Ana-Klon" mimarisini tercih eder.
• Bu, bağlamın parçalanmasını önlerken esnekliği korur.
• Claude Code'un alt ajanlarına slash komutuyla erişin: /agents.

6. Claude Yetenekleri ve MCP — Fark Nedir?

a. Claude Yetenekleri, Claude'a belirli görevleri nasıl gerçekleştireceğini öğreten önceden oluşturulmuş "modüllerdir". Markdown veya kodla yazılırlar ve yalnızca ihtiyaç duyulduğunda yüklenirler. Raporları biçimlendirme, verileri özetleme veya ekibinizin stilini uygulama gibi iş akışlarını tanımlamak için Yetenekleri kullanabilirsiniz.

b. Öte yandan Model Bağlam Protokolü (MCP), Claude'u dış verilere ve araçlara (veritabanları, kod tabanınız veya iş sistemleri gibi) bağlamak için bir protokoldür. Claude'un özel araç entegrasyonları olmadan harici kaynaklara erişmesini ve bunlar üzerinde işlem yapmasını sağlayan bir "evrensel adaptör" gibidir.

c. Temel Farklar:

1. Amaç:

• Yetenekler prosedürel bilgiyi kodlar.
• MCP, araç ve veri bağlantısını yönetir.

2. Token Verimliliği:

• Yetenekler yalnızca gerektiğinde yüklenir ve nispeten az token kullanır.
• Birçok MCP araç tanımı etkinleştirilirse önemli token alanı kaplayabilir.

d. Kullanım Durumu:

• Claude'a alana özel iş akışlarını öğretmek için Yetenekleri kullanın (örneğin, "durum raporları yazarken her zaman X, Y, Z'yi dahil et").
• Claude'un veri okuması/yazması, API'leri çağırması veya Git veya veritabanı gibi harici sistemlere erişmesi gerektiğinde MCP'yi kullanın.

Pratikte, ikisi birlikte en iyi şekilde çalışır: MCP Claude'a verilerinize erişim sağlarken, Yetenekler Claude'a bu verileri yapılandırılmış, tekrarlanabilir bir şekilde nasıl kullanacağını öğretir.

6. Kancalar (Hooks)

a. Kancalar, kuralları otomatik olarak uygulamanızın yoludur.

b. İki yaygın tür:

• Gönderimde Engelleme: Örneğin, bir PreToolUse kancası, testler geçmediği sürece git commit'i engelleyebilir.
• İpucu Kancaları: Engellemeyen; yürütmeyi durdurmadan rehberlik veya öneriler sağlarlar.

c. "Yazımda engelleme" kancalarından kaçının — Claude'un planını tamamlamasına izin vermek ve ardından doğrulamak daha kararlıdır.

# .claude/settings.toml dosyasında örnek bir Kanca

[[hooks]]
# Kancayı tetikleyen olay.
event = "PostToolUse" 

# (İsteğe bağlı) Kancanın çalışması için koşullar.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# Yürütülecek kabuk komutu.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (İsteğe bağlı) Komutun arka planda çalışıp çalışmayacağı.
run_in_background = false 

7. CLI SDK

• Claude Code SDK, Claude etkileşimlerini betiklemenizi sağlar: toplu işleme, dahili araçlar oluşturma veya ajan prototipleri hazırlama için kullanışlıdır.
• Paralel yeniden düzenlemeler çalıştırmak, şablonlardan kod oluşturmak veya CI/CD iş akışlarının içinde hafif bir ajan olarak kullanın.

Kurulum:

# Typescript:
npm install @anthropic-ai/claude-agent-sdk

# Python:
pip install claude-agent-sdk

8. Claude Code GitHub Actions (GHA)

• Claude Code'u doğrudan GitHub Actions ile entegre edebilirsiniz.
• CI pipeline'ınızın bir parçası olarak otomatik olarak çekme istekleri oluşturmak, kod standartlarını uygulamak veya CLAUDE.md odaklı kontrolleri çalıştırmak için kullanın.
• Loglar depolandığı için ajan davranışını denetleyebilir ve CLAUDE.md dosyanızı zamanla geliştirebilirsiniz.

9. Ayarlar ve Yapılandırma

a. settings.json dosyasında şunları yapılandırabilirsiniz:

• Proxy (HTTPS_PROXY) — CLI trafiğini hata ayıklamak için kullanışlıdır.
• Zaman aşımları (MCP_TOOL_TIMEOUT, BASH_MAX_TIMEOUT_MS) — uzun görevler çalıştırıyorsanız bunları artırın.
• API anahtarı (ANTHROPIC_API_KEY) — Anthropic'ten anahtarınızı veya bir yardımcı betik kullanın.
• İzinler — Claude Code'un hangi sistem araçlarını çalıştırmasına izin verildiğini kontrol edin.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

Gelişmiş Özellikler ve Verimlilik İpuçları

1. Model Değiştirme: Görevinize bağlı olarak Claude 4 Sonnet veya Opus'u seçin. Sonnet hızlı ve uygun maliyetliyken; Opus, karmaşık, çoklu dosya değişiklikleri için daha yeteneklidir.
2. Düşünme Modları (Hile): Bazı kullanıcılar Claude'un muhakeme modunu think, think hard, think harder veya ultrathink olarak ayarlayarak ne kadar derinlemesine düşündüğünü ayarlar.
3. Özel Komutlar: .claude/commands içinde dinamik yer tutucular ($argument) ile yeniden kullanılabilir slash komutları tanımlayın. Test, geliştirme veya inceleme için harikadır.
4. Oturum Geçmişi: Eski oturumları devam ettirmek için claude --resume veya claude --continue kullanın. Claude tüm oturum geçmişini yerel olarak saklar.
5. Geri Bildirim Döngüsü: GitHub Action günlükleri veya geçmiş oturum verileri aracılığıyla ajan davranışını gözden geçirin ve yanlış anlaşılmaları düzeltmek veya daha iyi koruyucu önlemler uygulamak için CLAUDE.md dosyanızı güncelleyin.

Sıkça Sorulan Sorular (SSS)

S1. CLAUDE.md'nin amacı nedir?
C: CLAUDE.md, ajanın manifestosu olarak işlev görür. Claude Code'un takip edeceği kuralları, araçları ve sözleşmeleri tanımlar. Deponuz genelinde davranışın standartlaştırılmasına yardımcı olur.

S2. Alt ajanları mı yoksa sadece basit görevleri mi kullanmalıyım?
C: Kesin modüler iş akışları istiyorsanız alt ajanları kullanın. Ancak çoğu kişi Ana-Klon modelini (Task(...) kullanarak) daha esnek bulur — alt görevleri delege ederken bağlamı korursunuz.

S3. Claude oturumunu her şeyi kaybetmeden nasıl yeniden başlatırım?
C: Sohbeti sıfırlamak için /clear kullanın ve ardından Claude'un tam bağlama sahip olması için Git dalınızdaki dosyaları yüklemek üzere /catchup kullanın.

S4. Kancalar nelerdir ve onlara neden ihtiyacım var?
C: Kancalar, Claude işleri commit ettiğinde kuralları veya kontrolleri uygular. Örneğin, bir gönderimde engelleme kancası, Git commit'ine izin verilmeden önce testlerin geçtiğinden emin olabilir.

S5. Claude Code'u CI/CD'ye nasıl entegre edebilirim?
C: Görevleri çalıştırmak, kodu doğrulamak, çekme istekleri oluşturmak veya otomatikleştirilmiş pipeline'larda CLAUDE.md koruyucu önlemlerinizi uygulamak için Claude Code GitHub Action'ı kullanın.

Sonuç

Bu Claude Code Hızlı Başvuru Rehberi, Claude Code'u etkili bir şekilde nasıl kullanacağınıza dair pratik, yapılandırılmış bir genel bakış sunar. İyi hazırlanmış bir CLAUDE.md dosyası yazmaktan slash komutlarını, alt ajanları, kancaları ve CI entegrasyonunu kullanmaya kadar — bu modeller, Claude Code'u güvenilir bir yapay zeka destekli geliştirme ortağı olarak kullanmak için sağlam bir temel oluşturur.

Bu özellikleri ustaca kullanarak, yeni geliştiriciler hızla uyum sağlayabilir ve daha deneyimli mühendisler iş akışlarını düzenleyebilir, koruyucu önlemleri uygulayabilir ve Claude destekli üretkenliği ölçeklendirebilir. Claude Code, sadece bir kod üretme aracından daha fazlasıdır — ekibinizin ihtiyaçlarına uyum sağlayan programlanabilir, ajansel bir sistemdir.