Cara Automatik Kemas Kini Fail AGENTS.md Dengan Dox

Mengapa AGENTS.md anda menjadi tidak tepat selepas tiga minggu

Fail AGENTS.md menjadi lapuk kerana tiada kaitan antara fail tersebut dengan kod. Anda menulisnya sekali sahaja, secara manual, pada hari repositori berada dalam keadaan tertentu. Kemudian, pelari ujian berubah, pakej dinamakan semula, servis dipadamkan, namun fail tersebut masih menggambarkan keadaan bulan Jun. Tiada apa-apa yang gagal, kerana tiada langkah binaan (build step) yang membacanya.

Ejen membaca fail tersebut dan mempercayainya. Itulah bahagian yang merugikan anda. Repositori tanpa AGENTS.md memaksa ejen pengekodan untuk meninjau keadaan sekeliling sebelum bertindak. Repositori dengan AGENTS.md yang salah membuatkan ejen berhenti meninjau, kerana ia sudah mempunyai jawapan. Ia menjalankan arahan yang dinamakan dalam fail anda, shell menjawab Missing script: "test", dan kini ejen mula meneka. Sering kali, ia menyunting package.json untuk menambah skrip yang dijanjikan oleh dokumentasi anda. Fail yang lapuk tidak gagal secara senyap. Ia menyebabkan suntingan yang tidak anda inginkan.

dox adalah salah satu jawapan untuk masalah ini. Ia merupakan satu set peraturan, yang ditulis untuk ejen, yang menjadikan pengemaskinian dokumentasi sebagai sebahagian daripada penyelesaian kerja, supaya fail tersebut berubah dalam commit yang sama dengan kod yang menyebabkannya menjadi tidak tepat.

Apakah dox, dan apa yang bukan

dox ialah satu fail Markdown tunggal. Repositori ini adalah agent0ai/dox, ia dilesenkan di bawah MIT, dan setakat 11 Ogos 2026 keseluruhan projek ini hanyalah satu AGENTS.md bersaiz 3906-bait, satu README, satu LICENSE dan dua imej. Tiada pakej untuk dipasang dan tiada runtime.

Perkara ini penting, kerana perkataan generator membayangkan sebuah program yang menghurai kod anda. Tiada apa-apa yang menghurai kod anda. dox ialah kontrak yang dibaca oleh ejen pengekodan anda: ejen anda ialah generator, dan dox ialah set arahan yang memberitahunya bila perlu membaca dokumentasi, bila perlu menulisnya semula, dan apakah bentuk setiap dokumen.

Fail ini mempunyai sepuluh bahagian dan dua daripadanya melakukan kerja tersebut. "Read Before Editing" memberitahu ejen untuk berjalan dari root repositori ke setiap laluan yang dirancang untuk disentuh, dan membaca setiap AGENTS.md di sepanjang setiap laluan, dalam sesi semasa, tanpa bergantung pada memori. "Update After Editing" memberitahu ejen bahawa setiap perubahan yang bermakna memerlukan langkah DOX, bermaksud langkah kemas kini dokumentasi yang dijalankan sebelum tugasan dianggap selesai. Langkah ini mengemas kini dokumen pemilik terdekat apabila tujuan, struktur, aliran kerja, kebenaran atau pilihan pengguna berubah.

Selebihnya adalah bentuk. AGENTS.md anak mempunyai susunan bahagian lalai: Tujuan, Pemilikan, Kontrak Tempatan, Panduan Kerja, Pengesahan, dan Indeks DOX Anak. Fail root menyimpan peraturan seluruh projek serta Indeks DOX Anak peringkat tertinggi, yang merupakan cara ejen menemui dokumen anak. "Closeout" ialah senarai semak yang dijalankan oleh ejen pada akhir tugasan: semak semula laluan yang diubah terhadap rantaian, kemas kini dokumen pemilik terdekat, segarkan setiap indeks yang terjejas, padam percanggahan, jalankan pengesahan sedia ada, dan laporkan dokumen yang sengaja tidak diubahnya.

Sematkan dox pada satu commit, bukan pada main

