dox ile AGENTS.md dosyasını otomatik güncelleme

AGENTS.md dosyanız üç hafta sonra neden yanlış hale gelir

AGENTS.md dosyası kodla bağlantılı olmadığı için zamanla güncelliğini yitirir. Belirli bir günde, repository belirli bir durumdayken bu dosyayı elle bir kez yazarsınız. Ardından test runner değişir, bir paket yeniden adlandırılır, bir servis silinir ve dosya hâlâ Haziran ayındaki durumu anlatır. Hiçbir işlem başarısız olmaz; çünkü hiçbir build adımı bu dosyayı okumaz.

Agent dosyayı okur ve içeriğine güvenir. Size maliyeti olan kısım budur. AGENTS.md dosyası bulunmayan bir repository, coding agent'ın işlem yapmadan önce yapıyı incelemesine neden olur. Yanlış bir AGENTS.md dosyası bulunan repository ise agent'ın incelemeyi bırakmasına neden olur; çünkü yanıtı zaten aldığını düşünür. Dosyanızda belirtilen komutu çalıştırır, shell Missing script: "test" yanıtını verir ve agent tahmin yürütmeye başlar. Çoğu zaman, belgelerinizde vaat edilen script'i eklemek için package.json üzerinde değişiklik yapar. Güncelliğini yitirmiş dosya sessizce başarısız olmadı. İstemediğiniz bir değişikliğe neden oldu.

dox buna yönelik çözümlerden biridir. Agent için yazılmış bir kurallar bütünüdür. Dokümantasyonun güncellenmesini işi tamamlamanın bir parçası haline getirir. Böylece dosya, onu yanlış hale getiren kodla aynı commit içinde değişir.

dox nedir ve ne değildir

dox tek bir Markdown dosyasıdır. Depo agent0ai/dox, MIT lisanslıdır ve 11 Ağustos 2026 itibarıyla projenin tamamı 3906 baytlık bir AGENTS.md, bir README, bir LICENSE ve iki görselden oluşur. Kurulacak bir paket veya çalışma zamanı yoktur.

Bu önemlidir; çünkü generator sözcüğü kodunuzu ayrıştıran bir programı çağrıştırır. Kodunuzu ayrıştıran hiçbir şey yoktur. dox, kodlama aracınızın okuduğu bir sözleşmedir: generator aracınızdır, dox ise araca belgeleri ne zaman okuyacağını, ne zaman yeniden yazacağını ve her belgenin hangi biçimde olacağını bildiren yönerge kümesidir.

Dosyada on bölüm vardır ve işin büyük kısmını bunlardan ikisi yapar. "Düzenlemeden Önce Oku" bölümü, araca repository root konumundan düzenlemeyi planladığı her path'e kadar ilerlemesini ve her rota üzerindeki tüm AGENTS.md dosyalarını mevcut oturumda, belleğe güvenmeden okumasını söyler. "Düzenleme Sonrasında Güncelle" bölümü ise her anlamlı değişikliğin bir DOX pass gerektirdiğini belirtir; yani görevin tamamlanmış sayılmasından önce bir documentation update adımı çalıştırılmalıdır. Bu pass, amaç, yapı, iş akışı, izinler veya kullanıcı tercihleri değiştiğinde, değişiklikten sorumlu en yakın belgeyi günceller.

Geri kalan bölümler biçimi tanımlar. Bir alt AGENTS.md dosyasında varsayılan bölüm sırası şöyledir: Amaç, Sahiplik, Yerel Sözleşmeler, Çalışma Rehberi, Doğrulama ve Child DOX Index. Root dosyası proje genelindeki kuralları ve üst düzey Child DOX Index'i içerir; agent, alt belgeleri bu dizin üzerinden keşfeder. "Kapanış", agent'ın görevin sonunda uyguladığı kontrol listesidir: değiştirilen path'leri zincire göre yeniden kontrol etmek, değişiklikten sorumlu en yakın belgeleri güncellemek, etkilenen tüm dizinleri yenilemek, çelişkileri silmek, mevcut doğrulamayı çalıştırmak ve bilerek dokunmadığı belgeleri bildirmek.

Tek bir commit'e sabitleyin, main'e değil

