İlk persona'yı baştan sona üret

Bu rehber bir niyet (intent) cümlesinden çalışan bir persona'ya (karaktere) kadar olan tüm süreci adım adım açar.

Hızlı başlangıç beş dakikada en kısa başarıyı verir; bu eğitim bir adım derine iner: iyi bir niyet cümlesi nasıl yazılır, yanıttaki her alan ne anlama gelir, denetim ve voice fingerprint arka planda neyi ölçer.

Bu rehberi bitirdiğinde

• Niyet cümlesi yazma sezgin oluşacak.
• Yanıttaki Soul / Self / Mask / Surface alanlarını okuyabileceksin.
• Denetim (audit) ve voice fingerprint çıktılarının neyi ölçtüğünü bileceksin.
• Persona'yı bir sonraki adımda — sohbet, refine veya fork — nasıl kullanacağını seçebileceksin.

Ön koşul: Hızlı başlangıç'ı tamamladıysan veya elinde sk_test_… ile başlayan bir API anahtarı varsa hazırsın.

1. İyi bir niyet (intent) cümlesi yaz

Niyet, Moonborn'un karakterin iç motivasyonunu çıkarmaya başladığı tek cümledir. Üretim hattı bu cümleyi içten dışa dört katmana açar. İyi bir niyet kısadır, davranışsal ipuçları taşır ve karakterin ne istediği veya neden korktuğu konusunda bir sinyal verir.

İstanbul'da yaşayan 34 yaşında bir startup kurucusu. Parlak ama huzursuz; sahtekârlık sendromunu (imposter syndrome) durmak bilmeyen ivmenin arkasına saklıyor.

2. Persona'yı üret

Tek bir POST /v1/personas çağrısı niyeti altı adımlı üretim hattına verir.

curl -X POST https://api.moonborn.co/v1/personas \
  -H "Authorization: Bearer $MOONBORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"intent\": \"İstanbul'da yaşayan 34 yaşında bir startup kurucusu. Parlak ama huzursuz; sahtekârlık sendromunu durmak bilmeyen ivmenin arkasına saklıyor.\",
    \"workspaceId\": \"ws_...\"
  }"

İlk yanıt bilinçli olarak yalındır — uzun katmanları beklemek yerine kimlikleri (ID) hemen alırsın:

{
  "id": "per_01H...",
  "status": "active",
  "pipelineRunId": "run_01H..."
}

Üretim genelde 30–90 saniye sürer. Arka planda Soul → Self → Mask → Surface sırayla kurulur, sonra denetim ve voice fingerprint koşar.

3. Persona'yı katman katman oku

GET /v1/personas/{id} çağrısı dört katmanı + çalışma zamanı alanlarını döner.

const detail = await client.personas.get({ id: persona.id });
 
console.log('Soul:', detail.soul);
console.log('Self:', detail.self);
console.log('Mask:', detail.mask);
console.log('Surface:', detail.surface);
console.log('voiceFingerprintId:', detail.voiceFingerprintId);
console.log('audit:', detail.audit);

Beklenen yanıt (kısaltılmış):

{
  "id": "per_01H...",
  "soul": {
    "desire": "Kontrolü kaybetmemek",
    "fear": "Boş kalmak",
    "wound": "Erken sorumluluk almaya zorlandı",
    "growthArc": "Yavaşlamayı öğrenmek"
  },
  "self": {
    "traits": ["disiplinli", "tetikte", "merhametli"],
    "values": ["hız", "güven", "dürüstlük"]
  },
  "mask": {
    "voice": "Kısa, doğrudan, az duygu",
    "signaturePhrases": ["Hızlıca toparlayalım", "Şu an için yeter"]
  },
  "surface": {
    "name": { "display": "Cem Aksoy" },
    "age": 34,
    "location": "İstanbul, TR"
  },
  "voiceFingerprintId": "vfp_01H...",
  "audit": { "score": 4.3, "passed": true }
}

Her katman ne anlatır:

• Soul — karakterin neden var olduğu. Tüm varyantlar ve refine'lar boyunca sabit kalan en içsel katman.
• Self — kararlarını nasıl verdiği. Özellikler (traits), değerler, bağlanma stili (attachment style).
• Mask — nasıl konuştuğu. Ton, imza ifadeler, sosyal rol. Varyant ürettiğinde tipik olarak değişen katman.
• Surface — nereli, ne yaşta, hangi dilde. Yerel (locale) varyantı ürettiğinde değişen katman.

Detaylı yapı için Persona katmanları kavramına bak.

4. Denetim ve voice fingerprint arka planda neyi ölçtü

Üretim hattı bitmeden iki ek adım koşar.

Denetim (audit) — LLM-as-judge (yargıç-LLM) ile yedi eksen üzerinden persona'yı puanlar (uyum, derinlik, ayırt edicilik, ...). 5 üzerinden bir skor + her eksenin geçti/başarısız (pass/fail) durumu. Çalışma alanı eşiğinin altında kalan persona'lar status: "needs_review" ile döner.

Voice fingerprint — persona 50 kısa senaryoda konuşturulur, ortaya çıkan konuşma örüntüsü bir referans imzaya dönüştürülür. Bu imza sonradan drift detection (sesin kaymasını ölçme) ve distinctiveness (ayırt edicilik) karşılaştırmaları için kullanılır.

Bu rehberde yapman gerekmeyenler

• Model seçimi — Soul taslağı için claude-opus-4-7, sonraki adımlar için claude-sonnet-4-6 varsayılandır. İhtiyacın varsa çalışma alanı yapılandırmasından geçersiz kılabilirsin.
• Denetimi elle tetikleme — üretim hattının parçasıdır, persona ile birlikte gelir.
• Voice fingerprint'i elle hesaplama — üretim sonrası otomatik koşar.

Başardın

Elinde per_… ile başlayan bir persona kimliği, dört katmanın gerçek içeriği ve bir vfp_… parmak izi kimliği varsa rehber bitti. Persona artık her yerden kullanılabilir.

Sonraki adım