Repositori ini tidak mempunyai tag atau release, jadi tiada nombor versi untuk disematkan. Sematkan commit tersebut sebaliknya. AGENTS.md semasa ialah commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, bertarikh 1 Ogos 2026.

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 sepatutnya mencetak 3906. Nombor yang berbeza bermakna anda tidak mengambil fail yang diterangkan oleh panduan ini, jadi bacalah ia sebelum anda mempercayainya. Jika anda tersalah taip hash commit, -f akan menyebabkan curl berhenti dengan curl: (22) The requested URL returned error: 404 dan tidak menulis sebarang kandungan, dan wc -c kemudiannya mencetak 0. Fail yang terpotong adalah lebih buruk daripada tiada fail, kerana ejen akan mengikuti separuh daripada kontrak tanpa menyedarinya.

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

cp itu adalah untuk repositori yang belum mempunyai AGENTS.md. Jika anda sudah mempunyainya, jangan tulis ganti fail tersebut. Letakkan bahagian dox di atas kandungan sedia ada anda, kekalkan peraturan anda sendiri di bawahnya, dan baca hasilnya sekali dari atas ke bawah. Dua dokumen yang bercanggah antara satu sama lain akan menghasilkan ejen yang mengikuti baris mana pun yang dibacanya terakhir.

Kemudian minta ejen anda, di dalam repositori, untuk langkah pertama. README memberikan perkataan yang tepat:

Initialize DOX tree for this project now.

Ia mencipta fail AGENTS.md anak dan indeks yang menghala kepadanya. Semak apa yang dilakukannya sebelum anda mempercayainya:

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

Setiap fail dalam output find itu sepatutnya muncul dalam Indeks DOX Anak di suatu tempat di atasnya. Dokumen anak yang tidak disebut oleh mana-mana indeks adalah dokumen yang boleh terlepas oleh ejen, kerana indeks adalah cara ia mencari dokumen yang tidak terletak terus pada laluan yang sedang dilaluinya.

Apa yang boleh dilihat oleh dox, dan apa yang tidak diketahuinya

Ejen yang membina pepohon anda membaca repositori tersebut, jadi apa-apa sahaja di dalam repositori boleh dimasukkan ke dalam inventori: susun atur direktori, manifes pakej dan fail kunci, skrip dalam package.json atau Makefile atau pyproject.toml, fail aliran kerja CI, Dockerfile, titik masuk, dan CODEOWNERS jika anda memilikinya. Inventori yang dibina daripada perkara tersebut benar-benar bersifat menyelenggara diri. Apabila sesuatu pakej dialihkan, hantaran seterusnya akan mengalihkan baris yang menerangkannya.

Segala perkara di bawah adalah untuk anda nyatakan, kerana ia tidak terdapat dalam repositori untuk dibaca:

• sebab sesuatu peraturan wujud, yang merupakan perkara yang menghalang ejen daripada membuangnya sebagai kerumitan yang tidak perlu
• antara dua laluan kerja, yang mana satu disokong dan yang mana satu sedang menunggu untuk dipadamkan
• apa-apa sahaja di luar repositori, seperti persekitaran staging atau sebab sesuatu dependensi ditetapkan pada dua versi sebelumnya
• apa yang anda rancang untuk lakukan pada minggu hadapan, iaitu perbezaan antara fail yang semasa dan fail yang berguna

dox mengetahui perkara ini tentang dirinya. Peraturannya sendiri menyatakan Panduan Kerja (Work Guidance) mesti mencerminkan piawaian semasa projek atau arahan pengguna, dan jika belum ada, anda perlu membiarkan bahagian tersebut kosong. Pengesahan (Verification) mesti mencerminkan semakan yang sedia ada, jadi tanpa rangka kerja ujian dalam repo, bahagian tersebut kekal kosong sehingga ada satu. Fail yang dijana yang mencipta piawaian adalah lebih buruk daripada bahagian yang kosong, kerana ejen tersebut kemudiannya akan menguatkuasakan ciptaan tersebut.

Kekalkan niat yang ditulis tangan di luar inventori yang dijana

Ini adalah kegagalan yang menyebabkan orang berputus asa dengan dokumentasi yang dijana. Anda menulis perenggan yang menjelaskan bahawa baris gilir (queue) kerja mesti kekal sebagai pengguna tunggal (single consumer). Tiga minggu kemudian, satu proses penulisan semula mengubah fail tersebut dan perenggan anda hilang, di dalam diff sebanyak empat puluh baris yang kebanyakannya hanya menyusun semula nama fail, dan tiada siapa yang menyedarinya.

