Yapay zekâ ve çalışma sistemleri

Bir AI aracının kullanım kılavuzu: .md dosyaları ne işe yarar?

Özel bir AI aracı geliştirdiğini düşün. Model hazır, araç bağlantıları yapılmış ve arayüz çalışıyor. Fakat model hâlâ senin kurumunda hangi kaydın güvenilir kaynak sayıldığını, bir işi hangi sırayla yürüttüğünü veya hangi durumda kullanıcıya geri dönmesi gerektiğini kendiliğinden bilemez. .md dosyaları tam bu noktada devreye girer. Bunlar AI'ı daha zeki yapan gizli dosyalar değil; aracın kullanım kılavuzunu, alan bilgisini ve çalışma kurallarını açık biçimde saklayan metinlerdir.

Anıl Mirap10 Ağustos 20268 dk okuma

Önce en basit cevap

.md, AI'a özel bir dosya biçimi değildir.

Markdown aslında düz metindir. Başlık, liste, bağlantı, tablo ve kod bloğu gibi yapıları birkaç basit işaretle gösterebilir. Herhangi bir metin düzenleyicide açılır; insan tarafından kolay okunur ve yazılım tarafından kolay işlenir. AI araçları açısından avantajı da tam olarak budur: Metin doğal dil olarak kalırken yapısı görünür olur.

Başlıklar konu hiyerarşisini, listeler işlem sırasını, kod blokları değiştirilmemesi gereken örnekleri anlatır. Model metni yalnızca uzun bir paragraf olarak değil; bölümleri ve aralarındaki ilişkileri daha açık bir bağlam olarak görür. Buna rağmen dosyanın uzantısında özel bir zekâ yoktur. Kullanılan sistem o dosyayı okumuyor veya modele vermiyorsa .md dosyası davranışı hiçbir şekilde değiştirmez.

Bu yüzden Markdown'ı 'AI'ın sevdiği format' diye değil, insanın yazabildiği ve makinenin düzenli biçimde tüketebildiği ortak bir bağlam katmanı olarak düşünmek daha doğrudur.

Prompt ile araç arasındaki fark

Sohbette verilen talimat geçicidir; özel bir araç kalıcı davranış ister.

Bir AI ile tek seferlik çalışırken ihtiyacını mesaj içinde anlatabilirsin. Fakat aynı işi her gün yapan, farklı kişiler tarafından kullanılan veya başka sistemlerle işlem yapan bir araçta bu yeterli olmaz. Her kullanıcının aynı açıklamayı yeniden yazmasını beklemek, aracın davranışını kişisel hafızaya bağlar.

Örneğin IT deposuna gelen talepleri değerlendiren bir AI aracı; yalnızca 'talebi sınıflandır' komutunu değil, hangi envanter kaydının esas olduğunu, aciliyetin nasıl belirlendiğini, hangi durumda otomatik işlem yapılabileceğini ve ne zaman sorumlu kişiye dönülmesi gerektiğini bilmelidir. Bunlar modelin genel bilgisinden çıkaracağı ayrıntılar değildir. Kuruma ve sürece özgü gereksinimlerdir.

.md dosyaları bu gereksinimleri sohbet geçmişinden çıkarıp aracın kalıcı çalışma tanımına dönüştürür. Bir bakıma AI için hazırlanan gereksinim dokümanı, çalışma talimatı ve kullanım kılavuzunun birleşimidir.

Modüler yapı

Tek bir dev prompt yerine, küçük ve görevli dosyalar.

Bütün rol tanımını, alan bilgisini, kuralları ve örnekleri tek bir metne yığmak başlangıçta kolay görünür. Sağlıklı yapı ise her dosyaya tek bir sorumluluk verir.

custom-ai-tool/

