Sarmal

İNSAN MAKİNİST, AI HIZLI TREN, SARMAL HEDEFE SAPMADAN GÖTÜREN RAY

Sarmal, bir yazılım projesinin planını, kurallarını ve kararlarını .sar dosyalarında tutan açık kaynak bir dildir. Bu dosyalar insan için okunur, makine için denetlenebilir: motor her kaydetmede planı diskle karşılaştırır, VS Code eklentisi sonucu panellerde gösterir, MCP sunucusu aynı bilgiyi yapay zekâ ajanlarına verir. Sarmal kod üretmez; kodun neden ve hangi sırayla yazıldığını kaybolmaz hâle getirir.

Hangi derdi çözüyor

Yapay zekâ ajanlarıyla çalışan bir projede plan sohbette kalır, karar bir önceki oturumun bağlamında kalır, kod plandan önde koşar ve üç hafta sonra kimse hangi işin neden yapıldığını söyleyemez. Ajan her oturuma sıfırdan başlar, insan bağlamı yeniden anlatır ve anlatılan şey her seferinde biraz değişir. Sorun ajanın zekâsı değil, projenin hafızasının makinenin okuyamadığı yerlerde durmasıdır.

Sarmal bu hafızayı tek bir kaynağa indirir. Plan dört eksende yazılır: zaman (Faz), iş (Blok), teknoloji (Katman) ve akış (Adım). Her Adım görevini, kabul ölçütünü, sınırını, dayandığı kararı ve ürettiği dosyayı beyan eder. Kararlar gerekçesiyle kaydedilir, kurallar tek bir kanonda toplanır ve motor bütün bu beyanları gerçekle karşılaştırır: ilan edilen dosya diskte var mı, tamamlandı denen iş kanıt taşıyor mu, atıf verilen karar gerçekten tanımlı mı, açılan klasör ilan edilmiş mi.

Nasıl çalışıyor: gerçek bir örnek

Doğuş paketiyle doğan küçük bir projede ikinci Faz kendi dosyasında açılmış ve işin Bloku o Fazın gövdesine yazılmış olsun (is/plan/faz/2_randevu.sar):

Faz( kod: FAZ-RANDEVU-UC, ad: "Randevu Ucu Mevsimi" ) {
  Blok( kod: BLK-RANDEVU-API, ad: "Randevu Ucu",
    ne: "Randevu oluşturma ucunun yazımı" ) {
    Katman( kod: KAT-RANDEVU-ARKAYUZ, ad: "Arka Yüz", takım: TAKIM-ARKAYUZ ) {
      AltKatman( kod: ALT-RANDEVU-UC, ad: "Uç", departman: kodlama ) {
        Adım( kod: ADM-RANDEVU-01, ad: "Randevu ucu", durum: tamamlandı,
          görev: "POST /randevu ucunu yaz",
          kabul: [ "uç 201 döner" ],
          üretir: [ Meyve( kod: MYV-RANDEVU-UC, tür: Kod, dosya: "src/randevu.ts" ) ] )
        Adım( kod: ADM-RANDEVU-02, ad: "Randevu sınaması", durum: geliştirmede,
          bağımlı: [ ADM-RANDEVU-01 ], referans: [ KRR-RANDEVU-03 ],
          görev: "Ucun sınamasını yaz",
          kabul: [ "sınama yeşil" ] )
      }
    }
  }
}

Birinci Adım tamamlandı diyor ama src/randevu.ts diskte yok; ikinci Adım hiç yazılmamış bir karara atıf veriyor. sarmal denetle . bunu şöyle bildirir (çıktı gerçektir, satırlar kırılmıştır):

✖ is/plan/faz/2_randevu.sar:11:52 [kırık-referans] 'referans: KRR-RANDEVU-03' hedefi çözülmüyor —
  bu KOD hiçbir .sar'da tanımlı değil.
✖ is/plan/faz/2_randevu.sar:9:21 [meyve-dosyası-eksik] Meyve "MYV-RANDEVU-UC" (tür: Kod) dosya-zorunlu
  bir teslim ama beyan edilen yol diskte çözülmüyor ("src/randevu.ts").