Terdapat dua mekanisme, dan anda memerlukan kedua-duanya.

Pertama, pindahkan niat yang tahan lama ke dalam fail yang berbeza. Keputusan reka bentuk dan alasan di sebaliknya perlu diletakkan di dalam fail DESIGN.md yang ditulis untuk ejen, dan nota yang wujud untuk manusia perlu diletakkan di tempat anda mengasingkan HUMAN.md daripada AGENTS.md. AGENTS.md kemudiannya menyimpan inventori dan kontrak tempatan, yang merupakan bahagian yang sepatutnya berubah apabila kod berubah.

Kedua, pagarkan niat yang perlu kekal di dalam AGENTS.md. Balut ia dengan penanda dan anggap blok tersebut sebagai milik manusia:

## 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 -->

Komen Markdown tidak dipaparkan pada halaman, dan ejen masih membacanya. Sekarang, jadikan kelangsungan blok tersebut boleh diperiksa, supaya proses yang memadamnya akan gagal dengan ketara. Jalankan ini dalam CI (continuous integration) pada setiap pull request:

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 tidak mencetak apa-apa dan keluar dengan kod 0 apabila blok tersebut tidak disentuh. Sebarang output bermakna proses tersebut telah menulis semula teks milik manusia, jadi seseorang perlu meluluskannya atau membatalkannya. Pemeriksaan ini kekal tanpa perlu sesiapa pun mengingatinya.

Jana semula pada pull request, bukan mengikut pemasa

Detik terbaik untuk menyegarkan dokumen ialah pada commit yang menyebabkannya menjadi tidak tepat. Masukkan proses DOX dalam pull request yang sama dengan perubahan struktur supaya diff kekal cukup kecil untuk dibaca.

Semakan penyekat yang menguatkuasakannya:

#!/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

Laraskan laluan mengikut repositori anda. Nilainya ialah ia gagal pada cawangan (branch), di mana pembaikan adalah murah, dan ia gagal atas sebab yang boleh diambil tindakan oleh penyemak.

Jadual hanyalah sandaran, bukan mekanisme utama. Tugasan mingguan menangkap perkara yang tidak disedari sesiapa pada cawangan: fail yang dialihkan oleh rebase, pakej yang dipadamkan dalam merge, atau dokumen yang menamakan direktori yang tidak lagi wujud. Jalankan ia pada pelayan kecil, pelayan yang sama yang mungkin anda gunakan untuk menjalankan ejen pengekodan pada VPS, dan minta ia membuka pull request dan bukannya melakukan push ke main.

#!/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

Komen itu sengaja diletakkan sebagai pemegang tempat. Setiap ejen mempunyai CLI (antara muka baris perintah) dan flag bukan interaktifnya sendiri, dan arahan yang disalin dari halaman web yang tidak sepadan dengan versi anda akan gagal di dalam cron di mana tiada sesiapa yang melihat ralat tersebut. Isikan bahagian itu dan jalankan skrip secara manual sekali sebelum anda menjadualkannya. || exit 0 juga penting: git commit keluar dengan status bukan sifar dengan nothing to commit, working tree clean apabila pepohon (tree) sudah terkini, dan di bawah set -e, itu akan melaporkan larian yang sihat sebagai kegagalan.

Setiap proses menggunakan token, kerana "Baca Sebelum Menyunting" (Read Before Editing) memaksa ejen membaca keseluruhan rantaian pada setiap tugasan. Itulah pertukarannya, dan ia berbaloi untuk dipantau jika anda sudah mengira kos larian ejen anda.

Monorepo: banyak kontrak, satu indeks

Satu fail AGENTS.md akar dalam repositori yang mempunyai empat puluh pakej menghasilkan diff penjanaan semula yang tidak dibaca oleh sesiapa, dan dokumen yang kebanyakannya tidak relevan dengan apa jua yang sedang dilakukan oleh ejen tersebut. Jawapan dox ialah Indeks DOX Anak: akar menyimpan peraturan seluruh repo dan menghala ke anak-anaknya, dan setiap sempadan yang tahan lama memiliki failnya sendiri. Cara menyusun pepohon tersebut, dan alatan yang membaca fail bersarang, diliputi dalam fail AGENTS.md bersarang untuk monorepo.

