Claude Code Rust: cargo, clippy ve testlerle pratik rehber

Claude Code Rust projelerinde cargo ekosistemiyle birlikte çalışır; borrow checker hatalarını yorumlamaktan test yazmaya kadar günlük işleri hızlandırır. Doğru CLAUDE.md ile projeye bağlam verdiğinizde ajan, workspace yapısını, clippy kurallarını ve test alışkanlıklarınızı bilir. Bu rehberde gerçek bir Rust iş akışı kurmayı ve ajanı denetlemeyi anlatıyorum.

Neden Claude Code Rust işine uygun?

Rust derleyicisi deterministik bir geri bildirim kaynağıdır: cargo check, cargo test ve clippy çıktıları nettir ve ajan bu çıktıları okuyup tekrar tekrar düzeltebilir. Claude Code, terminalde bu komutları kendisi çalıştırabildiği için bir hata döngüsünü sizin adınıza kapatır. Ayrıca Cargo.toml, Cargo.lock ve kaynak dosyalara erişerek crate sınırlarını, feature flag’leri ve modül hiyerarşisini anlayabilir. Trait implementasyonları, lifetime elision kuralları ve Result/Option dönüşümleri gibi Rust’a özgü konularda dil modelinin bilgisi, derleyici hatalarıyla birleşince pratik çözümler üretir. Workspace’lerde birden fazla crate arasındaki bağımlılıkları takip edebilir; örneğin crates/common içindeki bir tip değiştiğinde tüm kullanımları güncelleyebilir. Feature flag’leri devre dışıyken ortaya çıkan derleme hatalarını cargo check --features ile yakalayabilir.

Claude Code’un gücü, yalnızca kod yazmak değil, aynı zamanda cargo metadata gibi komutların çıktısını okuyarak workspace’in tamamını haritalayabilmesidir. Bu sayede crates/api içindeki bir fonksiyon imzası değiştiğinde, crates/db içinde bu fonksiyonu kullanan tüm çağrıları bulup düzeltebilir. Özellikle büyük workspace’lerde bu, manuel aramanın yerini alır. Ayrıca cargo add ile yeni bağımlılık eklerken mevcut Cargo.lock’u günceller ve uyumsuz sürümleri kontrol eder. Ajana “bu hatayı düzelt, ama önce cargo check ile doğrula” dediğinizde, derleyici mesajını okur, ilgili satırları değiştirir ve tekrar kontrol eder. Bu döngü, Rust’un katı tip sistemi sayesinde çoğu zaman başarılı olur.

Rust projesi için Claude Code kurulumu

Proje kökünde claude komutuyla ajanı başlatmadan önce CLAUDE.md dosyasını hazırlayın. Bu dosya, ajanın her oturumda okuyacağı proje talimatlarını içerir. Rust projesi için şunları ekleyin: build, test, lint ve format komutları; workspace üyeleri ve dizin düzeni; hata yönetimi tercihleri; unsafe kullanım kuralları; clippy ve rustfmt beklentileri. Aşağıdaki örnek, tipik bir cargo workspace için yeterlidir:

# Rust Projesi Kuralları

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

## Dizin Düzeni
- `crates/` altında workspace üyeleri; ortak tipler `crates/common` içinde.
- Binary'ler `src/main.rs`, kütüphaneler `src/lib.rs`.

## Rust'a Özel Kurallar
- `unsafe` bloğu eklemeden önce gerekçeyi yorumla ve mevcut kodu incele.
- Hata yönetiminde `anyhow` (uygulama) / `thiserror` (kütüphane) kullan.
- `cargo test` geçmeden ve clippy temiz olmadan işi bitmiş sayma.
- Değişikliklerin `rustfmt` ile biçimlendiğinden emin ol.

CLAUDE.md dosyasını kısa ve spesifik tutun; ajanın her seferinde tümünü okuması gerekir. Rust edition’ı (2021, 2024) ve minimum desteklenen Rust sürümünü (MSRV) de dosyaya ekleyin; ajan dependency güncellerken bu sınırı dikkate alır. Ayrıca proje kökündeki Cargo.toml’da workspace ayarlarının doğru olduğundan emin olun; ajan bu dosyayı referans alır. Özellikle rust-toolchain.toml kullanıyorsanız, ajan bu dosyayı okuyarak doğru toolchain’i seçer; nightly feature gerektiren kodlarda bu önemlidir. Ajan, Cargo.toml içindeki feature tanımlarını da okur; bu yüzden feature’ları açıklayıcı isimlendirin ve varsayılanları belirtin. Ajana cargo check --no-default-features gibi alternatif senaryoları denemesini söyleyerek tüm kombinasyonların derlendiğini doğrulatabilirsiniz.

