Claude Code in Action

Herkese merhaba! 👋

Anthropic Academy’nin resmi kurslarını Türkçe notlara dönüştürdüğüm yazı serisinin 9. bölümüne hoş geldiniz! Bu yazıda, kodlama asistanlarının perde arkasında nasıl çalıştığından başlayıp Anthropic’in Claude Code aracını uçtan uca ele alıyoruz. Anthropic’in Claude Code in Action kursundan edindiğim notların derlenmiş hali olan bu içerikte; kurulumdan CLAUDE.md ile bağlam yönetimine, planlama moduna, hooks ve MCP sunucularına, hatta Agent SDK ile programatik kullanıma kadar pratik bir yolculuğa çıkıyoruz. Hazırsanız başlayalım!

Claude Code in Action: Claude Code Nedir ve Neden Önemli?

Yapay zeka destekli kodlama asistanları artık yazılım geliştirme sürecinin ayrılmaz bir parçası haline geldi. Ancak bu asistanların perde arkasında nasıl çalıştığını anlamak, gerçekten güçlü bir kodlama asistanının ne olduğunu takdir etmemizi sağlıyor. Bu yazıda Anthropic’in Claude Code aracını hem kavramsal hem de pratik açıdan derinlemesine inceleyeceğiz.

Kodlama Asistanları Nasıl Çalışır?

Bir kodlama asistanına, örneğin bir hata mesajına dayanarak bug düzeltmesi gibi bir görev verdiğinizde, süreç bir insan geliştiricinin izleyeceği yola benzer üç aşamadan geçer:

1. Bağlamı toplama: Hatanın neyle ilgili olduğunu, kod tabanının hangi kısmının etkilendiğini ve hangi dosyaların ilgili olduğunu anlamak
2. Plan oluşturma: Sorunu nasıl çözeceğine karar vermek: kodu değiştirmek, testleri çalıştırıp doğrulamak gibi
3. Aksiyon alma :Dosyaları güncelleyerek ve komutlar çalıştırarak çözümü gerçekten hayata geçirmek

Buradaki kritik nokta şu: ilk ve son adımlar, asistanın dış dünyayla etkileşime girmesini gerektirir; dosya okumak, dokümantasyon çekmek, komut çalıştırmak veya kod düzenlemek gibi.

Araç Kullanımı (Tool Use) Sorunu

İşte burada işler ilginçleşiyor. Dil modelleri tek başlarına sadece metin işleyip metin döndürebilir; gerçek anlamda dosya okuyamaz ya da komut çalıştıramazlar. Bir dil modeline doğrudan bir dosyayı okumasını isterseniz, bunu yapamayacağını söyler.

Peki kodlama asistanları bu sorunu nasıl çözüyor? “Tool use” (araç kullanımı) adı verilen akıllı bir sistemle.

Araç Kullanımı Nasıl İşler?

1. Kullanıcı sorar: “main.go dosyasında ne yazıyor?”
2. Kodlama asistanı isteğe otomatik olarak araç talimatları ekler
3. Dil modeli yanıt verir: ReadFile: main.go
4. Asistan gerçek dosyayı okur ve içeriğini modele geri gönderir
5. Dil modeli, dosya içeriğine dayanarak nihai cevabı üretir

Bu sistem sayesinde dil modelleri, aslında sadece özenle biçimlendirilmiş metin yanıtları üretiyor olsalar da, etkili bir şekilde “dosya okuyabiliyor”, “kod yazabiliyor” ve “komut çalıştırabiliyor” gibi görünür.

Claude’un Araç Kullanımındaki Gücü Neden Önemli?

Tüm dil modelleri araçları aynı yetkinlikte kullanmıyor. Claude modelleri, araçların ne işe yaradığını anlama ve karmaşık görevleri tamamlamak için bunları etkili şekilde kullanma konusunda özellikle güçlü.

Bu güçlü araç kullanımı, Claude Code için şu temel avantajları sağlıyor:

• Daha zor görevleri üstlenebilme — Claude farklı araçları birleştirerek karmaşık işleri halledebilir, hatta daha önce hiç görmediği araçları bile kullanabilir
• Genişletilebilir platform — Claude Code’a yeni araçlar kolayca eklenebilir ve Claude, iş akışınız geliştikçe bunlara uyum sağlar
• Daha iyi güvenlik — Claude Code, kod tabanını indekslemeye gerek kalmadan gezinebilir; bu genellikle tüm kod tabanınızı dış sunuculara göndermek zorunda kalmadığınız anlamına gelir

