Ekip, yapay zeka agentları için yazılmış bir dokümantasyon standardı olan documentation.ai.md'yi open source yaptı

Agentlar birincil okuyucu haline geldi

Birkaç geliştirici ürünü geliştiren — bunlar arasında bir event-ledger veritabanı ve S3 uyumlu bir object store bulunan — bir ekip, insanların araçlarını benimseme şeklinin sessizce değiştiğini söylüyor. 30 Ağustos'ta dev.to'da yayımlanan bir yazıda ekip, ürünlerini deneyen insanların artık çoğunlukla bir tarayıcıyla başlamadığını; bir kodlama agentına aracı projesine eklemesini söylediğini ve agentın kurulum ile bağlantıları hallettiğini yazıyor.

Ekip, bu agentların mevcut dokümantasyonla çalışmasını izlemenin çoğunlukla sorunsuz geçtiğini bildiriyor. Ama ara sıra bir agent var olmayan bir yapılandırma bayrağı uyduruyor, yanlış portu kullanıyor ya da neredeyse doğru bir endpoint'i çağırıyordu. Ekip bunun modelin başarısızlığı olmadığı teşhisini koyuyor. Dokümanlar insanları ikna etmek ve alıştırmak için yazılmıştı; bu da agentı, paragraflara dağılmış düz yazıdan gerçekleri yeniden inşa etmek zorunda bırakıyordu.

Farklı bir okuyucu için ikinci bir doküman

Çözüm, her sürümün yanına ikinci bir dosya koymak oldu: documentation.ai.md. Ekip, bunun insanlar için yazılmış dokümanların daha kısa bir çevirisi olmadığını açıkça vurguluyor; farklı bir okuyucu için yazılmış, daha katı bir hassasiyet standardına tabi farklı bir doküman. İngilizce yazılmış, yoğun ve kendi başına yeterli — yalnızca o dosyayı okumuş bir agent, ürünü kurabilmeli, yapılandırabilmeli ve çağırabilmeli.

Format, sabit bir sırada sabit bölümler kullanıyor:

• ürünün ne olduğuna dair tek satırlık bir ifade
• tam komutlar, image adları ve portlarla birlikte kurulum ve çalıştırma talimatları
• her ortam değişkenini ve anahtarı kapsayan, her birinin varsayılan değeriyle birlikte verildiği bir yapılandırma bölümü
• pseudocode yerine gerçek bir istek ve yanıta dayalı bir API quickstart'ı
• ilk credential'ın nasıl elde edildiği ve yaygın işlemlerin de dahil olduğu bir admin yüzeyi
• entegrasyonu etkileyen mimari gerçekler
• bağlantılar

Yazımı şekillendiren iki kural var. Pazarlama dili yok. Ve dosya durum hakkında açık sözlü: bir şey erken aşamadaysa veya denetlenmemişse bunu söylüyor; çünkü dokümantasyonun abarttığı bir özelliği agentın kullanıcıya önermesi gerçek bir başarısızlık senaryosu, varsayımsal olan değil.

Bir llms.txt daha değil

Yazı bariz soruyu öngörüyor. documentation.ai.md, ekibin iyi bir site düzeyinde içerik indeksi olarak tanımladığı llms.txt'nin yerine geçme girişimi değil. Dosyaları bunun yerine ürün başına, sürüm başına operasyonel bir doküman; ruh olarak llms-full.txt'ye daha yakın: indeks değil, eksiksiz. İki formatın çakışmadan birlikte kullanılabileceğini, rekabet etmek yerine, savunuyorlar.

Açık standart olarak yayımlandı

Format kendi ürünlerinde kendini kanıtladıktan sonra ekip, onu CC BY 4. lisansıyla açık bir standart olarak yazdı; şartname, iwasoftcom organizasyonu altındaki herkese açık bir GitHub deposunda yayımlandı, böylece diğer üreticiler olduğu gibi benimseyebiliyor.

Neden önemli

Bu yazı, birçok geliştirici araçları şirketinin daha yeni adlandırmaya başladığı bir değişim için somut bir veri noktası: dokümantasyonunuzun okuyucusu giderek artan biçimde ürününüzü kurmaya karar veren kişi değil, onun adına hareket eden agent oluyor. Agentlar farklı okuyor. Boşlukları muhakemeyle doldurmuyorlar; makul tahminlerle dolduruyorlar — uydurulmuş bir bayrak, ıskalanmış bir endpoint. Bu mantıkla, bir agentın yeniden inşa etmek zorunda kaldığı her gerçek, fiilen dokümantasyonun hiç söylemediği bir gerçektir; ve bu boşluğun maliyeti artık hafif kafası karışmış bir okuyucu olarak değil, kullanıcının projesindeki bir entegrasyon hatası olarak ortaya çıkıyor.

Bu hamle ayrıca dokümantasyonu bir dağıtım aracı olarak yeniden çerçeveliyor. Değerlendirme ve bağlantıyı agentlar yapıyorsa, makineye dönük hassasiyet benimseme hunisinin bir parçası haline geliyor ve bir özelliğin olgunluğuna dair dürüstlük yalnızca itibari değil, işlevsel hale geliyor; çünkü agentlar dokümanların iddia ettiği her şeyi yineliyor. documentation.ai.md'nin özellikle tutup tutmayacağı açık bir soru — llms.txt'deki mevcut bir konvansiyonun yanında duruyor — ama temeldeki uygulama, her sürümle birlikte makine okuyucular için ayrı ve daha katı bir doküman yayımlamak, diğer ekiplerin bugünden kopyalayabileceği kısım.