AGENT.mdKimlik ve davranışAracın amacı, hedef kullanıcısı, öncelikleri ve kapsam dışı işleri.
KNOWLEDGE.mdAlan bilgisiTerimler, iş kuralları, güvenilir kaynaklar ve kurum içi anlamlar.
WORKFLOW.mdİş akışıGirdiden sonuca kadar adımlar, karar noktaları ve tamamlanma ölçütü.
RULES.mdOperasyonel sınırlarHangi aracın ne zaman kullanılacağı, neyin yasak olduğu ve nerede durulacağı.
EXAMPLES.mdDavranış örnekleriİyi ve kötü çıktı örnekleri, beklenen ton, biçim ve hata yönetimi.
tools/Uygulama katmanıAPI çağrısı, hesaplama, dosya işleme ve diğer deterministik işlemler.

Bu adlar açıklayıcı bir örnektir. Bazı platformlar AGENTS.md veya SKILL.md gibi belirli adlar ve klasör yapıları bekler; kullanılan sistemin yükleme kuralları esas alınmalıdır.

Bağlam bütçesi

Her dosyanın her görevde okunması gerekmez.

Modüler yapının faydası yalnızca düzen değildir. Bir kullanıcı e-posta taslağı istediğinde envanter politikalarının, veri analizi istediğinde de kurumsal yazışma örneklerinin modele verilmesi gereksizdir. İlgisiz içerik token tüketir, önemli kuralların görünürlüğünü azaltır ve modelin dikkatini dağıtır.

İyi bir AI aracı önce kısa dosya açıklamalarına veya metadata'ya bakar, sonra yalnızca görevle ilişkili belgeleri yükler. Beceri dosyaları, arama tabanlı getirme ve RAG yaklaşımlarının ortak mantığı budur: Bütün bilgi her zaman bağlamda durmaz; doğru bilgi ihtiyaç anında getirilir.

Burada dosyanın içeriği kadar adı, açıklaması ve ne zaman okunacağını belirleyen tetikleme kuralı da önemlidir. Çok iyi yazılmış fakat hiçbir akışın çağırmadığı bir .md dosyası, çalışan bağlam değil arşivdir.

İki yaklaşım

Aynı bilgi, iki farklı mimari.

Sorun Markdown kullanıp kullanmamak kadar, bilginin nasıl bölündüğü ve hangi anda bağlama alındığıdır.

Kırılgan yaklaşım

Tek dev prompt

Rol, kurallar, bütün alan bilgisi ve tüm örnekler aynı metindedir.
Her istekte tamamı modele gönderilir.
Bir cümle değiştiğinde ilgisiz görevlerin davranışı da etkilenebilir.
Çelişkileri, tekrarları ve güncelliğini yitiren bilgiyi bulmak zordur.

Sürdürülebilir yaklaşım

Modüler .md yapısı

Ortak ilkeler, görev akışları, bilgi ve örnekler ayrı katmanlardadır.
Yalnızca ilgili dosyalar ihtiyaç anında yüklenir.
Her değişikliğin kapsamı ve sorumlusu daha nettir.
Davranış değişikliği küçük bir Git farkı üzerinden incelenebilir.

Sadece anlatma, göster

EXAMPLES.md bazen on sayfa kuraldan daha etkilidir.

AI modelleri yalnızca açık kurallardan değil, örüntülerden de güçlü biçimde yararlanır. 'Kısa, teknik ve suçlayıcı olmayan bir açıklama yaz' demek bir yön verir; fakat iyi bir örnek hedeflenen uzunluğu, tonlamayı, ayrıntı seviyesini ve paragraf ritmini aynı anda gösterir.

Özellikle çıktı şeması, hata mesajı, rapor düzeni veya araç seçimi gibi konularda iyi-kötü örnek çiftleri belirsizliği azaltır. Model ne yapması gerektiği kadar, hangi görünüşteki sonucun kabul edilmemesi gerektiğini de görür. Bu yöntem genellikle daha fazla sıfat ve soyut kural eklemekten etkilidir.

Yine de örnek, tek doğru cevaba dönüşmemelidir. Temsil edici birkaç örnek davranışın sınırlarını göstermeli; modeli yalnızca isimleri ve cümleleri kopyalamaya zorlamamalıdır.

Doğru bilgi, doğru katman

.md her şeyin yerine geçen bir çözüm değildir.

Özel AI aracı, farklı görevleri olan birkaç katmanın birlikte çalışmasıyla oluşur. Markdown bu yapının önemli bir parçasıdır; tamamı değildir.