Kurulum: Claude Code’u Yerel Ortamınıza Yükleme

Claude Code’u kurmak oldukça basit. İşletim sisteminize göre:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

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

:: Windows Command Prompt
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# macOS (Homebrew)
brew install --cask claude-code

Kurulumdan sonra terminalde claude komutunu çalıştırın. İlk çalıştırmada bir renk teması seçmeniz ve claude.ai kimlik bilgilerinizle giriş yapmanız istenecek.

Amazon Bedrock, Google Cloud Vertex AI veya Microsoft Foundry üzerinden kullanacaksanız, üçüncü taraf sağlayıcı kurulum dokümantasyonuna göz atmanız gerekiyor.

Bağlam Yönetimi: CLAUDE.md Dosyası

Claude ile kodlama projelerinde çalışırken bağlam (context) yönetimi son derece kritik. Projeniz onlarca hatta yüzlerce dosya içerebilir, ancak Claude’un etkili yardımcı olabilmesi için yalnızca doğru bilgiye ihtiyacı vardır. Fazla gereksiz bağlam aslında Claude’un performansını düşürür.

/init Komutu

Yeni bir projede Claude’u ilk kez başlattığınızda /init komutunu çalıştırın. Bu komut, Claude'a tüm kod tabanınızı analiz etmesini ve şunları anlamasını söyler:

• Projenin amacı ve mimarisi
• Önemli komutlar ve kritik dosyalar
• Kodlama kalıpları ve yapısı

Analiz sonrasında Claude bir özet oluşturup CLAUDE.md dosyasına yazar. Bu dosya her isteğinize dahil edildiği için, projeniz için kalıcı bir sistem promptu gibi işlev görür.

CLAUDE.md Dosya Konumları

Claude üç farklı CLAUDE.md dosyasını üç farklı konumda tanır:

Dosya Açıklama CLAUDE.md /init ile oluşturulur, kaynak kontrolüne eklenir, diğer geliştiricilerle paylaşılır CLAUDE.local.md Paylaşılmaz, kişisel talimatlar ve özelleştirmeler içerir ~/.claude/CLAUDE.md Makinenizdeki tüm projelerde kullanılır, genel talimatlar içerir

Özel Talimatlar Ekleme

CLAUDE.md dosyasını doğrudan editörünüzde düzenleyebilir veya Claude Code içinde /memory komutunu çalıştırarak açabilirsiniz. Örneğin Claude koda çok fazla yorum ekliyorsa şu talimatı ekleyebilirsiniz:

“Yorumları az kullan. Sadece karmaşık kodları yorumla.”

@ ile Dosya Referansı

@ sembolünü kullanarak belirli dosyaları isteğinize dahil edebilirsiniz:

Auth sistemi nasıl çalışıyor? @auth

Aynı şekilde CLAUDE.md içinde de @ sözdizimini kullanarak, her projede sık başvurulan dosyaları (örneğin bir veritabanı şema dosyasını) otomatik olarak dahil edebilirsiniz. Projenizde zaten bir AGENTS.md dosyası varsa, CLAUDE.md'nin ilk satırına @AGENTS.md yazarak onu içe aktarabilir, altına Claude'a özel talimatlar ekleyebilirsiniz.

Değişiklik Yapma: Ekran Görüntüleri ve Gelişmiş Akıl Yürütme

Ekran Görüntüleriyle İletişim

Arayüzünüzün belirli bir bölümünü değiştirmek istediğinizde, ekran görüntüsü paylaşmak Claude’un tam olarak neyden bahsettiğinizi anlamasına yardımcı olur. Ctrl+V (macOS’ta da Cmd+V değil, Ctrl+V) ile ekran görüntüsünü yapıştırabilirsiniz.

Planlama Modu (Planning Mode)

Kod tabanınızda geniş çaplı araştırma gerektiren karmaşık görevler için Planlama Modu’nu etkinleştirebilirsiniz: /plan yazarak ya da Shift+Tab tuşuna iki kez basarak. Bu modda Claude:

• Projenizdeki daha fazla dosyayı okur
• Detaylı bir uygulama planı oluşturur
• Tam olarak ne yapmayı planladığını gösterir
• Uygulamaya geçmeden önce onayınızı bekler

