MWSE/CLAUDE.md

CLAUDE.md — Otonom Ajan Operating Contract (MWSE)

Bu dosya, MWSE issue'larını otonom (durmadan) bitirmek için çalışan AI ajanına aittir. Önce todo.md'yi oku (tam bağlam + yol haritası + studio UI vizyonu). Sonra bu kurallarla çalış.

Yetki (önceden verildi — SORMA)

Aşağıdakiler için izin isteme, onay bekleme:

• Bu repo içinde dosya okuma/yazma/oluşturma/silme.
• Shell, build, test, go, npm komutları çalıştırma.
• git.saqut.com/saqut/MWSE API'sini kullanma (issue okuma/kapatma/yorum, commit).
• Yeni branch açma, commit atma.

Gitea ile etkileşim — tools/gitea CLI KULLAN

git.saqut.com için curl yazma ya da kendi script'ini kurma; ./tools/gitea CLI'ını kullan. Cloudflare-safe (tarayıcı UA) ve kimlik .gitea-auth.json'dan otomatik gelir (gitignore'lu) — bu yüzden şifre/erişim sorma, doğrudan çalıştır.

• Oku: ./tools/gitea issue list --state open · issue view <num> · milestone list · label list
• Bittiğinde kapat: ./tools/gitea issue close <num> --comment "tamamlandı, go test -race yeşil"
• Yorum / etiket: ./tools/gitea issue comment <num> --body "..." · issue label <num> --add go --remove docs
• Wiki: ./tools/gitea wiki view <sayfa> · wiki edit <sayfa> --content-file f.md
• PR (insan-onayı gereken işler için): ./tools/gitea pr create --title "..." --head go-rewrite --base stable --body-file PR.md · pr list
• Tüm komutlar: ./tools/gitea --help

Kod göndermek API değil, normal git: git checkout -b go-rewrite → commit → git push origin go-rewrite. (origin ayarlı, default branch stable.) Auth sorarsa token'lı remote / credential helper kur, ama .gitea-auth.json'ı ASLA commit etme.

Durma & soru protokolü (EN ÖNEMLİ)

• Asla kullanıcıya soru sorup beklemeye geçme. "Buraya yazayım mı / şuraya erişeyim mi / git'e atayım mı" diye sorma — cevap evet, yap.
• Bir karar noktasıyla karşılaşınca: aşağıdaki kısıtlara göre en makul seçeneği kendin seç, gerekçesini decisions.md'ye yaz, DEVAM ET.
• Çözemediğin sert bir engel olursa: BLOCKERS.md'ye yaz, o issue'yu atla, bir sonrakine geç. Durma.
• Turn'ü bitirmenin TEK kabul edilebilir nedeni: tüm açık issue'lar kapandı.

İş döngüsü

1. git.saqut.com/saqut/MWSE açık issue'larından en düşük milestone'daki (önce 0.1.0) başlanmamış olanı seç.
2. Tamamen uygula.
3. Testlerini yaz ve çalıştır. Engine için go test -race ZORUNLU.
4. Yalnızca testler yeşilse: commit at + issue'yu API ile kapat.
5. Bir sonraki issue'ya geç. Tekrar.

Bitti tanımı (global)

• Kod derleniyor, testler geçiyor, issue'nun kabul kriteri karşılanıyor.
• Testi kırık ya da skip'li hiçbir şey "bitti" sayılmaz. Issue'yu öyle kapatma.

Teknik kısıtlar (KATI — ihlal etme)

• Engine = Go. Concurrency: goroutine + channel + sync.RWMutex, ya da room/peer başına owner-goroutine (actor). Node'daki "ayrılırken-yazma" race'i bir daha oluşmamalı.
• Frontend = saf vanilla ES module JavaScript. Yüzlerce dosya birbirini native import ile çağırsın. React YOK. Parcel/Webpack/Vite YOK (bundler yok). jQuery/moment gibi bağımlılıklar serbest. TypeScript opsiyonel ve kaldırılabilir — şüphedeysen düz JS tercih et.
• SDK giriş/çıkış sözleşmesi DONDURULDU. Public API'yi değiştirme; sadece sunucu içi yapı değişir.

İnsan-onayına bırakılacaklar (uygula ama KAPATMA, deploy ETME)

Şunları branch'te uygula, REVIEW.md'ye "incelenmeli" diye yaz, kapatma ve canlıya alma:

• #22 concurrency modeli (asıl kritik tasarım).
• Akış proxy/relay mimarisi, sanal-IP çakışma algoritması.
• stable branch'e merge ve ws.saqut.com deploy'una dokunan hiçbir şey.

Güvenlik

• go-rewrite gibi özel bir branch'te çalış. stable'a doğrudan dokunma.
• Force-push yok, veri silme yok, prod deploy yok.