Codex ile Flask Projesi Geliştirme: Adım Adım Rehber

Codex, terminalde codex komutuyla başlattığınız bir kodlama ajanıdır. Flask projelerinde blueprint, application factory, Jinja ve SQLAlchemy gibi yapıları okuyup mevcut desenlere uygun değişiklikler yapabilir; projeye özel komutları AGENTS.md ile verdiğinizde isabet oranı belirgin biçimde artar. Bu rehber, Codex’i Flask iş akışınıza pratik olarak nasıl yerleştireceğinizi gösterir.

Codex neden Flask işine uygun

Flask projeleri genellikle küçük, okunaklı dosyalara ayrılır: app/__init__.py, models.py, blueprint dosyaları, şablonlar ve testler. Codex bu dosya haritasını hızlı çıkarır; create_app içindeki kayıt sırasını, blueprint’lerin url_prefix değerlerini ve Jinja şablonlarının extends/block yapısını anlamakta iyidir. Elinizdeki proje bu kalıplara uyuyorsa ajan, boilerplate üretmek yerine mevcut yapıyı genişletir. Yine de Flask’ın uygulama bağlamı, current_app, g ve SQLAlchemy oturum yönetimi gibi hassas noktaları vardır; bu yüzden ajanı serbest bırakmadan önce AGENTS.md ile sınırları çizmek gerekir. Codex hakkında temel bilgileri içeren sayfa, CLI davranışını anlamak için başlangıç olabilir.

Projeyi ajan için hazırlama

Codex proje kökünde AGENTS.md arar. Bu dosyaya Flask’a özel komutlar, klasör düzeni ve kod kalıpları yazarsanız her oturumda aynı bağlamı tekrar anlatmazsınız. Aşağıdaki örnek, küçük bir Flask uygulaması için yeterli bir başlangıçtır:

# AGENTS.md

## Komutlar
- Kurulum: `pip install -r requirements.txt`
- Geliştirme: `flask --app run.py run --debug`
- Test: `pytest -q`
- Lint: `ruff check app tests`

## Klasör yapısı
- `app/` uygulama paketi; `app/__init__.py` içinde `create_app` fabrikası
- `app/blueprints/` her özellik için bir blueprint
- `app/templates/` Jinja şablonları
- `app/models.py` SQLAlchemy modelleri
- `tests/` pytest testleri

## Flask kuralları
- Yeni özelliği mevcut blueprint'e ekle; yeni blueprint oluşturuyorsan `create_app` içinde kaydet.
- `current_app`, `g` gibi nesneleri yalnızca request/context içinde kullan; context dışında erişme.
- SQLAlchemy oturumunu `commit`'lemeden önce hataları yakala, `rollback` yap.
- Jinja şablonlarında tanımsız filtre veya global kullanma; gerekiyorsa `app.jinja_env` üzerinden kaydet.

Bu dosya ne kadar net olursa Codex’in ürettiği kod o kadar projeye oturur. Bağlamın nasıl yapılandırılacağına dair daha geniş bir çerçeve için bağlam mühendisliği rehberine göz atabilirsiniz.

Çalışma döngüsü

Codex’i tek seferde büyük bir refactor yapmak için değil, planla → küçük adım at → test et → diff’i incele döngüsüyle kullanın. Önce ajanın ne yapacağını sözlü olarak planlamasını isteyin; sonra değişikliği yaptırın; ardından pytest -q çalıştırıp kırılan testleri düzeltmesini söyleyin. Her adımda git diff veya Codex’in gösterdiği değişiklikleri inceleyin; özellikle context manager, import satırları ve blueprint kayıt sırası gibi Flask’a özgü ayrıntılara bakın.

Flask projelerinde sık kullanacağınız istem örnekleri:

• “app/auth/views.py içindeki login view’ına hata mesajlarını flash ile ekle, form boş gelirse 400 döndür. Önce planı göster, sonra kodu değiştir.”
• “User modeline last_login alanı ekle, migration oluşturma; mevcut testleri çalıştır ve kırılanları düzelt.”
• “create_app içindeki blueprint kayıtlarını gözden geçir; auth blueprint’inin url_prefix='/auth' ile bağlı olduğundan emin ol.”
• “tests/test_auth.py içine login başarılı ve başarısız senaryolar için iki pytest testi yaz.”
• “app/templates/base.html içindeki blok yapısını bozmadan navbara aktif sayfa vurgusu ekle.”

Bu döngüyü her görev için tekrarlayın; büyük değişiklikleri üç-beş küçük istem halinde bölün.

Codex’in iyi olduğu Flask işleri ve tuzaklar

Flask özelinde Codex; form doğrulama, basit CRUD route’ları, SQLAlchemy sorguları, Jinja şablon düzenlemeleri ve pytest testleri yazmada hızlıdır. Ancak aşağıdaki tabloda görüldüğü gibi her görev türünde belirli riskler vardır:

Codex bazen current_app’i modül düzeyinde kullanmak, db.session’i kapatmadan bırakmak veya blueprint’i kaydetmeden route yazmak gibi hatalar üretebilir. Bu nedenle diff’i okumadan birleştirmeyin.

Test ve doğrulama

Codex ile çalışırken doğrulamayı yalnızca ajanın söylediğine bırakmayın. Her değişiklikten sonra pytest -q çalıştırın; hata varsa ajanın düzeltmesini isteyin. Flask test istemcisini kullanan entegrasyon testleri, view’ların gerçek HTTP davranışını daha iyi yakalar:

def test_login_success(client):
    response = client.post('/auth/login', data={'email': 'a@b.com', 'password': 'secret'})
    assert response.status_code == 302
    assert '/dashboard' in response.headers['Location']

Codex’e “bu testi tests/test_auth.py içine ekle ve pytest -q ile çalıştır” dediğinizde hem testi yazar hem de hata ayıklama döngüsünü kendisi yürütür. Testlerin yanında flask routes komutuyla blueprint’lerin doğru kaydedildiğini, ruff check app tests ile lint hatalarını kontrol edin. Doğrulama adımını her küçük değişiklikte tekrarlamak, Flask’a özgü bağlam hatalarını erken yakalar.

Birden çok ajanla çalışma

Flask projesinde birden çok Codex oturumunu paralel yürütmek isterseniz AgentVera uygun bir ortamdır. AgentVera nasıl kullanılır sayfasındaki anlatım, çok ajanlı kurulumu gösterir. Her ajan kendi git worktree’sinde çalıştığı için app/blueprints gibi ortak klasörlerde dosya çakışması yaşanmaz; bir ajan durduğunda ikinci model kodu otomatik inceler ve bulgular dosya:satır olarak işaretlenir. Token bütçeleri sayesinde gece uzun süren işlerde maliyet sınırlanır ve ajan durduğunda konuşma korunur. Bu üç özellik, Flask gibi dosya sayısı çok olan projelerde hem güvenliği hem hızı artırır.

Özet

Flask projelerinde Codex’i verimli kullanmanın anahtarı, AGENTS.md ile net bir bağlam kurmak, işi küçük adımlara bölmek ve her adımı pytest ile doğrulamaktır. Ajan, blueprint, uygulama fabrikası, Jinja ve SQLAlchemy kalıplarını öğrenir; siz de context yönetimi, oturum kapatma ve diff incelemesi gibi hassas noktaları elde tutarsınız. Böylece Codex hızlı bir yardımcı olur, riskli bir otomatik pilot değil.