Structured data

Bu modül için tahmini süre: 6 dakika

Genel bakış

Claude’un JSON, Python kodu veya bullet list gibi structured data üretmesi gerektiğinde sık karşılaşılan bir sorun vardır: Claude yardımcı olmak ister ve içeriğinizin etrafına açıklayıcı metin ekler. Bu çoğunlukla harikadır ama bazen yanında hiçbir şey olmadan sadece raw data istersiniz.

Bir AWS EventBridge kuralı üreten bir web uygulaması düşünün. Kullanıcılar bir açıklama girer, generate’e basar ve hemen kopyalayıp kullanabilecekleri temiz JSON görmeyi bekler. Claude JSON’ı markdown code block içinde açıklayıcı metinle birlikte döndürürse, kullanıcılar tüm yanıtı kopyalayamaz — manuel olarak sadece JSON kısmını seçmek zorunda kalır.

Default response’ların problemi

Default olarak Claude’tan JSON üretmesini istediğinizde şunun gibi bir şey alabilirsiniz:

```json
{
  "source": ["aws.ec2"],
  "detail-type": ["EC2 Instance State-change Notification"],
  "detail": {
    "state": ["running"]
  }
}
```

This rule captures EC2 instance state changes when instances start running.

JSON doğrudur ama markdown formatına sarılı ve açıklayıcı metin içeriyor. Kullanıcının raw JSON kopyalaması gereken bir web uygulamasında bu kullanıcı deneyimine sürtünme katar.

Çözüm: Assistant message prefilling + stop sequences

Tam istediğiniz içeriği almak için assistant message prefilling ile stop sequences’ı birleştirebilirsiniz. İşte nasıl çalıştığı:

messages = []

add_user_message(messages, "Generate a very short event bridge rule as json")
add_assistant_message(messages, "```json")

text = chat(messages, stop_sequences=["```"])

Bu teknik şu şekilde çalışır:

1. User message Claude’a ne üreteceğini söyler
2. Prefill edilmiş assistant message, Claude’a markdown code block’a zaten başlamış gibi düşündürür
3. Claude sadece JSON içeriğini yazarak devam eder
4. Claude code block’u ``` ile kapatmaya çalıştığında stop sequence generation’ı anında sonlandırır

Sonuç ekstra formatlama olmadan temiz JSON:

{
  "source": ["aws.ec2"],
  "detail-type": ["EC2 Instance State-change Notification"],
  "detail": {
    "state": ["running"]
  }
}

Response’u işlemek

Yanıtta birkaç ekstra newline karakteri fark edebilirsiniz. Bunları kolayca temizlersiniz:

import json

# Clean up and parse the JSON
clean_json = json.loads(text.strip())

JSON’ın ötesinde

Bu teknik sadece JSON üretimi ile sınırlı değil. Açıklama içermeyen structured data’ya ihtiyacınız olduğunda her zaman kullanın:

• Python kod parçacıkları
• Bullet list’ler
• CSV verisi
• Sadece içerik istediğiniz, açıklama istemediğiniz herhangi bir formatlı içerik

Anahtar nokta: Claude’un içeriğinizi doğal olarak neye sarmak istediğini belirleyip o şeyi prefill ve stop sequence olarak kullanmak. Kod için bu genelde markdown code block’tır. Listeler için farklı formatlama işaretleri olabilir.

Bu yaklaşım Claude’un output formatı üzerinde size hassas kontrol sağlar; AI tarafından üretilen içeriği temiz, yapısal verinin esas olduğu uygulamalara entegre etmeyi çok daha kolaylaştırır.

Temel çıkarımlar

• Default davranışta Claude structured çıktının etrafına açıklama, başlık veya markdown formatı ekleyebilir
• Prefilling: assistant message’a "\“json”` gibi bir başlangıç koymak Claude’u o block’un içinde devam etmeye zorlar
• Stop sequences: kapanış işaretiyle (örn. ```) generation’ı tam o noktada durdurur — tek atışta temiz çıktı
• Aynı teknik JSON, Python, regex, CSV gibi farklı yapısal formatlara uygulanabilir
• json.loads(text.strip()) ile çıktıyı parse etmek tipik bir tamamlayıcı adımdır