Çalışma döngüsü ve örnek komutlar

Rust’ta ajanla çalışırken şu döngüyü izleyin: önce küçük bir görev tanımlayın, ajanın plan sunmasını isteyin, sonra tek bir değişiklik yaptırın, ardından cargo test ve clippy çalıştırın, en son diff’i inceleyin. Claude Code’un plan modunu (Claude Code plan modu: önce planla, sonra yaptır) kullanarak büyük refactor’ları adımlara bölmek işe yarar. Her adımdan sonra ajanın komutları kendisinin çalıştırmasını isteyin; böylece hata mesajlarını doğrudan okuyup düzeltir. Önce cargo check çalıştırmak testlerden daha hızlıdır; ajanı buna yönlendirin. Claude Code en iyi pratikler kontrol listesi (Claude Code en iyi pratikler: uygulamalı kontrol listesi) bu döngüyü sistematikleştirir.

Döngüyü şu adımlarla uygulayın: 1) Görevi tek bir cümlede, dosya veya modül belirterek tanımlayın; 2) Ajanın değişiklik planını açıklamasını isteyin ve onaylayın; 3) Ajanın yalnızca planlanan değişikliği yapmasına izin verin; 4) cargo check, cargo test ve clippy komutlarını ajanın çalıştırmasını sağlayın; 5) git diff ile değişikliği inceleyin, gereksiz import veya format farklarını temizletin. Büyük refactor’larda her adımı ayrı bir oturumda ele alın; böylece hata durumunda geri almak kolaylaşır.

Aşağıdaki örnek prompt’lar günlük Rust görevleri için başlangıç noktasıdır:

• cargo check çalıştır; çıkan borrow checker hatasını açıkla ve dosyayı düzelt.
• Bu fonksiyon için unit test ekle; cargo test <modül> ile doğrula, kırılanları düzelt.
• Cargo.toml’daki serde derive bağımlılığını güncelle ve Cargo.lock’u yeniden oluşturmadan önce diff göster.
• clippy’nin çıkardığı tüm uyarıları listele ve güvenli olanları sırayla düzelt.
• Workspace’teki crates/common içindeki Error enum’unu thiserror ile yeniden yaz; diğer crate’lerdeki kullanımları güncelle.

Bu prompt’ları kullanırken her zaman tam dosya yolunu ve beklenen davranışı belirtin. Örneğin “lib.rs’deki parse fonksiyonunu jenerik yap, &str ve &[u8] kabul etsin” gibi. Ajanın önerdiği çözümü önce --dry-run veya plan modunda görmek, istenmeyen değişiklikleri engeller.

Rust’ta ajanın güçlü olduğu ve dikkat edilmesi gereken yerler

Ajan özellikle şu görevlerde hızlıdır: derive eklemek (Serialize, Deserialize, Debug), trait implementasyonu yazmak, hata tiplerini thiserror ile dönüştürmek, test fonksiyonları üretmek, clippy uyarılarını gidermek ve küçük API değişikliklerini tüm workspace’e yaymak. Ayrıca From/TryFrom implementasyonları, iterator adaptörleri ve basit Display implementasyonları gibi tekrarlayan işlerde de güvenilirdir. Ancak Rust’a özgü bazı tuzaklara dikkat edin:

Ajanın en sık yaptığı hatalar şunlardır: borrow checker’ı susturmak için gereksiz clone() veya Rc<RefCell<T>> eklemek; lifetime’ı doğru analiz etmeden 'static kullanmak; feature flag’leri veya cfg attribute’larını göz ardı edip başka hedef platformda derlemeyi bozmak; format değişikliklerini mantık değişiklikleriyle karıştırmak; Cargo.lock’u veya bağımlılık sürümlerini gereksiz yere güncellemek. Ayrıca unsafe kod eklerken güvenlik gerekçesini atlayabilir; bu tür değişiklikleri mutlaka inceleyin. Tokio veya async-std gibi runtime’larla çalışırken ajan Send bound hatalarını çözmekte zorlanabilir; bu tür görevlerde daha küçük adımlar isteyin.

