Bir gece, beş ajan: Glyphbooth'u yayına almak

Glyphbooth nedir?

Glyphbooth kameranı, ekranını, bir videoyu, bir görseli veya yazdığın bir kelimeyi canlı ASCII, dither, halftone, braille ya da piksel sanatına çevirir. Görüntü müziğe tepki verir. PNG kaydedebilir, WebM video alabilir veya kareyi düz metin olarak kopyalayabilirsin.

Tarayıcıda ve macOS, Windows, Linux için masaüstü uygulaması olarak çalışır. MIT lisanslıdır. Görüntü motoru ham WebGL2 shader'larıyla yazıldı, grafik kütüphanesi yok.

Bu yazı yapım hikâyesidir. Köln'de 5 Ekim'i 6 Ekim'e bağlayan bir geceyi anlatır.

İstek

Claude'a (Opus 5.5) verdiğim istek kısaydı:

• Luis Bizarro'nun Visualizer.app uygulamasından ilham alan, etkileşimli ve indirilebilir bir ürün planla.
• Fikri bir adım öteye taşı.
• Sabaha kadar açık kaynak olarak yayına al.
• Planda benim Prompt Atlası'mı kullan.

Prompt Atlası, prompt yazma ve öğrenme kartlarını topladığım, İngilizce ve Türkçe bir rehber. Plan bu tekniklerden üçünü kullandı.

Plan: üç teknik, her biri için bir örnek

Plan repoda duruyor: docs/PLAN.tr.md.

1. Görev sözleşmesi. İş başlamadan önce amacı, girdiyi, çıktıyı ve bitiş ölçütünü yaz. Glyphbooth'un bitiş ölçütü şuydu:

npm test ve uçtan uca duman testi geçer. Uygulama konsolda hata vermeden açılır. Her mod ve her kaynak en az bir kez çizilir.

Bu cümle daha sonra test paketine dönüştü. Ajanların kontrol edebileceği bir hedefi vardı.

2. Premortem. Sabah olduğunu ve yayının kötü gittiğini varsay. Nedenlerini yaz. Bir satır şöyleydi: kullanıcı kamera iznini reddeder, siyah ekran görür ve gider. Önlem: açılışta hiç izin isteme. Bunun yerine bir demo sahne ve dahili bir ritim çal. Uygulama bugün böyle çalışıyor. Kamerayı istediğinde C tuşuna basıyorsun.

3. Belirsizlik sözleşmesi. Bilgi eksikse makul bir varsayılan seç ve yaz. Böylece kimse gece üçte bir kararı beklemez. Yazılan varsayımlardan biri şuydu: macOS sürümü Apple ile imzalı değil, README ilk açılışı anlatır. Bunu aklında tut. Sonra geri döndü.

Kural yolun ortasında değişti

Planı Claude yazdı. Sonra ilk iskeleti de kendisi yazdı: durum, WebGL2 görüntü motoru ve shader'lar, ses motoru ve sentezleyici, kaynaklar, dışa aktarma ve kontrol paneli. Bu ilk commit saat 01:59'da geldi. Kilit dosyası hariç 23 dosya ve 3.573 satır ekledi.

Sonra onu durdurdum. Şunu söyledim: tek başına yazma. Alt ajanlara yazdır. Sen planla, onları yönet, modellerini sen seç. Standart kural bu.

O andan sonra bütün kodu alt ajanlar yazdı. Orkestratör işi planladı, her ajana kendi dosyalarını verdi ve her turu kontrol etti. Ekran görüntülerine kendisi baktı, testleri kendisi çalıştırdı.

Bence hikâyenin en faydalı kısmı bu. Araçlar değişmedi. Kural değişti.

Ajanlar

Her ajanın ayrı bir dosya grubu vardı. Her turda her dosyanın tek bir sahibi vardı. Commit başlıkları rolleri gösteriyor: (FRONTEND-LEAD), (QA-LEAD), (DEVOPS-LEAD).

