# Claude Code Python: projede verimli kullanım rehberi

Adres: https://agentvera.dev/blog/claude-code-ile-python/ · Yayın: 2026-11-01

Claude Code’u Python projelerinde verimli kullanın: sanal ortam, pyproject.toml, mypy, pytest, ruff ve CLAUDE.md ayarları pratik örneklerle.

**Kısaca:**

- Claude Code, Python projesinde terminalde claude komutuyla başlar; CLAUDE.md ile proje kuralları netleştirilir.
- Sanal ortam, pyproject.toml, pytest, mypy ve ruff entegrasyonu sayesinde ajan test ve statik analiz hatalarını düzeltebilir.
- Her değişiklikten sonra test, lint ve tip kontrolü çalıştırmak ve git diff’i incelemek güvenli kullanımın anahtarıdır.

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](/blog/claude-code-nasil-kullanilir/) 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](/blog/claude-code-plan-modu/). 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](/blog/claude-code-komutlari/) 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.

| Görev | Etkili istek örneği | Dikkat edilecek nokta |
| --- | --- | --- |
| Refactor | "`src/parser.py` içindeki `parse_log` fonksiyonunu `@dataclass` döndürecek şekilde yeniden yaz; tüm çağıranları güncelle." | Veri sınıfı alan sırası, varsayılan değerler, eşitlik davranışı. |
| Test ekleme | "`src/cache.py` için `pytest` testleri yaz; `tmp_path` fixture kullan, dosya temizliğini doğrula." | Fixture kapsamı, geçici dosya yolları, test izolasyonu. |
| Lint ve tip | "`mypy src` çıktısını oku, `src/api/` altındaki tüm `Optional` hatalarını düzelt; `Any` kullanma." | Aşırı daraltma, gereksiz `cast`, tip eşdeğerliği. |
| Bağımlılık | "`pyproject.toml` içinde `requests` bağımlılığını `httpx` ile değiştir; testleri güncelle." | Senkron/asenkron farkları, versiyon kilitleri, import değişiklikleri. |
| Docstring | "`src/` altındaki tüm public fonksiyonlara Google stilinde docstring ekle; parametre ve dönüş açıklamalarını yaz." | Gereksiz ayrıntı, yanlış tip açıklaması, mevcut docstring’lerin üzerine yazma. |

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](/blog/birden-fazla-claude-code-ajani/) 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.

## Sık sorulanlar

**Claude Code Python projesinde nasıl başlatılır?** Proje klasöründe terminal açıp claude yazmanız yeterlidir. Ajan, bulunduğu dizindeki kodu ve CLAUDE.md dosyasını okuyarak çalışmaya başlar. Sanal ortamı önceden aktifleştirmeniz önerilir.

**Claude Code sanal ortamı otomatik kullanır mı?** Hayır, sanal ortamı otomatik aktifleştirmez. CLAUDE.md içinde source .venv/bin/activate komutunu belirtirseniz ajan her turda doğru ortamı kullanır. Ayrıca pip install -e ".[dev]" gibi kurulum komutlarını da bu dosyaya ekleyebilirsiniz.

**Claude Code pytest ve mypy hatalarını düzeltebilir mi?** Evet, terminalde pytest -q ve mypy src komutlarını çalıştırıp çıktıyı okuyarak hataları düzeltebilir. Ancak tip daraltması veya Any kullanımı gibi konularda bazen yanlış karar verebilir; diff’i incelemek önemlidir.

**CLAUDE.md dosyasına Python için ne yazmalıyım?** Sanal ortam oluşturma, kurulum, test, lint, format ve tip kontrolü komutlarını; dizin yapısını; tip ipucu ve Any kullanımı gibi kuralları yazın. Böylece ajan her görevde aynı standartlara uyar.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/