Repository içinde tag ve release bulunmadığından sabitlenecek bir sürüm numarası yoktur. Bunun yerine commit sabitlenmelidir. Güncel AGENTS.md dosyası f34ec7ad1055d3393887e5a2670e8cb7320c9165 commit'idir ve tarihi 1 August 2026'dır.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c komutu 3906 çıktısını vermelidir. Farklı bir değer, bu kılavuzda açıklanan dosyanın alınmadığını gösterir; dosyaya güvenmeden önce dosyayı okuyun. Commit hash'i yanlış yazılırsa -f, curl işlemini curl: (22) The requested URL returned error: 404 ile durdurur ve içerik yazmaz; ardından wc -c komutu 0 çıktısını verir. Kısaltılmış bir dosya, hiç dosya olmamasından daha kötüdür; çünkü agent, sözleşmenin tamamını bilmeden yalnızca yarısını izler.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

Bu cp, henüz AGENTS.md içermeyen bir repository içindir. Zaten bir AGENTS.md dosyanız varsa dosyanın üzerine yazmayın. dox bölümlerini mevcut içeriğin üstüne ekleyin, kendi kurallarınızı alt bölümde tutun ve ortaya çıkan dosyayı baştan sona bir kez okuyun. Birbiriyle çelişen iki belge, agent'ın en son okuduğu satırı izlemesine neden olur.

Ardından repository içinde agent'tan ilk geçişi yapmasını isteyin. README dosyası tam ifadeyi verir:

Initialize DOX tree for this project now.

Bu işlem, child AGENTS.md dosyalarını ve bunlara işaret eden index dosyalarını oluşturur. Çıktıya güvenmeden önce yapılan değişiklikleri kontrol edin:

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

Bu find çıktısındaki her dosya, yukarıdaki bir Child DOX Index içinde yer almalıdır. Hiçbir index'in söz etmediği bir child belgesi agent tarafından atlanabilir; çünkü agent'ın doğrudan izlediği yol üzerinde bulunmayan belgeleri bulmasını sağlayan mekanizma index'tir.

dox neyi görebilir, neyi bilemez

Ağacınızı oluşturan agent repository'yi okur. Bu nedenle repository içindeki her şey envantere girebilir: dizin yapısı, package manifest'leri ve lockfile'lar, package.json, Makefile veya pyproject.toml içindeki script'ler, CI workflow dosyaları, Dockerfile'lar, entry point'ler ve varsa CODEOWNERS. Bunlardan oluşturulan bir envanter gerçekten kendi kendini güncel tutar. Bir package taşındığında sonraki taramada onu açıklayan satır da taşınır.

Aşağıdaki bilgileri sizin belirtmeniz gerekir. Çünkü bunlar repository içinde bulunmaz:

• bir kuralın neden var olduğu; bu bilgi, agent'ın kuralı gereksiz bir karmaşıklık olarak kaldırmasını engeller
• çalışan iki yoldan hangisinin desteklendiği ve hangisinin silinmeyi beklediği
• staging ortamı veya bir dependency'nin neden iki sürüm geriden sabitlendiği gibi repository dışındaki her şey
• gelecek hafta ne yapmayı planladığınız; güncel bir dosya ile yararlı bir dosya arasındaki fark budur

dox bunu kendisi için bilir. Kendi kuralları, Work Guidance bölümünün projenin güncel standartlarını veya kullanıcının talimatlarını yansıtması gerektiğini belirtir. Henüz bunlardan hiçbiri yoksa bölüm boş bırakılır. Verification bölümü mevcut bir kontrolü yansıtmalıdır. Bu nedenle repository'de test framework'ü yoksa ilgili bölüm, böyle bir framework eklenene kadar boş kalır. Bir standardı uyduran generated file, boş bir bölümden daha kötüdür. Çünkü agent daha sonra bu uydurulan standardı zorunlu kılar.

Oluşturulan envanterde elle yazılmış niyet metnini koruyun

Bu, oluşturulan belgelerden vazgeçilmesine yol açan hatadır. İş kuyruğunun tek tüketiciyle çalışması gerektiğini açıklayan bir paragraf yazılır. Üç hafta sonra bir işlem dosyayı yeniden oluşturur ve paragraf, çoğunlukla dosya adlarını yeniden sıralayan kırk satırlık bir diff'in içinde kaybolur. Kimse de bunu fark etmez.

