GitHub Copilot CLI ve Flask: Pratik Kullanım Rehberi

GitHub Copilot CLI (GitHub Copilot CLI) Flask projenizde terminalden copilot komutuyla çalışır; proje talimatlarını okur, dosyaları düzenler ve test komutlarını çalıştırabilir. Blueprint, uygulama fabrikası, Jinja şablonları ve SQLAlchemy modelleri gibi Flask bileşenlerinde küçük adımlarla ilerlemek için iyi bir iş ortağıdır. Bu rehber, kurulumdan doğrulamaya kadar Flask’a özel bir çalışma düzeni sunar.

Neden GitHub Copilot CLI Flask işine yarar

Flask projeleri genellikle çok dosyalı ve bağlam bağımlıdır. Bir rota eklemek blueprint dosyasını, import listesini, şablonu ve testi aynı anda değiştirmeyi gerektirir. GitHub Copilot CLI, depo genelinde arama yapabildiği ve birden fazla dosyayı tek seferde düzenleyebildiği için bu tür işleri tek komutla toparlar. Ayrıca pytest ve ruff gibi komutları çalıştırıp çıktıyı yorumlayarak düzeltme önerebilir. Uygulama fabrikası içindeki create_app ve blueprint kayıtlarını değiştirmeden yeni bir modül eklemek istediğinizde ajanın proje talimatlarına uyması da tutarlılığı artırır. Özellikle birden fazla blueprint ve model dosyası olan orta ölçekli projelerde, ajanın bağlamı sürekli elinde tutması hız kazandırır.

Flask’a özgü kalıplar tekrarlıdır: url_for ile rota üretmek, form verisini doğrulamak, db.session yönetimi ve test istemcisi kurulumu gibi işler her projede benzerdir. Ajan, bu kalıpları proje talimatlarından öğrenirse her seferinde sıfırdan keşfetmez. Ayrıca bir değişikliği yaparken hem ilgili şablonu hem testi hem de gerekirse rotayı birlikte güncellemesi, insan geliştiricinin unutabileceği noktaları azaltır. Jinja şablonundaki bir değişken adı değiştiğinde ajan, ilgili render_template çağrısını da bulup güncelleyebilir. Bu çoklu dosya farkındalığı, Flask geliştirmede ciddi zaman kazandırır.

Projeyi ajan için hazırlama

Flask projesinde ajanın doğru kararlar verebilmesi için kök dizine .github/copilot-instructions.md veya AGENTS.md koyun. Bu dosyada komutlar, klasör düzeni ve Flask’a özel kurallar yer almalı. Ajan her oturumda bu talimatları okur; böylece her seferinde proje yapısını yeniden keşfetmez. Talimat yazımıyla ilgili ipuçları için CLAUDE.md nasıl yazılır? AGENTS.md ve GEMINI.md rehberi sayfasına göz atabilirsiniz.

Dosya içeriği ne kadar net olursa ajan o kadar az hata yapar. Örneğin uygulama fabrikasının hangi dosyada olduğunu, test yapılandırmasının nasıl devreye girdiğini ve hangi Python sürümünün hedeflendiğini belirtin. Ayrıca migration aracı (Alembic/Flask-Migrate) kullanılıyorsa komutunu ekleyin. Lint ve format komutları da yazım tarzını korumak için gereklidir. Aşağıdaki örnek, orta ölçekli bir Flask projesi için başlangıç noktasıdır:

# Flask projesi için Copilot talimatları

## Komutlar
- Bağımlılık kurulumu: `pip install -e .[dev]`
- Test: `pytest -q`
- Lint: `ruff check .`
- Format: `ruff format .`
- Migration: `flask db upgrade` (Alembic üzerinden)

## Klasör düzeni
- `app/` uygulama paketi; `app/__init__.py` uygulama fabrikası içerir.
- Blueprint'ler `app/blueprints/<ad>/` altında, rota dosyası `routes.py`.
- Jinja şablonları `app/templates/<blueprint>/<sayfa>.html`.
- SQLAlchemy modelleri `app/models.py` veya `app/models/` içinde.
- Testler `tests/` altında, blueprint başına `tests/test_<ad>.py`.

## Flask'a özel kurallar
- `app` ve `request` gibi bağlamlara ihtiyaç duyan kodu yalnızca istek bağlamında veya uygulama bağlamında çalıştır.
- `db.session` işlemlerini try/except içinde yap, hata durumunda `db.session.rollback()` çağır.
- URL'ler için `url_for` kullan; sabit path yazma.
- Blueprint eklerken `url_prefix` ve şablon klasörünü açıkça belirt.
- Form doğrulama için Flask-WTF kullan; CSRF token'ı unutma.
- Büyük sorgulardan kaçın; `paginate` veya `limit` kullan.

