Claude Code Python: projede verimli kullanım rehberi

Claude Code, Python projesinde terminalde proje klasörüne gidip claude yazarak başlatılır. Kod tabanını okur, komut çalıştırır, dosyaları düzenler ve test sonuçlarına göre iterasyon yapar. Python’a özgü araçlarla (venv, pyproject.toml, mypy, pytest, ruff) uyumlu çalışması için projeyi doğru hazırlamak ve CLAUDE.md dosyasını kullanmak yeterlidir.

Claude Code Python projelerinde neden iyi çalışır

Python’un açık ortam modeli, sanal ortamlar, pyproject.toml, tip ipuçları ve hızlı test döngüsü Claude Code’un işini kolaylaştırır. Ajan, terminalde pytest -q, mypy src, ruff check . gibi komutları çalıştırıp çıktıyı okuyabilir; böylece statik analiz ve test hatalarını kendi başına düzeltebilir. Refactoring, test ekleme, bağımlılık güncelleme gibi işlerde tip bilgisi sayesinde daha az tahmin yapar. Özellikle tip ipuçları tutarlıysa ajan, fonksiyon imzalarını ve veri akışını daha doğru analiz eder. Ayrıca Python’un yaygın test kültürü sayesinde ajan, eklediği her değişikliği hızlıca doğrulayabilir. Yine de her değişiklikten sonra insan gözüyle doğrulama gerekir.

Projeyi ajan için hazırlamak

Claude Code proje kökündeki CLAUDE.md dosyasını otomatik okur. Python projesi için aşağıdakileri ekleyin: sanal ortam oluşturma ve aktifleştirme komutları, kurulum, test, lint, format ve tip kontrolü komutları, dizin yapısı ve Python’a özgü kurallar. Sanal ortamı her zaman kullanmak kritiktir; ajan her yeni terminal oturumunda ortamı aktifleştirmeyi unutabilir. CLAUDE.md içinde açıkça source .venv/bin/activate yazmak bu riski ortadan kaldırır. Ayrıca bağımlılıkların pyproject.toml içinde tanımlanması, ajanın pip install -e ".[dev]" ile tüm geliştirme araçlarını aynı anda kurmasını sağlar. Gerçek bir örnek:

# CLAUDE.md

## Komutlar
- Sanal ortam: `python -m venv .venv && source .venv/bin/activate`
- Kurulum: `pip install -e ".[dev]"`
- Test: `pytest -q`
- Lint: `ruff check .`
- Format: `ruff format --check .`
- Tip kontrolü: `mypy src`

## Dizin yapısı
- `src/` altında paket; testler `tests/` altında.
- Yeni kod mutlaka `src/` içinde; test dosyaları `test_*.py`.

## Python kuralları
- Tüm yeni fonksiyonlara tip ipucu ekleyin; dönüş tipi `None` ise `-> None` yazın.
- `Any` kullanmayın; `Protocol` veya generic tercih edin.
- Bağımlılıkları `pyproject.toml` içinde `[project.optional-dependencies]` altında `dev` grubuna ekleyin.
- Değişiklik yaptıktan sonra `pytest -q`, `ruff check .`, `mypy src` çalıştırın; hepsi temiz olmadan iş bitmez.

Bu dosya, ajanın her turda hangi komutları çalıştıracağını ve hangi standartlara uyacağını netleştirir; böylece pip install -e ".[dev]" gibi komutlar tekrar tekrar sorulmaz. Daha genel başlangıç için Claude Code nasıl kullanılır? Başlangıç rehberi sayfasına bakın.

Çalışma döngüsü: plan, küçük adımlar, testleri çalıştır, diff’i gözden geçir

Claude Code’da önce plan modunu kullanın; ajan kodu değiştirmeden ne yapacağını anlatsın, sonra onaylayın. Plan modu hakkında ayrıntı: Claude Code plan modu: önce planla, sonra yaptır. Ardından şu döngüyü izleyin: 1) küçük ve net bir görev verin; 2) ajan değişikliği yapsın; 3) test, lint ve tip kontrolü komutlarını çalıştırmasını isteyin; 4) git diff ile değişiklikleri inceleyin; 5) hata varsa aynı turda düzelttirin. Görevleri küçük tutmak özellikle önemlidir; tek seferde büyük refactor istemek yerine dosya bazında ilerleyin. Her adımdan sonra testlerin yeşil kaldığını doğrulayın. Ajan bazen kendi ürettiği kodu test etmeden geçebilir; bu yüzden komutları açıkça isteyin. Aşağıdaki istekler bu döngüye uygun örneklerdir:

