Agent Skills: Yapay Zeka Kodlama Ajanlarına Kıdemli Mühendis Disiplini Kazandırmak

Kıdemli bir mühendisin işinin büyük bölümü, diff'te görünmeyen kısımlardan oluşur. Spesifikasyonlar, testler, kod incelemeleri, kapsam disiplini ve doğrulanamayan şeyleri sevk etmeyi reddetmek. Yapay zeka kodlama ajanları varsayılan olarak bu kısımları atlar. Agent Skills projesi, bu adımları opsiyonel olmaktan çıkarma girişimimdir.

Yapay Zeka Ajanlarının Varsayılan Davranışı Neden Sorunlu?

Herhangi bir yapay zeka kodlama ajanının varsayılan davranışı, "tamamlandı" durumuna en kısa yoldan ulaşmaktır. Bir özellik istersiniz, ajan o özelliği yazar. Spesifikasyonunuz olup olmadığını sormaz, uygulamadan önce test yazmaz, değişikliğin bir güven sınırını aşıp aşmadığını düşünmez veya PR'ın bir incelemeciye nasıl görüneceğini kontrol etmez. Kod üretir, zaferi ilan eder ve devam eder.

Bu, her kıdemli mühendisin kariyeri boyunca kaçınmayı öğrendiği aynı başarısızlık modelidir. Herhangi bir görevin kıdemli versiyonu, diff'te görünmeyen işleri içerir: varsayımları yüzeye çıkarmak, spesifikasyon yazmak, işi incelenebilir parçalara bölmek, sıkıcı tasarımı seçmek, sonucun doğru olduğuna dair kanıt bırakmak, bir insanın gerçekten inceleyebileceği şekilde değişikliği boyutlandırmak. Bu adımlar, ölçekte güvenilir yazılım sevk eden mühendisleri, bozulan kod gönderen insanlardan ayıran şeyin büyük kısmını oluşturur.

Ajanlar bu adımları, herhangi bir junior mühendisin atlayacağı sebeple atlar: görünmezler. Ödül sinyali "tasarım dokümanı var ve görev tamamlandı"yı değil, "görev tamamlandı"yı işaret eder. Bu yüzden kıdemli mühendis iskeletini geri takmamız gerekiyor.

Agent Skills Projesi Nedir?

Agent Skills, bu iskelet için yaptığım girişimdir. Şu anda 26 bin yıldızı geçmiş durumda, görünüşe göre bunu isteyen tek kişi ben değilim. Bu yazı, README'nin tam olarak kapsamadığı kısımdır: her tasarım kararının neden var olduğu, standart SDLC ve Google'ın yayınlanmış mühendislik uygulamalarıyla nasıl eşleştiği ve tek bir skill bile yüklemeseniz bile projeden ne çalmanız gerektiği.

"Skill" Aslında Nedir?

"Skill" kelimesi Claude Code/Anthropic sözlüğünde çok iş yapıyor ve net olmak gerekiyor. Bir skill, durum gerektirdiğinde ajanın bağlamına enjekte edilen frontmatter'lı bir markdown dosyasıdır. Sistem prompt parçası ile çalışma kılavuzu arasında bir yerde durur.

Skill referans dokümantasyonu değildir. "Test hakkında bilmeniz gereken her şey" değildir. Bir iş akışıdır: ajanın takip ettiği bir adım dizisi, kanıt üreten kontrol noktaları ve tanımlanmış bir çıkış kriteriyle biten bir süreç.

Bu ayrım tüm oyunun kendisidir. Ajanın bağlamına test en iyi uygulamaları hakkında 2.000 kelimelik bir makale koyarsanız, ajan onu okur, makul görünen metin üretir ve gerçek testi atlar. Oraya bir iş akışı koyarsanız (önce başarısız testi yaz, çalıştır, başarısız olduğunu gör, geçmesi için minimum kodu yaz, geçtiğini gör, refactor et), ajanın yapacak bir şeyi olur ve sizin doğrulayacak bir şeyiniz.

Düzyazı yerine süreç. Referans yerine iş akışları. Çıkış kriteri olmayan makaleler yerine çıkış kriteri olan adımlar. Bu tek ayrım, kullanışlı bir skill ile güzel bir markdown dosyasını birbirinden ayırır. Ayrıca pek çok "AI rules" deposunun pratikte neden hiçbir şey yapmadığını da açıklar. Kurallar makaledir.

Skills'in Kodladığı SDLC

