ASD-STE100 Basitleştirilmiş Teknik İngilizcesiyle belge yazmayı zorunlu kılan Agent Skill

 (github.com/AminBlg)
2 puan yazan GN⁺ 2 시간 전 | 1 yorum | WhatsApp'ta paylaş
  • SimpleEnglish, LLM’lerin 1983’ten beri havacılık ve uzay alanında kullanılan kontrollü dil ASD-STE100’e uygun, kısa ve belirsiz olmayan teknik belgeler yazmasını sağlayan bir Agent Skill’dir
  • Cümle uzunluğu sınırı, etken çatı, basit zamanlar, koşulların önce verilmesi, cümle başına tek talimat gibi 53 kural uygular; belgeler, hata mesajları, runbook’lar, olay raporları, sürüm notları, prompt’lar ve çeviri hazırlığını destekler
  • 6 Claude modeli ve 8 görevin iki koşulda karşılaştırıldığı 96 değerlendirmede, 100 kelime başına STE ihlalleri ortalama %72,9 azaldı; tüm modellerde çıktı token sayısı da düştü
  • Agent Skills standardını destekleyen Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI gibi ortamlarda bağımlılık olmadan kurulabilir; desteklenmeyen ortamlarda sistem prompt’u veya kullanıcı yönergeleriyle uygulanabilir
  • Sonuçlar ASD’nin resmi sertifikası değildir ve pazarlama, blog ya da marka üslubuna uygulanmaz. Varsayılan mod yapı kurallarıyla alan sözlüğünü birleştirir; katı moddaki kelime kararları için resmi standart gerekir

Projenin çözdüğü sorun

  • SimpleEnglish, LLM’lerin abartılı ve belirsiz cümlelerini ASD-STE100 Simplified Technical English’e yakın teknik cümlelere dönüştüren bir Agent Skill’dir
  • ASD-STE100, yorgun bir bakım teknisyeninin talimatları yanlış yorumlamasını önlemek için 1983’ten beri havacılık ve uzay alanında kullanılan kontrollü bir dildir
  • Claude’un ürettiği özgün metin ile Skill uygulanmış sonuç arasındaki fark, somutluk ve uygulanabilirliktedir
    • “Sağlam bir mimariden yararlanarak sorunsuz biçimde senkronize eder” cümlesini, Postgres tablolarının S3’e kopyalandığını ve bir yapılandırma dosyası gerektiğini söyleyen bir metne dönüştürür
    • Genel bir bağlantı hatası mesajını, app kullanıcısının parola hatasına ve DB_PASSWORD düzeltme adımına dönüştürür
    • Belirsiz kullanıcıları etkilemiş olabileceğini söyleyen olay ifadesini, hata zamanı, %12 istek hatası, dağıtım nedeni ve geri alma saatiyle değiştirir
  • README, hata mesajları, olay raporları ve sürüm notları için ek karşılaştırmalar examples/before-after.md dosyasında yer alır

Kurulum ve desteklenen ortamlar

  • Agent Skills standardını destekleyen Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose, OpenCode gibi yaklaşık 25 harness üzerinde çalışır
  • Proje tek bir klasörden oluşur, dış bağımlılığı yoktur ve MIT lisansını kullanır
  • Kurulum komutu şöyledir
npx skills add AminBlg/SimpleEnglish
  • skills CLI, yüklü ajanları algılar ve Skill’i kullanıcının seçtiği hedefe kurar
  • Kurulumdan önce şu komutla deneyebilirsiniz
npx skills use AminBlg/SimpleEnglish@simple-english
  • SKILL.md desteği olmayan ortamlarda prompts/system-prompt.md, sistem prompt’u, AGENTS.md veya .cursorrules içine konabilir
    • Küçük token bütçeli ortamlar için yaklaşık 60 tokenlık bir sürüm de sunulur
    • Teknik belge yazılmasını isteyerek veya “rewrite this with simple-english” talimatını vererek kullanılabilir

Terminal olmayan ortamlarda kullanım

  • Claude.ai ücretli planları Skill’i yerleşik olarak destekler
    • SKILL.md dosyasını kaydedin
    • Settings → Capabilities altında kod çalıştırmayı etkinleştirin
    • Settings → Customize → Skills → Upload altında dosyayı yükleyin
    • Skill’i açtığınızda teknik belge yazma isteklerine uygulanır
  • ChatGPT Skill’i desteklemediği için prompt sürümü kullanılır
    • prompts/system-prompt.md içindeki bloğu Settings → Personalization → Custom Instructions, Project veya Custom GPT yönergelerine koyun
  • Gemini içinde bir Gem oluşturun ve aynı prompt’u yönergelere yapıştırın
  • Diğer sohbet botlarında prompt dosyasını ekleyin veya içeriğini yapıştırın ve tüm çıktılara uygulamasını söyleyin