Perkara yang diubah oleh dox ialah permukaan semakan. Permintaan tarik (pull request) yang menyentuh packages/api sepatutnya menghasilkan diff dokumentasi di dalam packages/api dan bukan di tempat lain:

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

Jika arahan tersebut menyenaraikan enam fail untuk perubahan satu pakej, pepohon tersebut adalah salah. Sama ada sempadannya terlalu kasar, atau peraturan yang sepatutnya berada di akar telah disalin ke dalam setiap anak. dox menyatakan pembaikan tersebut secara terus: peraturan umum diletakkan dalam dokumen induk, butiran konkrit diletakkan dalam dokumen anak. Peraturan yang diduplikasi adalah punca semakan rutin menulis semula segala-galanya. Jika peraturan yang sama benar-benar terpakai merentasi repositori yang berasingan, itu adalah masalah yang berbeza, dan berkongsi kemahiran ejen merentasi repositori ialah alat yang lebih baik untuknya.

Semak diff seperti kod

Diff dokumentasi yang dijana mudah diluluskan tanpa dibaca, dan inilah punca fail yang salah dihantar. Baca diff tersebut dengan penuh syak wasangka seperti anda menyemak kod yang dijana, dan perhatikan empat perkara ini.

• arahan yang kini dinamakan dalam fail, yang perlu anda jalankan sendiri sebelum melakukan merge. Arahan binaan yang direka-reka adalah kegagalan yang paling kerap berlaku.
• baris yang dipadam yang membawa maksud tertentu. Penambahan adalah mudah. Pemadaman adalah tempat di mana kehilangan maklumat berlaku.
• laluan mutlak (absolute path), nama hos, URL dalaman, atau apa-apa yang menyerupai kelayakan (credential).
• entri inventori untuk sesuatu yang tidak lagi wujud, yang mana ls akan selesaikan dalam sekelip mata.

Kemudian, semak saiznya dengan wc -l AGENTS.md. Fail root yang melebihi dua ratus baris adalah isyarat untuk memecahkannya, kerana nilai keseluruhan rantaian tersebut adalah ejen membaca bahagian kecil yang relevan dan bukannya membaca keseluruhan fail.

Apabila berlaku kerosakan

Pass tersebut memadamkan blok intent anda. Semakan diff di atas mencetak baris yang telah dibuang. Pulihkan fail daripada titik cawangan (branch point) dengan git restore --source=origin/main AGENTS.md, kemudian jalankan semula pass tersebut dengan arahan yang lebih khusus yang menamakan bahagian yang boleh diubah suai.

Dua cawangan dijana semula serentak. Anda akan mendapat CONFLICT (content): Merge conflict in AGENTS.md dan penanda konflik <<<<<<< HEAD di dalam fail tersebut. Jangan sunting penanda tersebut secara manual. Fail ini dijana secara automatik, jadi penyelesaian yang betul ialah menjalankan pass baharu ke atas pepohon (tree) yang telah digabungkan.

Ejen mengabaikan fail sepenuhnya. Semak nama fail yang sebenarnya dibaca oleh alat anda. Jika ia membaca fail yang berbeza, halakan ia kepada kandungan yang sama dengan ln -s AGENTS.md CLAUDE.md dan lakukan commit pada symlink tersebut, supaya anda mengekalkan satu sumber dan bukannya dua dokumen yang berbeza. Jika nama fail sudah betul tetapi peraturan masih diabaikan, jalankan diagnosis untuk mengapa ejen pengekodan mengabaikan arahan anda sebelum anda menulis semula dokumen tersebut.

Pepohon mempunyai anak yang tidak diindeks. Bandingkan output find . -name AGENTS.md dengan entri indeks dalam dokumen induk. Anak yang tidak disebut dalam mana-mana indeks adalah anak yang akan diabaikan sepenuhnya oleh ejen.

Apabila penjana menjadi keterlaluan