Depodaki yirmi skill, üstünde yedi slash komutuyla altı yaşam döngüsü fazı etrafında düzenlenir. Define (/spec), gerçekte ne inşa ettiğinize karar verdiğiniz yerdir. Plan (/plan) işi parçalara böler. Build (/build) bunu dikey dilimler halinde uygular. Verify (/test) çalıştığını kanıtlar. Review (/review) gözden kaçanları yakalar. Ship (/ship) güvenli şekilde kullanıcılara ulaştırır. /code-simplify tüm bunların tabanında oturur.

Bu bir tesadüf değil. Bu, işleyen her mühendislik organizasyonunun farklı kelimelerle yürüttüğü aynı SDLC'dir. Google buna tasarım dokümanı → inceleme → uygulama → okunabilirlik incelemesi → lansman kontrol listesi der. Amazon buna geriye doğru çalışan memo ve bar raiser der. Sağlıklı her ekibin bu döngünün bir versiyonu vardır.

Yapay zeka kodlama ajanlarıyla yeni olan şey, çoğu ajanın bu fazların çoğunu varsayılan olarak atlamasıdır. Bir özellik istersiniz, bir uygulama alırsınız ve spesifikasyon, plan, testler, inceleme ve lansman kontrol listesi olmaz. Skills, ajanı bir kıdemli mühendisin kendini zorladığı aynı fazlardan geçirir, çünkü kodu bunlar olmadan göndermek olayların nasıl üretildiğidir.

İşi Yapan Beş Prensip

Projede beş tasarım kararı yük taşıyıcı olanlardır. Sistemin geri kalanı bunlardan akar.

1. Düzyazı Yerine Süreç

Zaten kapsandı. İş akışları ajan tarafından eyleme geçirilebilir; makaleler değil. Aynısı insan ekipler için de geçerlidir. Ekip el kitabınız 200 sayfaysa, kimse zaman baskısı altında okumaz. Kontrol noktalı küçük bir iş akışı setiyse, insanlar gerçekten çalıştırır.

2. Anti-Rasyonalizasyon Tabloları

Bu, projedeki en ayırt edici tasarım kararıdır ve diğer ekiplerin çalmasını en çok istediğim şeydir.

Her skill, bir ajanın (veya yorgun bir mühendisin) iş akışını atlamak için kullanabileceği yaygın mazeretler tablosu içerir, yazılı bir karşı argümanla eşleştirilmiştir. Orijinallere yakın birkaç örnek:

"Bu görev spesifikasyon gerektirmeyecek kadar basit." → Kabul kriterleri hâlâ geçerlidir. Beş satır iyidir. Sıfır satır değil.

"Testleri sonra yazarım." → "Sonra" yük taşıyan kelimedir. Sonra diye bir şey yoktur. Önce başarısız testi yaz.

"Testler geçiyor, gönder." → Geçen testler kanıt değil, ipucudur. Çalışma zamanını kontrol ettin mi? Kullanıcının gördüğü davranışı doğruladın mı? Bir insan diff'i okudu mu?

Bunun işe yaramasının nedeni, LLM'lerin rasyonalizasyonda mükemmel olmasıdır. Bu özel görevin neden spesifikasyon gerektirmediğini veya bu özel değişikliğin neden inceleme olmadan birleştirilmesinin uygun olduğunu açıklayan makul görünen bir paragraf üreteceklerdir. Anti-rasyonalizasyon tabloları, ajanın henüz söylemediği yalanlara önceden yazılmış karşı argümanlardır.

3. Doğrulama Tartışılmaz

Her skill somut kanıtla biter. Testler geçer. Build çıktısı temizdir. Çalışma zamanı izi beklenen davranışı gösterir. Bir incelemeci onaylar. "Doğru görünüyor" asla yeterli değildir.

Bu, Anthropic'in harness'ının başarısızlıklardan kurtulmasını sağlayan, Cursor'ın planner/worker/judge bölünmesinin gerçekten hata yakalamasını sağlayan, uzun süreli herhangi bir ajanın kurtarılabilir olmasını sağlayan aynı prensiptir. Ajan bir üreticidir. İşin yapıldığına dair ayrı bir sinyale ihtiyacınız vardır. Skills bu sinyali her iş akışına yerleştirir.

4. Aşamalı Açıklama (Progressive Disclosure)

Yirmi skill'in tamamını oturum başlangıcında bağlama yüklemeyin. Faza göre etkinleştirin. Küçük bir meta-skill (using-agent-skills), mevcut göreve hangi skill'in uygulanacağına karar veren bir router olarak çalışır.