İki mekanizma kullanılmalıdır ve ikisi de gereklidir.

İlk olarak kalıcı niyet metni farklı bir dosyaya taşınmalıdır. Tasarım kararları ve bunların gerekçeleri, ajan için yazılmış bir DESIGN.md dosyasına konulmalıdır. İnsanlar için hazırlanan notlar ise HUMAN.md dosyasına AGENTS.md dosyasından ayrılmalıdır. Böylece AGENTS.md yalnızca envanteri ve yerel sözleşmeleri içerir. Kod değiştiğinde değişmesi gereken bölüm de tam olarak budur.

İkinci olarak AGENTS.md içinde kalması gereken niyet metni bir koruma alanına alınmalıdır. Metin işaretlerle çevrelenmeli ve blokun insan tarafından yönetildiği kabul edilmelidir:

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Markdown yorumları sayfada görüntülenmez, ancak ajan bunları okumaya devam eder. Şimdi blokun korunup korunmadığını denetlenebilir hale getirilmelidir. Böylece bloğu silen bir işlem açıkça başarısız olur. Bu komut, her pull request için CI (continuous integration) kapsamında çalıştırılmalıdır:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

diff, blok değiştirilmediğinde hiçbir çıktı üretmez ve 0 durum koduyla çıkar. Herhangi bir çıktı, işlemin insan tarafından yönetilen metni yeniden yazdığı anlamına gelir. Bu durumda bir kişi değişikliği onaylamalı veya geri almalıdır. Böylece denetim, herhangi bir kişinin bunu hatırlamasını gerektirmeden çalışır.

Pull request üzerinde yeniden oluşturun, zamanlayıcıya bağlamayın

Bir belgeyi yenilemek için en uygun zaman, belgeyi geçersiz hale getiren commit'in oluşturulduğu andır. DOX çalıştırmasını yapısal değişiklikle aynı pull request içine ekleyin. Böylece diff, gerçekten incelenebilecek kadar küçük kalır.

Bunu zorunlu kılan engelleyici bir kontrol:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

Yolları repository'nize göre düzenleyin. Bu yaklaşımın değeri, kontrolün branch üzerinde başarısız olmasıdır. Düzeltme bu aşamada düşük maliyetlidir. Ayrıca başarısızlık nedeni, reviewer'ın işlem yapabileceği kadar açıktır.

Schedule yedek mekanizmadır; temel mekanizma değildir. Haftalık bir job, branch üzerinde kimsenin fark etmediği durumları yakalar: rebase ile taşınan dosyalar, merge sırasında silinen bir package veya artık bulunmayan bir directory'yi gösteren belge. Bu işi küçük bir box üzerinde çalıştırın. Bir coding agent'ı VPS üzerinde çalıştırmak için kullanabileceğiniz aynı box olabilir. Değişiklikleri main branch'e push etmek yerine bir pull request açmasını sağlayın.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

Bu yorum bilerek placeholder olarak bırakılmıştır. Her agent'ın kendine ait bir CLI'si (command line interface) ve non-interactive flag'i vardır. Web sayfasından kopyalanan ve kullandığınız sürümle eşleşmeyen bir command, hatayı kimsenin görmediği cron ortamında başarısız olur. Bu kısmı doldurun ve script'i schedule etmeden önce bir kez elle çalıştırın. || exit 0 de önemlidir: tree zaten güncelse git commit, nothing to commit, working tree clean ile non-zero çıkar. set -e altında bu durum başarılı bir çalışmanın başarısız olarak raporlanmasına neden olur.

Her çalıştırma token tüketir. Bunun nedeni, "Read Before Editing" yaklaşımının agent'a her görevde zincirin tamamını okutmasıdır. Bu bir ödünleşimdir. Zaten agent'ınızın çalıştırmalarının maliyetini hesaplıyorsanız bunu izlemeye değer.

Monorepo'lar: çok sayıda sözleşme, tek bir indeks