Planı incelerken Ctrl+G ile metin editörünüzde açabilir, hassas düzenlemeler yapabilirsiniz.

Effort (Çaba) Seviyesi

/effort komutuyla mevcut seviyenizi görüp ayarlayabilirsiniz: low daha hızlı ve ucuzdur, max zor problemlerde en uzun süre akıl yürütür. Tek bir prompt üzerinde ekstra düşünmesini istiyorsanız ultrathink kelimesini kullanabilirsiniz; bu yalnızca o turda etkilidir, oturumun genel seviyesini değiştirmez.

Planlama Modu geniş kod tabanı anlayışı, çok adımlı uygulamalar ve birden fazla dosyayı etkileyen değişiklikler için idealdir. Effort seviyesini yükseltmek ise karmaşık mantık problemleri, zor hata ayıklama ve algoritmik zorluklar için daha uygundur.

Konuşmayı Kontrol Etme

Escape ile Kesme

Claude yanlış bir yöne gidiyorsa veya aynı anda çok fazla şey yapmaya çalışıyorsa Escape tuşuna basarak durdurabilir ve konuşmayı yönlendirebilirsiniz.

Escape + Memory Kombinasyonu

Claude aynı hatayı tekrar tekrar yapıyorsa:

1. Escape ile mevcut yanıtı durdurun
2. /memory çalıştırarak (veya CLAUDE.md'yi doğrudan düzenleyerek) doğru yaklaşımı not edin
3. Düzeltilmiş bilgiyle konuşmaya devam edin

Rewind (Geri Sarma)

Escape tuşuna iki kez basarak veya /rewind yazarak konuşmayı geri sarabilirsiniz. Bu, gönderdiğiniz tüm mesajları gösterir ve önceki bir noktaya atlayıp oradan devam etmenizi sağlar.

/compact ve /clear

• /compact — Tüm konuşma geçmişini, Claude'un öğrendiği kritik bilgileri koruyarak özetler. İlgili görevlere devam ederken kullanışlıdır.
• /clear — Tamamen farklı, ilgisiz bir göreve geçerken temiz bir bağlamla yeni bir konuşma başlatır. Önceki konuşmaya /resume ile geri dönebilirsiniz.

Özel Komutlar Oluşturma

Claude Code’un yerleşik komutlarının yanı sıra, sık tekrarlanan görevleri otomatikleştirmek için kendi özel komutlarınızı da oluşturabilirsiniz.

Get Özcan Kara’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Bir özel komut oluşturmak için:

1. Proje dizininizde .claude klasörünü bulun
2. İçinde commands adında yeni bir dizin oluşturun
3. İstediğiniz komut adıyla bir markdown dosyası oluşturun (örneğin audit.md)

Dosya adı komutunuzun adı olur; yani audit.md, /audit komutunu oluşturur.

$ARGUMENTS ile Argüman Kullanımı

Özel komutlar $ARGUMENTS yer tutucusuyla argüman kabul edebilir. Örneğin bir write_tests.md komutu:

Şunun için kapsamlı testler yaz: $ARGUMENTS

Test kuralları:
* Vitest ve React Testing Library kullan
* Test dosyalarını kaynak dosyayla aynı klasördeki __tests__ dizinine yerleştir
* Test dosyalarını [dosyaadi].test.ts(x) şeklinde adlandır
* Import'larda @/ önekini kullan

Bu komutu şu şekilde çalıştırabilirsiniz:

/write_tests hooks dizinindeki use-auth.ts dosyası

MCP Sunucuları ile Yetenekleri Genişletme

Claude Code’un yeteneklerini MCP (Model Context Protocol) sunucuları ekleyerek genişletebilirsiniz. Bu sunucular yerel veya uzaktan çalışır ve Claude’a normalde sahip olmadığı yeni araçlar sağlar.

En popüler MCP sunucularından biri, Claude’a bir web tarayıcısını kontrol etme yeteneği veren Playwright’tır.

Kurulum

claude mcp add playwright npx @playwright/mcp@latest

İzin Yönetimi

.claude/settings.local.json dosyasına şunu ekleyerek sunucuyu önceden onaylayabilirsiniz:

{
  "permissions": {
    "allow": ["mcp__playwright"],
    "deny": []
  }
}

Pratik Örnek

Playwright MCP sunucusuyla Claude’a şunu söyleyebilirsiniz:

“localhost:3000'e git, temel bir bileşen oluştur, stilini incele ve @src/lib/prompts/generation.tsx dosyasındaki oluşturma promptunu daha iyi bileşenler üretecek şekilde güncelle.”

Claude, tarayıcı araçlarını kullanarak uygulamanızla etkileşime girer, üretilen çıktıyı inceler ve prompt dosyanızı buna göre değiştirir. Bunun avantajı, Claude’un sadece kodu değil gerçek görsel çıktıyı da görebilmesidir.

GitHub Entegrasyonu

Claude Code, GitHub Actions içinde çalışmasını sağlayan resmi bir entegrasyon sunuyor. Kurulum için /install-github-app komutunu çalıştırmanız yeterli; bu komut GitHub uygulamasını kurar, API anahtarınızı ekler ve iş akışı dosyalarını içeren bir pull request otomatik olarak oluşturur.

İki Ana İş Akışı

• Mention Action — Herhangi bir issue veya pull request’te @claude ile bahsedildiğinde Claude isteği analiz eder, bir görev planı oluşturur, kod tabanına tam erişimle görevi yürütür ve sonuçlarla yanıt verir
• Pull Request Action — Her pull request oluşturulduğunda Claude önerilen değişiklikleri otomatik olarak inceler ve detaylı bir rapor gönderir

İş akışı dosyalarını özelleştirerek proje kurulum adımları, özel talimatlar, MCP sunucu yapılandırmaları ve araç izinleri ekleyebilirsiniz. GitHub Actions’ta yerel geliştirmedeki gibi kısayollar olmadığından, her aracın her iznini ayrı ayrı listelemeniz gerekir.

Hooks: Otomatik İş Akışları

Hooks, Claude bir araç çalıştırmadan önce veya sonra komutlar çalıştırmanıza olanak tanır. Kod formatlayıcıları çalıştırma, dosya değişikliklerinde test yürütme veya belirli dosyalara erişimi engelleme gibi otomatik iş akışları için son derece kullanışlıdır.

İki Ana Hook Türü

• PreToolUse hooks — Bir araç çağrılmadan önce çalışır; işlemi engelleyebilir
• PostToolUse hooks — Bir araç çalıştırıldıktan sonra çalışır; işlem zaten gerçekleştiği için engelleyemez ama takip işlemleri yapabilir (örneğin düzenlenen dosyayı formatlamak)

Hook Yapılandırması

Hooks şu dosyalarda tanımlanabilir:

Konum Kapsam ~/.claude/settings.json Global — tüm projeleri etkiler .claude/settings.json Proje — takımla paylaşılır .claude/settings.local.json Proje (paylaşılmaz) — kişisel ayarlar

Örnek bir PreToolUse hook yapılandırması:

"PreToolUse": [
  {
    "matcher": "Read",
    "hooks": [
      { "type": "command", "command": "node /home/hooks/read_hook.js" }
    ]
  }
]

Örnek: Hassas Dosyaları Koruma

.env dosyasının okunmasını engelleyen bir hook örneği. Önce .claude/settings.local.json dosyasına hook eklenir:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          { "type": "command", "command": "node $PWD/hooks/read_hook.js" }
        ]
      }
    ]
  }
}