ASD-STE100’den alınan yazım kuralları

  • Skill, 1983’te oluşturulan 9 bölümdeki 53 kuralı teknik belgelere uygular
  • Temel kurallar şunlardır
    • Talimat cümlelerini en fazla 20 kelimeyle, açıklama cümlelerini en fazla 25 kelimeyle sınırlar
    • Belge genelinde bir kelimeye yalnızca bir anlam verir; check, verify, confirm, validate gibi ifadelerin karışık kullanılmasını engeller
    • Yalnızca basit zamanlar kullanır; “has been updated” yerine kimin neyi güncellediğini doğrudan yazar
    • -ing fiil biçimlerini ve bunlara bağlı ek yan tümceleri kullanmaz
    • “it should be noted that” gibi dolaylı ifadeleri kaldırmak için etken çatı kullanır
    • should, would, may, might kullanımını yasaklar; ancak can, will, must kullanımına izin verir
    • Kullanıcının koşulu geç okumasını önlemek için koşulu komuttan önce yerleştirir
    • Bir cümleye yalnızca bir talimat koyar
    • Artikelleri ve that kelimesini korur; kısa olsa bile telgraf tarzı cümleler oluşturmaz
  • Yazılım örnekleri dahil tam yeniden yazım kuralları SKILL.md dosyasında bulunur
  • Pazarlama STE kapsamının dışında olduğu için README’deki pazarlama metinlerine kurallar uygulanmaz; Skill de yalnızca belge yazımına uygulanır

Teknik belgeler dışındaki kullanım kapsamı

  • use-cases.md, farklı formatlara göre kurallar sağlar
    • Hata mesajları, olan şey, neden ve kullanıcının yapması gereken işlem sırasıyla yazılır
    • Runbook’lar bakım kılavuzlarına benzediği için STE doğrudan uygulanır
    • Olay raporlarında belirsiz ve örtük ifadeleri kaldırmak için basit geçmiş zaman kullanılır
    • Sürüm notlarındaki uyumluluğu bozan değişiklikler, önce komutu sonra riski yazan uyarılar olarak düzenlenir
    • AGENTS.md ve sistem prompt’ları, soru soramayan okuyuculara yönelik prosedürler olarak ele alınır; modelin seçenek olarak yorumlayabileceği should yasaklanır
    • Çeviri öncesi belgeler, ana dili İngilizce olmayanların daha kolay okuyacağı ve yerelleştirme maliyeti daha düşük olacak şekilde düzenlenir
  • Pazarlama metinlerine, blog üslubuna ve marka yazımına uygulanmaz; üslubun düz olması amaçlanan bir özelliktir

Benchmark sonuçları

  • Değerlendirmede, 6 Claude modelinde 8 yazım görevi Skill uygulanmadan ve uygulandıktan sonra çalıştırıldı; toplam 96 üretim sonucu ölçüldü
  • 100 kelime başına STE ihlalleri genel ortalamada %72,9 azaldı
    • claude-opus-4-8: 1,05’ten 0,62’ye düştü; %41 iyileşme
    • claude-opus-4-7: 2,28’den 0,42’ye düştü; %82 iyileşme
    • claude-opus-4-6: 2,24’ten 0,40’a düştü; %82 iyileşme
    • claude-opus-4-5: 2,55’ten 0,57’ye düştü; %78 iyileşme
    • claude-sonnet-5: 2,67’den 0,53’e düştü; %80 iyileşme
    • claude-sonnet-4-6: 2,06’dan 0,52’ye düştü; %75 iyileşme
  • Tüm modellerde çıktı token sayısı azaldı; ortalama cümle uzunluğu 11,2 kelimeden 9,7 kelimeye indi
  • İki koşula da aynı kuralları uygulayan deterministik regex linter kullanıldı; tam yöntem ve sınırlamalar evals/results/RESULTS.md dosyasında yer alır
  • Oturum açılmış Claude Code CLI varsa şu komutla yeniden üretilebilir
python3 evals/run_bench.py

Kural doğrulama yöntemi

  • Skill, blog özeti değil 2025 Issue 9 özgün metni temel alınarak test odaklı biçimde geliştirildi
  • Skill olmayan referans ajan 40 kelimelik cümleler yazdı ve var olmayan kural numaraları da üretti
    • Bir sonuç, kısa cümle kuralını “Rule 3.1” olarak alıntıladı; oysa gerçek Rule 3.1 fiil biçimleriyle ilgili bir kuraldır
  • Bazı ikincil kaynakların aksine resmi PDF, can ve will kullanımına izin verir
  • Skill, kaydedilen referans hataları tek tek engelleyecek şekilde yazıldı ve ajan geçene kadar yeniden test edildi; senaryolar ve sonuçlar evals/pressure-tests.md dosyasında bulunur

