Yapay Zeka İş Akışı

Bu proje Claude Code ile inşa edildi. Çoğu “yapay zeka ile geliştirildi” iddiası etikette kalır. İşte tam resim: yapay zekanın ne bildiği, oturumların nasıl işlediği, pratikte istem yazmanın nasıl göründüğü ve insanın çizgiyi nerede çektiği. Eğer siz de yapay zeka ile bir şeyler geliştiriyorsanız veya bunun gerçekte nasıl göründüğünü merak ediyorsanız, bu sayfa tam size göre.

Yapay Zekanın Bildikleri

Claude Code, oturumlar arasında bağlamı taşıyan kalıcı bir bellek dosyasına sahiptir. Her sohbette kod tabanını yeniden keşfetmek yerine, kaldığımız yerden devam eder. İşte bu dosyanın içeriği (hassas bilgiler temizlenmiş haliyle):

Proje Kimliği

Uygulama adı, kaynak konumu, lisans, uygulama tanımlayıcısı
Çatallanma ilişkisi: üst kaynak, Francisco Salgueiro tarafından geliştirilen En Croissant’tır; biz kendi çatalımızı bağımsız olarak sürdürüyoruz
Çatallanmanın nedeni: üst kaynak geliştiricisi TTS özelliğini reddetti — bu anlaşılır bir karar, aynı proje için farklı vizyonlar

Derleme Kuralları

Yalnızca pnpm — npm, vanillaExtract’ı bozar (çalışma zamanında beyaz ekran, hata yok, sadece hiçbir şey)
Node.js 22+ gerekli (Vite 7 için crypto.hash lazım)
Commit öncesi her zaman pnpm format && pnpm lint:fix çalıştır
İkili dosyayı üzerine yazmadan önce uygulamayı kapat (“Text file busy”)
Kaynak dizinlerini taşıdıktan sonra, eski yol referanslarını temizlemek için cargo clean çalıştır

Mimari Bilgisi

Hangi dosyaların hangi özelliklere sahip olduğu (atom’lar atoms.ts’de, ağaç gezintisi tree.ts’de, TTS motoru tts.ts’de)
Neden tüm TTS atom’larının getOnInit: true olması gerektiği (React abone olmadan önce store.get() ile zorunlu okumalar)
Ses önbelleğinin nasıl çalıştığı (provider:voiceId:lang:text anahtarları)
Chessground koordinat düzeltmesinin CSS tarafında olduğu, kütüphanenin çatallanmasıyla değil
Veri düzeni: neyin nerede yaşadığı, neyin sembolik bağlantılı olduğu, neyin uygulama yeniden başlatmalarında korunduğu

Bilmediği Şeyler

Bellek dosyası API anahtarları, parolalar veya kimlik bilgileri içermez. Depolama konumlarına referans verir (localStorage atom adları) ancak asla değerleri içermez. Yapay zeka, anahtarları ayarlardan okuyan kod üretir — gerçek sırları asla görmez veya işlemez.

Yapay Zekaya Söylenenler

Bellek dosyasının ötesinde, Claude Code sistemine yerleştirilmiş kurallara uyar:

Aşırı mühendislik yapma. Yalnızca doğrudan istenen değişiklikleri yap. Bir hata düzeltmesi, çevresindeki kodun temizlenmesini gerektirmez. Üç benzer satır kod, erken soyutlamadan daha iyidir.
URL’leri tahmin etme. Asla uydurma bağlantı veya uç nokta oluşturma.
Düzenlemeden önce oku. Okumadığı koda asla değişiklik önerme.
Oluşturmak yerine düzenlemeyi tercih et. Kesinlikle gerekmedikçe yeni dosya oluşturma.
Güvenlik açığı bırakma. Enjeksiyon, XSS ve OWASP ilk 10 sorununa dikkat et.
Emin olmadığında sor. Bir talimat belirsizse, tahmin etmek yerine sor.
İki kez ölç, bir kez kes. Yıkıcı işlemler (force push, reset —hard, dosya silme) açık insan onayı gerektirir.

İyi İstem Yazmak

