Claude Code SDK

 (docs.anthropic.com)
1 puan yazan GN⁺ 2025-05-20 | 1 yorum | WhatsApp'ta paylaş
  • Claude Code SDK, yapay zeka tabanlı kodlama araçlarını uygulamalara entegre etme imkanı sunar
  • Geliştiriciler Claude Code'u alt süreç olarak çalıştırabilir; öncelikli destek komut satırı kullanımı içindir
  • Etkileşimli bağlam yönetimi, özel sistem istemi tanımlama ve harici araç entegrasyonu (MCP) özelliklerini içerir
  • Çeşitli çıktı formatları (metin, JSON, akış JSON'u) ve ayrıntılı CLI seçeneklerinden yararlanılabilir
  • Gerçek örnek olarak, GitHub Actions ile entegre edilerek otomatik kod incelemesi, PR oluşturma gibi gerçek geliştirme iş akışlarına entegrasyon olanağı sunar

Giriş

Claude Code SDK, Claude Code'un yeteneklerini doğrudan uygulamalara programatik olarak entegre etmeyi sağlayan açık kaynaklı bir geliştirme aracıdır. SDK, Claude Code'u ayrı bir süreç olarak çalıştırarak yapay zeka tabanlı kod asistanları, otomasyon araçları, kod inceleme sistemleri gibi çeşitli geliştirme iş akışlarına uyarlanabilecek bir genişletilebilirlik sunar.

Şu anda komut satırı (CLI) tabanlı arayüzü desteklemektedir; TypeScript ve Python için SDK'lerin yakında yayınlanması planlanmaktadır.

Temel SDK kullanımı

Claude Code SDK, etkileşimsiz (non-interactive) çalıştırmayı destekler. Örneğin, programlama kodu içinde Claude Code'u komut satırı argümanlarıyla çağırarak istenen çıktıyı otomatik olarak elde edebilirsiniz.

Gelişmiş kullanım

Çok turlu konuşma oturumunu sürdürme

  • Birden çok kez mesaj alışverişi yaparken, önceki oturum veya belirli bir oturum kimliği kullanılarak konuşma bağlamını koruma ve sürdürme özelliği sunulur
  • Geliştiriciler en son oturumdan konuşmaya devam edebilir veya belirli bir oturumu yükleyebilir

Özel sistem istemi

  • Claude'un varsayılan çalışma biçimi, geliştiriciye özel sistem istemi ile ayarlanabilir
  • Varsayılan sistem istemine ek yönergeler eklenerek assistant'ın görev odaklılığı ve davranış kapsamı değiştirilebilir

MCP(Model Context Protocol) yapılandırması

  • MCP, Claude Code yeteneklerini genişletmek için kullanılan harici sunucu entegrasyon protokolüdür
  • --mcp-config bayrağı ve JSON yapılandırma dosyası aracılığıyla, harici sunucuların sunduğu veritabanı erişimi, API entegrasyonu, özel araçlar gibi imkanlar eklenebilir
  • MCP araçları kullanılırken yalnızca açıkça izin verilen araçlar kullanılabilmelidir (--allowedTools bayrağı); ad deseni mcp__<serverName>__<toolName> biçimindedir

Kullanılabilir CLI seçenekleri

Claude Code SDK'de çeşitli komut satırı bayrakları kullanılarak çalışma ortamı yapılandırılabilir.

  • --print, -p : etkileşimsiz modda çalıştırma
  • --output-format : çıktı formatı seçimi (metin, JSON, akış JSON'u vb.)
  • --resume, -r : belirli bir oturum kimliğiyle konuşmayı sürdürme
  • --continue, -c : en son oturumu sürdürme
  • --verbose : ayrıntılı günlük çıktısı
  • --max-turns : etkileşimsiz modda en fazla konuşma turu sınırı
  • --system-prompt : sistem istemini geçersiz kılma
  • --append-system-prompt : sistem istemine ek yönerge ekleme
  • --allowedTools : izin verilen araç listesini belirtme (MCP araçları dahil)
  • --disallowedTools : yasaklı araç listesini belirtme
  • --mcp-config : MCP sunucu yapılandırma dosyasını yükleme
  • --permission-prompt-tool : izin istemi işlemesi için MCP aracı belirtme

Kullanılabilen tüm seçenekler ve kullanım örnekleri için resmi CLI belgelerine bakılması gerekir.

Çıktı formatları

SDK, çeşitli çıktı formatlarını destekler.

Metin çıktısı (varsayılan)

  • Yalnızca yanıt metnini döndürür

JSON çıktısı

  • Meta veriler ve yapılandırılmış veriler döndürdüğü için programatik ayrıştırma açısından avantaj sağlar
  • API yanıt mesajları katı bir tip yapısını izler ve ileride tip tanımlarının JSON Schema formatında da sunulması planlanmaktadır

Akış JSON çıktısı

  • Her mesajı gerçek zamanlı olarak akış halinde iletir
  • Konuşma oturumu ilerlerken, başlatma mesajı (init), kullanıcı/assistant mesajları ve istatistik içeren son result mesajı ayrı JSON nesneleri olarak iletilir

Mesaj şeması

  • JSON API yanıt mesajları kesin bir şemaya göre yapılandırılır
  • Şemanın düzenli olarak güncellenmesi ve sürüm yönetiminin yapılması planlanmaktadır

Örnekler

  • Basit betik entegrasyonu
  • Claude kullanarak dosya işleme
  • Oturum yönetimi ile karmaşık konuşma akışlarını destekleme

En iyi uygulamalar

  1. Yanıt ayrıştırma için JSON çıktı formatını kullanın
  2. Hata işleme: çıkış kodunu ve hata akışını kontrol edin
  3. Oturum yönetimi: çok turlu konuşmalarda bağlamı koruyun
  4. Zaman aşımını dikkate alın: uzun süren işlerde güvenliği sağlayın
  5. İstekler arasındaki aralığı ayarlayın: aşırı çağrıları önleyin ve hizmet kararlılığını koruyun

Gerçek kullanım örnekleri

Claude Code SDK, gerçek geliştirme ortamlarında güçlü otomasyon ve entegrasyon yetenekleri sunar.

  • Temsilî örnek olarak, GitHub Actions ile birleştirilerek otomatik kod incelemesi, PR oluşturma, issue sınıflandırma gibi geliştirme iş akışları tamamen otomatikleştirilebilir

İlgili okumalar

1 yorum

 
GN⁺ 2025-05-20
Hacker News görüşleri

  • Claude Code’un yöneldiği istikametin, benim agent tabanlı kodlama araçlarında görmek istediğim tam "unix toolish" felsefe biçimi olduğunu vurgulamak istiyorum. İlk açık önizleme döneminden beri Claude Code kullanıyorum ve gelişim sürecini izledim. Bir kodlama ajanı için "altın standart"ın, bir özellik isteğini (ör. Jira bileti) verip karşılığında benim bizzat inceleyip geri bildirim verebileceğim bir PR almak olduğunu düşünüyorum. Cursor, windsurf vb. araçların yerel editör olması nedeniyle CI ortamına entegre edilememesinin bir sınır olduğunu düşünüyorum. Eğer kod tabanını yapay zeka için optimize etmek (MCP, kurallar vb.) istiyorsanız, headless olarak da kullanılabilen bir teknolojiyi hedeflemeniz gerektiğini vurgulamak isterim. Claude Code otomasyon araçlarıyla birlikte basitçe kullanılabildiği için, artık benim için kodlama ajanı denince temel araç haline geldi. Codex npm paketi için de benzer düşünüyorum. Bu arada, ben bu tür ideal araç kurulumlarına yardımcı olan bir rolde çalıştığım için, kolay kurulum sunan araçlara doğal olarak daha olumlu bakıyor olabilirim

    • Benim arzuladığım "altın son durum", kod yazan, tasarım yapan, test gerçekleştiren yapay zeka ajanlarıyla çevrili bir odanın tam ortasında olmam. Ben de o ortamın merkezinde klavyeye neredeyse hiç dokunmadan sadece yönü, estetik ölçütleri ve rehberliği konuşarak veriyor olayım. Böyle bir geleceği bekliyorum

    • Anthropic’in bugün buna benzer bir özelliği beta olarak duyurduğunu da belirtmek isterim. İlgili dokümanı paylaşmak isterim. https://docs.anthropic.com/en/docs/claude-code/github-actions

    • Benim düşündüğüm kodlama ajanı için "altın son durum", bilgisayarımda ya da istediğim herhangi bir yerde özgürce çalıştırabileceğim ücretsiz açık kaynaklı bir kodlama ajanı kullanmak. Terminalde ls, ps, kill gibi komutları her çalıştırdığımda ücret ödemeyi hayal etmek ne kadar anlamsız geliyorsa, LLM için de aynı şekilde düşünüyorum. Amaç özel mülk LLM’leri "yasaklamak" değil, fakat bu alanda hacker denilen kişilerin ana araç olarak açık kaynaklı araçları benimsemesini isterdim

    • Cursor, windsurf vb. araçların yerel editör olduğu için CI’de kullanmasının zor olduğunu söylemişsiniz ama ben bunu Cursor + MCP kombinasyonuyla denedim. Bir gün boyunca başarılı şekilde kullandım ama kısa süre sonra rate limit’e takıldım ve sistem en yavaş, en aptal modele geçti. Claude ile de denedim ama onda da çok geçmeden limitim tükendi. Ayrıca PR’ların yalnızca yaklaşık %25’i "anında kullanılabilir" seviyedeydi ve yapay zekanın nerede hata yaptığını anlamaya çalışmaktansa çoğu zaman işi kendim yapmak daha hızlı oluyordu

    • Zaten bu tür CI tabanlı otomasyonları bugün de yapamaz mıyız diye düşünüyorum. Aider CLI’ı GitHub Action olarak tanımlayıp bir issue oluştuğunda otomatik çalışacak şekilde ayarlarsanız, bu yapı zaten kurulabiliyor

  • Claude Code, LLM’i kodlama için kullanırken en sevdiğim yaklaşım. Ama aslında ihtiyaç duyulan şeyin Claude Code’un açık kaynaklı bir sürümü olduğunu düşünüyorum. İstediğim modeli kullanabileceğim ve farklı modellerin yanıtlarını doğrudan karşılaştırabileceğim bir ortam gerekli. Aider gibi diğer alternatiflerin Claude Code seviyesinde bir deneyim sunmadığını hissediyorum. Anthropic’in bunu istememesini anlayabiliyorum (savunma duvarı zayıflar). Ama bir tüketici olarak en iyi modeli kullanmak istiyorum ve tek bir ekosisteme bağlanmak istemiyorum. Bunun LLM sağlayıcılarının en büyük korkusu olduğunu tahmin ediyorum

    • OpenAI codex, anlattığınıza en yakın açık kaynak seçeneği. İstediğiniz sağlayıcının modelini kullanabiliyorsunuz. Şu anda Claude Code’dan geride ama yakında yetişeceğini düşünüyorum. https://github.com/openai/codex/tree/main

    • Claude Code’u MCP sunucusu olarak kullanarak istediğiniz ortama bir ölçüde yaklaşabilirsiniz

  • Aider, Python ve shell scripting desteğini epey uzun zamandır sunuyordu. Kısa süre önce 130 yeni programlama dili desteği ekleme sürecinin bir parçası olarak ad-hoc bash scripting aide içeren bir screencast de hazırladılar. Bu betik odaklı yaklaşımın ne kadar güçlü olduğunu bizzat hissedebilirsiniz. https://aider.chat/docs/scripting.html, https://aider.chat/docs/recordings/tree-sitter-language-pack.html

    • Aider’ı gerçekten çok seviyorum. MCP desteği de yakında geliyor; geliştirme dalında test ediliyor. Bu gerçekleşirse, güvendiğiniz modellerle PR, ticket vb. uçtan uca geliştirme gerçekten mümkün hale gelecek

    • Aider’ı Claude Code’u sevdiğim kadar sevebileceğim bir noktaya getirmenin mümkün olup olmadığını merak ediyorum. Claude Code’un UX’ini seviyorum ama Gemini 2.5 Pro’yu tercih ettiğim için Claude Code kullanmıyorum. Commit gibi özelliklerden çok iyi UX’i cazip geliyor. Bunun hakkında ne düşündüğünüzü duymak isterim

    • Aider, GitHub Actions entegrasyonu iş akışını daha polished hale getirirse gerçekten çok büyüyebilir diye düşünüyorum. Depoya tek bir dosya ekleyerek issue üzerinden istediğiniz modelle konuşabilirsiniz

  • Claude Code ekibinin bizzat paylaştığı ek bağlamı aktarmak istiyorum. http://latent.space/p/claude-code Ana noktaların özeti şu: Anthropic çalışanları sınırsız Claude ile günde ortalama yaklaşık 6 dolar kullanıyor. CI için bir tür "linux" yardımcı aracı gibi çalışan headless Claude Code çok cazip. Ayrıca ölçeklenebilir bir kullanıcı platformu olma yönelimi de var. Gelecek yol haritasında sandboxing, branching ve planning özellikleri bulunuyor. Sonnet 3.7 adlı sürekli agentic model de planlanıyor

    • "Anthropic çalışanları sınırsız Claude ile ortalama günde $6 kullanıyor" demişsiniz ama yazıda bazı mühendislerin günde 1.000 dolar harcadığından da söz ediliyor. Ortalama yerine P50, P75, P95 gibi dağılım metriklerini merak ediyorum

    • Claude Code’u sadece yaklaşık 2 saat kullandığımda bile 20 doları rahatça aştığım deneyimi birkaç kez yaşadım. Kişisel projeler için fazla pahalı, bu yüzden fiilen kullanamıyorum

    • Son zamanlarda latent space podcast’ini gerçekten çok keyifle dinledim. Bu kadar yüksek SNR’yi korurken aynı zamanda bu kadar üretken biçimde kamusal içerik üretmeye devam eden kişi/podcast gerçekten çok az. Birden fazla işi aynı anda yürütürken bu düzeyde kamusal çıktı üretmeyi sürdürmek etkileyici. Daha fazla insanın bu tür bir üretkenlik eğimini deneyimlemesini isterdim. Kendi sırlarını paylaşıyor ama bunu gerçekten uygulamak kolay değil

  • Eğer ben bir yapay zeka kod asistanı yapacak olsam, onu asla belirli bir foundation model sağlayıcısına bağımlı kılmazdım. Bunun mantıklı bir strateji olabilmesi için model etkisinin artık neredeyse tavana ulaşmış, performansların birbirine çok yaklaşmış ve geriye sadece alışıldık SDK düzeyinde küçük farkların kalmış olması gerekir

    • Sadece komutlar ya da argümanlar farklı olduğu için, aslında lock-in’in o kadar büyük olmadığını düşünüyorum. Sonuçta ortada bir girdi-çıktı fonksiyonu var; gerekli kısımları değiştirip kullanabilir ya da sarmalayabilirsiniz. Yapısal olarak çok karmaşık bir şey yok

    • Şu anda Claude Code’un agent tabanlı kodlama pazarında gerçek bir farklılaştırıcı olduğunu düşünüyorum. Ben de bir AI code assistant geliştiriyorum ve ilk denemek istediğim entegrasyon Claude Code oldu. Erken aşamada lock-in’i düşünmek için doğru zaman olmadığını hissediyorum. En iyisini seçip onun etrafında geliştirmeye başlamak gerektiğini düşünüyorum

  • Claude Code zaten non-interactive modda da kullanılabildiği için, UNIX komut satırı yardımcı programı gibi başka uygulamalara kolayca entegre edilebildiğini vurgulamak isterim. Bu SDK da şu anda yalnızca komut satırı kullanımını destekliyor gibi görünüyor; özünde mevcut olandan ne farkı var pek anlayamadım. Kaçırdığım nokta ne, merak ediyorum

  • Anthropic’in kullanım şartlarındaki "hizmeti genel zekâ ile rekabet eden herhangi bir ürün veya hizmetin geliştirilmesi, eğitimi ya da yeniden satışı için kullanmayı yasaklar" ifadesini alıntılıyorum. Eğer neredeyse tüm yazılımlar genel zekâ ile "rekabet ediyor" sayılabilecekse, bunu katı yorumladığınızda aslında hiçbir amaçla kullanılamaz hale gelmiyor mu? Bu tür hukuki ifadelerin kendisi fazla muğlak ve bu yüzden uygulanamaz olduğunu düşünüyorum. Yapay zekanın çıktılarının sahibi olabiliyorsunuz ama genel zekâ ile rekabet etmemesi gerekiyor gibi bir durum var; neden bu kadar geniş kapsamlı yasakladıklarını merak ediyorum. Yoksa sadece hukuki sorumluluğu kullanıcıya yıkmak mı istiyorlar? Aklımda birçok soru var

    • Avukatların kuralları istedikleri gibi yazmasına izin verilince böyle şeyler oluyor bence

  • Yeni eklenen GitHub Action tam da aradığım işleve karşılık geliyor, bu yüzden çok sevindim. https://docs.anthropic.com/en/docs/claude-code/github-action... Ancak şu anda bunu Claude Code’un Max planıyla birlikte kullanmanın bir yolu yok gibi görünüyor. Sadece API key kabul ediyor olması biraz hayal kırıklığı yarattı

  • Özellikle GitHub Actions ve issue/PR entegrasyonu uzun zamandır istediğim şeydi. https://docs.anthropic.com/en/docs/claude-code/github-action...

  • Copilot üzerinden Claude desteği başladığında kesinlikle deneyeceğim. Şirket politikası nedeniyle şu anda onun dışındaki araçları kullanamıyorum