Kırk paket içeren bir repository'de tek bir kök AGENTS.md dosyası, kimsenin okumadığı bir yeniden oluşturma farkı ve agent'ın o anda yaptığı işle büyük ölçüde ilgisiz bir belge üretir. dox bu sorunu Child DOX Index ile çözer: kök dosya repository genelindeki kuralları içerir ve alt dosyaları gösterir; her kalıcı sınır da kendi dosyasını yönetir. Bu ağacın nasıl düzenleneceği ve iç içe dosyaları hangi araçların okuyabildiği monorepo'lar için iç içe AGENTS.md dosyaları bölümünde açıklanır.

dox, inceleme kapsamını değiştirir. packages/api dosyasına dokunan bir pull request yalnızca packages/api içinde bir dokümantasyon farkı oluşturmalıdır:

git diff --stat -- '*AGENTS.md'

Bu komut tek paketlik bir değişiklik için altı dosya listeliyorsa ağaç yanlıştır. Sınırlar fazla geniş olabilir veya köke ait bir kural her alt dosyaya kopyalanmış olabilir. dox düzeltmeyi doğrudan belirtir: genel kurallar üst düzey dokümanlara, somut ayrıntılar alt düzey dokümanlara konur. Rutin bir geçişte her şeyin yeniden yazılmasına neden olan şey, kuralların yinelenmesidir. Aynı kurallar gerçekten ayrı repository'ler genelinde geçerliyse bu farklı bir sorundur; bu durumda repository'ler arasında agent skill'lerini paylaşma daha uygun bir araçtır.

Farkı kod gibi inceleyin

Oluşturulan bir dokümantasyon farkı okunmadan kolayca onaylanabilir. Hatalı bir dosya bu şekilde yayımlanır. Farkı, oluşturulan kodu incelerken göstereceğiniz şüphecilikle okuyun ve dört noktayı kontrol edin.

• Dosyanın artık belirttiği ve birleştirmeden önce kendiniz çalıştırmanız gereken bir komut. Uydurma derleme talimatları en yaygın hatadır.
• Amacını taşıyan silinmiş bir satır. Eklemelerin maliyeti düşüktür. Kayıp, silinen satırlarda oluşur.
• Mutlak bir yol, bir ana makine adı, dahili bir URL veya kimlik bilgisine benzeyen herhangi bir içerik.
• Artık mevcut olmayan bir öğe için envanter girdisi; ls bunu saniyeler içinde çözümler.

Ardından boyutu wc -l AGENTS.md ile kontrol edin. İki yüz satırı aşan bir root dosyası, dosyanın bölünmesi gerektiğini gösterir. Çünkü bu zincirin temel değeri, aracının her şeyi okumak yerine küçük ve ilgili bölümü okumasıdır.

Sorun çıktığında

Geçiş, intent bloğunuzu sildi. Yukarıdaki diff kontrolü kaldırılan satırları gösterir. git restore --source=origin/main AGENTS.md ile dosyayı branch point durumundan geri yükleyin. Ardından geçişi, yalnızca dokunabileceği bölümleri belirten daha dar bir talimatla yeniden çalıştırın.

Her iki branch de dosyayı yeniden oluşturdu. Dosyada CONFLICT (content): Merge conflict in AGENTS.md ile conflict marker'ları <<<<<<< HEAD görürsünüz. Marker'ları elle düzenlemeyin. Dosya oluşturulduğu için doğru çözüm, merge edilmiş tree üzerinde yeni bir geçiş çalıştırmaktır.

Agent dosyayı tamamen yok sayıyor. Aracınızın gerçekte hangi filename'ı okuduğunu kontrol edin. Farklı bir dosya okuyorsa ln -s AGENTS.md CLAUDE.md ile aynı içeriğe yönlendirin ve symlink'i commit edin. Böylece zaman içinde farklılaşan iki belge yerine tek bir kaynak kullanılır. Filename zaten doğruysa ve kurallar yine de atlanıyorsa belgeyi yeniden yazmadan önce coding agent'ların talimatlarınızı neden yok saydığını belirlemek için teşhis çalıştırın.

Tree içinde kimsenin index'lemediği child'lar oluştu. find . -name AGENTS.md çıktısını, parent document'larda bulunan index entries ile karşılaştırın. Hiçbir index'te yer almayan bir child'ı agent doğrudan atlayabilir.