Bu, harness mühendisliği dersinin skill granülerliğinde uygulanmasıdır. Bağlama yüklenen her token bir yerde performansı düşürür, bu yüzden alakalı olanı yüklersiniz ve geri kalanını diskte bırakırsınız. Aşamalı açıklama, yirmi skill'lik bir kütüphaneyi 5K token'lık bir slota kuyuyu zehirlemeden nasıl sığdırdığınızdır.

5. Kapsam Disiplini

Meta-skill, yapabilseydim her ajana zımbalayacağım tartışılmaz bir kuralı kodlar: "yalnızca dokunmanız istenen yere dokunun." Komşu sistemleri refactor etmeyin. Tam olarak anlamadığınız kodu kaldırmayın. Bir TODO'ya çarpıp dosyayı yeniden yazmaya karar vermeyin.

Bu, bir ajanın bir hatayı düzeltmenin ilgisiz üç dosyayı modernize etmeyi gerektirdiğine karar vermesini izleyene kadar bariz görünür. Kapsam disiplini, bir ajanın PR'ının birleştirilebilir olup olmadığını veya geri alınması gerekip gerekmediğini belirleyen en büyük tek faktördür.

Google DNA'sı

Skills, "Software Engineering at Google" kitabından ve Google'ın kamuya açık mühendislik kültüründen uygulamalarla doludur. Bu kasıtlıdır. Google ölçekli yazılımı çalıştıran şeylerin çoğu belgelenmiş ve kamuya açıktır ve ajanların atlamasının en olası olduğu kısım tam olarak budur.

Hangi skill'in hangi uygulamayı kodladığına dair kısmi bir harita:

api-and-interface-design skill'inde Hyrum Yasası. API'nizin gözlemlenebilir her davranışı sonunda biri tarafından bağımlı hale gelecektir, bu yüzden bunu göz önünde bulundurarak tasarlayın.

test-driven-development skill'inde test piramidi (~80/15/5) ve Beyoncé Kuralı. "Beğendiyseniz, üzerine bir test koymalıydınız." Altyapı değişiklikleri hata yakalamaz; testler yakalar.

Testlerde DRY yerine DAMP. Google'ın test felsefesi, bazı tekrarların maliyetiyle bile test kodunun bir spesifikasyon gibi okunması gerektiğini açıkça belirtir.

code-review-and-quality skill'inde Critical/Nit/Optional/FYI önem etiketleriyle ~100 satırlık PR boyutlandırması. Doğrudan Google'ın kod inceleme normlarından. Büyük PR'lar incelenmez; lastik damgalanır.

code-simplification skill'inde Chesterton Çiti. Neden konulduğunu anlayana kadar bir şeyi kaldırmayın.

git-workflow-and-versioning skill'inde trunk tabanlı geliştirme ve atomik commit'ler.

ci-cd-and-automation skill'inde Shift Left ve özellik bayrakları. Sorunları mümkün olduğunca erken yakalayın, dağıtımı sürümden ayırın.

deprecation-and-migration skill'inde yükümlülük olarak kod. Tuttuğunuz her satır sonsuza kadar bakım yapmanız gereken bir satırdır.

Bu fikirlerin hiçbiri yeni değil. Mesele, hiçbirinin ajanda varsayılan olarak olmamasıdır. Bir frontier model, eğitim verisinde "Hyrum Yasası" ifadesini okumuştur, ancak sabah 3'te API'nizi tasarlarken Hyrum Yasasını uygulamaz.

Nasıl Gerçekten Kullanılır?

Üç mod, kabaca artan taahhütle.

Mod 1: marketplace üzerinden yükleyin. Claude Code kullanıyorsanız:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

Slash komutlarını alırsınız (/spec, /plan, /build, /test, /review, /ship, /code-simplify) ve ajan, bağlama göre ilgili skill'leri otomatik olarak etkinleştirir. Çoğu insanın başlamasını önereceğim yol budur.

Mod 2: markdown'ı seçtiğiniz araca bırakın. Skill'ler frontmatter'lı düz markdown'dır. Cursor kullanıcıları bunları .cursor/rules/ içine koyar. Gemini CLI'nin kendi yükleme yolu vardır. Codex, Aider, Windsurf, OpenCode, sistem prompt kabul eden her şey bunları okuyabilir.

Mod 3: bunları spesifikasyon olarak okuyun. Hiçbir şey yüklemeseniz bile, skill'ler yapay zeka ajanlarıyla iyi mühendisliğin neye benzediğinin belgelenmiş bir tanımıdır.

