AGENTS.md dosyasını otomatik güncel tutma rehberi

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

Bir AGENTS.md dosyası, kod ile arasında hiçbir bağ bulunmadığı için güncelliğini yitirir. Dosyayı, deponun belirli bir durumda olduğu gün elle bir kez oluşturursunuz. Ardından test çalıştırıcısı değişir, bir paket yeniden adlandırılır, bir servis silinir ancak dosya hala Haziran ayını anlatmaya devam eder. Hiçbir yapılandırma adımı dosyayı okumadığı için süreçte bir hata oluşmaz.

Ajan dosyayı okur ve ona inanır. Size asıl maliyeti olan kısım budur. AGENTS.md dosyası bulunmayan bir depo, kodlama yapan bir ajanın harekete geçmeden önce etrafı incelemesini sağlar. AGENTS.md dosyası hatalı olan bir depo ise ajanın inceleme yapmayı bırakmasına neden olur, çünkü elinde zaten bir cevap vardır. Ajan, dosyanızda belirttiğiniz komutu çalıştırır, kabuk Missing script: "test" yanıtını verir ve ajan tahmin yürütmeye başlar. Çoğu zaman, dokümantasyonunuzun vaat ettiği betiği eklemek için package.json dosyasını düzenler. Güncelliğini yitirmiş dosya sessizce başarısız olmaz. İstemediğiniz bir değişikliğe yol açar.

dox buna bir çözümdür. Ajan için yazılmış bir dizi kural bütünüdür; dokümantasyonun güncellenmesini işin tamamlanmasının bir parçası haline getirir. Böylece dosya, onu hatalı hale getiren kodla aynı commit içerisinde 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 11 Ağustos 2026 itibarıyla projenin tamamı 3906 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" (üretici) 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 üreticidir, dox ise ona belgeleri ne zaman okuyacağını, ne zaman yeniden yazacağını ve her belgenin hangi biçimi alacağını söyleyen talimat setidir.

Dosya on bölümden oluşur ve bunlardan ikisi işi yapar. "Düzenlemeden Önce Oku" (Read Before Editing), temsilciye depo kökünden dokunmayı planladığı her yola gitmesini ve her yol üzerindeki tüm AGENTS.md dosyalarını, hafızasına güvenmeden, mevcut oturumda okumasını söyler. "Düzenlemeden Sonra Güncelle" (Update After Editing), anlamlı her 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 belirtir. 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 en üst düzey Alt DOX Dizini'ni tutar. "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 tüm dizinleri yenile, çelişkileri sil, mevcut doğrulamayı çalıştır ve kasıtlı olarak dokunmadığı belgeleri raporla.

Dökümantasyonu main dalına değil, tek bir commit'e sabitleyin

Depoda herhangi bir etiket veya sürüm bulunmadığından, sabitlenecek bir sürüm numarası yoktur. Bunun yerine commit'i sabitleyin. Mevcut AGENTS.md dosyası, 1 Ağustos 2026 tarihli f34ec7ad1055d3393887e5a2670e8cb7320c9165 commit'idir.

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 sayı, bu kılavuzda açıklanan dosyayı çekmediğiniz anlamına gelir; bu nedenle güvenmeden önce kılavuzu okuyun. Commit hash değerini yanlış yazarsanız, -f komutu curl işlemini curl: (22) The requested URL returned error: 404 ile durdurur ve hiçbir 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ü ajan, bir sözleşmenin yarısını bilmeden takip eder.

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 komutu, henüz AGENTS.md dosyası bulunmayan depolar içindir. Eğer zaten bir dosyanız varsa, üzerine yazmayın. Dökümantasyon 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çerisinde ajandanıza 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. İ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 Alt DOX Dizini içinde 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üğü yolda bulunmayan belgeleri bulmasını sağlayan araçtır.