Yukarıdaki blok yalnız iki hatayı gösterir; tam koşu uyarı ve bilgi satırlarını da taşır.

Dosya yazılıp atıf düzeltildiğinde motor bu kez başka bir şeyi fark eder: src/ klasörü diskte var ama projenin giriş dosyasında ilan edilmemiştir.

✖ [beyansız-yapı] 'src/' diskte var ama randevu_anadizin.sar'da ilan edilmemiş — açılan her
  klasör giriş dosyasında bildirilmelidir; ilansız yapı zamanla plandan kopar.
   ↳ randevu_anadizin.sar'a ekle: Kitaplık( kod: KTP-…, yol: "src/", ne: "…" ) — ya da klasörü kaldır.

Klasör ilan edilince karne temizdir: yirmi bir düğüm, üç Adım, sıfır hata. Plan yalan söyleyemez, disk de; ikisi ayrıştığında bunu bir insanın fark etmesi gerekmez.

Aynı plan editörde de yaşar: Yol Haritası ağacı, Mini Graf ve Sorunlar paneli aynı kaynağı okur, dosya kaydedildiği anda tanı düşer.

Çalışma ağacı

Sarmal'da her şey bir ağaçtır ve ağacın kökü projenin giriş dosyasıdır. Doğuş paketiyle doğan bir proje diskte şöyle durur:

randevu/
├── randevu_anadizin.sar        giriş: Proje → Kitaplık → Raf, Teknoloji ve Takım burada ilan edilir
├── is/                         işin kitaplığı
│   ├── plan/faz/               her Faz sıra önekli kendi dosyasında: Faz → Blok → Katman → AltKatman → Adım
│   │   ├── 1_dogus.sar
│   │   └── 2_randevu.sar
│   └── durum/durum_devir.sar   nerede kaldık: oturum sonu devir kaydı
├── ogreti/ogrenme/             dersler ve geribildirim; Bellek buradan Beceriye yükselir
├── oz/siniflama/isaretci.json  tip kanonu işaretçisi; eklenti kanon kaydını bu raftan çözer
├── CLAUDE.md · AGENTS.md       ajan yönergesi (ikisi bayt özdeş ikizdir)
├── .mcp.json                   Sarmal MCP sunucusunun kaydı — ajan araçlara buradan bağlanır
├── .claude/                    settings.json ve kanca/: denetim kapısı ile doğuş kilidi
├── .gitignore                  "!*.sar" istisnası; küresel yok sayma plan hafızasını yutamaz
└── src/                        kod; diskte açılan her klasör giriş dosyasında ilan edilmek zorundadır

Çizimdeki 2_randevu.sar ile src/ klasörü işin kendisine aittir; geri kalan on üç dosyanın
tamamını dogus aracı yazar ve hiçbiri elle kurulmaz. Çalışma alanı türü seçilirse
aynı paket iki kere doğar: bir kere çatı için, bir kere de çatının altındaki ilk proje için.

Mantık dört cümledir. Birincisi, yapı önce ilan edilir: giriş dosyası dallanan her klasörü Kitaplık, bir Kitaplığın içindeki her yaprak klasörü Raf olarak yazar ve ilansız klasör motor için drifttir. Kitaplık kademesi atlanamaz; kökün altına çıplak Raf dizilirse ağaç büyüdükçe giriş dosyası okunamaz bir liste hâline gelir. İkincisi, plan zamandan işe, işten teknolojiye, teknolojiden akışa iner: Faz bir mevsimdir, Blok tek kimlikli bir iş gövdesidir ve yaşadığı Fazın gövdesine sarılır, Katman bir Takıma ya da Teknolojiye bağlanır, AltKatman o teknolojinin içindeki konudur, Adım en küçük yürütme birimidir ve ürettiği Meyve diskte bir dosyaya çözülür. Üçüncüsü, her düğümün tekil bir kodu vardır ve düğümler yalnız kenarla bağlanır: bağımlı sırayı, üretir teslimi, referans dayanağı, uygular kuralı taşır; bir bağ tek yerde yazılır. Dördüncüsü, çalışma alanı birden çok projeyi kapsayabilir ve her proje kimliğini kendi kökünden türetir; bu depo da tam böyle yaşar: is/ altındaki plan Sarmal'ın kendi ağacıdır.

