Tüm blog yazıları

Bağlam yönetimi: doğru dosyalar, proje kuralları ve iş devri

6 dk okuma
Ders 4: Bağlam yönetimi ve kurallar — BilGen Akademi kapak slaydı.

Bir ajana çok açık bir görev vermiş olabilirsiniz: “Görev başlığında arama ekle, boş aramada bütün kayıtları göster.” Ancak ajan başlığın name alanında tutulduğunu varsayıyor, gerçek projede ise title kullanılıyorsa iyi yazılmış istek yanlış bir başlangıç yapar. İş tarifi ile proje bilgisi birlikte çalışmalıdır.

Dördüncü dersin konusu bağlam yönetimi: doğru bilgiyi seçmek, kalıcı kuralları düzenlemek ve uzun çalışmalarda kararları korumak. Burada amaç her dosyayı her konuşmaya eklemek değildir. O anki işin anlaşılması ve doğrulanması için gereken bilgiyi erişilebilir tutmaktır.

Yeni bir görevde başlangıç paketi

Bir göreve başlarken üç bilgi grubu düşünün. İlki istenen davranış: ne değişecek, ne korunacak? İkincisi mevcut uygulama: ilgili ekran, veri yapısı ve kullanılan işlevler. Üçüncüsü çalışma kuralları: hangi komutlarla kontrol yapılır, hangi dosyalar üretilmiş çıktıdır, hangi bağımlılıklar korunmalıdır?

Arama örneğinde başlangıç paketi; liste bileşeni, görev veri tipi, varsa mevcut filtreleme işlevi ve kabul kriterlerinden oluşabilir. Ödeme entegrasyonu veya kullanılmayan bir yönetim panelinin dosyaları bu iş için başlangıçta gerekli değildir. İnceleme sırasında bağlantı ortaya çıkarsa bağlamı genişletirsiniz.

Bağlamı göreve göre seçmeyi anlatan BilGen slaydı.

Şekil 1. İlgili bilgiyi seçmek, asıl kararı ilgisiz ayrıntıların içinde kaybetmeyi önler.

Bir dosyanın açık olması, içeriğinin tamamının modele sunulduğunu her araçta garanti etmez. Aracın dosya ekleme ve okuma davranışını öğrenin. Gerekirse dosyayı açıkça belirtip önce incelemesini isteyin. VS Code bağlam rehberi, konuşma ve proje bilgilerinin modele nasıl taşındığına ilişkin temel ayrımları açıklar.

Veri örneğini varsayımdan ayırın

Aşağıdaki TypeScript tipi öğretim amaçlıdır; gerçek projenizdeki şemanın yerine geçmez:

typescript
type Gorev = {
  id: number;
  title: string;
  completed: boolean;
};

Bu küçük tanım bile birkaç belirsizliği giderir. Başlık alanı metindir, tamamlanma durumu bir mantıksal değerdir ve kimlik sayıdır. Fakat verinin nereden geldiğini, hangi alanların zorunlu olduğunu doğrulamak için gerçek kaynak yine incelenmelidir. Bir örnek kayıt bütün veri koşullarını kanıtlamaz.

“Başlık alanı muhtemelen title” ile “Veri tipinde başlık alanı title olarak tanımlı” farklı ifadelerdir. Birincisi varsayım, ikincisi incelenmiş kaynağa dayalı bulgudur. Ajandan bu ayrımı korumasını istemek, hatalı varsayımların sessizce koda dönüşmesini azaltır.

Kalıcı proje kuralları ne işe yarar?

Aynı projede her görevde tekrar edilen bilgiler vardır: mevcut bileşenleri kullanmak, yerel fontları korumak, belirli kontrol komutunu çalıştırmak veya üretilmiş dosyayı doğrudan düzenlememek. Bunları kısa bir proje talimatında toplamak yararlıdır.

Bazı araçlar bunun için özel dosya adları kullanır. Codex, AGENTS.md dosyasını proje rehberi olarak tanır; bu dosya zorunlu değildir. Bu davranış OpenAI’ın geliştirme iş akışı rehberinde açıklanır. Başka araçlarda dosya adı, kapsam ve yükleme sırası farklı olabilir; tek bir dosyanın bütün araçlarda aynı biçimde uygulanacağını varsaymayın.

Proje talimatlarını somut çalışma kurallarına dönüştüren BilGen slaydı.

Şekil 2. İyi bir proje kuralı, hangi durumda hangi davranışın beklendiğini söyler.

Aşağıdaki içerik bir proje kuralı taslağıdır. Komut adları, gerçek projenizde bulunan komutlarla değiştirilmelidir:

markdown
# Projede çalışma kuralları

- Önce README ve ilgili özellik tanımını oku.
- Görev verisinin gerçek alanlarını kaynak dosyadan doğrula.
- Yeni ekranlarda mevcut ortak bileşenleri kullan.
- İlgisiz dosyaları ve kullanıcının değişikliklerini koru.
- Kod değişikliğinde proje için tanımlı kontrol komutunu çalıştır.
- Çalıştırılmayan kontrolü sonuç raporunda açıkça belirt.
- Özellik davranışı değişirse ilgili açıklamayı güncelle.

“Kaliteli kod yaz” gibi bir beklenti tek başına yönlendirici değildir. “Mevcut ortak bileşeni kullan” daha gözlenebilir bir davranıştır. Kuralların kısa tutulması da önemlidir: aynı cümleyi farklı biçimlerde tekrar eden uzun belgeler, gerçek öncelikleri görünmez hâle getirebilir.

