Flask projelerinde opencode’u terminalde opencode komutuyla başlatıp doğrudan kod yazdırabilir, test çalıştırabilir ve hata ayıklatabilirsiniz. Bu rehber, blueprint, application factory, Jinja ve SQLAlchemy kullanan bir Flask uygulamasında ajandan en iyi verimi almak için somut kurulum, çalışma düzeni ve doğrulama adımlarını gösterir. opencode hakkında temel bilgi için ilgili sayfaya bakabilirsiniz; uygulama özelinde kalacağız.
Neden opencode Flask işlerine uygundur
Flask projeleri genellikle app/__init__.py içinde application factory, app/models.py, app/templates/ ve blueprint paketleri gibi küçük ama birbiriyle bağlantılı dosyalardan oluşur. opencode bu yapıyı tarar, AGENTS.md talimatlarını okur ve bağlamı koruyarak değişiklik yapar. Blueprint’lerin ayrı klasörlerde olması, ajanın bir rotayı veya şablonu ilgili blueprint altında doğru yere eklemesini kolaylaştırır; SQLAlchemy modelleri ve Jinja şablonları arasındaki ilişkiyi de dosya içeriklerinden çıkarabilir. Ayrıca pytest -q gibi komutları terminalde çalıştırıp çıktıyı okuyabilmesi, Flask’a özgü hata ayıklama döngüsünü kısaltır. Flask’ın istek ve uygulama bağlamları, test istemcisi ve blueprint kayıt sırası gibi kavramları proje içinde açıkça belirtildiğinde ajan bunlara uyum sağlar. Uygulama fabrikası deseni, ajanın yeni eklentileri veya blueprint’leri eklerken create_app() fonksiyonunu doğru yerde güncellemesini kolaylaştırır; ancak bu güncellemeleri her zaman gözden geçirmek gerekir. opencode nasıl kullanılır? Adım adım rehber başlangıç için ek ipuçları sunar.
Projeyi ajana hazırlamak
opencode, proje kökündeki AGENTS.md dosyasını talimat kaynağı olarak kullanır. Bu dosyada Flask projenize özgü komutları, klasör kurallarını ve test beklentilerini açıkça yazın. İşte tipik bir AGENTS.md örneği:
# AGENTS.md
## Komutlar
- Çalıştır: flask --app app run
- Test: pytest -q
- Lint: ruff check .
- Veritabanı geçişi: flask --app app db upgrade
## Klasör düzeni
- app/ içinde blueprint paketleri bulunur; her blueprint kendi routes.py, models.py ve templates/<blueprint>/ klasörünü kullanır.
- app/templates/base.html ana şablon; blueprint şablonları {% extends 'base.html' %} ile başlar.
- tests/ altında conftest.py, test istemcisi fixture'ı sağlar.
## Kurallar
- SQLAlchemy modelleri app/extensions.py içindeki db nesnesini kullanır.
- Rota eklerken blueprint'in url_prefix değerine dikkat et.
- Form doğrulamada WTForms kullan; CSRF token alanını şablona eklemeyi unutma.
- Değişiklikten sonra mutlaka pytest -q çalıştır.Bu dosya, ajanın hangi komutları hangi sırayla çalıştıracağını ve proje yapısına nasıl müdahale edeceğini netleştirir. Özellikle --app parametresi, uygulama nesnesinin yolunu belirterek import hatalarını önler. pytest -q ve ruff check . gibi komutların yanına, projenizde kullandığınız formatter veya migration araçlarını da ekleyebilirsiniz. Ajan bu komutları sizin yerinize çalıştıracağı için, her komutun sanal ortamda çalıştığından emin olun. Ayrıca blueprint klasörü ve şablon yapısı hakkında net kurallar, ajanın yanlış dosyaya yazmasını engeller.
Çalışma döngüsü ve örnek promptlar
Ajana büyük bir görev vermek yerine küçük, doğrulanabilir adımlar verin. Döngü şöyle işler: önce plan isteyin, sonra tek bir değişiklik yaptırın, ardından pytest -q çalıştırıp sonucu paylaşın, en son git diff ile değişiklikleri gözden geçirin. Gerekirse düzeltmeleri tekrar isteyin. İlk olarak ajanın mevcut yapıyı özetlemesini isteyin; bu, bağlamı doğru anlamasını sağlar. Ardından tek bir görev verin ve sonucu test edin. Büyük refactor işlerini küçük parçalara bölün; örneğin önce modeli ekleyin, sonra formu, sonra rotayı, sonra şablonu. Her parça için ayrı commit’ler oluşturun. Aşağıdaki tablo tipik görevler için iyi prompt örnekleri gösterir:
| Görev | İyi bir prompt |
|---|---|
| Yeni blueprint ekleme | app/ altında auth adında bir blueprint oluştur, __init__.py, routes.py ve templates/auth/login.html dosyalarını ekle. Blueprint’i url_prefix='/auth' ile uygulama fabrikasına kaydet. |
| Model ekleme | app/models.py içine User modelini ekle: id, username, email, password_hash alanları. User için set_password ve check_password metodlarını yaz, SQLAlchemy db nesnesini kullan. |
| Şablon düzenleme | app/templates/base.html içindeki navbar’a Giriş Yap ve Kayıt Ol linklerini ekle, url_for kullanarak blueprint endpoint’lerini hedefle. |
| Test yazma | tests/test_auth.py içinde kayıt ve giriş akışını test eden iki pytest fonksiyonu yaz, client fixture’ını kullan. |
| Hata düzeltme | Şu hatayı düzelt: RuntimeError: Working outside of application context. Testlerde db.create_all() çağrısı yaparken neden olur? |
Bu döngüde ajanın her adımda ne yaptığını izleyin; git diff çıktısı özellikle app/__init__.py, extensions.py ve test dosyalarındaki değişiklikleri net gösterir. Eğer ajan bir hata alırsa, hata mesajını kopyalayıp geri verin; genellikle bir iki iterasyonda düzeltir. Prompt yazarken dosya yolunu, fonksiyon adlarını ve beklenen davranışı açıkça belirtin. Ayrıca “çalıştır ve sonucu göster” gibi talimatlar, ajanın doğrulama yapmasını sağlar.
Hangi işleri iyi yapar, nelere dikkat etmeli
opencode, blueprint ekleme, model ve migration oluşturma, basit CRUD rotaları, Jinja şablon düzenleme ve pytest testleri yazma konularında iyidir. Uygulama fabrikası içinde blueprint kaydı, create_app() içinde eklenti başlatma gibi işleri tutarlı biçimde yapar. Ancak şu tuzaklara dikkat edin:
- Uygulama bağlamı: Model tanımları
dbnesnesini kullanırken ajan bazendb.init_app(app)çağrısını unutabilir veya yanlış yere koyabilir; bu, testlerdeRuntimeErrorüretir. - Blueprint içinde çakışan endpoint adları: İki blueprint aynı fonksiyon adını kullanırsa
url_forhata verir; ajan buna dikkat etmeyebilir. - Test izolasyonu: Her test öncesi veritabanını sıfırlamak gerekir; ajan bazen fixture’ı yanlış kapsamda yazabilir ve testler arasında durum sızdırır.
- Jinja şablonlarında
url_forargümanlarını blueprint adıyla yazmak; ajan bazen sadece endpoint adını verebilir ve çalışma anında hata oluşur. - CSRF token: Form içeren şablonlara
{{ csrf_token() }}eklemeyi atlayabilir; bu, 400 hatasına yol açar.
Bu nedenle her değişiklikten sonra diff’i gözden geçirin ve testleri çalıştırın. Ayrıca ajanın ürettiği SQLAlchemy sorgularını kontrol edin; bazen gereksiz join veya eksik filter yazabilir. Özellikle ilişkili modellerde backref ve lazy seçeneklerini yanlış kullanabilir; bu performans sorunlarına yol açar. Şablonlarda döngü ve koşul ifadelerinde Jinja sözdizimini doğru yazdığından emin olun.
Test ve doğrulama
Ajana test yazdırırken pytest -q komutunu AGENTS.md içinde belirtin. Test istemcisi fixture’ını tests/conftest.py içinde tanımlayın; ajan bu fixture’ı kullanarak istek simülasyonu yapar. Ajan test çalıştırdığında, hata çıktısını özetleyip ilgili dosyaya düzeltme yapar. Kapsamı artırmak için pytest --cov=app gibi komutlar da ekleyebilirsiniz, ancak opencode’un çıktıyı okuyup yorumlaması için önce temel testlerin geçtiğinden emin olun. Ayrıca git diff ile ajanın test dosyalarında yaptığı değişiklikleri kontrol edin; bazen üretim kodunu değiştirmeden testi geçirecek sahte düzeltmeler yapabilir. Gerçek bir Flask projesinde, ajanın yazdığı testler app nesnesini doğru içe aktarmalı ve her testten sonra veritabanını temizlemelidir. pytest çıktısındaki traceback’leri ajanla birlikte inceleyip düzeltme istemek, hata ayıklama süresini kısaltır. Fixtures’ta db.session.remove() ve db.drop_all() çağrılarının doğru sırada olduğundan emin olun; ajan bazen temizliği atlayabilir. Ajan test başarısız olduğunda, hangi testin neden başarısız olduğunu sorarak daha hedefli düzeltmeler isteyebilirsiniz.
Birden fazla ajanı AgentVera ile çalıştırmak
Flask projesinde birden fazla opencode oturumunu paralel yürütmek isterseniz AgentVera gerçek terminal panelleriyle ajanları yan yana çalıştırır. Her ajan ayrı git worktree’de çalışabildiği için blueprint veya model dosyaları üzerinde çakışma yaşanmaz; iş bitince değişiklikler birleştirilir. Otomatik kod incelemesi, bir ajanın yazdığı rotayı veya şablonu ikinci bir modelin denetlemesini ve hataları dosya:satır ile raporlamasını sağlar. Checkpoint’ler sayesinde hatalı bir tur tek tıkla geri alınabilir. Token bütçeleri, uzun Flask oturumlarında ajanın kontrolsüz tüketim yapmasını önler. Bu özellikler, bir ajan app/__init__.py üzerinde çalışırken diğerinin auth blueprint’ini güvenle geliştirmesine olanak tanır.
Sonuç
opencode, Flask projelerinde AGENTS.md ile yönlendirildiğinde üretken bir yardımcıdır; küçük adımlar, sürekli test ve diff incelemesi ile kaliteli kod elde edersiniz. Bağlam ve uygulama yapısını ne kadar iyi tanımlarsanız ajan o kadar tutarlı sonuç verir. Paralel işler için AgentVera gibi araçlar çakışma riskini azaltır. En iyi Claude Code alternatifleri 2026: 9 CLI ajanı sayfasındaki diğer seçenekleri de değerlendirebilirsiniz.