opencode ile Rust projelerinde verimli çalışma rehberi

opencode’i bir Rust projesinde kullanmak için proje kökünde opencode komutunu çalıştırmanız yeterlidir; ajan, opencode olarak AGENTS.md dosyasındaki talimatları okur ve cargo, clippy, rustfmt gibi araçlarla uyumlu çalışır. Rust’ın katı derleyici kontrolleri ve uzun derleme-test döngüleri, ajanın küçük adımlarla kod yazmasını ve her adımın sizin tarafınızdan doğrulanmasını gerektirir. Bu rehber, opencode’u Rust işlerinde etkili kullanmak için somut bir çalışma düzeni sunar.

opencode Rust işlerinde neden iyi çalışır?

Rust’ın güçlü tip sistemi ve derleyici hataları, ajana net ve ölçülebilir bir hedef verir. cargo test, cargo clippy ve cargo fmt --check gibi komutlar, başarının nesnel olarak doğrulanmasını sağlar; ajan bu komutların çıktısına göre iterasyon yapabilir. Clippy lint’leri ve rustfmt stili, kod tabanında tutarlılığı korur. Borrow checker hataları ise ajanı büyük ve riskli değişiklikler yerine küçük, odaklı düzenlemelere iter; bu da review sürecini kolaylaştırır. Ayrıca AGENTS.md ile crate yapısı, modül sınırları ve yasaklar (unsafe, unwrap gibi) netleştirilebilir. Daha genel kurulum ve kullanım için opencode nasıl kullanılır? Adım adım rehber sayfasına bakabilirsiniz.

Projeyi hazırlama: AGENTS.md

opencode, proje kökündeki AGENTS.md dosyasını okur; bu yüzden Rust’a özel beklentileri oraya yazmak en etkili yöntemdir. Dosya kısa ve emredici olmalı; komutlar, klasör sözleşmeleri ve değişmez kurallar içermelidir.

Aşağıdaki örnek, bir workspace’i olan tipik bir Rust projesi için yeterlidir:

# Rust Projesi İçin Ajan Talimatları

## Komutlar
- Derleme: `cargo build --workspace`
- Test: `cargo test --workspace --all-features`
- Lint: `cargo clippy --workspace --all-targets --all-features -- -D warnings`
- Format: `cargo fmt --check`

## Klasörler
- `src/`: ana kütüphane veya binary kodu
- `tests/`: entegrasyon testleri
- `benches/`: benchmarklar
- `crates/`: workspace üyeleri

## Rust'a Özel Kurallar
- Kütüphane kodunda `unwrap` ve `expect` kullanma; `Result` ve `?` operatörü ile ilerle, panik durumlarını belgele.
- `unsafe` bloğu eklemeden önce onay iste; gerekçeyi ve güvenlik argümanını yaz.
- Clippy uyarılarını açıklama olmadan bastırma (`allow` attribute kullanma).
- Bağımlılık eklerken mevcut MSRV'yi ve lisans uyumluluğunu kontrol et; `Cargo.lock` dosyasını elle düzenleme.
- Her değişiklikten sonra `cargo fmt --all` çalıştır.
- Değişiklikleri küçük ve tek amaca odaklı tut; büyük refactor yapma.

Bu kurallar, ajanın Rust’a özgü yaygın hatalara düşmesini önler.

Çalışma döngüsü: planla, küçük adım at, testi çalıştır, diff’i incele

Rust’ta başarılı bir opencode deneyimi, ajanın serbest bırakılmasıyla değil, sıkı bir döngüyle gelir. Her görevde önce plan isteyin: “önce mevcut kodu ve etkileri açıkla, değişikliği adımlara böl, onay bekle.” Sonra tek bir adımı uygulatın. Ajan işini bitirdiğinde siz şu komutları çalıştırın:

• cargo test --workspace --all-features
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo fmt --check

Ardından git diff çıktısını inceleyin; özellikle clone(), unsafe, gereksiz lifetime parametreleri ve Cargo.toml değişikliklerine bakın. Tüm testler geçerse bir sonraki adıma geçin. Bu döngü, borrow checker hatalarının birikmesini önler.

Tipik Rust görevleri için kullanabileceğiniz örnek promptlar:

