HexabitLabs Studio

Problem

AI ajanlarla birden çok projede çalışırken bağlam, kurallar ve öğrenilenler oturumlar arasında kayboluyor. Hangi ajanın ne yaptığı görünmüyor, değişikliklerin etkisi bilinmiyor ve ajanlar başka projeleri ya da ana dosyaları bozabiliyor.

Rolüm

Ürün sahibi, mimar ve geliştirici: ürün yönünü ve kararları belirledim; macOS uygulamasını, hx CLI'yi ve kütüphaneyi geliştirdim.

Dil, çatı ve kütüphaneler

Dil

• Swift 6 (swift-tools-version 6.2)
• Python 3 (stdlib)

Arayüz

• SwiftUI
• Observation (@Observable)
• SwiftUI Canvas (HexaCanvas)
• macOS 26+

Paketler

• SwiftPM
• Yams 6.x (YAML)
• SwiftTerm 1.20.0 (PTY terminal)
• CryptoKit (Ed25519)
• FSEvents (CoreServices)

Betikler ve araçlar

• hx CLI (Swift)
• Claude Code hooks (Python)
• git pre-commit hook
• build-app.sh

AI araçları

• Claude Code + subagents
• Codex
• Gemini CLI
• Ollama / LM Studio

Test

• Swift Testing (@Test)
• Python unittest

Mimari

• HexabitKit: SwiftUI'dan bağımsız Swift çekirdeği; YAML/Markdown ayrıştırma, model, bilgi grafiği, etki analizi, doğrulama, yazma, senkron ve dosya izleme.
• hx CLI aynı çekirdeği kullanır; komut mantığı test edilebilsin diye ayrı bir kütüphane hedefinde (HXCLI), yürütülebilir yalnız onu çağırır.
• macOS uygulaması üç hedefe bölünür: SwiftUI'sız test edilebilir çekirdek (HexabitLabsCore), yerel kanvas motoru (HexaCanvas) ve SwiftUI görünümleri.
• Kütüphane (kurallar, temel ajanlar, skill'ler, şablonlar, BPMN süreçleri) projelere hx sync ile kopyalanır; projede öğrenilen dersler hx promote ile kütüphaneye yükselir.
• Doğruluk kaynağı dosyalardır: uygulama, CLI, hook'lar ve AI ajanları aynı dosyaları okur/yazar; FSEvents izleyici değişiklikleri uygulamada canlı gösterir. Veritabanı ve sunucu yok.
• Python hook'ları Claude Code olaylarına bağlanır: promptları kaydeder, etkinliği günlüğe yazar, bütçeyi denetler ve proje dışına yazmayı engeller.

Veri yapıları

• HXF-2 dosya formatı: hub, kütüphane ve her proje için hexabit/ klasörü; her kayıt (görev, karar, ders, prompt, rapor) ayrı dosya.
• Kayıtlar YAML frontmatter'lı Markdown: ör. görev (TASK-###) durum/atanan/kabul kriteri, karar (DEC-###) bağlam/karar/alternatifler/sonuçlar.
• Bilgi modeli: gereksinim, BPMN süreci, varlık (ERD + DB eşlemesi), ekran/bileşen, fonksiyon, sembol ve test; aralarındaki ilişkiler izlenebilirlik ve etki analizi grafiğini oluşturur.
• HXP-1 .hexabit paketi: ZIP kabı, manifest (HXPACKAGE.yaml), payload/ klasör ağacı, isteğe bağlı git bundle ve SHA-256 sağlama listesi; taşıma ve sürüm arşivi için.
• Canlı etkinlik sürümlenmeyen JSON/JSONL dosyalarında tutulur (aktif oturumlar, günlük olay kaydı, kullanım defteri).

Yöntem ve desenler

Zorluklar ve çözümler

1. Zorluk v1, TOGAF tabanlı tek projelik bir stüdyoydu (~50 bin satır Swift); 20–30 projenin bakımı hedefine uymuyordu.

   Çözüm Radikal yeniden başlangıç: v1 bir git etiketinde korundu, TOGAF yerine hafif bir bilgi modeli ve tek sözleşme olarak HXF-2 dosya formatı tanımlandı.

2. Zorluk BPMN/diyagram editörü için bpmn-js filigran şartı getiriyordu; web tabanlı editörler çevrimdışı ve tutarlı görünüm hedefiyle çelişiyordu.

   Çözüm SwiftUI Canvas üzerinde kendi kanvas motoru (HexaCanvas) yazıldı; notasyonlar eklenti olarak eklenir, BPMN XML formatı standart kaldığı için dosyalar diğer araçlarda da açılır.

3. Zorluk Ajanlar kendi projesi dışındaki dosyaları, kütüphaneyi ya da ana dosyaları bozabiliyordu.

   Çözüm Her proje ayrı git deposu; guard hook yazmaları proje köküyle sınırlar ve kütüphaneye yazmayı engeller; kütüphane değişikliği yalnız ders önerisi ve director onayıyla (hx promote) olur.

Ölçülebilir sonuçlar

• Swift Testing ile 1.200'ü aşkın test tanımı (çekirdek ve uygulama).
• Hook betikleri için 184 Python testi (grep ile sayıldı).
• Yaklaşık 113 bin satır Swift, 614 kaynak dosyası (testler hariç).
• Kütüphane 1.18.0: 28 temel ajan, 56 skill, 12 kural dosyası.
• Proje kendi kendini yönetir: 152 görev, 23 karar kaydı, 139 ders dosyası.

Sık sorulanlar