Bu talimat dosyası, ajanın Flask’a özgü hatalardan kaçınmasını sağlar. Örneğin app bağlamı dışında current_app kullanmaması gerektiğini bilirse daha az hata üretir. Aynı şekilde url_for ile blueprint adını kullanmayı öğrenmesi, sabit URL’lerden kaynaklanan kırılmaları önler. Ayrıca ruff komutlarını bilmesi, ajanın yazdığı kodun projeyle aynı stile uymasını kolaylaştırır.

Ek olarak ortam değişkenlerini ve gizli anahtarları nasıl yöneteceğinizi belirtin. Örneğin FLASK_APP ve FLASK_ENV değişkenlerini ajana söylemek yerine talimatlara yazın; böylece ajan test ve geliştirme komutlarını doğru bağlamda çalıştırır. Eğer bir .env dosyası kullanıyorsanız python-dotenv yükleme sırasını ekleyin.

Çalışma döngüsü: planla, küçük adımlarla ilerle, test et, diff’i gözden geçir

Ajanla çalışırken en verimli döngü şudur: önce yapılacak değişikliği bir cümleyle tarif edin, ardından ajanın küçük bir yama üretmesini isteyin, pytest ile doğrulayın ve git diff çıktısını inceleyin. Büyük bir özelliği tek seferde istemek yerine blueprint’i, modeli ve şablonu ayrı adımlara bölmek hataları azaltır. Her adımdan sonra pytest -q çalıştırıp sonucu ajana iletin; böylece bir sonraki adımda aynı hatayı tekrarlamaz.

Bu döngüyü somutlaştırmak için örnek bir akış: kullanıcı kaydı eklemek istiyorsunuz. İlk adımda ajana “User modeline email ve password_hash alanlarını ekle; migration oluştur” dersiniz. Ajan çıktıyı ürettikten sonra git diff ile modeli inceleyip pytest çalıştırırsınız. Başarılıysa ikinci adımda “auth blueprint oluştur ve /register rotasını ekle, formu doğrula” dersiniz. Yine test edip şablondaki eksikleri kontrol edersiniz. Üçüncü adımda “başarılı kayıt sonrası kullanıcıyı veritabanına ekle ve giriş sayfasına yönlendir” diyerek session yönetimini devreye alırsınız. Her adım küçük olduğu için hata ayıklama kolaylaşır ve ajanın bağlamı korunur.

Aşağıdaki prompt’lar Flask projelerinde sık kullanılan görevler için başlangıç noktasıdır:

• ‘Yeni bir auth blueprint oluştur; giriş, kayıt ve çıkış rotalarını ekle; şifreleri werkzeug.security.generate_password_hash ile sakla.’
• ‘User modeline email alanını ekle; migration dosyasını oluştur ve mevcut testleri güncelle.’
• ‘dashboard sayfasında giriş yapan kullanıcının son 10 siparişini gösteren sorguyu yaz ve şablona aktar.’
• ‘auth blueprint için başarılı ve başarısız giriş senaryolarını kapsayan pytest testleri ekle.’
• ‘Kayıt formundaki hata mesajlarını Türkçe göster; CSRF token’ı koru ve input değerlerini geri doldur.’

Bu prompt’lar tek başına yeterli değildir; ajanın ürettiği diff’i incelemeden merge etmeyin. Özellikle create_app içindeki blueprint kayıt sırası, db nesnesinin başlatılması ve login_manager gibi uzantıların ayarlanması kritik kontrol noktalarıdır. Diff’i incelemek için git diff --cached veya git diff HEAD kullanabilirsiniz; ajanın değiştirdiği dosyaları tek tek gözden geçirin.

Flask’a özgü güçlü yönler ve dikkat edilmesi gerekenler

Ajan; blueprint kaydı, url_for kullanımı, Jinja döngüleri ve SQLAlchemy sorguları gibi tekrarlayan işlerde hızlıdır. Buna karşılık Flask’ın bağlam yönetimi, uygulama fabrikası sırasındaki import döngüleri ve test istemcisi kurulumu gibi konularda ürettiği kodu dikkatle incelemek gerekir. Aşağıdaki tablo sık karşılaşılan durumları özetler:

Özellikle uygulama fabrikası ve circular import hatalarında ajan bazen modülü yanlış yere import edebilir. app/__init__.py içindeki uzantı başlatma sırasını ve blueprint importlarını her zaman diff’te kontrol edin. Ayrıca db.session kullanılan yerlerde işlem sonunda commit veya rollback çağrıldığından emin olun; ajan bu adımı atlayabilir.