• “src/models.py içindeki User sınıfına created_at alanı ekle; datetime tipini kullan, __init__’i güncelle ve tests/test_models.py içinde iki test yaz.”
• “tests/test_api.py içindeki ilk üç testi @pytest.mark.parametrize ile birleştir; mevcut kapsamı koru, fixture’ları değiştirme.”
• “pyproject.toml içinde [tool.ruff] altında select = ["E", "F", "I", "UP"] yap, sonra ruff check . çalıştır ve tüm hataları düzelt.”
• “src/service.py içindeki fetch_data fonksiyonunu asenkrona çevir; httpx.AsyncClient kullan, çağıranları güncelle, mypy src temiz kalsın.”
• “Değişikliklerin özetini çıkar ve git diff üzerinde Python’a özgü riskleri işaretle (import döngüsü, varsayılan argüman, yan etki).”

Claude Code komutları hakkında genel bilgi için Claude Code komutları: bayraklar, slash ve kısayollar sayfasına bakabilirsiniz.

Claude Code’un iyi yaptığı tipik Python işleri ve dikkat edilmesi gerekenler

Ajan; tip ipuçları ekleme, refactor, test yazma, docstring, bağımlılık güncelleme, ruff/mypy hatalarını giderme konularında iyidir. Ancak Python’a özgü bazı tuzaklara dikkat edin: sanal ortam aktif değilken komut çalıştırma, Any kullanarak tip güvenliğini bozma, mutable default argümanlar, dairesel import, global state, pytest fixture kapsamı. Ajan bu hataları bazen gözden kaçırabilir; diff’i inceleyin.

Asenkron kod ve eşzamanlılık söz konusu olduğunda ajan bazen await eklemeyi unutabilir veya yanlış yerde asyncio.run kullanabilir. Global state içeren modüllerde değişiklik yaparken testlerin sıralı olarak çalıştığını unutmayın; pytest varsayılan olarak her testi aynı süreçte çalıştırır. Bu yüzden global değişkenleri sıfırlamak için fixture kullanmasını isteyin. Dairesel import riski taşıyan modüllerde TYPE_CHECKING kullanmasını önerebilirsiniz.

Python’da test ve doğrulama

Ajanın her değişiklikten sonra pytest -q, mypy src, ruff check . çalıştırmasını isteyin. pytest -k ile yalnızca ilgili testleri koşturun; pytest --cov=src --cov-report=term-missing ile kapsamı görün. Hata çıktısını ajana yapıştırmak yerine doğrudan komutu çalıştırmasını ve çıktıya göre düzeltme yapmasını söyleyin. Sanal ortamın aktif olduğundan emin olun; ajan yeni terminal açtığında .venv/bin/activate çalıştırmayabilir. CLAUDE.md içinde bu komutları tanımlarsanız ajan her turda doğru ortamı kullanır.

Mypy için --strict seçeneği varsayılan olarak güvenli sonuç verir; ancak mevcut proje tam olarak tiplenmemişse önce --check-untyped-defs gibi adımlarla başlayın. Ajanın # type: ignore eklemesine izin vermeyin; bunun yerine hatayı düzgün çözmesini isteyin. Ruff için pyproject.toml içinde [tool.ruff.lint] altında select ve ignore listelerini netleştirin. Özellikle I (import sıralaması) ve UP (modern Python) kuralları ajanın otomatik düzeltmesi için uygundur; ruff check --fix . komutunu güvenle kullanabilir.

Birden fazla ajanı tek Python projesinde çalıştırmak: AgentVera

Birden fazla Claude Code ajanını aynı Python deposunda çalıştırırken AgentVera işe yarar. Her ajan kendi git worktree’sinde çalışır; böylece aynı dosyayı ezmezler ve paralel refactor güvenli olur. Bir ajanın turu bitince ikinci model otomatik kod incelemesi yapar; bulgular satır satır işaretlenir, tip uyumsuzluğu veya import hatası hızla yakalanır. Ajan başına token bütçesi belirlenebilir; %80’de uyarı verir, limitte durur ama konuşmayı korur. Bekleyen onaylar da tek sırada toplanır. Daha fazlası için Birden fazla Claude Code ajanını paralel çalıştırma sayfasına bakın.

Kısa kapanış

Claude Code, Python projesinde sanal ortam, pyproject.toml, tip ipuçları ve test araçlarıyla birlikte kullanıldığında gerçek bir kod ortağına dönüşür. Anahtar, CLAUDE.md ile beklentileri netleştirmek, her adımda test ve statik analiz çalıştırmak ve diff’i gözden geçirmektir. Plan modunu düzenli kullanmak büyük hataları önler; küçük adımlar ise geri almayı kolaylaştırır. Birden çok ajan gerektiğinde AgentVera ile paralel çalışma düzenini kurmak mümkündür.