SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor · Güncellendi 2026-10-23

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

Üç hafta sonra yanlış kalan AGENTS.md dosyasını dox ile repository üzerinden yeniden oluşturun. Değişiklikleri kod gibi inceleyerek agent'ın eski bilgilere güvenmesini önleyin.

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 şeklindedir, MIT lisanslıdır ve 13 Ekim 2026 itibarıyla tüm proje 3965 baytlık bir AGENTS.md, bir README, bir LICENSE ve iki görselden oluşmaktadır. Kurulacak bir paket veya çalışma zamanı (runtime) yoktur.

Bu önemlidir, çünkü "generator" (üreteç) kelimesi kodunuzu ayrıştıran bir programı çağrıştırır. Hiçbir şey kodunuzu ayrıştırmaz. dox, kodlama temsilcinizin (agent) okuduğu bir sözleşmedir: temsilciniz üreteçtir ve dox, ona belgeleri ne zaman okuyacağını, ne zaman yeniden yazacağını ve her belgenin hangi biçimi alacağını söyleyen talimat setidir.

Dosya dokuz bölümden oluşur ve bunlardan ikisi asıl işi yapar. "Düzenlemeden Önce Oku" (Read Before Editing), temsilciye depo kökünden dokunmayı planladığı her yola gitmesini ve mevcut oturumda, hafızaya güvenmeden, yol üzerindeki her AGENTS.md dosyasını okumasını söyler. "Düzenlemeden Sonra Güncelle" (Update After Editing), ona her anlamlı değişikliğin bir DOX geçişi gerektirdiğini, yani görevin tamamlanmış sayılmasından önce bir dokümantasyon güncelleme adımı çalıştırılması gerektiğini bildirir. Bu geçiş; amaç, yapı, iş akışı, izinler veya kullanıcı tercihleri değiştiğinde en yakın sahiplik belgesini günceller.

Geri kalanı biçimdir. Bir alt AGENTS.md dosyası varsayılan bir bölüm sırasına sahiptir: Amaç, Sahiplik, Yerel Sözleşmeler, İş Rehberi, Doğrulama ve Alt DOX Dizini. Kök dosya, proje genelindeki kuralları ve temsilcinin alt belgeleri nasıl keşfettiğini belirleyen üst düzey Alt DOX Dizini'ni barındırır. "Kapanış" (Closeout), temsilcinin bir görevin sonunda çalıştırdığı kontrol listesidir: değiştirilen yolları zincire göre tekrar kontrol et, en yakın sahiplik belgelerini güncelle, etkilenen her dizini yenile, çelişkileri sil, mevcut doğrulamayı çalıştır ve kasıtlı olarak dokunmadığı belgeleri raporla.

Dox'u main dalına değil, belirli bir commit'e sabitleyin

Depoda herhangi bir etiket veya sürüm (release) bulunmadığı için sabitlenecek bir sürüm numarası yoktur. Bunun yerine commit'i sabitleyin. Mevcut AGENTS.md dosyası, 1 Eylül 2026 tarihli 765ae4ac02cc884eefcd41a3d0f71941721adb89 commit'idir.

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

wc -c komutu 3965 çıktısını vermelidir. Farklı bir sayı, bu kılavuzda açıklanan dosyayı çekmediğiniz anlamına gelir; bu nedenle dosyaya güvenmeden önce kılavuzu okuyun. Commit hash değerini yanlış yazarsanız, -f parametresi curl işlemini curl: (22) The requested URL returned error: 404 hatasıyla durdurur ve hiçbir içerik yazmaz; ardından wc -c komutu 0 çıktısını verir. Eksik bir dosya, hiç dosya olmamasından daha kötüdür; çünkü ajan, bir sözleşmenin yarısını bilmeden takip eder.

Eğer daha önceki bir commit'i, yani 1 Ağustos 2026 tarihli f34ec7a commit'ini sabitlediyseniz, Child DOX Index kısmını kontrol edin. O sürümdeki bölüm, dox'un kendi deposunu tanımlar: hiçbir alt AGENTS.md dosyasına gerek olmadığını belirtir ve README.md, LICENSE ile iki görseli root sahipli dosyalar olarak listeler. Projenize kopyalanan bu dizin, yanlış depoyu tanımlar. 1 Eylül revizyonu, bu bölümü projenin henüz dizinlenmediğini belirten ve ajana devam etmeden önce depoyu tarayıp ağacı oluşturmasını söyleyen bir yer tutucu (placeholder) ile değiştirmiştir. Eski bölümü gerçek dizininizle veya yeni yer tutucu ile değiştirin.

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

Bu cp komutu, henüz AGENTS.md dosyası olmayan depolar içindir. Eğer halihazırda bir dosyanız varsa, üzerine yazmayın. Dox bölümlerini mevcut içeriğinizin üzerine ekleyin, kendi kurallarınızı altta tutun ve sonucu baştan sona bir kez okuyun. Birbiriyle çelişen iki belge, en son okuduğu satırı takip eden bir ajan oluşturur.

Ardından, depo içerisindeki ajandan ilk geçişi yapmasını isteyin. README dosyası tam olarak şu ifadeyi verir:

Initialize DOX tree for this project now.

Bu komut, alt AGENTS.md dosyalarını ve onları işaret eden dizinleri oluşturur. Yer tutucu dizin ajana başka hiçbir iş yapmadan önce bunu yapmasını söylese bile, açıkça istemek yine de faydalıdır: tüm ağacı, ilgisiz bir görevin yan etkisi olarak değil, incelenebilir tek bir commit halinde alırsınız. İnanmadan önce ne yaptığına bakın:

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