İnceleme ve CI neleri yakaladı?

Ekran görüntülerinde (orkestratör). ASCII kenar glifleri | / - \ fazla baskındı. Açık paletler sahneleri mürekkeple boğuyordu. Frontend ajanı kenar çizgilerini seyreltti ve sahnelerde ton ters çevirmeyi kaldırdı (ff00970, 9314b5e).

Testlerde (test uzmanı). Kaynak kodda iki gerçek hata. HTML dışa aktarma sayfa başlığını doğru kaçışlamıyordu. Ses bandı enerjisi, Nyquist frekansının üstünde başlayan bir bant için değer döndürüyordu. İkisi de ff00970 içinde düzeldi.

İncelemede (gözden geçiren). On dört bulgu. Engelleyici olan şuydu: macOS uygulaması imzasızdı. Bu yüzden Apple Silicon'da "hasarlı" görünüyor ve açılmıyordu. Belirsizlik sözleşmesi "imzasız" seçeneğini varsayılan olarak kabul etmişti. Premortem riski yazmıştı, ama önlemi yalnızca belgelemeydi. DevOps ajanı ad-hoc imzalama ekledi (94031ac). Frontend ajanı sağlamlık bulgularını düzeltti (c2e863d).

CI'da (GitHub Actions). Uçtan uca testler yerelde geçti, GitHub'ın makinesinde kaldı. O makinede GPU yok. WebGL yazılımla çalıştı ve saniyede yaklaşık 1 kare çizdi. Test uzmanı yalnızca testlerin kullandığı bir ?quality=low modu ekledi (PR #1). Aynı iş başka bir sorunu da gösterdi: yaklaşık 2 saniyeden kısa kayıtlar boş dosya üretiyordu. Uygulama artık en az 1 saniye kaydediyor. Dosya yine boşsa "Kayıt çok kısaydı" mesajını gösteriyor (e7fe0fe).

Sürümden sonra (ben). v0.1.0 Mac sürümü ad-hoc imzalı. Uygulama açılıyor, ama macOS "Apple doğrulayamadı" diyor. Çünkü ad-hoc imza, Apple onayı (notarization) değildir. DevOps ajanı Developer ID imzasını ve Apple onayını hazırladı (5967f31). Bu adım Apple geliştirici üyeliğimi bekliyor.

Sayılar

Bütün saatler 6 Ekim, Köln saatidir. Git yalnızca ilk commit'ten sonraki işi gösterir. Plan ve iskelet 01:59'dan önce yazıldı.

Bir daha yapsam neyi farklı yapardım?

1. Kuralı ilk kod satırından önce koy. İskeleti, planı yazan ajan yazdı. Sonraki her commit'in ayrı bir yazarı ve ayrı bir kontrolcüsü vardı. İlk commit'in yoktu.
2. Uçtan uca testleri ilk push'tan önce GPU'suz bir ortamda çalıştır. Üç CI çalıştırması, yerelde de üretebileceğim bir sorun yüzünden kaldı.
3. İmzalamayı README notu olarak değil, sürüm şartı olarak ele al. Plan riski yazmıştı. Yazmak yetmedi.
4. Her commit'e modeli kaydet. Her ajan oturumun aynı ortak yazar satırını kullandı. Bu yüzden hangi commit'i hangi modelin yazdığını git tek başına göstermiyor. Yukarıdaki tablo git'ten değil, orkestrasyon kaydından geliyor.

Buradaki ajanlar Claude alt ajanlarıydı. İş akışı araca bağlı değil: plan, sözleşme, dosya sahipliğiyle paralel ajanlar, bağımsız inceleme, CI, sürüm.

Bağlantılar

• Repo: github.com/mrsarac/glyphbooth
• Canlı demo: glyphbooth.mustafasarac.com
• Sürüm: v0.1.0
• Plan: docs/PLAN.tr.md
• Prompt Atlası: mustafasarac.com/prompt-atlasi