Uygulama sınırları ve standart durumu

  • Çıktılar STE sertifikalı belge değildir
    • ASD hiçbir aracı sertifikalandırmaz
    • Varsayılan mod yapı kurallarıyla kullanıcının alan sözlüğünü birleştirir
    • Katı mod standarda daha çok yaklaşır, ancak kelime bazlı kararlar için resmi standart gerekir
  • Sonuçlar Airbus kılavuzları gibi düz ve yanlış anlaşılması zor biçimde yazılır; kişilikli üslup blog gibi diğer kullanımlar için ayrılacak şekilde tasarlanmıştır
  • “Açık yaz” gibi öznel talimatların aksine “cümleleri 20 kelimenin altında yaz” doğrulanabilir bir şartnamedir; bu nedenle ajan bunu izleyebilir
  • ASD-STE100, 40 yıldan eski bir standarttır; ancak Ocak 2025 tarihli Issue 9’a kadar korunmuş ve güncellenmiştir, numaralandırılmıştır ve test edilebilir

Lisans ve gayriresmî durum

  • Depo bütünüyle MIT lisansı altında sunulur
  • Kurallar eğitim amacıyla yeniden ifade edilir; resmi şartname ifadeleri veya sözlük içeriği kopyalanmaz
  • Proje ASD veya STEMG ile bağlantılı ya da onaylı değildir; ASD-STE100, ASD’nin tescilli ticari markasıdır

İlgili okumalar