find çıktısındaki her dosya, üzerinde bir yerlerde bir Child DOX Index içerisinde görünmelidir. Hiçbir dizinde belirtilmeyen bir alt belge, ajanın gözünden kaçabilir; çünkü dizin, ajanın doğrudan üzerinde yürüdüğü yolun dışındaki belgeleri bulmasını sağlayan araçtır.

Dox neleri görebilir ve neleri bilemez

Ağacınızı oluşturan aracı, depoyu okur; bu nedenle depodaki her şey envantere dahil edilebilir: dizin yapısı, paket bildirimleri ve kilit dosyaları, package.json, Makefile veya pyproject.toml içindeki betikler, CI iş akışı dosyaları, Dockerfile'lar, giriş noktaları ve varsa CODEOWNERS. Bunlardan oluşturulan bir envanter, gerçekten kendi kendini idame ettirir. Bir paket taşındığında, bir sonraki geçişte onu tanımlayan satır da taşınır.

Aşağıdakilerin tümü sizin tarafınızdan belirtilmelidir, çünkü bunlar okunmak üzere depoda bulunmazlar:

  • Bir kuralın neden var olduğu; bu, bir aracının onu gereksiz karmaşıklık olarak görüp kaldırmasını engeller.
  • İki çalışma yolundan hangisinin desteklendiği ve hangisinin silinmeyi beklediği.
  • Hazırlık ortamı (staging) veya bir bağımlılığın neden iki sürüm geride sabitlendiği gibi depo dışındaki her şey.
  • Gelecek hafta ne yapmayı planladığınız; bu, güncel bir dosya ile yararlı bir dosya arasındaki farktır.

Dox, kendisi hakkında bunları bilir. Kendi kuralları, İş Rehberliği'nin projenin güncel standartlarını veya kullanıcının talimatlarını yansıtması gerektiğini ve henüz hiçbiri yoksa bu bölümü boş bırakmanız gerektiğini söyler. Doğrulama, mevcut bir denetimi yansıtmalıdır; bu nedenle depoda bir doğrulama çerçevesi yoksa, bir tane olana kadar o bölüm boş kalır. Bir standart uyduran oluşturulmuş bir dosya, boş bir bölümden daha kötüdür; çünkü aracı daha sonra bu uydurma standardı zorunlu kılacaktır.

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 gerekiyor mu?

Hayır. dox tek bir Markdown dosyasıdır, MIT lisanslıdır ve 13 Ekim 2026 itibarıyla depo herhangi bir paket veya sürüm yayınlamamaktadır. İçeriğini projenizin AGENTS.md dosyasına kopyalarsınız ve kodlama temsilciniz oradaki kuralları izler. Kopyaladığınız commit'i sabitleyin (yazıldığı sırada 765ae4ac02cc884eefcd41a3d0f71941721adb89 idi) ve commit mesajınızda belirtin; böylece ağacınızın hangi sürüm kurallarına göre oluşturulduğunu daha sonra anlayabilirsiniz.

Yeniden oluşturma işleminin el ile yazdığım kuralları silmesini nasıl engellerim?

Niyet ve envanteri ayrı tutun. Kalıcı mantık ayrı bir belgede yer almalı ve AGENTS.md içinde kalması gereken her şey işaretli bir blok içinde bulunmalıdır. Ardından bloğu CI sürecinde kontrol edin: bloğu daldan ve origin/main içinden sed ile çıkarın, ikisini diff ile karşılaştırın ve herhangi bir fark durumunda derlemeyi başarısız kılın. Büyük bir diff içinde fark edilmeden geçmesi yerine, bir kişi değişikliği onaylamalı veya geri almalıdır.

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

Hatalı olduğu anlaşılan pull request üzerinde. Yapısal bir değişiklik ve onun dokümantasyonu tek bir diff içinde yer almalıdır, çünkü her ikisini de incelemek için gerekli bağlama sahip olunan tek an budur. Haftalık planlanmış bir geçiş, daldan kaçan sapmalar için bir yedekleme görevi görür ve main dalına commit atmak yerine bir pull request açmalıdır.

Derleme komutları kök dizindeki AGENTS.md dosyasında mı yoksa alt dizinde mi bulunmalı?

Onlara sahip olan en yakın belgede. Depo genelindeki kurallar ve alt dizin indeksi kökte yer alır. Tek bir pakete uygulanan komut, o paketin AGENTS.md dosyasında bulunur. Belgeler çeliştiğinde, dox daha yakın olan belgenin yerel çalışma detaylarını kontrol etmesine izin verir; hiçbir alt belgenin zayıflatamayacağı tek şey ise DOX sözleşmesinin kendisidir. Genel kurallar üst belgelerde, somut detaylar ise alt belgelerde yer alır. Aynı komutu her alt dizine kopyalamak, rutin bir geçişin tüm ağacı yeniden yazmasına neden olur.

dox küçük bir depo için buna değer mi?

Genellikle hayır. Tek bir test komutuna ve yirmi satırlık bir AGENTS.md dosyasına sahip bir paket yavaş bozulur ve fark ettiğiniz anda bir dakika içinde düzeltebilirsiniz. dox, depo farklı kurallara sahip birkaç sınıra sahip olduğunda veya katkıda bulunanların gerekli arka plana sahip olmadığı durumlarda maliyetini karşılar; çünkü o zaman belge zinciri, hiçbir bireyin tek başına yapmadığı bir işi yürütür.

Bu yazı işinize yaradı mı?