Kural yazmak ile yetki vermek arasındaki fark

Bir talimat dosyası, ajanın nasıl çalışmasını beklediğinizi anlatır. Dosya erişimi, komut çalıştırma sınırları ve dış servis yetkileri ise çalışma ortamının ayarlarıyla ilgilidir. “Yalnızca bu klasörde çalış” cümlesi faydalı bir yönlendirmedir; işletim sistemi düzeyinde erişim engeli oluşturmaz.

Benzer şekilde “testleri çalıştır” kuralı, testin gerçekten çalıştırıldığına dair kayıt değildir. Sonuç raporunda komutun ne olduğu, çalışıp çalışmadığı ve ne sonuç verdiği görülmelidir. Kural, uygulama ve kanıtı ayrı tuttuğunuzda hem beklenti hem kontrol netleşir.

Bu ayrım, ajan özelleştirme rehberinde talimatlar ile çalışma zamanı mekanizmaları arasındaki fark olarak da ele alınır. Bir metin dosyasına güvenlik sınırlarının bütün sorumluluğunu yüklemeyin.

Uzun konuşmalarda kararları korumak

Bir oturumda önce açıklamada da arama düşünülmüş, sonra yalnızca başlıkta aramaya karar verilmiş olabilir. Konuşma uzadıkça iki kararın da geçmişte durması kafa karıştırır. Güncel kararı kısa bir özellik belgesine işlemek, aynı konunun tekrar tekrar açılmasını önler.

Bağlam penceresi ve uygulamanın geçmiş yönetimi nedeniyle eski ayrıntılar her zaman aynı biçimde kullanılmayabilir. Bu yüzden önemli kararların tek kaynağı uzun sohbet geçmişi olmamalıdır. Güncel belgede hangi kararın geçerli olduğunu yazın; eski seçenekleri güncel gereksinim gibi bırakmayın.

Karar kaydı basit olabilir: “Arama yalnızca başlıkta; açıklama araması bu sürümün dışında.” Tarih ve gerekçe eklemek, ileride neden bu sınırın konduğunu anlamayı kolaylaştırır. Ancak belgeyi proje gerçeğiyle birlikte güncellemek gerekir. Yapılmamış bir işi “tamamlandı” diye kaydetmek, sonraki oturumu yanıltır.

İş devri notu nasıl hazırlanır?

İş devri, bütün konuşmayı yeniden anlatmak değildir. Bir sonraki kişinin veya oturumun güvenilir biçimde başlayabilmesi için hedefi, kararları, tamamlananları ve kalanları taşır.

İş devrinde hedef, karar, tamamlanan iş ve sıradaki adımı gösteren BilGen slaydı.

Şekil 3. Kısa bir iş devri, geçmiş sohbeti baştan okumadan mevcut durumu değerlendirmeyi sağlar.

Aşağıdaki örnek bir devir notu şablonudur; gerçek proje sonucu olarak okunmamalıdır:

text
Hedef: Görev listesine başlık araması eklemek.
Güncel karar: Boşluklar kırpılacak; Türkçe harf eşlemesi kullanılacak.
Kapsam: Yalnızca tarayıcıda yüklenmiş görevlerin başlıkları.
Tamamlanan: [Gerçekte yapılan değişiklikleri yaz.]
Kontroller: [Komut, sonuç ve varsa çalıştırılamama nedenini yaz.]
Kalan: [Henüz yapılmayan davranış veya incelemeyi yaz.]
Başlangıç kaynakları: [Gerçek dosya yollarını yaz.]
Sonraki adım: Kalan en küçük işi, mevcut dosyalardan doğrulayarak başlat.

Yeni oturumda bu notu okumak başlangıçtır. Dosyaların güncel durumunu da kontrol etmek gerekir; arada başka biri değişiklik yapmış olabilir. Devir notunun tarihi ile dosyanın gerçek içeriği çelişiyorsa farkı araştırın.

Uygulama: bağlam paketinizi küçültün ve netleştirin

Bir özelliğiniz için gereken üç kaynağı seçin. Her birinin yanına neden gerekli olduğunu tek cümleyle yazın. Sonra bir proje kuralı ve dört satırlık devir notu hazırlayın. “Her ihtimale karşı” eklediğiniz dosyaları yeniden değerlendirin: mevcut işi anlamaya veya kontrol etmeye gerçekten katkı sağlıyorlar mı?

Eksik bilgiyle karşılaşıldığında doğru tepki, boşluğu kesin bilgi gibi doldurmak değildir. Önce kaynak araştırılır; ürün kararı hâlâ belirsizse açıkça sorulur. Böylece bağlam yönetimi yalnızca dosya ekleme işleminden çıkar, çalışma boyunca doğruluğu koruyan bir alışkanlığa dönüşür.

Sıradaki aşamada bu bilgileri bir geliştirme planına dönüştüreceğiz. Beşinci dersin yazısı, fikirden gereksinime, özellik tanımına ve küçük uygulama adımlarına giden yolu anlatır.

Çerez tercihlerin

Platformun çalışması için zorunlu çerezler kullanıyoruz. İzin verirsen anonim kullanım verilerini ölçüyoruz. Ayrıntıları incele