Ajanlar için ne değişiyor

Aynı dosyaları MCP sunucusu ajana on sekiz araçla açar. sef bir Adımın konisini, yani görevini, kabul ölçütünü, sınırını, dayanağını ve son koşu özetini tek istemde toplar; gezin bir kodun tanımını ve bütün atıflarını verir; etki bir düğüme dokununca hangi Adımların etkileneceğini söyler; denetle-proje bütün projenin hükmünü döndürür. Ajan dosya taramak yerine grafı sorar ve oturum değişince bağlam kaybolmaz, çünkü bağlam sohbette değil kaynaktadır. Üretici ile denetçi ayrıdır; bir Adımın kapanışı kanıt ister ve kanıt olmayan kapanışı motor gösterir.

TEK TEKNOLOJİYLE, TEK AJANLA KÜÇÜK BİR PROJE YAPACAKSANIZ SARMAL SİZE TAVSİYE EDİLMEZ

Dürüst olalım: tek dilli, tek teknolojili, birkaç haftalık bir iş için Sarmal ağırdır. Yüz on dokuz maddelik bir kanon, yüz yetmiş beş tanı ve altı kademeli bir plan ağacı, üç ekranlık bir uygulamanın taşıyamayacağı bir törendir; o işte iyi bir README ve Git yeter. Sarmal'ın değeri üçüncü haftada, bir kararın gerekçesini ararken ya da kod plandan koptuğunda hissedilir; ondan önce yalnız bedelini ödersiniz.

BİRDEN ÇOK YAPAY ZEKÂ AJANIYLA ON CİVARI TEKNOLOJİYİ BİR ARAYA GETİRİYORSANIZ YA DA SEKTÖREL VEYA KİŞİSEL BİR İŞLETİM SİSTEMİ KURUYORSANIZ SARMAL BUNUN İÇİN YAPILDI

Birden çok ajanın aynı planda çalıştığı, arka yüzden mobil uygulamaya, veritabanından altyapıya on civarı teknolojinin tek ürün içinde buluştuğu, kararların aylarca geçerli kalması gereken ve işin çoğunu ajanların yaptığı projelerde Sarmal tam yerindedir. Ajanlar dosya taramak yerine aynı grafı sorar, her teknoloji kendi Katmanında kendi Takımına bağlanır, kararlar gerekçesiyle kalır ve plan ile disk ayrıştığında motor bunu insana taşır. Bir işletmenin ya da bir kişinin bütün işini ajan kadrosuyla yürüten bir işletim sistemi kurmak isteyen için Sarmal o kadronun ortak dili ve denetçisidir; bu deponun kendisi o düzenin ilk örneğidir.

Beş yüz kişilik bir monorepo için yine değildir; orada olgun araçlar vardır ve Sarmal ikinci bir gerçek kaynağı olur. Git'e rakip değildir: Git satırın tarihini tutar, Sarmal aynı değişikliğin plan düzeyindeki anlamını. İş takip aracına da rakip değildir: iş listesi tutmaz, işin gerçekle tutarlılığını ölçer.

Bu depo Sarmal'ın kendisiyle yönetilir: is/ altındaki plan, durum kaydı ve hatırlatıcılar dilin kendi üstünde koştuğunun kanıtıdır ve olduğu gibi açıktır.

Aşağıdaki bölümler kanonik kaynaklardan üretilir; yalnız bu giriş elle yazılır.

Kurulum