Sonra hooks/read_hook.js dosyası oluşturulur:

process.stdin.setEncoding("utf8");
let input = "";
process.stdin.on("data", (d) => (input += d));
process.stdin.on("end", () => {
  const toolArgs = JSON.parse(input);
  const readPath = toolArgs.tool_input?.file_path || "";
  if (readPath.includes(".env")) {
    console.error("You cannot read the .env file");
    process.exit(2);
  }
  process.exit(0);
});

Hook, stdin’den gelen JSON verisini okur, tool_input.file_path alanını kontrol eder ve çağrıyı engellemek için çıkış kodu 2 ile çıkar (stderr'e yazılan her şey Claude'a mesaj olarak iletilir).

Önemli not: Bu hook yalnızca Read aracını kapsar. Grep veya Bash üzerinden aynı dosyaya erişimi engellemek için her aracın girdi yapısını ayrı ayrı kontrol etmeniz gerekir. Kapsamlı dosya koruması için hook'u "Read(**/.env)" gibi bir permissions.deny kuralıyla birleştirmek daha etkilidir.

Diğer Hook Türleri

PreToolUse ve PostToolUse dışında şu hook türleri de mevcuttur:

• Notification — Claude bir araç için izin istediğinde veya 60 saniye boyunca boşta kaldığında çalışır
• Stop — Claude yanıt vermeyi bitirdiğinde çalışır
• SubagentStop — Bir alt ajan (arayüzde “Task” olarak görünür) işini bitirdiğinde çalışır
• PreCompact — Bir compact işleminden önce çalışır
• UserPromptSubmit — Kullanıcı bir prompt gönderdiğinde, Claude işlemeden önce çalışır
• SessionStart / SessionEnd — Oturum başladığında veya bittiğinde çalışır

