IVRALO.md

Dosyanın yeri

IVRALO.md, çalışma alanının, yani ivralo'nun çalıştığı repo'nun kökünde bulunur. Adı sabittir.

• IVRALO.md yoksa kökteki AGENTS.md okunur; diğer kodlama ajanlarının da okuduğu dosya budur.
• Yalnızca bir dosya okunur. İkisi de varsa IVRALO.md geçerli olur, AGENTS.md yok sayılır; ikisi hiçbir zaman birleştirilmez.
• Boş ya da yalnızca boşluk içeren bir dosya hiç yokmuş gibi sayılır.
• Dosya yoksa ivralo init bir başlangıç dosyası yazmayı önerir ve ancak "evet" derseniz yazar.

Serbest metin

Dosyadaki her şey, bölümler de dahil, ana ajana ve bütün uzmanlara diğer talimatlarından sonra projenin kendi kuralları olarak verilir. Yeni gelen bir ekip arkadaşına anlatır gibi yazın: yeni kod nereye yazılır, nelere asla dokunulmaz, projede neye ne ad verilir.

Metnin bir sınırı vardır, çünkü her turda her ajanın bağlamında yer kaplar:

Hangisine önce ulaşılırsa dosya orada kesilir. Kesimin denk geldiği satır tamamen atılır ve sona eklenen bir not modele dosyanın devam ettiğini söyler; böylece model okumadığı kısımda bir şey olmadığı sonucuna varmaz. Dosyanın bağlamda ne kadar yer tuttuğunu ivralo doctor ve /context gösterir.

Bu dosya ivralo'nun yapabildiklerini yalnızca daraltabilir. İzinlere karar veren hiçbir kod onu okumaz. Tek istisnayı klasörü güvenilir sayarak siz seçersiniz: # Language servers altındaki bir satır, o sunucunun başlatılmasına onay demektir. "Force-push yapabilirsin" gibi bir cümle prompt'taki bir metindir, hiçbir şeyi değiştirmez.

Bölümler nasıl okunur

Bir bölüm, adını taşıyan bir başlıkla başlar ve bir sonraki başlıkta biter. Başlığın seviyesi ve büyük küçük harf önemli değildir (# Commands, ## commands). Her girdi bir madde işaretiyle yazılır. Değeri ters tırnak içine almak isteğe bağlıdır, çünkü insanlar iki türlü de yazar:

- test: uv run pytest -q
- test: `uv run pytest -q`

Başlangıç dosyasındaki - test: gibi değeri boş olan maddeler dikkate alınmaz. Bölümün biçimine uymayan satırlar yok sayılır.

Commands

Projenin kendi komutları, - name: command biçiminde. Dört ad, ivralo verify'ın ve ajanların bir değişikliği kontrol etmek için çalıştırdığı aşamalardır; en ucuzdan başlanır ve ilk hatada durulur:

# Commands

- format: `uv run ruff format --check .`
- lint: `uv run ruff check .`
- types: `uv run mypy`
- test: `uv run pytest -q`
- test-paths: `make test FILES="{paths}"`

Başka adlar da yazılabilir ve planlayıcının özetinde görünür, ama aşama olarak yalnızca bunlar çalışır. Bir komutu buraya yazmak ona izin vermek anlamına gelmez: her komut çalışmadan önce yine shell politikasından geçer ve onay isteyecek bir komut yine onay ister.

Kurulum adımı başında kimse yokken yalnızca elle yazılmış bir ivralo init --server --yes ile çalışır; terminalde bir kez sorulur. IVRALO_INSTALL_TIMEOUT saniye (varsayılan 1800) sonra durdurulur.

Reports

Bir aşamanın standart biçimde rapor yazdığı yer, - role: path biçiminde. Rol, aşamanın adıdır; yol çalışma alanına göredir ve glob olabilir. Aynı rol birkaç satırda geçebilir.

# Reports

- test: reports/junit.xml
- lint: reports/ruff.sarif

Okunan biçimler JUnit XML ve SARIF 2.1'dir. Bir aşama başarısız olduğunda ivralo hatayı çıktıdan tahmin etmeye çalışmaz, o aşamanın raporlarından okur. Komutunuza hiçbir bayrak eklemez: raporu komutunuzun kendisi yazmalıdır. Raporlar yalnızca okunur ve yalnızca çalışma alanının içindekiler.

Language servers

Projenin kullandığı dil sunucusu, - suffixes: command biçiminde. Uzantılar virgülle ayrılmış bir listedir; başında nokta olsa da olmasa da olur, büyük küçük harfe bakılmaz. Bir uzantıya, sunucuya bildirilecek dil kimliği suffix=id biçiminde eklenebilir; eklenmezse uzantının kendisi gönderilir.

# Language servers

- py,pyi=python: pyright-langserver --stdio
- ts,tsx=typescriptreact: typescript-language-server --stdio

Her dosya, adının sonuna uyan en uzun uzantının satırına bağlanır. Bir uzantıyı önceki bir satır almışsa o satırda kalır; hatalı bir girdi bildirilir ve atılır. Güvenilir bir klasörde bir satır, sunucunun başlatılmasına verilmiş onaydır; bu yüzden hiçbir şey sorulmaz. Shell politikasının red listesindeyse yine de reddedilir. Ayrıntılar Kod analizi sayfasında.

Dependencies

Projenin bağımlılıklarının tanımlandığı dosyalar, her satıra bir yol ya da glob (** klasörleri aşar). - name: path biçimindeki bir satır da aynı şekilde okunur.

# Dependencies

- uv.lock
- requirements/*.txt

Bir changeset'in düzenlemeleri bu dosyalardan birine dokunursa, doğrulama sonucunda yeni bağımlılıklar için kurulmamış bir ortamda çalışıldığı belirtilir. Ayrıntılar Changeset'ler sayfasında.

Evidence

git'in yok saydığı ama dosya arama araçlarının yine de girebileceği, incident kanıtının bulunabileceği klasörler: log'lar, yerel bir yapılandırma, build çıktısı. Her satıra çalışma alanına göre bir yol ya da glob.

# Evidence

- logs/
- var/log/app/*.log

.env, .ivralo/ ve .git/ bu klasörlerin içinde de kapalı kalır. Çalışma alanının dışındaki bir kök sorun olarak bildirilir ve kullanılmaz. Ayrıntılar Kanıt paketi sayfasında.

Documents

Bilgi dizinine nelerin gireceği. Her satıra çalışma alanına göre bir dosya, bir klasör (guide/ altındaki her şeyi kapsar) ya da bir glob.

# Documents

- guide/
- docs/**/*.md
- README.md

Bölüm varsa dizine yalnızca burada yazanlar girer. Bölüm yoksa ya da içi boşsa, okunabilen her dosya dizine girer. Mutlak bir yol ya da .. ile çalışma alanının dışına çıkan bir yol hiçbir şeyi kapsamaz ve bildirilir. Ayrıntılar Bilgi dizini sayfasında.

Güven neyi değiştirir

Klonladığınız bir repo, çalıştırılacak programları tanımlayan bir IVRALO.md ile gelebilir. Klasörü güvenilir saymadığınız sürece bu tanımlar hiçbir şey yapmaz:

Son ikisi hiçbir şeye izin vermez; yalnızca yolları karşılaştırır ya da okunacakları daraltır. Güven kaydı klasörde değil, ana dizininizdeki trusted.json'da tutulur. Bir klasörü ivralo trust ile, oturumda /trust yes ile ya da oturumun ilk açılışta sorduğu soruyu cevaplayarak güvenilir sayabilirsiniz. Ayrıntılar Ayar dosyaları sayfasında.