Dox neleri görebilir, 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 eğer varsa CODEOWNERS. Bunlardan oluşturulan bir envanter, gerçekten kendi kendini güncel tutar. Bir paket taşındığında, bir sonraki taramada 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; bir aracın onu gereksiz bir karmaşıklık olarak görüp kaldırmasını engelleyen şey budur.
• Çalışan iki yoldan hangisinin desteklendiği ve hangisinin silinmeyi beklediği.
• Hazırlık ortamı (staging environment) 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; güncel bir dosya ile faydalı bir dosya arasındaki fark budur.

dox, kendisi hakkında bunları bilir. Kendi kuralları, Çalışma Rehberi'nin (Work Guidance) projenin güncel standartlarını veya kullanıcının talimatlarını yansıtması gerektiğini, eğer henüz bunlar yoksa ilgili bölümün boş bırakılması gerektiğini söyler. Doğrulama (Verification), mevcut bir denetimi yansıtmalıdır; bu nedenle depoda bir test ç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.

Elle yazılmış amacı oluşturulan envanterin dışında tutun

Bu, insanların oluşturulan belgelere olan inancını yitirmesine neden olan başarısızlık türüdür. İş kuyruğunun tek bir tüketiciyle sınırlı kalması gerektiğini açıklayan bir paragraf yazarsınız. Üç hafta sonra bir işlem dosyayı yeniden yazar ve paragrafınız, çoğunlukla dosya adlarının yerini değiştiren kırk satırlık bir diff içinde kaybolur; kimse de bunu fark etmez.

İki mekanizma vardır ve her ikisine de ihtiyacınız olur.

İlk olarak, kalıcı amacı farklı bir dosyaya taşıyın. Tasarım kararları ve bunların arkasındaki mantık agent için yazılmış bir DESIGN.md dosyasında yer almalıdır; insanlar için tutulan notlar ise HUMAN.md dosyasını AGENTS.md dosyasından ayırdığınız yerde bulunmalıdır. AGENTS.md dosyası, envanteri ve yerel sözleşmeleri tutar; bu da kod değiştiğinde değişmesi gereken kısmın tam olarak kendisidir.

İkinci olarak, AGENTS.md içinde kalması gereken amacı korumaya alın. Bloğu işaretleyicilerle çevreleyin ve bu bloğu insan sahipliğinde kabul edin:

## 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 agent bunları okumaya devam eder. Şimdi bloğun varlığını denetlenebilir hale getirin; böylece onu silen bir işlem gürültülü bir şekilde başarısız olsun. Bunu her pull request üzerinde CI (sürekli entegrasyon) içinde çalıştırın:

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 hiçbir çıktı vermez ve blok dokunulmamışsa 0 koduyla çıkar. Herhangi bir çıktı, işlemin insan sahipliğindeki metni yeniden yazdığı anlamına gelir; bu durumda bir kişi onay vermeli veya değişikliği geri almalıdır. Denetim, kimsenin hatırlamasına gerek kalmadan geçerliliğini korur.

Zamanlayıcı yerine pull request üzerinde yeniden oluşturun

Bir dokümanı yenilemek için en uygun an, onu hatalı hale getiren commit anıdır. DOX işlemini yapısal değişikliğin yapıldığı aynı pull request içine dahil edin; böylece diff, gerçekten okunabilecek 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ı kendi deponuza göre ayarlayın. Bunun değeri, düzeltmenin maliyetinin düşük olduğu branch aşamasında hata vermesi ve bir gözden geçirenin üzerinde işlem yapabileceği bir gerekçe sunmasıdır.

Zamanlanmış görev bir mekanizma değil, yedekleme yöntemidir. Haftalık bir iş, branch üzerinde kimsenin fark etmediği durumları yakalar: rebase ile taşınan dosyalar, merge sırasında silinen bir paket veya artık var olmayan bir dizine atıfta bulunan bir doküman. Bu işi, VPS üzerinde kodlama ajanı çalıştırmak için kullanabileceğiniz küçük bir sunucuda çalıştırın ve main dalına push yapmak 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 kasıtlı olarak bir yer tutucudur. Her ajanın kendi CLI (komut satırı arayüzü) ve kendi etkileşimli olmayan (non-interactive) bayrağı vardır; bir web sayfasından kopyalanan ve sürümünüzle eşleşmeyen bir komut, kimsenin hatayı görmediği cron içinde başarısız olur. Zamanlamadan önce ilgili alanı doldurun ve betiği bir kez manuel olarak çalıştırın. || exit 0 de önemlidir: git commit, ağaç zaten güncel olduğunda nothing to commit, working tree clean ile sıfır olmayan bir çıkış kodu üretir ve set -e altında bu durum, sağlıklı bir çalışmayı hata olarak raporlar.