Faydalı bir yapay zeka etkileşimi ile sinir bozucu bir etkileşim arasındaki fark neredeyse her zaman istemdir.

Ne istediğinizi net belirtin. “Hatayı düzelt” değil, “TTS önbellek anahtarı sağlayıcı adını içermiyor, bu yüzden ElevenLabs’tan Google’a geçildiğinde yeni ses üretmek yerine önbellekteki ElevenLabs sesi çalıyor.”

Yapay zekanın sahip olmadığı bağlamı ekleyin. Yapay zeka kodunuzu okuyabilir, ama aklınızı okuyamaz. “Kullanıcı tahtadaki koordinatların ters olduğunu bildirdi” cümlesi, “chessgroundBaseOverride.css’deki CSS’te sıralar ve sütunlar yer değiştirmiş — Francisco’nun orijinalinde terslerdi” cümlesinden daha az yararlıdır.

Kısıtlamalarınızı belirtin. “Yeni dosya oluşturma” veya “mevcut atom kalıbını kullan” veya “bunun API anahtarı olmadan çalışması gerekiyor” gibi ifadeler, yapay zekaya sınırları gösterir.

Ne istemediğinizi söyleyin. “Gerçekleşemeyecek durumlar için hata işleme ekleme” veya “çevresindeki kodu yeniden düzenleme” ifadeleri, en yaygın yapay zeka başarısızlık modu olan aşırı mühendisliği önler.

Kalıp şudur: niyet + bağlam + kısıtlamalar. Bunu öğrenirseniz, yapay zeka çarpıcı biçimde daha kullanışlı hale gelir.

Plan Modu: Bir Claude’u Diğerini Yönlendirmek İçin Kullanmak

Claude Code, düşünmeyi yapmaktan ayıran bir “plan modu”na sahiptir. Plan modunda yapay zeka dosyaları okur, kod tabanını keşfeder ve bir plan üretir — ancak kod yazmaz. Planı gözden geçirir, ayarlarsınız, ardından yapay zekanın uyguladığı uygulama moduna geçersiniz.

Bu neden işe yarar? Çünkü herhangi bir kodlama görevinin en zor kısmı kodu yazmak değildir. Asıl zor olan hangi kodun yazılacağını anlamaktır — hangi dosyaların değişeceği, hangi kalıpların izleneceği, hangi uç durumların var olduğu. Plan modu, tek bir satır yazılmadan önce tüm dikkatini bu soruya verir.

Bu projeden bir örnek: Yardım menüsünü yeniden yapılandırıp Dil seçiciyi eklediğimizde, plan modu sohbeti Tauri menülerinin nasıl çalıştığını, hangi atom’ların zaten mevcut olduğunu, belge görüntüleyicinin kaynak yollarını nasıl çözdüğünü ve onay diyalogu API’sinin nasıl göründüğünü araştırdı. Uygulama moduna geçtiğimizde, yapay zeka değişikliklerin eksiksiz bir haritasına sahipti. Yanlış başlangıç olmadı.

Aslında yapay zekanın bir örneğini kıdemli mimar, diğerini geliştirici olarak kullanıyorsunuz. Aynı model, farklı roller.

Oturumlar Nasıl İşler

Tipik bir oturum şu şekilde görünür:

İnsan niyetini belirtir. “KittenTTS bölümüne önbellek notu ekle.” “PostHog telemetrisini kaldır.” “Kalite derecelendirmeleri yanlış, doğruları şunlar.”
Yapay zeka ilgili dosyaları okur. Bir dosyada ne olduğunu tahmin etmez. Okur, mevcut durumu anlar, ardından değişiklik önerir. Birbirinden bağımsız dosyalar paralel olarak okunur.
Yapay zeka değişikliği yapar. Mevcut dosyalara hedefli düzenlemeler. Yeniden yazma değil — çevresindeki her şeyi koruyan cerrahi müdahaleler.
İnsan gözden geçirir. Her düzenleme diske yazılmadan önce gösterilir. İnsan onaylar, reddeder veya yönlendirir. “Hayır, çok yumuşak olmuş — gerçekten berbat olduğunu söyle.” “O paragrafı yukarı taşı.” “Kastettiğim bu değildi.”
Söylendiğinde commit eder. Yapay zeka kendi inisiyatifiyle asla commit etmez. İnsan “commit et” veya “commit et ve gönder” der. Commit’ler Co-Authored-By: Claude Opus 4.6 içerir — her zaman atıf yapılır, asla gizlenmez.