Çekirdek Node 23.6 ya da üstünü ister: cd urun/cekirdek && npm link komutu sarmal komutunu kabuğa bağlar; sürüm şartının kaynağı urun/cekirdek/package.json dosyasıdır. Eklenti mağazada yayımlandığında oradan kurulur; o güne kadar urun/eklenti içinde npm install && npm run build ile derlenir ve F5 ile geliştirme penceresinde koşar (urun/eklenti/README.md). MCP sunucusu node urun/cekirdek/src/mcp.ts komutuyla stdio üzerinden başlar; Claude Code için claude mcp add sarmal -- node <depo>/urun/cekirdek/src/mcp.ts yeterlidir.

MCP sunucusu: kurulum ve erişim

Bu bölüm, sunucuyu inceleyen kişinin onu sıfırdan kurmasını ve her araca ulaşmasını sağlar. Sunucu yerelde stdio üzerinden koşar, hesap, anahtar ya da oturum açma istemez ve hiçbir ağ çağrısı yapmaz. Gereksinimler yalnız Node.js 23.6 ya da üstü ile Git'tir: Node sunucunun TypeScript kaynağını doğrudan koşturur ve sunucu yalnız Node'un yerleşik modüllerini içe aldığı için npm install adımı yoktur.

1. Kodu alın ve çalışma zamanını doğrulayın; node --version komutu v23.6.0 ya da üstünü basmalıdır.

git clone https://github.com/nexivion-labs/sarmal.git
cd sarmal
node --version

1. Sunucudan araç listesini hiçbir istemci olmadan isteyin. Araç başlıkları ve açıklamaları varsayılan olarak Türkçedir; komutun önüne SARMAL_DIL=en yazılırsa İngilizce döner.

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | node urun/cekirdek/src/mcp.ts 2>/dev/null \
  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{for(const t of JSON.parse(s).result.tools)console.log(t.name.padEnd(15),(t.annotations.readOnlyHint?"okur":"yazar").padEnd(10),t.title)})'

Beklenen çıktı her araç için bir satır olmak üzere 18 satırdır: 15 araç yalnız okur, 3 araç diske yazar.

sef             okur       Adım brifingi üret
ogret           okur       Sarmal'ı öğret
kavram          okur       Kavram sorgula
karne           okur       Etmen karnesini oku
basla           okur       Doğuş rehberi ve şablon iste
dogus           yazar      Doğuş paketini diske yaz
graf            okur       Proje grafını oku
gezin           okur       Tanıma ve atıflara git
denetle         okur       Tek .sar kaynağını denetle
kurallar        okur       Kanon kurallarını oku
siniflama       okur       Tip kanonunu oku
denetle-proje   okur       Projeyi baştan sona denetle
iskelet         yazar      İlan edilen iskeleti üret
etki            okur       Etki analizini oku
bul             okur       Düğüm metninde ara
bicimle         okur       Kaynağı biçimlendir
prizma          okur       Kaynağı başka yüze yansıt
durum-guncelle  yazar      Adım durumunu yaz

1. Sunucuyu bir istemciye bağlayın. Claude Code için aşağıdaki iki komutu çalışacağınız klasörde, klonunuzun mutlak yoluyla koşturun. Klonun kendi içinde bir şey eklemeye gerek yoktur, çünkü klonun .mcp.json dosyası sunucuyu zaten kaydeder ve claude ilk açılışta bir kez onay ister.

claude mcp add sarmal -- node /mutlak/yol/sarmal/urun/cekirdek/src/mcp.ts
claude mcp list

Beklenen satır sarmal: node /mutlak/yol/sarmal/urun/cekirdek/src/mcp.ts - ✔ Connected biçimindedir.

1. Örnek bir proje doğurun ve üzerinde bir araç çağırın. MCP Inspector her aracı komut satırından çağırır; iki komutu klonun içinde koşturun. İlki dogus aracıyla bir proje yazar ve doğan dosyaları listeler; ikincisi o projeyi denetle-proje aracıyla denetler ve özet satırı sıfır hatayı 0 hata olarak bildirir.