Her işlem token maliyeti oluşturur, çünkü "Düzenlemeden Önce Oku" prensibi ajanın her görevde tüm zinciri okumasını gerektirir. Bu bir takastır ve eğer halihazırda ajanınızın çalışma maliyetini hesaplıyorsanız izlemeye değerdir.

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

Kırk pakete sahip bir depodaki tek bir kök AGENTS.md dosyası, kimsenin okumadığı bir yeniden oluşturma farkı ve ajanın o an yaptığı işle büyük ölçüde ilgisiz bir belge üretir. Dox'un buna cevabı Çocuk DOX Dizini'dir: kök dizin depo genelindeki kuralları tutar ve alt öğeleri işaret eder; her kalıcı sınır ise kendi dosyasına sahip olur. Bu ağacın nasıl yapılandırılacağı ve hangi araçların iç içe geçmiş dosyaları okuduğu, monorepo'lar için iç içe AGENTS.md dosyaları bölümünde ele alınmıştır.

Dox'un değiştirdiği şey inceleme yüzeyidir. packages/api dosyasını etkileyen bir pull request, yalnızca packages/api içinde bir dokümantasyon farkı üretmeli, başka hiçbir yerde üretmemelidir:

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

Eğer bu komut tek bir paket değişikliği için altı dosya listeliyorsa, ağaç yapısı yanlıştır. Ya sınırlar çok geniştir ya da kök dizinde olması gereken bir kural her alt öğeye kopyalanmıştır. Dox, çözümün ne olduğunu doğrudan belirtir: genel kurallar üst dokümanlarda, somut detaylar ise alt dokümanlarda yer almalıdır. Yinelenen kurallar, rutin bir geçişin her şeyi yeniden yazmasına neden olan şeydir. Eğer aynı kurallar gerçekten farklı depolar genelinde geçerliyse, bu farklı bir sorundur ve bunun için ajan becerilerini depolar arasında paylaşma daha uygun bir araçtır.

Diff dosyasını kod gibi inceleyin

Oluşturulan bir dokümantasyon diff'ini okumadan onaylamak kolaydır; hatalı bir dosyanın yayınlanmasına bu şekilde sebep olunur. Diff dosyasını, oluşturulmuş bir koda uygulayacağınız şüpheyle okuyun ve şu dört noktaya dikkat edin:

• Dosyanın belirttiği bir komut; bunu merge etmeden önce kendiniz çalıştırmalısınız. Uydurma derleme talimatları en yaygın başarısızlık sebebidir.
• Bir amacı taşıyan silinmiş bir satır. Eklemeler kolaydır. Kayıplar silinen satırlarda gerçekleşir.
• Mutlak bir yol, bir hostname, dahili bir URL veya kimlik bilgisine benzeyen herhangi bir veri.
• Artık var olmayan bir şey için tutulan envanter kaydı; bu durum ls ile saniyeler içinde çözülür.

Ardından wc -l AGENTS.md ile boyutu kontrol edin. İki yüz satırı aşan bir root dosyası, dosyanın bölünmesi gerektiğine dair bir işarettir; çünkü zincirin tüm değeri, ajanın her şeyi değil, yalnızca ilgili küçük kısmı okumasından gelir.

Hata durumunda

Geçiş işlemi niyet bloğunuzu sildi. Yukarıdaki diff denetimi, silinen satırları yazdırır. Dosyayı git restore --source=origin/main AGENTS.md ile dal noktasından geri yükleyin, ardından etkileyebileceği bölümleri belirten daha dar bir talimatla geçişi yeniden çalıştırın.