Her hook türünün stdin girdisi farklıdır. Girdiyi anlamak için şu yardımcı hook kullanılabilir:

"PostToolUse": [
  {
    "matcher": "*",
    "hooks": [
      { "type": "command", "command": "jq . > post-log.json" }
    ]
  }
]

Bu komut, hook’a gelen girdiyi post-log.json dosyasına yazarak yapıyı incelemenizi sağlar.

İleri Düzey Örnekler

TypeScript Tip Kontrolü Hook’u: Claude bir fonksiyon imzasını değiştirdiğinde, genellikle o fonksiyonun çağrıldığı diğer yerleri güncellemeyi unutur. Her dosya düzenlemesinden sonra tsc --noEmit çalıştıran bir PostToolUse hook'u, oluşan tip hatalarını yakalayıp anında Claude'a geri bildirir.

Sorgu Tekrarını Önleme Hook’u: Büyük projelerde Claude bazen var olan bir sorguyu kullanmak yerine yeni, tekrarlayan bir sorgu yazabilir. ./queries dizinindeki değişikliklerde tetiklenen bir hook, ayrı bir Claude Code örneğini programatik olarak başlatarak değişiklikleri incelemesini ve benzer mevcut sorguları kontrol etmesini sağlayabilir.

Agent SDK ile Programatik Kullanım

Agent SDK, Claude Code’u kendi uygulamalarınızdan ve script’lerinizden programatik olarak çalıştırmanızı sağlar. TypeScript ve Python için mevcuttur ve CLI’nin kullandığı aynı ajan döngüsünü (dosya okuma, düzenleme, araç kullanımı) size sunar.

Kurulum

mkdir sdk-demo
cd sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk

Not: Paket adı @anthropic-ai/claude-agent-sdk'dır. Benzer isimli @anthropic-ai/claude-code paketi CLI'nin kendisidir ve import edilemez.

Minimal Bir Örnek

index.mjs dosyası oluşturun:

import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = "List the files in the current directory";
for await (const message of query({ prompt })) {
  console.log(JSON.stringify(message, null, 2));
}

Çalıştırın:

node index.mjs

Bir dizi JSON mesajı göreceksiniz; CLI’de göreceğiniz aynı konuşma olayları: araç çağrıları, araç sonuçları ve Claude’un metinleri.

Araçları Kısıtlama

Varsayılan olarak SDK, tam araç setine erişime sahiptir. Bunu kısıtlamak için allowedTools parametresini kullanabilirsiniz:

for await (const message of query({
  prompt,
  options: { allowedTools: ["Read", "Glob"] },
})) {
  // ...
}

SDK; özel sistem promptları, MCP sunucuları, hooks, alt ajanlar (subagents) ve oturum devam ettirme dahil CLI’nin sunduğu her şeyi destekler.

Sonuç

Claude Code, basit bir kod tamamlama aracından çok daha fazlasıdır. Güçlü araç kullanımı, esnek bağlam yönetimi, özel komutlar, MCP sunucuları, GitHub entegrasyonu, hooks sistemi ve Agent SDK ile birleştiğinde, gerçek anlamda kapsamlı bir geliştirme ortağına dönüşür. Kod tabanınızı anlayabilen, dosyalarınızı okuyup düzenleyebilen, komutlar çalıştırabilen ve iş akışınıza uyum sağlayabilen bu sistem, yazılım geliştirme sürecinin geleceğine dair güçlü bir örnek sunuyor.

Kaynakça: anthropic.skilljar.com/claude-code-in-action