Satu pakej, satu arahan ujian, dua orang yang kedua-duanya mengenali repositori tersebut: tulis dua puluh baris kod itu secara manual. Fail AGENTS.md sepanjang dua puluh baris tidak akan menjadi usang dengan cukup pantas untuk mewajarkan penggunaan tree, index, pemeriksaan CI, dan tugasan mingguan. Baca semula fail tersebut apabila anda menukar binaan (build). Itu sahaja kos penyelenggaraannya, dan ia lebih kecil daripada kos infrastruktur yang mengelilinginya.

dox berbaloi digunakan apabila repositori mempunyai sempadan yang tidak mampu diingati oleh seseorang secara sendirian: beberapa pakej dengan peraturan berbeza, atau penyumbang yang datang tanpa latar belakang projek. Nilainya bukan terletak pada teks yang dijana. Nilainya adalah dokumentasi tersebut menjadi sesuatu yang boleh menyebabkan pull request gagal, yang merupakan satu-satunya sebab mana-mana fail dalam repositori kekal terkini.

FAQ

Adakah saya perlu memasang apa-apa untuk menggunakan dox?

Tidak. dox ialah satu fail Markdown, dilesenkan di bawah MIT, dan setakat 11 Ogos 2026 repositori tersebut tidak mengeluarkan sebarang pakej atau releases. Anda hanya perlu menyalin kandungannya ke dalam fail AGENTS.md projek anda dan ejen pengekodan anda akan mengikuti peraturan tersebut. Pin commit yang anda salin, f34ec7ad1055d3393887e5a2670e8cb7320c9165 pada masa penulisan ini, dan namakannya dalam mesej commit anda supaya anda boleh mengenal pasti versi peraturan yang digunakan semasa binaan tree anda dibuat.

Bagaimanakah cara untuk menghalang penjanaan semula daripada memadam peraturan yang saya tulis sendiri?

Asingkan niat (intent) dan inventori. Penaakulan yang tahan lama (durable reasoning) perlu diletakkan dalam dokumen berasingan, dan apa-apa yang mesti kekal di dalam AGENTS.md perlu diletakkan di dalam blok bertanda. Kemudian, semak blok tersebut dalam CI: ekstrak ia daripada branch dan daripada origin/main menggunakan sed, bandingkan kedua-duanya dengan diff, dan gagalkan binaan (build) jika terdapat sebarang perbezaan. Seseorang kemudiannya perlu meluluskan atau membatalkan perubahan tersebut, bukannya membiarkannya terlepas pandang di dalam diff yang besar.

Berapa kerapkah saya perlu menjana semula AGENTS.md?

Pada pull request yang menyebabkannya menjadi tidak tepat. Perubahan struktur dan dokumentasinya perlu berada dalam satu diff yang sama, kerana itu adalah satu-satunya saat seseorang mempunyai konteks untuk menyemak kedua-duanya. Pas mingguan yang dijadualkan adalah sandaran untuk perubahan (drift) yang terlepas daripada branch, dan ia sepatutnya membuka pull request dan bukannya melakukan commit terus ke main.

Patutkah arahan binaan (build commands) diletakkan di dalam AGENTS.md root atau di dalam child?

Di dalam dokumen terdekat yang memilikinya. Peraturan seluruh repositori dan indeks child berada di root. Arahan yang terpakai untuk satu pakej diletakkan di dalam AGENTS.md pakej tersebut. dox menyelesaikan konflik mengikut jarak: dokumen yang lebih dekat mengawal perincian tempatan, dan tiada child yang boleh melemahkan peraturan parent. Menyalin arahan yang sama ke dalam setiap child adalah punca mengapa proses penulisan semula rutin akan mengubah keseluruhan tree.

Adakah dox berbaloi untuk repositori kecil?

Biasanya tidak. Satu pakej dengan satu arahan ujian dan AGENTS.md sepanjang dua puluh baris akan merosot dengan perlahan, dan anda boleh membaikinya dalam masa seminit selepas anda menyedarinya. dox memberikan nilai apabila repositori mempunyai beberapa sempadan dengan peraturan yang berbeza, atau penyumbang yang tidak mempunyai latar belakang yang mencukupi, kerana pada ketika itu rantaian dokumen tersebut melakukan kerja yang tidak dilakukan oleh mana-mana individu.