Aslında üçüncü moddan başlardım. Mevcut acınıza en yakın dört veya beş skill seçin. Hangi iş akışlarının uygulanmasını istediğinize karar verin. Sonra çalışma zamanını yükleyin veya kendi zorlamanızı yazın.

Hiç Yüklemeseniz Bile Çalmanız Gerekenler

Yapay zeka kodlama ajanlarını hiç kullanmasanız bile çalacağım birkaç desen.

Bir ekip pratiği olarak anti-rasyonalizasyon. Ekibinizin kendine söylediği yalanları yazın. "Lansmandan sonra testleri düzeltiriz." "Bu değişiklik tasarım dokümanı için çok küçük." "Sorun yok, monitoring'imiz var." Her birini karşı argümanla eşleştirin.

Dahili olarak yazdığınız her şey için düzyazı yerine süreç. "X'e nasıl yaklaşıyoruz" başlıklı 2.000 kelimelik bir doküman yazıyorsanız, referans materyali yazmışsınızdır. Bunu kontrol noktalı bir iş akışına dönüştürün.

Sert çıkış kriteri olarak doğrulama. Her görevin çıkış adımı olarak "kanıt üret"i yapın. Ajanlar için, mühendisler için, kendiniz için. Kanıt, işin yapıldığını kanıtlayan her şeydir: yeşil bir test çalıştırması, bir ekran görüntüsü, bir log, bir inceleme onayı.

Herhangi bir kural kitabı için aşamalı açıklama. 50 sayfalık bir el kitabı yazmayın. Duruma göre doğru küçük bölüme işaret eden küçük bir router yazın.

Meta-skill'den alınan ve yarın herhangi bir AGENTS.md'ye koyacağım beş tartışılmaz kural:

1. İnşa etmeden önce varsayımları yüzeye çıkar. Sessizce tutulan yanlış varsayımlar en yaygın başarısızlık modudur.
2. Gereksinimler çatıştığında dur ve sor. Tahmin etme.
3. Gerektiğinde geri it. Ajan (veya mühendis) bir evet makinesi değildir.
4. Sıkıcı, bariz çözümü tercih et. Akıllılık pahalıdır.
5. Yalnızca dokunman istenene dokun.

Bunun Harness'taki Yeri

Daha geniş resimde, skill'ler ajan harness mühendisliğinin bir katmanıdır. Harness, model artı etrafında inşa ettiğiniz her şeydir; skill'ler, sistem prompt'una aşamalı olarak açıklanan yeniden kullanılabilir iş akışı parçalarıdır. AGENTS.md (rolling kural kitabı), hooks (deterministik zorlama katmanı), tools (ajanın yapabileceği eylemler) ve oturum logu (dayanıklı bellek) yanında otururlar.

Skill'ler, sohbet tarzı ajanlardan ziyade uzun süreli ajanlar için daha önemlidir, çünkü uzun süreler her kısa yolu büyütür. 10 dakikalık bir oturumda testi atlayan bir ajan bir hata üretir. 30 saatlik bir oturumda testi atlayan bir ajan, çalışmanın sonunda kimsenin orijinal niyeti hatırlamadığı bir hata ayıklama arkeolojisi projesi üretir.

Sonuç

Bu projeden insanların skill'lerin kendisinden çok almak istediğim şey çerçevelemedir.

Yapay zeka kodlama ajanları, diff'te görünmeyen iş kısımları için içgüdüsü olmayan son derece yetenekli junior mühendislerdir. Kıdemli mühendislik işi (varsayımları yüzeye çıkarmak, değişiklikleri boyutlandırmak, spesifikasyonu yazmak, kanıt bırakmak, incelenemeyen şeyi birleştirmeyi reddetmek) tam olarak bir ajanın atlamasını imkansız hale getirmediğiniz sürece atlayacağı şeydir.

Skills bunun bir şeklidir. Anti-rasyonalizasyon tabloları. Aşamalı açıklama. Düzyazı yerine süreç. Yük taşıyan çıkış kriteri olarak doğrulama. Zaten işe yarayan Google uygulamaları, taşınabilir hale getirilmiş.

Benim versiyonumu yükleyebilirsiniz. Kendinizinkini yapabilirsiniz. Ders her iki şekilde de geçerlidir: işin kıdemli mühendis kısımları artık opsiyonel değil, mühendis bir model olduğunda bile.