1 yorum

 
GN⁺ 2 시간 전
Hacker News yorumları

  • Bir örneğin başına yalnızca “ASD-STE100 Basitleştirilmiş Teknik İngilizce ile yeniden yaz” cümlesini eklemek bile yeterince iyi sonuç veriyor. Bir iki cümlelik yönerge yeterli olmalı; ASD-STE100’ün zaten eğitim materyallerine dahil edilmiş olma ihtimali yüksekken neden devasa bir skill gerektiği belirsiz

    • Modelin ön eğitim bilgisini kendiliğinden kullanması beklentisini anlıyorum, ancak sonrasındaki eğitim aşamalarında ön eğitim verileri epey karışıyor gibi görünüyor

  • LLM tarafından üretilen metinlere The Economist stil kılavuzunu uygulayan bir skill yaptım: https://github.com/TAJD/economist-style-guide-plugin
    Görece iyi yapılandırılmış ve düzenlemesi kolay metinler üretiyor

  • Bu, STE’nin yanlış kullanımı ve sınırlı benimsenmesi hakkında: https://en.wikipedia.org/wiki/Simplified_Technical_English#M...

    • Eleştiri metnindeki “STE ile doğru yazmak için çok iyi İngilizce hâkimiyeti ve ilgili konu hakkında yeterli bilgi gerekir” cümlesi dikkat çekici. Bu, STE kullanılsın ya da kullanılmasın, her alanda iyi İngilizce yazım için gereken koşullardan ibaret
    • LLM’ler çeviride iyi olduğundan bu tür yazımda özellikle başarılı olmaları gerekir. Nitekim son bir hafta boyunca tüm prompt’lara uyguladığımda üsluptaki fazlalıkları temizlemede etkili oldu ve aşırı yinelenen niteleyici ifadeler hiç görmedim

  • Fikir hoşuma gidiyor ama skill’in kendisinden emin değilim. Bunun yerine https://vale.sh ve çeşitli linter’lar keşfettim; onları denemeyi düşünüyorum

    • STE zaten eğitim verilerinde bulunduğu için skill gereksiz tekrar ve yalnızca bağlam penceresini kirletiyor
    • LLM dokümantasyon işlerinde Vale’in nasıl kullanılabileceğini merak ediyorum

  • Fazla çok şey yapıyor gibi; tek satırlık bir sistem prompt’u yeterince iyi çalışır: “Çıktı token’ları değerlidir; kısa yanıt ver ve ASD-STE100 Basitleştirilmiş Teknik İngilizce kullan”

    • Bunun gerçekten sürekli iyi çalışıp çalışmadığını merak ediyorum. Kullanıcı profiline ve CLAUDE.md dosyasına kurallar eklesem de model sonunda rotadan çıkıp docstring’lere ve açıklamalara teknik jargon yığdı
      Kod açıklamalarını daha kolay ve basit hâle getirecek her yöntemi denemeye hazırım; bu yüzden bunu da merakla bekliyorum

  • README daha en baştan “muğlak bir cümle yüzünden okuyucuları ölebilecek kişilerin 1983’te yazdığı 9 bölüm, 53 kural” gibi LLM’e özgü üslubu açıkça gösteriyor; ironik. Bir yazım skill’i için pek umut verici bir işaret değil

    • Bunu kabul ediyor ama README’nin üslubunu gerçekten sevmiyorum. “Bu README kuralların yarısını çiğner ama pazarlama açıkça STE kapsamı dışındadır ve skill bunu bilir, belgenin içinde kalır”, “Pazarlama metnini, blog üslubunu ve marka yazımını reddeder; bilerek düz yazar” gibi ifadeler var
      Her cümlenin yanında HN’de kaldırılmış emojiler de var
    • Bir süre sade bir ASD-STE100 prompt’u kullandım; ajanın basitleştirilmiş İngilizcesini biraz daha beğendim ama metnin genel yapısını değiştiremiyor
      Cümleler kısalıyor, abartılı girişler veya sunum slaydı gibi boş bölüm başlıkları azalıyor; kalite belirgin biçimde artıyor ama devrimsel değil ve sorunu tamamen çözmüyor
    • README kısa ve doğru görünüyor; kendim deneyince iyi çalıştı. Çevremde gördüğüm birçok insan yazımı README’den daha iyi

  • Standart Issue 9’un ilk örneği daha baştan kendiyle çelişiyor. Test onaylı bir isim ama fiil olarak onaylı değil; STE örnek cümlesi ise “Test B is an alternative to test A”
    STE’ye özgü kuralları bilmiyorsanız açıkça iki anlamlı bir cümle ve açıklıktan uzak. Resmî site indirmeyi Google Form arkasına sakladığı için doğrudan alınabilecek bağlantıyı da bırakıyorum: https://www.asd-ste100.org/assets/files/ASD-STE100_ISSUE9.pd...

    • Neyin iki anlamlı olduğunu anlamıyorum. Baştaki Testi fiil olarak okumak için “B’nin A’ya alternatif olup olmadığını test et” anlamında thatin atlandığını varsaymak gerekir; bu durumda başta fiil, sonda isim olur ve paralellik bozulur
      Ayrıca birine böyle bir eylem talimatı verme yorumu zaten çok düşük olasılıklı

  • ASD-STE100’ün birden ilgi görmesinin sebebi viral bir tweet mi merak ediyorum. Bir arkadaşımdan duyup birkaç gün önce spesifikasyonu paylaşmıştım: https://asd-web-be-prod.azurewebsites.net/media/wunhmi5y/asd...
    PDF’den kopyalama yasaklanmış; kolayca aşılabiliyorken bunu neden yaptıklarını merak ediyorum. İzin verilmeyen kelimeleri engellemek için İngilizceye yönelik ruff gibi bir linter gerekir; yoksa ajan tek satırlık yönergeyi neredeyse kesinlikle unutur

  • Böyle yönergelerin modelin zekâsını veya düşünme yeteneğini nasıl etkilediğini merak ediyorum. Çıktıyı ya da düşünme sürecini değiştiriyorsa modelin kapasitesi de değişebilir; özellikle eğitim sırasında bu dili kullanacak şekilde eğitilmediyse

    • Yönerge olarak vermek yerine son işlem katmanı olarak uygulanmalı gibi

  • https://youtu.be/uJblcC4lKYw adresinde STE skill’i dahil çeşitli skill ve prompt’lar, George Orwell’ın 6 yazım ilkesi ile karşılaştırılarak değerlendirildi; genel olarak Orwell en iyi sonucu verdi
    Girdi bağlamına eklenen token sayısı da fazla değil; bu kuralların uygulandığı düzyazı prompt’larıyla uygulanmadığı prompt’ları karşılaştırdığımda sonuçları beğendim. Bilindik benzetmelerden kaçınmak, kısa kelime yeterliyse uzun kelime kullanmamak, çıkarılabilecek kelimeleri çıkarmak, edilgen yerine etken çatı kullanmak, gündelik bir karşılığı varsa yabancı sözcüklerden, bilimsel terimlerden ve jargondan kaçınmak, barbarca bir cümle yazmaktansa bu kuralları çiğnemek gibi maddelerden oluşuyor

    • Belki çok fazla AI metni okuduğumdandır ama videonun anlatım metni de bu kurallardan hiçbirini uygulamamış Claude tarafından yazılmış gibi geliyor
      “Dürüst olmak gerekirse çeviri iyileşmesi gerçekti ama küçüktü”, “Şimdi dürüst kısım geliyor”, “Aynı hastalık ama farklı belirtiler”, “O acımasız %3 rakamı doğa yasası değil, Claude’un bir özelliğiydi” gibi klişe ve AI’a özgü ifadeler çok fazla