İki dal da yeniden oluşturuldu. Dosya içinde CONFLICT (content): Merge conflict in AGENTS.md ve çakışma işaretleyicileri olan <<<<<<< HEAD ile karşılaşırsınız. İşaretleyicileri manuel olarak düzenlemeyin. Dosya oluşturulmuş bir dosya olduğundan, doğru çözüm birleştirilmiş ağaç üzerinde yeni bir geçiş yapmaktır.

Aracı dosyayı tamamen yok sayıyor. Aracınızın gerçekte hangi dosya adını okuduğunu kontrol edin. Eğer farklı bir dosya okuyorsa, ln -s AGENTS.md CLAUDE.md ile aynı içeriğe yönlendirin ve sembolik bağı commit edin; böylece birbirinden uzaklaşan iki belge yerine tek bir kaynak tutmuş olursunuz.

Ağaç, kimsenin indekslemediği alt öğeler oluşturdu. find . -name AGENTS.md çıktısını üst belgelerdeki indeks girişleriyle karşılaştırın. Hiçbir indeksin bahsetmediği bir alt öğe, aracın doğrudan pas geçeceği bir öğedir.

Jeneratörün gereksiz olduğu durumlar

Tek bir paket, tek bir test komutu ve depoya hakim iki kişi varsa, yirmi satırlık dosyayı elle yazın. Yirmi satırlık bir AGENTS.md dosyası; bir ağaç yapısını, indeksi, CI kontrolünü ve haftalık işleri haklı çıkaracak kadar hızlı eskimez. Yapılandırmayı değiştirdiğinizde dosyayı tekrar okuyun. Tüm bakım maliyeti budur ve bu maliyet, çevresine kurulan mekanizmanın maliyetinden daha düşüktür.

dox, deponun kimsenin tek başına zihninde tutamayacağı sınırları olduğunda ödenmeye değerdir: farklı kurallara sahip birden fazla paket veya arka plan bilgisi 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üşmesidir; depodaki herhangi bir dosyanın güncel kalmasının tek yolu budur.

FAQ

dox kullanmak için herhangi bir şey kurmam gerekiyor mu?

Hayır. dox tek bir Markdown dosyasıdır, MIT lisanslıdır ve 11 Ağustos 2026 itibarıyla depo herhangi bir paket veya sürüm (release) yayınlamamaktadır. İçeriğini projenizin AGENTS.md dosyasına kopyalarsınız ve kodlama aracınız oradaki kuralları takip eder. Kopyaladığınız commit'i, yazıldığı tarihte f34ec7ad1055d3393887e5a2670e8cb7320c9165 olan sürümü sabitleyin ve commit mesajınızda belirtin; böylece ağacınızın hangi kural sürümüyle 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 tutulmalı ve AGENTS.md içinde kalması gereken her şey işaretli bir blok içine alınmalıdır. Ardından bu 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ö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?

Yanlış olduğu anlaşılan pull request üzerinde. Yapısal bir değişiklik ve onun dokümantasyonu aynı diff içinde yer almalıdır, çünkü her ikisini de gözden geçirmek için gereken bağlama sahip olunan tek an budur. Haftalık planlanmış bir çalışma, daldan kaçan sapmalar için bir yedekleme niteliğindedir 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 bulunmalıdır. Depo genelindeki kurallar ve alt dizin indeksi kök dizinde yer alır. Tek bir pakete uygulanan komut, o paketin AGENTS.md dosyasında bulunur. dox çakışmaları mesafeye göre çözer: daha yakın olan belge yerel ayrıntıları kontrol eder ve hiçbir alt belge, üst belgedeki bir kuralı zayıflatamaz. Aynı komutu her alt dizine kopyalamak, rutin bir işlemin 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 komutu ve yirmi satırlık bir AGENTS.md dosyası olan 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 geçmiş bilgisi eksik olduğunda maliyetini karşılar; çünkü bu durumda belge zinciri, hiçbir kişinin tek başına yapmadığı bir işi yapmaktadır.