01ModelLLM
Muhakeme yapar, belirsizliği yorumlar ve doğal dil üretir.
02Davranış ve alan bilgisi.md
Amaç, iş akışı, kurallar, terminoloji ve örnekleri taşır.
03Kesin işlemkod
Hesaplama, doğrulama, dosya dönüştürme ve API işlemlerini tekrar edilebilir yapar.
04YapılandırmaJSON / YAML
Şema, parametre ve makinenin kesin biçimde ayrıştıracağı değerleri saklar.
05Güncel veya büyük veriAPI / DB / vektör arama
Sürekli değişen kayıtları ve çok hacimli bilgiyi ihtiyaç anında getirir.

Sürüm kontrolü

Bir .md değişikliği, aslında davranış değişikliğidir.

Talimat dosyaları Git gibi bir sürüm kontrol sisteminde tutulduğunda, aracın davranışındaki değişiklik görünür hâle gelir. Hangi kuralın eklendiği, bir istisnanın neden değiştiği ve önceki sürümde nasıl çalışıldığı satır satır incelenebilir. Gerekirse değişiklik geri alınabilir.

Bu, prompt düzenlemeyi kişisel bir deneme alanından ekipçe yönetilen bir mühendislik faaliyetine yaklaştırır. Alan uzmanı metni okuyabilir, geliştirici teknik uygulanabilirliği değerlendirebilir ve yapılan değişiklik aynı örnek görevlerle yeniden test edilebilir.

Sürüm geçmişi tek başına kalite sağlamaz; fakat kötü sonucu tartışırken 'model yine farklı cevap verdi' demek yerine, modele verilen davranış tanımının da değişip değişmediğini somut biçimde kontrol etmeyi sağlar.

Sınırlar

.md dosyasına her şeyi koymak doğru değildir.

Parola, erişim anahtarı ve hassas kişisel bilgiler okunabilir metin dosyalarında tutulmamalıdır. Sürekli değişen envanter, fiyat veya kullanıcı listeleri de .md içine kopyalanmamalı; doğrudan güncel sistemden alınmalıdır. Markdown kaynağın nasıl kullanılacağını anlatabilir, fakat canlı kaynağın yerine geçmemelidir.

Kesin hesaplama, yetkilendirme, şema kontrolü veya veri dönüştürme gibi deterministik işler de doğal dil talimatına bırakılmamalıdır. Aynı girdi için her zaman aynı sonucu vermesi gereken bölüm kodla güvence altına alınmalıdır.

Son olarak iyi yazılmış bir dosya doğru davranışı garanti etmez. Dosyanın gerçekten yüklenmesi, kuralların çelişmemesi ve aracın olumlu-olumsuz senaryolarla test edilmesi gerekir. Dokümantasyon kontrol sağlar; doğrulamanın yerini almaz.

Pratik başlangıç

İlk sürüm için beş net karar yeterlidir.

Dosya sayısını artırmadan önce aracın çalışma mantığını şu beş soruyla görünür kılmak gerekir.

01
Araç hangi problemi, kim için çözüyor ve açıkça hangi işleri yapmıyor?
02
Görev sırasında güvenilir kabul edilen bilgi kaynakları ve temel terimler hangileri?
03
İş hangi adımlarla ilerliyor, karar noktaları nerede ve tamamlanmış sayılması için ne gerekiyor?
04
Hangi işlem kodla veya araçla yapılmalı; hangi durumda kullanıcıya sorulmalı ya da durulmalı?
05
İyi sonuç, kötü sonuç ve sınırdaki durum somut örneklerde nasıl görünüyor?

↗

Kaynaklar ve ileri okuma

.md dosyalarıyla çalışmak, uzun bir promptu dosyaya kaydetmekten ibaret değildir. Asıl mesele; aracın kimliğini, bilgisini, iş akışını, kurallarını ve örneklerini birbirinden ayırarak yönetilebilir hâle getirmektir. Bu nedenle iyi bir özel AI aracı geliştirmek yalnızca prompt mühendisliği değil, aynı zamanda gereksinim ve sistem tasarımı işidir.