• “src/lib.rs içindeki parse_config fonksiyonunu &str yerine impl AsRef<str> kabul edecek şekilde genişlet; mevcut testleri bozma, yeni birim testlerini ekle.”
• “Workspace’teki parser ve compiler crate’leri arasındaki döngüsel bağımlılığı kaldır; tasarım önerini önce açıkla, sonra uygula.”
• “Bu match bloğunu clippy match_like_matches_macro uyarısı vermeyecek şekilde yeniden yaz ve cargo test ile doğrula.”
• “Hata tipini thiserror ile derive et, std::error::Error implementasyonunu ekle, main.rs içinde ? kullanacak şekilde düzenle.”
• “Aşağıdaki fonksiyonu Iterator trait’ini implement eden bir yapıya dönüştür; borrow checker hatalarını açıklayarak çöz.”

Tipik görevler ve dikkat edilecek yerler

opencode, Rust tarafında özellikle şablon ve mekanik işlerde hızlıdır: thiserror ile hata tipleri türetmek, From/TryFrom implementasyonları, dokümantasyon örnekleri, clippy düzeltmeleri ve saf fonksiyonlar için birim testleri yazmak. Ajan aynı zamanda API tasarımında öneri sunar ve mevcut kodun borrow checker hatasını çözmek için alternatifler üretebilir.

Aşağıdaki tablo, tipik görevler için iyi prompt örneklerini gösterir:

Ancak ajanın ürettiği kodda dikkat edilmesi gereken tuzaklar vardır:

• Gereksiz clone(): Borrow checker hatasını hızlıca çözmek için ajan clone() ekleyebilir; bu performansı düşürür. Diff’i incelerken her clone() çağrısının nedenini sorgulayın.
• unsafe kullanımı: Ajan, unsafe bloğu önerebilir; projeniz unsafe içermiyorsa, bunu reddedin veya gerekçesini isteyin.
• Büyük refactor: Ajan bazen tüm dosyayı yeniden yazar; bu, mevcut testlerin bozulmasına yol açar. Küçük adımlar isteyin.
• Cargo.toml sürprizleri: Ajan gereksiz bağımlılık ekleyebilir veya sürüm değiştirebilir. Cargo.toml diff’ini dikkatle okuyun.
• Dokümantasyon testleri: Rust dokümantasyon örnekleri test olarak çalışır; ajan bu örnekleri hatalı yazabilir, cargo test ile yakalanır.

Test ve doğrulama

Rust projesinde opencode ile çalışırken test ve doğrulama sizin sorumluluğunuzdadır. Ajan test komutlarını kendiliğinden çalıştırmaz; siz çalıştırırsınız. Her değişiklikten sonra şu üç komutu sırayla çalıştırın:

1. cargo test --workspace --all-features – tüm testleri koşar, dokümantasyon testleri dahil.
2. cargo clippy --workspace --all-targets --all-features -- -D warnings – lint’leri hata olarak ele alır.
3. cargo fmt --check – biçimlendirmeyi doğrular; hata varsa cargo fmt --all ile düzeltin.

Ayrıca, entegrasyon testleri için tests/ klasöründeki senaryoları ajanın değişikliklerinden sonra mutlaka çalıştırın. Eğer projenizde property-based testing (ör. proptest) veya fuzzing varsa, bu testleri de koşturun. Ajan, testleri yazabilir ama onları yorumlayamaz; başarısızlıkları siz değerlendirmelisiniz.

Birden fazla ajan: AgentVera

Rust projesinde birden fazla opencode örneğini veya farklı CLI ajanlarını paralel çalıştırmak isterseniz, AgentVera masaüstü uygulaması her ajanı kendi gerçek terminal panelinde çalıştırır. Her ajan ayrı bir git worktree üzerinde çalışabildiği için dosya çakışmaları yaşanmaz; böylece borrow checker veya cargo test gibi uzun süren işlemler paralel ilerler. Ajanın turu bittiğinde ikinci bir model otomatik kod incelemesi yapar ve bulguları dosya:satır biçiminde gösterir; checkpoints ile her turun anlık görüntüsü alınır ve tek tıkla geri alınabilir. Bu özellikler, Rust’taki riskli refactor işlerinde özellikle değerlidir. Daha fazla bilgi için Paralel kodlama ajanları için en iyi araçlar sayfasına bakabilirsiniz.

Sonuç

opencode, Rust projesinde doğru AGENTS.md kuralları ve disiplinli bir döngüyle kullanıldığında güçlü bir yardımcıdır. Ancak Rust’ın katı derleyicisi, ajanın her önerisini körü körüne kabul etmemenizi gerektirir; cargo test, cargo clippy ve git diff üçlüsü sizin kalite kapınızdır. Küçük adımlar atın, her adımı doğrulayın ve ajanın ürettiği kodu en az kendi yazdığınız kod kadar eleştirel inceleyin.