npx -y @modelcontextprotocol/inspector --cli node urun/cekirdek/src/mcp.ts --method tools/call --tool-name dogus --tool-arg hedef="$HOME/sarmal-demo" --tool-arg ad=Demo --tool-arg tur=proje
npx -y @modelcontextprotocol/inspector --cli node urun/cekirdek/src/mcp.ts --method tools/call --tool-name denetle-proje --tool-arg dizin="$HOME/sarmal-demo"

Gizlilik Politikası

Sarmal hiçbir veri toplamaz: motor sizin makinenizde koşar, planınız makinenizden çıkmaz ve eklenti hiçbir sunucuya bağlanmaz. Eklenti ile MCP sunucusu kişisel bilgi, dosya içeriği ya da kullanım istatistiği toplamaz; üçüncü taraflarla paylaşılan ya da saklanan hiçbir veri yoktur. Politikanın tam metni, iddianın nasıl ölçüldüğü ve iletişim adresi PRIVACY.md dosyasındadır.

İlk beş dakika

1. sarmal doğuş <klasör> --tur proje --ad <Ad> boş bir klasörde giriş dosyasını, ilk planı, durum kaydını ve ajan yönergesini doğurur.
2. sarmal denetle <klasör> ilk hükmü verir; doğan proje sıfır hata ile başlar ve tek açık Adımı kuruluş diyaloğudur.
3. Kuruluş Adımı kod yazmaz: teknolojiyi ve takımı giriş dosyasına ilan eder, doğuş paketinin bıraktığı yönerge metinlerini kendi cümlelerinle doldurur.
4. sarmal sef <ADIM-KOD> <klasör> bir Adımın konisini ajana verilecek istem olarak basar; sarmal sonraki <klasör> koşulabilir Adımları listeler.
5. sarmal ogret karşılama kartını, sarmal başla şablon kütüphanesini, sarmal gezin <KOD> <klasör> bir kodun tanımı ile atıflarını gösterir.

Raf haritası

yasa/kanon/ kanonun tek adresidir: sekiz bölüm dosyasında 163 tekil madde yaşar, 38 Karar ve 125 Kural. oz/siniflama/ tip sistemidir; ogreti/ şablonları, örnekleri ve öğretim yüzlerini taşır; is/ Sarmal'ın kendi planı, durum kaydı ve hatırlatıcılarıdır; urun/cekirdek/ motor, komut satırı ve MCP sunucusu, urun/eklenti/ VS Code eklentisidir. Kalıcı belgeler hüküm kopyası değil, bu kaynaklardan üretilen okuma yüzleridir.

Öğren

NEDIR.md kavramsal açıklamayı, KAVRAMLAR.md başvuru indeksini, ROL-HARITASI.md açık/kapalı rol sınırını, urun/eklenti/README.md eklentiyi kullanma görevini ve oz/siniflama/kayit.md tam tip/alan Reference tablosunu verir. Kendi etmenini yazma yeteneği açık kapsamın parçasıdır: Etmen · Beceri · Tetikleyici + sef. Etmen kimliği ve yetkisi, Beceri uygulanabilir bilgisini, Tetikleyici ne zaman devreye gireceğini bildirir; sef ise Adım konisini bu bağlamla kurar.

Katkı ve lisans

Katkı yolu CONTRIBUTING.md, davranış kuralları CODE_OF_CONDUCT.md, güvenlik bildirimi SECURITY.md dosyasındadır. Sarmal Apache-2.0 lisansı ile açıktır; üçüncü taraf atıfları NOTICE.md dosyasında yaşar. Sarmal ile yönetilen ayrı bir kapalı ürün vardır; bu belge o ürünün içeriğini anlatmaz.

Ölçülen yüzler

Yeni tanı kümesi 50 hata, 27 uyarı ve 21 bilgi düzeyindedir. Sabit sicilin yönlendirme matrisi 158 Problems, 3 Hatırlatıcılar ve 38 Bildirimler (Gözlemler) olarak ölçülür. Tanı metinlerinin 198'i, 18 MCP aracının açıklamaları, manifest, karşılama kartı ve bu belge yüzleri iki dillidir; sayılar kaynaktan ölçülür ve elle yazılmaz.