writing-for-agents

Files (1)

• SKILL.md

SKILL.md (first lines)

# Ajanlar İçin Yazma (writing-for-agents)

Ajanın tükettiği bir belge yazmanın referansı: bir skill, bir `AGENTS.md`/`CLAUDE.md`, pointer ile ulaşılan bir doküman. Paketleme değişir; yazma değişmez: aynı kaldıraçlar her birini öngörülebilir yapar — ajanın her çalıştırmada **aynı süreci** izlemesi, aynı çıktıyı üretmesi değil.

Skill yazıyorsan frontmatter, çağırma seçimi ve router skill'ler için `SKILL-MECHANICS.md`'yi oku.

## Bağlam pointer'ları

Bir **bağlam pointer'ı**, ajanın bağlamında tutulan ve bağlam dışındaki bir materyali adlandıran + ona ulaşma koşulunu kodlayan bir referanstır. Skill açıklaması biri, `AGENTS.md`'deki bir satır aynı nesnedir. Pointer'ın **ifadesi** değil, hedefi, ajanın materyale ne zaman ulaşacağına karar verir. Zayıf ifade edilmiş bir pointer'ın arkasındaki kritik bir hedef, varyans hatasıdır: önce ifadeyi keskinleştir, keskinleştirme başarısız olursa materyali inline et.

## İki yük

- **Bağlam yükü** — her zaman yüklü materyalin ajan penceresine maliyeti (her turda token/ilgi harcar)
- **Bilişsel yük** — insana maliyet: hangi belgeler var, hangisine ne zaman ulaşmalı. İnsan endekstir; minimuma indirilecek maliyet değil, insan kararının bedelidir

Yalnızca pointer ile ulaşılan materyal, pointer'ın kendi satırı bedeliyle bağlam yükünden kurtulur.

## Bilgi hiyerarşisi

Belge iki içerik türünden kurulur — **adımlar** (ajanın sıralı eylemleri) ve **referans** (talep üzerine danışılan tanımlar/kurallar). Çekirdek karar, her parçanın merdivende nereye oturduğudur:

1. **Dosya içi adım** — birincil katman: ajanın sırayla yaptığı
2. **Dosya içi referans** — talep üzerine danışılır
3. **Açıklanan referans** — ayrı dosyaya itilmiş, pointer ile ulaşılan

**Aşamalı açıklama (progressive disclosure):** her dalın ihtiyaç duyduğunu inline tut, yalnızca bazı dalların ulaştığını pointer arkasına it. Belge adımlar içeriyorsa, açıklanması gereken referans onları gömer ve onlara dikkat etmeyi yazı-turaya çevirir.

**Yayılma (sprawl):** her satır canlı ve benzersiz olsa bile çok uzun belge. Çare merdiven: referansı pointer arkasına açıkla, dal veya sıraya göre böl.

## Adımlar ve tamamlanma kriterleri

Her adım bir **tamamlanma kriterinde** biter — ajanın işin bittiğini söyleyen koşul:

- **Netlik** — ajan "bitti" ile "bitmedi"yi ayırt edebiliyor mu? Belirsiz sınır ("anlayışa ulaşıldı") **erken tamamlamayı** davet eder. Önce sınırı keskinleştir; hâlâ bulanık ve acele görüyorsan, sonraki adımları gizleyerek diziyi böl (yalnızca gerçek bağlam sınırında işe yarar)
- **Talep** — ne kadar gerektiriyor. "Her değiştirilen model hesaba katıldı" güçlü, "değişiklik listesi üret" zayıf. Talep, adıma bağlı olmayan **ayak işini** (legwork) sürükler

## Bölme

Bir belgeyi ikiye bölmek iki yükten birini harcar; yalnızca kesinti kazandırdığında böl:
- **Sıraya göre** — sonraki adımların önündeki adımı aceleye getirmeye teşvik ettiği yerde
- **Çağrıya göre** — skill'e özgü: `SKILL-MECHANICS.md`'ye bak

## Öncü kelimeler (leading words)

Modelin ön-eğitiminde zaten yaşayan kompakt bir kavram (`lesson`, `tracer bullet`) — belge çalışırken ajanın onunla düşündüğü token. Cümle olarak değil, token olarak tekrarlandığında dağıtık bir tanım biriktirir ve en az tokenla bir davranış bölgesini çapalar. Kendi kelimeni üretmek tanımla çalışır ama ön-çağrışım toplamaz — önce mevcut kelimeyi ara.

**Olumsuzlama** bu kaldıracın yanındaki başarısızlık modudur: yasakla yönlendirme, yasaklanan davranışı bağlama çekip onu *daha* erişilebilir kılar. Fil düşünme, fil her yerdedir. **Pozitifi** söyle — hedef davranışı belirt, yasaklananı hiç konuşma. Yasa, yalnızca pozitif ifade edilemeyen sert bir gardiyansa yerini hak eder; o zaman bile pozitif hedefle eşleştir.

## Budama

- Her anlam **tek doğruluk kaynağında**: davranışı değiştirmek tek yerden düzenleme
- **Ortam da kaynaktır** — `package.json` script'leri, config dosyaları, dizin düzeni. Onu tekrar eden belge bir **cache'tir**: maliyetini yalnızca arama pahalıysa hak eder. Ajanın bakarak bulamadığını cache'le: yazılmamış kural, seçimin gerekçesi, config'in itiraf etmediği tuzak
- Her satırı **ilgililik** için kontrol et. Budama disiplini olmadan kader **sedimenttir**: bayat katmanlar çöker
- **No-op'ları** avla: modelin varsayılan olarak zaten uyduğu talimat, söylemeye bedel yükler. Cümle başarısız olduğunda kelime kırpmak yerine cümleyi sil

From murataslan1/kamuyz-agent-starter, MIT.

More from murataslan1/kamuyz-agent-starter