Bir başka tipik tuzak, form doğrulamada CSRF korumasını test ortamında devre dışı bırakmayı unutmaktır. Ajan testleri yazarken test istemcisine WTF_CSRF_ENABLED = False ayarını eklemezse post istekleri başarısız olabilir. Benzer şekilde Flask-Login kullanıyorsanız, giriş yapan kullanıcıyı fixture içinde oturuma eklemek için login_user çağrısı yapması gerekir; ajan bunu bazen gözden kaçırır. Bu nedenle testlerde oturum açma yardımcı fonksiyonları tanımlayıp talimat dosyasına ekleyin.

Jinja şablonlarında ajan genellikle doğru döngü ve koşul yapılarını kurar, ancak url_for kullanırken endpoint adını yanlış yazabilir. Blueprint url_prefix ile kayıtlıysa, örneğin url_for('auth.login') gibi blueprint adını içeren endpoint kullanılmalıdır. Ajan sadece url_for('login') yazarsa rota bulunamayabilir. Bu tür hataları diff’te hızlıca fark edebilirsiniz.

Flask projesinde test ve doğrulama

GitHub Copilot CLI ile çalışırken testleri birincil doğrulama aracı olarak kullanın. pytest fixture’larında app ve client oluştururken uygulama fabrikasını çağırın; veritabanı gerektiren testlerde her testten önce tabloları oluşturup sonra bırakın. Ajanın yazdığı testleri çalıştırmadan önce pytest -q komutunun çıktısını okuyun; hata varsa ilgili çıktıyı ajana geri vererek düzeltme isteyin. Test kapsamını artırmak için coverage run -m pytest ve coverage report komutlarını da kullanabilirsiniz. Döngüyü kurduktan sonra GitHub Copilot CLI nasıl kullanılır? Adım adım rehber adresindeki adım adım anlatım işinize yarayabilir.

Bir test fixture örneği şu şekilde olabilir:

import pytest
from app import create_app, db
from app.models import User

@pytest.fixture
def app():
    app = create_app({
        'TESTING': True,
        'SQLALCHEMY_DATABASE_URI': 'sqlite:///:memory:',
        'WTF_CSRF_ENABLED': False,
    })
    with app.app_context():
        db.create_all()
        yield app
        db.session.remove()
        db.drop_all()

@pytest.fixture
def client(app):
    return app.test_client()

Bu fixture, her test için bağımsız bir SQLite veritabanı oluşturur ve test sonunda temizler. Ajan bu kalıbı öğrenirse sonraki testlerde veritabanı izolasyonunu korur. Ayrıca client fixture’ı sayesinde rotalara kolayca istek atılır. Test komutlarını ajanın kendisinin çalıştırmasını isteyebilirsiniz; hata çıktısını gördüğünde düzeltme önerileri üretir. Yine de her düzeltmeden sonra testleri siz de çalıştırıp diff’i inceleyin.

Doğrulama sürecini güçlendirmek için ruff check ve ruff format komutlarını da ajanın çalıştırmasını isteyin. Kod stili tutarlılığı, Flask projelerinde bakım maliyetini düşürür. AJan, ruff çıktısına göre import sıralamasını veya satır uzunluğunu düzeltebilir. Ayrıca flask routes komutu ile tanımlı rotaları listeleyip eksik endpoint’leri kontrol edebilirsiniz.

Aynı Flask projesinde birden fazla ajanı AgentVera ile çalıştırma

Flask projenizde birden fazla işi paralel yürütmek istediğinizde AgentVera, GitHub Copilot CLI gibi ajanları kendi gerçek terminal panellerinde yan yana çalıştırır. Her ajan kendi git worktree’sinde çalışabildiği için biri auth blueprint’ini geliştirirken diğeri dashboard şablonunu değiştirebilir ve dosyalar çakışmaz. Bir ajanın turu bitince ikinci bir model kodu otomatik inceler; bulguları file:line ile gösterdiği için Flask bağlam hatalarını yakalamak kolaylaşır. Her turun anlık görüntüsü alındığından yanlış bir değişiklik tek tıkla geri alınabilir; token bütçeleri ise ajanı sınırda durdurarak maliyeti kontrol altında tutar.

Sonuç

GitHub Copilot CLI, Flask projelerinde blueprint, şablon, model ve test döngüsünü hızlandıran pratik bir araçtır. Proje talimatlarını net tutar, küçük adımlarla ilerler ve her değişikliği test ederseniz ajanın çıktısı güvenilir olur. Aynı anda birden fazla işi yürütmek istediğinizde AgentVera gibi araçlarla paralel çalışma düzeni kurabilirsiniz. Unutmayın: ajan bir asistan değil, kod üreten bir yardımcıdır; nihai sorumluluk sizdedir.