Ek olarak, ajan bazen önerilen clippy::needless_return gibi uyarıları düzeltirken kodun okunabilirliğini bozabilir. Örneğin, fonksiyon sonundaki return ifadesini kaldırmak iyi olsa da, ajan bazen erken return kullanımını gereksiz yere değiştirebilir. Benzer şekilde, match yerine if let önerisi bazen pattern karmaşıklığını artırabilir. Bu yüzden clippy düzeltmelerini topluca değil, tek tek inceleyin ve gereksiz olanları geri alın. Ayrıca ajan, özellikle unsafe bloklarında std::mem::transmute gibi tehlikeli fonksiyonlar önerebilir; bunları asla otomatik kabul etmeyin ve mutlaka güvenli alternatifleri araştırın.

Test ve doğrulama

Ajanın yaptığı her değişiklikten sonra şu komutları bağımsız olarak çalıştırın: cargo test --workspace --all-features, cargo clippy --workspace --all-targets -- -D warnings ve cargo fmt --all -- --check. Ajanın kendi çalıştırdığı testlerin çıktısını körü körüne kabul etmeyin; terminal geçmişini veya CI loglarını kontrol edin. git diff --check ile boşluk hatalarını yakalayın. Eğer proje bir workspace ise testleri crate bazında da çalıştırın; bazı testler yalnızca belirli bir crate’te anlamlıdır. Ajanın test eklediği durumlarda testlerin gerçekten anlamlı senaryoları kapsadığını, sadece satır sayısını artırmadığını doğrulayın. Özellikle unsafe kod veya FFI içeren değişikliklerde cargo miri test gibi ek araçlar kullanmayı düşünün; ajan bunları kendiliğinden önermeyebilir. Property-based testing (proptest) veya snapshot testleri gibi daha az kullanılan araçlarda ajanın kütüphane API’sını doğru kullanıp kullanmadığını kontrol edin.

Ayrıca cargo check --workspace --all-targets komutunu çalıştırarak tüm hedeflerin (testler, örnekler, benchmarklar) derlendiğinden emin olun. cargo doc --no-deps ile dokümantasyon hatalarını yakalayın; özellikle public API’lerde eksik dokümantasyon yorumları varsa clippy’nin missing_docs lint’i uyarı verebilir. Ajan eklediği yeni public item’lara doc comment eklemeyi unutabilir; bunu CLAUDE.md’ye “public API’lerde dokümantasyon zorunlu” kuralıyla hatırlatın. cargo publish --dry-run gibi komutları kullanarak crate yayınlama öncesi sorunları tespit edin; ajan bu komutları bilir ve çalıştırabilir. Bağımlılık değişikliklerinde cargo tree ile bağımlılık ağacını inceleyin; ajanın eklediği yeni crate’lerin lisans uyumluluğunu ve güvenlik açıklarını cargo audit (varsa) ile kontrol edin.

Birden fazla ajanı AgentVera ile çalıştırmak

AgentVera masaüstü uygulamasında Claude Code dahil birden fazla ajanı ayrı gerçek terminal panellerinde yan yana çalıştırabilirsiniz. Rust workspace’lerinde her ajanı kendi git worktree’sine atamak, aynı dosyalar üzerinde çakışmayı önler; böylece biri crates/api üzerinde çalışırken diğeri crates/db üzerinde bağımsız ilerleyebilir. Ajanın sırası bittiğinde ikinci bir modelin otomatik kod incelemesi, gereksiz clone veya clippy ihlallerini dosya:satır olarak işaretler. Her turun checkpoint’i sayesinde hatalı bir borrow checker düzeltmesini tek tıkla geri alabilirsiniz. Token bütçeleri ise ajanın uzun süre derleme döngüsünde takılıp kaynak tüketmesini engeller.

Özet

Claude Code, Rust projelerinde compiler geri bildirimini okuyup düzelttiği için değerlidir; ancak verim, doğru CLAUDE.md ve sıkı bir doğrulama döngüsüne bağlıdır. Ajanın önerdiği lifetime çözümlerini, unsafe bloklarını ve clippy düzeltmelerini her zaman gözden geçirin. Küçük adımlarla ilerleyin, testleri çalıştırın ve diff’i inceleyin. Ajanı bir yardımcı olarak konumlandırın; nihai kararı her zaman siz verin.