Bağlam Pencereleri ve Kayıt Noktaları

Her yapay zeka sohbetinin bir bağlam penceresi vardır — aynı anda bellekte tutabildiği toplam metin miktarı. Sohbet yeterince uzadığında, yer açmak için eski mesajlar sıkıştırılır.

İki strateji: sohbetleri odaklı tutun (sohbet başına bir görev) ve kayıt noktalarını kullanın (Claude Code, tam bağlam geri yüklenerek devam edilebilen JSONL dosyaları olarak transkriptleri kaydeder). Bellek dosyası farklı bir amaca hizmet eder — tüm sohbetler boyunca kalıcı bir bilgi tabanıdır.

Yapay Zekanın Önerdiği ile Yayınlanan

Yapay zekanın ilk önerisi nadiren son sürümdür. Tipik bir alışveriş:

Yapay zeka makul bir şey taslaklar
İnsan “çok kurumsal” veya “daha doğrudan ol” veya “bu yanlış, sebebi şu” der
Yapay zeka ayarlar
İnsan onaylar

Zevk, üslup ve nihai karar her zaman insana aittir. Yapay zeka hızı sağlar — dosyaları okumak, bağlamı anlamak, bellekte tutabildiği bir kod tabanı boyunca hassas düzenlemeler yapmak. İnsan yargıyı sağlar — ne inşa edileceği, nasıl hissettirmesi gerektiği, ne zaman durulacağı.

Yetenekler ve Eğik Çizgi Komutları

Claude Code, .claude/commands/ dizininde markdown dosyaları olarak saklanan yeniden kullanılabilir istemler olan “yetenekleri” destekler. Bunları /translate-docs gibi bir eğik çizgi komutuyla çağırırsınız.

Bu proje, dokümantasyonu birden çok dile çevirmeyi otomatikleştiren bir /translate-docs yeteneği kullanır. Yetenek dosyası tam talimatları içerir: hangi dosyaların çevrileceği, hangi formatın kullanılacağı, kod blokları ve bağlantıların nasıl ele alınacağı, hangi üslubun korunacağı. Bunu her seferinde açıklamak yerine, sadece /translate-docs yazarsınız ve yapay zeka tam olarak ne yapacağını bilir.

Yetenekler yalnızca bilgiyi değil, süreci kodlar. Test çalıştırma, dağıtım yapma, PR inceleme, değişiklik günlüğü güncelleme gibi herhangi bir tekrarlayan iş akışı için yetenek oluşturabilirsiniz.

Kodlama İlkeleri

Tam ilkeler belgesi depoda .claude/01_UNIVERSAL_PRINCIPLES.md adresinde bulunmaktadır. Robert C. Martin’in Clean Code (2008) kitabıyla başladı ve yapay zeka çağı için eklemeler yapıldı. Ardından neyin hâlâ geçerli olduğu ve neyin olmadığı hakkında dürüst bir konuşma yaptık.

Zamana Dayanıklı Olanlar

Niyeti açıklayan isimler. Her zaman. Sonsuza dek.
Fonksiyonlar tek bir şey yapar. Asıl ilke tutarlılıktır, boyut değil.
Yan etkiler olmasın. Hâlâ çoğu hatanın kaynağı.
Yorumlar nedenini açıklar, ne olduğunu değil.
Tek Sorumluluk. Bir modülün değişmesi için tek bir neden olmalı.
Uygulamalara değil, arayüzlere programla.
Hataları yutma. Her hata bir bilgidir.
Beliren tasarım: tüm testleri geçer, tekrar yok, niyeti ifade eder, karmaşıklığı en aza indirir. Bu sırayla.