Bir generator gereksiz olduğunda

Tek bir paket, tek bir test komutu ve repository'yi bilen iki kişi varsa, yirmi satırı elle yazın. Yirmi satırlık bir AGENTS.md dosyası, bir ağaç yapısını, index'i, CI kontrolünü ve haftalık bir job'u haklı çıkaracak kadar hızlı eskimez. Build'i değiştirdiğinizde dosyayı yeniden okuyun. Tüm bakım maliyeti bundan ibarettir ve bu maliyet, etrafındaki mekanizmanın maliyetinden daha düşüktür.

Repository'de tek bir kişinin zihninde tutamayacağı sınırlar varsa dox kullanmak anlamlıdır: farklı kurallara sahip birden çok paket veya gerekli arka plan bilgisine sahip olmadan gelen katkıcılar. Değer, oluşturulan metinde değildir. Değer, dokümantasyonun bir pull request'in başarısız olmasına neden olabilecek bir unsura dönüşmesindedir. Repository'deki herhangi bir dosyanın güncel kalmasını sağlayan tek neden budur.

FAQ

dox kullanmak için herhangi bir şey yüklemem gerekir mi?

Hayır. dox, MIT lisanslı tek bir Markdown dosyasıdır ve 11 August 2026 itibarıyla repository herhangi bir package veya release içermez. İçeriği projenizin AGENTS.md dosyasına kopyalarsınız ve coding agent kuralları buradan uygular. Kopyaladığınız commit'i, yazım sırasında f34ec7ad1055d3393887e5a2670e8cb7320c9165 olan sürümü sabitleyin ve commit mesajında belirtin. Böylece daha sonra tree'nin hangi kurallar sürümü temel alınarak oluşturulduğunu belirleyebilirsiniz.

Elle yazdığım kuralların yeniden oluşturma sırasında silinmesini nasıl önlerim?

Amacı ve envanteri birbirinden ayrı tutun. Kalıcı gerekçeleri ayrı bir document içine yazın. AGENTS.md içinde mutlaka kalması gereken her şeyi işaretlenmiş bir block içine koyun. Ardından block'u CI içinde kontrol edin: branch'ten ve origin/main üzerinden sed ile çıkarın, ikisini diff ile karşılaştırın ve herhangi bir fark varsa build'i başarısız yapın. Böylece değişiklik, büyük bir diff içinde fark edilmeden geçmek yerine bir kişi tarafından onaylanır veya geri alınır.

AGENTS.md dosyasını ne sıklıkla yeniden oluşturmalıyım?

Onu yanlış hale getiren pull request içinde. Yapısal değişiklik ile buna ait documentation aynı diff içinde bulunmalıdır. Çünkü her ikisini incelemek için gerekli bağlam yalnızca o anda mevcuttur. Haftalık scheduled pass, bir branch'ten gözden kaçan drift için yedek kontroldür. Bu işlem main'e doğrudan commit göndermek yerine pull request açmalıdır.

Build komutları root AGENTS.md dosyasında mı, yoksa bir child dosyada mı bulunmalı?

Komutların sahibi olan en yakın document içinde bulunmalıdır. Repository genelindeki kurallar ve child index root dizinde yer alır. Yalnızca bir package için geçerli olan komut, o package içindeki AGENTS.md dosyasında bulunur. dox, çakışmaları distance üzerinden çözer: daha yakın document yerel ayrıntıları belirler ve hiçbir child parent kuralını zayıflatamaz. Aynı komutu her child içine kopyalamak, rutin bir pass'in tüm tree'yi yeniden yazmasına neden olur.

Küçük bir repository için dox kullanmaya değer mi?

Genellikle hayır. Tek test komutuna sahip tek bir package ve yirmi satırlık bir AGENTS.md dosyası yavaş şekilde güncelliğini kaybeder. Fark ettiğiniz anda bunu bir dakika içinde düzeltebilirsiniz. Repository'de farklı kurallara sahip birden fazla sınır olduğunda veya gerekli arka plana sahip olmayan contributor'lar bulunduğunda dox maliyetini karşılar. Çünkü bu durumda document chain, tek bir kişinin üstlenmediği bir işi yürütür.