Copilot Talimat Dosyası Hijyeni: Neyi Yazmalı, Neyi Atmalı?
Depolardaki talimat dosyaları (instructions files) genellikle tek yönde büyür: Model hata yapar, biri kural ekler; araç değişir, biri geçici çözüm yazar; yeni model gelir, ama eski yönlendirmeler yerinde kalır. Bir süre sonra depo; işe alım kılavuzu, stil belgesi, sorun giderme günlüğü ve eski prompt mühendisliği notlarının karışımına dönüşen bir dosyayla baş başa kalır. Bu yaklaşım güvenli görünse de kodlama ajanının verimini pratikte düşürebilir. Microsoft.NET Blog’da Wendy Breiding’in yayımladığı “Instructions Hygiene” yazısı, sınır (frontier) modeller çağında bu dosyaları nasıl sadeleştirmek gerektiğini ele alıyor.
📋 İçindekiler
- Talimat hijyeninin amacı nedir?
- Bağlamı bir bütçe gibi düşünün
- Modelin sizden hâlâ ihtiyaç duyduğu bilgiler
- Modelin genelde ihtiyaç duymadığı şeyler
- Model sürümü için değil, model sınıfı için yazın
- Talimatları doğru kapsama yerleştirin
- “Sakla, kaldır, taşı, doğrula” incelemesi
- Derli toplu bir örnek
- Talimatları mühendislik bakımının parçası yapın
- Hedeflenmesi gereken standart
- Kaynaklar ve İleri Okuma
Talimat hijyeninin amacı nedir?
Amaç dosyayı olabildiğince kısaltmak değil. Amaç, sonucu güvenilir biçimde değiştiren yüksek sinyalli en küçük bilgi kümesini korumak. Modern sınır modeller depoları keşfetme, yaygın çerçeveleri tanıma, kalıpları izleme ve sıradan hatalardan kurtulma konusunda önceki nesillere göre çok daha başarılı. Yine de ekibin zihninde duran özel kararları, gizli kısıtlamaları ve operasyonel bilgiyi kendiliğinden bilemezler. Talimat dosyasının değeri işte tam da burada devreye giriyor.
Bağlamı bir bütçe gibi düşünün
Talimat dosyası, ilgili her istekte modele sunulan bağlamın parçasıdır. Her satır; geliştiricinin görevi, ilgili kod, araç çıktısı, konuşma geçmişi ve diğer talimatlarla dikkat için yarışır. Anthropic’in etkili bağlam mühendisliği yaklaşımı, istenen sonucu üretme olasılığını en üst düzeye çıkaran en küçük yüksek sinyalli token kümesini bulmayı önerir. GitHub’ın kendi rehberi de kısa bir proje özeti, teknoloji yığını, kodlama yönergeleri, proje yapısı ve önemli kaynaklara işaret eden bağlantılar tavsiye eder.
Bu yüzden sorulacak soru “Modele bu depo hakkında ne söyleyebiliriz?” değil, “Modelin güvenilir biçimde keşfedemeyeceği, çıkaramayacağı veya alamayacağı ne var?” olmalı.
Modelin sizden hâlâ ihtiyaç duyduğu bilgiler
1. Sistemle ilgili açık olmayan gerçekler
Deponun ne yaptığını kısaca açıklayın ve yanlış anlaşılması kolay mimari sınırları belirtin. Örneğin Billing.Api‘nin genel HTTP sözleşmesine sahip olduğunu, Billing.Worker‘ın uç nokta açmaması gerektiğini; alan (domain) kurallarının kontrolcülerde değil src/Core altında yer aldığını; legacy/ dizininin hâlâ üretimde kullanıldığını; src/Clients/Generated altındaki istemcilerin elle değil üretici (generator) üzerinden güncellenmesi gerektiğini yazmak bu türden bilgilerdir. Model bir klasör ağacını tarayabilir; ama hangi sınırın kasıtlı olduğunu ya da eski görünen bir bileşenin hâlâ kritik olduğunu depo açıkça belirtmedikçe güvenilir biçimde çıkaramaz.
2. Doğrulamanın en kısa güvenilir yolu
Özellikle açık olan komut eksik ya da yanlışsa, yetkili komutları belgeleyin. Yazıda verilen örnek şu:
## Build and validation
- Run `dotnet restore App.slnx` before the first build.
- Build with `dotnet build App.slnx --no-restore`.
- For API changes, run `dotnet test tests/App.Api.Tests/App.Api.Tests.csproj`.
- Run `./eng/verify-generated.ps1` after changing contracts.
- The integration tests require Docker and should not be run in parallel.
Bu, talimat dosyasının içerebileceği en yüksek değerli bilgilerdendir. Gereksiz keşfi önler, bilinen hataları atlar ve ajana somut bir “bittiği zaman” tanımı sunar. Yalnızca doğruladığınız komutları yazın; kendinden emin ama yanlış bir komut, hiç komut olmamasından daha kötüdür.
3. Kod tabanının tutarlı karar veremediği seçimler
Birden fazla makul yaklaşım varsa ekibin tercihini net biçimde belirtin. Örnekler: Yeni testler için MSTest kullanılması; uç noktaların kontrolcü yerine Minimal API ile eklenmesi; beklenen alan hataları için Result<T> döndürülmesi ve istisnaların beklenmeyen hatalara ayrılması; DateTime.UtcNow yerine paylaşımlı TimeProvider kullanılması; yeni bağımlılık eklemek yerine mevcut depo soyutlamalarının tercih edilmesi. Bunlar evrensel programlama gerçekleri değil, yerel kararlar; talimat için biçilmiş kaftan olmalarının nedeni bu.
4. Sert kısıtlamalar ve pahalı hatalar
Bir kuralın çiğnenmesi güvenlik, uyumluluk, uyum veya operasyonel bir soruna yol açacaksa, modele neyin değişmemesi gerektiğini söyleyin. Örneğin görev açıkça istemedikçe genel JSON sözleşmesinin korunması; müşteri verilerinin loglara asla yazılmaması; veritabanı göçlerinin önceki uygulama sürümüyle geriye dönük uyumlu olması; infra/production altındaki dosyaların açık bir dağıtım görevi olmadan değiştirilmemesi. always, never ve must gibi güçlü ifadeleri yalnızca gerçekten mutlak olan kurallara saklayın.
5. Doğrulanmış kaynağın nerede olduğu
Talimatların her ayrıntıyı içermesi gerekmez; güvenilir bir kaynağa işaret etmesi yeterli. API tasarım kuralları için docs/api-guidelines.md, desteklenen çalışma zamanı sürümleri için global.json ve Directory.Build.props, dağıtım iş akışı için docs/deployment.md, mimari kararlar için docs/decisions/ gibi işaretçiler kademeli açıklama (progressive disclosure) sağlar: Modele ihtiyaç duyduğu bağlamı bulacağı kadarını verirsiniz.
Modelin genelde ihtiyaç duymadığı şeyler
Eski bir talimat dosyasını iyileştirmenin en hızlı yolu genellikle çıkarma işlemidir.
Genel yazılım mühendisliği tavsiyeleri
“Temiz ve bakımı kolay kod yaz”, “en iyi uygulamaları izle”, “anlamlı değişken adları kullan”, “hataları uygun şekilde ele al”, “performans ve güvenliği düşün”, “yüksek kaliteli testler yaz” gibi ifadeler nadiren yararlı depo bağlamı ekler. Sınır modeller bunları zaten bilir; üstelik bu ifadeler somut bir kararı çözemeyecek kadar muğlaktır. “Hataları uygun şekilde ele al” yerine örneğin şunu yazın: Doğrulama hatalarını 400‘e, eksik kaynakları 404‘e, eşzamanlılık çatışmalarını 409‘a mevcut ProblemDetails yardımcılarıyla eşleyin.
Eksiksiz depo envanterleri
Tam bir dizin listesi hızla eskir ve modelin saniyeler içinde alabileceği bilgiyi tekrarlar. Yalnızca amacı açık olmayan veya değişikliklerin nereye yapılacağını önemli ölçüde etkileyen yolları ekleyin.
Araçların zaten zorunlu kıldığı bilgiler
Biçimlendiricinin otomatik uyguladığı kuralları veya her derleyici/linter ayarını tekrar tekrar açıklamayın. Bunu uygulayan komutu gösterin: “dotnet format --verify-no-changes çalıştırın; depo analiz kurallarını elle geçersiz kılmayın.” Yazılı kuralı yalnızca araç uygulayamıyorsa veya model uygulamayı seçmeden önce kurala ihtiyaç duyuyorsa saklayın.
Yinelenen belgeler
README, mimari kılavuz ve katkı rehberini talimat dosyasına kopyalamak bakım maliyetini artırır ve çelişki fırsatları yaratır. Modelin ihtiyaç duyduğu kararı özetleyin ve doğrulanmış kaynağa bağlantı verin.
Prompt folkloru ve modele özel yalvarmalar
“Derin bir nefes al”, “adım adım düşün”, “dünya standartlarında kıdemli mühendis gibi davran”, “son derece titiz ol”, “değişiklikten önce her dosyayı oku”, “çözüm mükemmel olana dek asla durma” gibi ifadeler proje bilgisi değil. Yetenekli akıl yürütme modelleri tiyatral teşvike ihtiyaç duymaz; katı prosedürel yönergeler gereksiz keşfe veya araçlarla çatışmaya yol açabilir. Bunun yerine sonucu, kısıtlamaları ve doğrulamayı yazın: Kök nedeni ele alan en küçük değişikliği yapın, genel davranışı koruyun ve etkilenen projenin hedefli testlerini çalıştırın.
Eski hataların günlüğü
Bir geçici çözüm yalnızca hâlâ gerekliyse talimat dosyasında yer almalıdır. Betik, bağımlılık veya platform sorunu düzeltildiğinde uyarıyı da kaldırın; yoksa ajanlar artık var olmayan sorunların etrafından dolaşmaya devam eder.
Model sürümü için değil, model sınıfı için yazın
Model yükseltmeleri talimatları gözden geçirmek için iyi bir vesile; ama talimatlar “Model A kullanıyorsan önce üç dosyayı incele”, “Model B ise onay iste”, “Model C ise adım adım düşün” gibi dallanmalara dönüşmemeli. Model kullanılabilirliği ve davranışı, depo mimarisinden çok daha hızlı değişir. Model bağımsız ifadeleri tercih edin: Gereken sonuç, yerel kısıtlamalar, yetkili komutlar, tamamlama için gereken kanıt ve insan onayının gerektiği noktalar. Yeni bir model eski bir iskelet olmadan başarılı olduğunda o iskeleti kaldırın; depo bilgisi eksikliğinden başarısız olduğunda ise modele özel ritüel yazmak yerine bu bilgiyi belgeleyin.
Talimatları doğru kapsama yerleştirin
Her kural depo geneli dosyaya ait değildir. GitHub Copilot; .github/copilot-instructions.md içinde depo geneli talimatları, .github/instructions/ altında yol tabanlı dosyaları ve AGENTS.md gibi ajan talimatlarını destekler. Depo geneli ve eşleşen yol tabanlı talimatlar birlikte varsa ikisi de kullanılır.
- Depo geneli: Mimari, paylaşımlı komutlar, evrensel kısıtlamalar ve ortak “bittiği zaman” tanımları.
- Yol tabanlı: Çerçeve kuralları, test kalıpları, üretilmiş kod kuralları veya deponun yalnızca bir bölümüne uygulanan doğrulamalar.
- Bağlantılı belgeler: Ayrıntılı açıklamalar, öğreticiler, mimari geçmişi ve nadiren gereken prosedürler.
Örneğin React bileşen testleriyle ilgili bir kural, bir veritabanı göçü sırasında dikkat çalmamalı; ön uç test dizinlerine uygulanan yol tabanlı bir dosyaya taşıyın. İyi kapsamlama, yararlı yönlendirmeyi çöpe atmadan genel dosyayı derli toplu tutar.
“Sakla, kaldır, taşı, doğrula” incelemesi
Belirgin biçimde daha yetenekli bir modele geçtiğinizde, derleme sistemini değiştirdiğinizde, depoyu yeniden düzenlediğinizde veya ajanların yönlendirmeleri tekrar tekrar görmezden geldiğini fark ettiğinizde talimat dosyasını gözden geçirin. Her talimat için dört eylemden birini seçin:
- Sakla: Bilgi hâlâ doğru, önemli ve çıkarılması zor.
- Kaldır: Model zaten hallediyor, bir araç zorunlu kılıyor, muğlak veya güncelliğini yitirmiş.
- Taşı: Kural yararlı ama yol tabanlı bir dosyaya ya da bağlantılı belgeye ait.
- Doğrula: Talimat, değişmiş olabilecek bir komutu, geçici çözümü, sürümü veya bağımlılığı tanımlıyor.
Ardından küçültülmüş dosyayı temsili iş üzerinde test edin: Güncel sınır modelden yaygın, sınırlı bir görevi tamamlamasını isteyin; gerçek başarısızlık kalıplarını gözlemleyin; tekrarlanan bir hatayı önlemek için gereken minimum talimatı ekleyin ve farklı bir görevde yeniden test edin. Bu, yaygın bir yanlış kalıbı tersine çevirir: Gereksizliği ispatlanana kadar her eski talimatı taşımak yerine, yetenekli modelle başlayıp yalnızca kanıt eksik olduğunda bağlam eklersiniz.
Derli toplu bir örnek
Yazıda birçok ekibin hedefleyebileceği depo geneli dosya örneği şöyle veriliyor:
# Project context
This repository contains the Contoso Orders API and its background
fulfillment worker. Public API contracts are owned by `src/Orders.Api`.
Business rules belong in `src/Orders.Core`.
## Engineering decisions
- Target the.NET version specified in `global.json`.
- Use Minimal APIs for new endpoints.
- Use the existing `Result<T>` pattern for expected domain failures.
- Use `TimeProvider`; do not call the system clock directly.
- Do not edit files under `src/Generated`; run `./eng/generate.ps1`.
## Validation
- Build: `dotnet build Orders.slnx`
- Unit tests: `dotnet test tests/Orders.UnitTests`
- API changes: also run `dotnet test tests/Orders.Api.Tests`
- Contract changes: run `./eng/verify-generated.ps1`
## Constraints
- Preserve public JSON contracts unless a breaking change is explicit.
- Never log secrets, tokens, or customer payloads.
- Keep migrations compatible with the previous deployed version.
## References
- Architecture decisions: `docs/decisions/`
- Deployment process: `docs/deployment.md`
Dikkat çeken şey, dosyada olmayanlar: Tam bir dosya ağacı, genel kodlama tavsiyeleri, uzun bir persona ve modelin nasıl düşüneceğine dair ayrıntılı yönergeler yok. Dosya, uygulama seçimlerini değiştiren gerçeklere odaklanıyor.
Talimatları mühendislik bakımının parçası yapın
Talimat dosyaları kod gibi incelenmeli; çünkü kodu etkiliyorlar. Yazının önerdiği hafif uygulamalar şunlar: Talimat değişikliklerini normal pull request incelemesine dahil edin; yeni bir kuralın geniş kullanıma uygun mu yoksa tek görevi çözmek için mi olduğunu inceleyicilere sorun; operasyonel komutlar ve ortam gereksinimleri için bir sahip belirleyin; geçici çözümleri, altındaki sorunu düzelten aynı pull request içinde kaldırın; SDK, çerçeve, test koşucusu veya derleme hattı yükseltmelerinden sonra komutları yeniden kontrol edin; sınır modele düzenli aralıklarla yinelenen, muğlak, çelişkili veya keşfedilebilir talimatları belirletin ve önerilerini doğrulayın.
Kaliteyi yalnızca satır sayısıyla ölçmeyin. Yanlış komutlar içeren 30 satırlık bir dosya, gerekli monorepo sınırlarını barındıran 100 satırlık bir dosyadan daha kötüdür. Sadelik, keyfi bir hedefin değil, alaka düzeyinin sonucudur.
Hedeflenmesi gereken standart
Sağlıklı bir talimat dosyası, yetenekli bir modelin nasıl yetenekli olacağını anlatmadan hızlıca yararlı işe başlamasını sağlar. Yalnızca ekibinizin sağlayabileceği bilgileri saklayın: Sistemin ne olduğu, önemli sınırların nerede olduğu, hangi yerel seçimlerin kasıtlı olduğu, güvenilir biçimde nasıl derlenip doğrulanacağı, nelerin asla bozulmaması gerektiği ve daha derin gerçeğin nereden alınabileceği. Modelin zaten çıkarabileceği, deponun ortaya koyabileceği veya araçların uygulayabileceği bilgileri kaldırın. Sınır modeller geliştikçe en iyi talimat dosyaları ortadan kalkmayacak; daha odaklı hale gelecek. Kalıcı değer, modele akıl yürütmeyi öğretmek değil; ona doğru gerçekleri, doğru kapsamda ve o gerçeklerin önem kazandığı anda vermektir.
Kaynaklar ve İleri Okuma
- Instructions Hygiene – What Frontier Models Still Need You to Say (Wendy Breiding,.NET Blog)
- GitHub Copilot için depo özel talimatları ekleme
- Copilot için daha iyi özel talimatlar yazmak için 5 ipucu
- Anthropic: AI ajanları için etkili bağlam mühendisliği
- OpenAI Cookbook: GPT-5 prompting kılavuzu
- .NET Blog
- .NET Modernizasyonunda Yepyeni Bir Dönem: GitHub Copilot ile İstediğin Yerden
- GitHub Copilot app: Ajanlarla Çalışmanın Yeni Düzeni
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
2 comments