Bağlama Bağlı Olanlar

Bu ilkeler sağlamdır, ancak spesifik kurallar yapay zeka öncesi veya dile özgü bir dünyayı yansıtır. Harfi harfine değil, ruhunu uyguluyoruz:

DRY. Birbirinden ayrışan tekrar tehlikelidir. Ancak tekrarlanan her kalıbı bir soyutlamaya çıkarmak, daha kötü olabilecek bir dolaylama yaratır. Bazen başka bir dosyadaki erken soyutlamadan, tam burada okunabilir üç satır daha iyidir.
Katı TDD seremonisi. İlke — test edilmiş kod gönder, çalıştığını bil — tartışılmaz. Seremoni — test koddan önce var olmalı — insanların yavaş yazdığı bir iş akışı için tasarlanmıştı. Test yaz. Geçtiğinden emin ol. Testin mi kodun mu önce geldiği, ikisinin de var olup olmadığından daha az önemlidir.
İzci Kuralı. “Kamp alanını daha temiz bırak” — evet. Ama izci kamp alanını temizledi, tüm ormanı değil. Dokunduğunu düzelt. Bir satırını değiştirdiğin için dosyanın tüm yapısını yeniden düzenleme.

Yapay Zeka Çağı Eklemeleri

İlke tabanlı rehberlik, kurallardan daha iyi ölçeklenir. İlke yargıya izin verir; kural kırılgandır.
Aracı inşa ettiyse, aracı bakımını da yapabilir. Sohbet bağlamını ve çıktıları koruyun. Sadece sonucu değil, inşa sürecini de belgeleyin.
Açıklık, zekilikten önce gelir. Bu sistemi inşa eden yapay zekanın muhakemeyi yeniden kurması ve doğru şekilde değiştirmesi gerekir. Açık yapı, küçük zeki soyutlamalardan üstündür.
Bu altyapı olabilir mi? Bir araç sizin için bir problemi çözer. Altyapı, başkalarının üzerine inşa etmesini sağlar. Buna göre tasarlayın.

İnsanın Çizgiyi Çektiği Yer

Yapay zeka bir araçtır. Son derece iyi bir araç. Ancak yapmadığı şeyler vardır:

Ürün kararları. Hangi özelliklerin geliştirileceği, neyin çıkarılacağı, uygulamanın nasıl hissettirmesi gerektiği. “Sistem TTS kalite derecelendirmesi ‘idare eder’ demeli çünkü gerçekten berbat” — bu, gerçekten dinleyerek yapılan bir insan yargısı.
Zevk. Yapay zeka temiz düzyazı yazabilir, ancak projenin sesi, kalite konusunda dobra olmak kararı, Francisco’yu belirgin şekilde takdir etme tercihi — bunlar insan seçimleridir.
Etik. PostHog’u kaldırmak bir yeniden düzenleme görevi değildi. “Ayarlar sayfası telemetri toplamadığımızı söylüyor, ama kodda aktif bir PostHog API anahtarı var. Bu bir yalan. Düzelt.” demekti. Yapay zeka uyguladı. Problemi tespit eden ve umursayan insandı.
Satranç. Tahta araçlarınızla ilgilenmez.

Bunu Neden Paylaşıyoruz

Çünkü “yapay zeka ile geliştirildi” anlamsız hale geldi. Herkes söylüyor. Kimse göstermiyor. İlginç soru yapay zekanın dahil olup olmadığı değil — nasıl dahil olduğu ve insanın gerçekte ne katkı sağladığı.

İşte cevap bu. İnsan vizyonu, zevki, yargıyı ve hesap verebilirliği getirir. Yapay zeka hızı, belleği ve gece 2’de Rust hata mesajlarını okuma konusundaki yorulmak bilmez istekliliği getirir.

Hiçbiri bunu tek başına inşa edemez. İkisi de takdir edilir. Anlaşma budur.

En Parlant~, Francisco Salgueiro tarafından geliştirilen En Croissant’ın bir çatalı olup, Anthropic tarafından geliştirilen Claude Code ile inşa edilmiştir.