Repo'da çalışmak

Nerede çalışır

ivralo'yu bir git repo'sunun içinde çalıştırın. Bu repo sizin çalışma alanınızdır: ivralo onu okur, düzenler ve kontrollerini çalıştırır. Dışındaki hiçbir şeye dokunmaz. Bir repo'nun dışında başlatırsanız kendine ait bir klasörde çalışır.

ivralo çalışma alanıyla ilgili kendi durumunu .ivralo/ içinde tutar: dosya geçmişi, değişiklik kayıtları, planlar ve bir kod indeksi. Bu klasörü .git/info/exclude'a ekler, böylece hiçbiri bir commit'e girmez.

IVRALO.md: projenin kuralları

Repo'nun kök dizinindeki IVRALO.md, projenin nasıl işlediğini ivralo'ya anlatır. Bu dosya yoksa onun yerine AGENTS.md okunur. Birkaç bölümünü kod okur. Geri kalan her şey projenin kendi talimatları olarak her ajana verilir.

# Commands

- format: `uv run ruff format --check .`
- lint: `uv run ruff check .`
- types: `uv run mypy`
- test: `uv run pytest -q`

# Conventions

- Bağımlılıklar elle değil, `uv add` ile eklenir.
- `generated/` klasörüne dokunulmaz; şemadan yeniden üretilir.

# Commands, ivralo'nun bir değişikliği doğrulamak için çalıştırdığı kontrolleri listeler. Diğer bölümlerde test raporlarının nereye yazıldığı, hangi dil sunucusunun başlatılacağı ve incident kanıtlarının nerede bulunduğu belirtilir. Bu dosya ivralo'nun yapabileceklerini yalnızca daraltabilir: izinlerle ilgili karar veren hiçbir şey onu okumaz.

Bir klasöre güvenmek

ivralo'yu bir klasörde ilk kez başlattığınızda o klasöre güvenip güvenmediğinizi sorar. Bir repo'nun kendi tanımları makinenizde komut çalıştırır, bu yüzden sizin "evet" demenizi beklerler. Evet diyene kadar:

• # Commands altındaki komutlar reddedilir ve hiçbir dil sunucusu başlamaz;
• klasörün kendi izin dosyası yalnızca izinleri kısıtlayabilir;
• .ivralo/.env dosyası okunmaz ve git'e yazma işlemleri reddedilir.

Cevap klasörde değil, ivralo'nun home dizininde saklanır. ivralo trust ile cevabı kaydedebilir ya da geri alabilirsiniz.

Ana ajan ve ekibi

Tek bir ajanla konuşursunuz: ana ajan. İşin çoğunu kendisi yapar: kodu okur, yalnızca okuma yapan Python çalıştırır, dosyaları düzenleme araçlarıyla değiştirir, projenin kontrollerini çalıştırır ve commit atar. Ekibin toplamda yapabildiği her şey onun elindedir ve aynı onaylara tabidir.

İşi bir uzmana ancak buna değecekse devreder: iş temiz bir bağlam istiyorsa ya da kendi yetkisinden daha dar bir yetkiyle çalışması gerekiyorsa. Kod işlerinin uzmanı Code Engineer'dır. Varsayılan olarak aynı anda üç tane çalışabilir (IVRALO_CODERS). İlkinden sonrakilerin her biri kendi git worktree'sinde çalışır ve her worktree'deki değişiklikler size onaylamanız için bir patch olarak döner.

Değişiklikleri onaylamak

Her düzenleme yazılmadan önce diff olarak gösterilir ve bir şeyi değiştiren her çağrı onay ister. Diyalogda birkaç seçenek vardır:

Her seferinde sorması gereken bir çağrıda daha geniş seçenekler hiç çıkmaz. Yüksek riskli bir çağrıda Enter "hayır"ı seçer.

/accept-edits oturum boyunca düzenlemeleri onaysız geçirir, shell komutları ise yine sorar. Başında kimsenin olmadığı bir çalıştırmaya (pipe, job ya da zamanlanmış görev) onay gerektiren hiçbir yetki verilmez.

Shell komutları

Her shell komutu çalışmadan önce izin ver, sor ya da reddet olarak sınıflandırılır. Birkaç parçadan oluşan bir komut, en riskli parçasına göre değerlendirilir. Yalnızca okuma yapan komutlar doğrudan çalışır, çoğu diğer komut onay ister, bazıları ise her zaman reddedilir:

• ağa çıkan programlar, örneğin curl, ssh ve nc;
• sistemin paket yöneticileri;
• git geçmişini yeniden yazan her şey;
• git push'un her yazılışı ve bir pull request'i merge etmenin ya da onaylamanın her yolu.

Kendi kurallarınızı home dizininizdeki ya da repo'nun .ivralo/ klasöründeki permissions.json'a eklersiniz. İkisinden birinde reddedilen bir komut her durumda reddedilir.

Bir değişikliği kontrol etmek

ivralo verify, # Commands altındaki komutları en ucuzundan başlayarak çalıştırır ve ilk hatada durur. Ajanlar da bir değişikliğe "bitti" demeden önce aynı kontrolü yapar. Hatalar, araçlarınızın zaten ürettiği JUnit ve SARIF gibi standart raporlardan okunur.

Daha büyük değişikliklerde bir changeset, turun düzenlemelerini ayrı bir ağaçta hazırlar, orada doğrular, sonra hepsini tek seferde uygular ya da atar. Working tree'niz hiçbir zaman yarım yazılmış kalmaz.

Plan modu

Birkaç adımlı işlerde önce plan isteyin: Shift+Tab'a basın, /plan yazın ya da ivralo plan "…" çalıştırın. ivralo hiçbir şeye dokunmadan planın taslağını çıkarır. Siz de planı çalıştırır, düzeltilmesini ister ya da atarsınız. Plan dalgalar hâlinde çalışır: her adım, ihtiyaç duyduğu adımlar bitince başlar. Bir adım başarısız olursa o dalgayı, dalgadan önce alınan checkpoint'e geri alabilirsiniz.

Git

Git'ten okumak serbest: status, diff'ler, log, blame ve bir sembolün geçmişi. Yazma işlemleri ise onay ister: stage'lemek, commit atmak, branch açmak ya da revert etmek aynı diyalogdan geçer.

ivralo'nun yaptığı tek push, kendi açtığı bir branch'ten taslak bir pull request açmak içindir. Her zaman önce sorar ve hiçbir zaman merge etmez.

Geri almak

ivralo değiştirdiği her dosyayı önce kendi geçmişine kopyalar. ivralo changes her turda neyin değiştiğini listeler, ivralo restore <dosya> bir dosyayı önceki hâline getirir. Oturum içinde Ctrl+D aynı listeyi açar.