Cara Automatik Kemas Kini Fail AGENTS.md Dengan dox

Mengapa fail 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, secara manual, pada hari repositori berada dalam keadaan tertentu. Kemudian, pelari ujian berubah, pakej dinamakan semula, servis dipadamkan, namun fail tersebut masih menerangkan 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 itu tidak gagal secara senyap. Ia menyebabkan penyuntingan yang tidak anda inginkan.

dox adalah salah satu jawapan kepada 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 itu dox, dan apakah ia bukan

dox ialah satu fail Markdown tunggal. Repositori tersebut 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 itu penting, kerana penjana perkataan 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 penjana, 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 path yang ia rancang untuk disentuh, dan membaca setiap AGENTS.md di sepanjang setiap laluan, dalam sesi semasa, tanpa bergantung pada memori. "Update After Editing" memberitahunya bahawa setiap perubahan yang bermakna memerlukan pas DOX, bermaksud langkah kemas kini dokumentasi yang dijalankan sebelum sesuatu tugasan dianggap selesai. Pas tersebut 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 memegang peraturan seluruh projek serta Indeks DOX Anak peringkat atas, yang merupakan cara ejen menemui dokumen anak. "Closeout" ialah senarai semak yang dijalankan oleh ejen pada akhir tugasan: semak semula path yang diubah terhadap rantaian, kemas kini dokumen pemilik terdekat, segarkan setiap indeks yang terjejas, padam percanggahan, jalankan pengesahan sedia ada, dan laporkan dokumen mana yang sengaja dibiarkan tanpa perubahan.

Kunci dox pada satu commit, bukan pada main

Repositori ini tidak mempunyai tag atau release, jadi tiada nombor versi untuk dikunci. Kunci pada commit 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 menyebabkan curl berhenti dengan curl: (22) The requested URL returned error: 404 dan tidak menulis sebarang kandungan, dan wc -c kemudian 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 memilikinya, jangan tulis ganti fail tersebut. Letakkan bahagian dox di atas kandungan sedia ada anda, kekalkan peraturan anda sendiri di bawah, dan baca hasilnya sekali dari atas ke bawah. Dua dokumen yang bercanggah antara satu sama lain akan menghasilkan ejen yang mengikut baris yang dibacanya paling akhir.

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 dox boleh lihat, dan apa yang ia tidak tahu

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 mempunyainya. Inventori yang dibina daripada perkara tersebut benar-benar bersifat menyelenggara diri. Apabila sesuatu pakej dialihkan, proses 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, yang merupakan perbezaan antara fail yang terkini dan fail yang berguna

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

Kekalkan niat penulisan manual di luar inventori yang dijana

Ini adalah kegagalan yang menyebabkan pengguna 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 fail berlaku dan perenggan anda hilang, tersembunyi di dalam diff sepanjang 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 boleh 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 berkuat kuasa tanpa perlu diingati oleh sesiapa pun.

Jana semula pada pull request, bukan mengikut pemasa

Detik terbaik untuk menyegarkan dokumen ialah pada commit yang menyebabkannya menjadi tidak tepat. Letakkan 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 akan 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 apa yang tidak disedari oleh sesiapa pada cawangan: fail yang dialihkan oleh rebase, pakej yang dipadam dalam merge, atau dokumen yang menamakan direktori yang tidak lagi wujud. Jalankannya pada pelayan kecil, pelayan yang sama yang mungkin anda gunakan untuk menjalankan ejen pengekodan pada VPS, dan minta ia membuka pull request dan bukannya menolak (push) terus 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 penanda tempat. Setiap ejen mempunyai CLI (antara muka baris perintah) dan flag bukan interaktifnya sendiri. Perintah yang disalin dari laman web yang tidak sepadan dengan versi anda akan gagal di dalam cron di mana tiada sesiapa yang melihat ralat tersebut. Isikan bahagian tersebut 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 pelaksanaan yang sihat sebagai kegagalan.

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

Monorepo: banyak kontrak, satu indeks

Satu fail AGENTS.md akar dalam repositori yang mempunyai empat puluh pakej akan menghasilkan perbezaan (diff) penjanaan semula yang tidak dibaca oleh sesiapa, serta dokumen yang kebanyakannya tidak relevan dengan apa yang sedang dilakukan oleh ejen tersebut. Jawapan dox ialah Indeks DOX Anak (Child DOX Index): akar menyimpan peraturan seluruh repositori dan menunjuk kepada anak-anaknya, manakala 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 perbezaan 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 sempadan tersebut 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 adalah 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 rasa curiga seperti anda menyemak kod yang dijana, dan perhatikan empat perkara berikut.

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

Kemudian, semak saiznya dengan wc -l AGENTS.md. Fail root yang melebihi dua ratus baris adalah isyarat untuk memecahkannya, kerana nilai keseluruhan rantaian tersebut terletak pada ejen yang 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 dengan git restore --source=origin/main AGENTS.md, kemudian jalankan semula pass tersebut dengan arahan yang lebih khusus yang menamakan bahagian yang boleh diubah suainya.

Dua cawangan kedua-duanya dijana semula. Anda 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 yang telah digabungkan.

Ejen mengabaikan fail tersebut 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 antara satu sama lain.

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

Apabila penjana (generator) tidak diperlukan

Satu pakej, satu arahan ujian, dua orang yang memahami repositori tersebut: tulis dua puluh baris kod secara manual. Fail AGENTS.md sepanjang dua puluh baris tidak akan menjadi usang dengan cepat sehingga memerlukan struktur tree, indeks, semakan CI dan tugasan mingguan. Baca semula fail tersebut apabila anda menukar binaan (build). Itu sahaja kos penyelenggaraannya, dan ia lebih kecil berbanding kos untuk menguruskan sistem automatik di sekelilingnya.

dox berbaloi digunakan apabila repositori mempunyai sempadan yang tidak mampu diingati oleh seorang individu: beberapa pakej dengan peraturan berbeza, atau penyumbang yang datang tanpa latar belakang projek. Nilainya bukan 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 hanyalah satu fail Markdown, dilesenkan di bawah MIT, dan setakat 11 Ogos 2026 repositori tersebut tidak menghantar sebarang pakej atau releases. Anda hanya perlu menyalin kandungannya ke dalam 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 mengetahui versi peraturan yang digunakan semasa binaan tree anda pada masa hadapan.

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

Asingkan niat (intent) dan inventori. Penaakulan yang kekal (durable reasoning) harus 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 (fail the build) jika terdapat sebarang perbezaan. Seseorang kemudiannya perlu meluluskan atau membatalkan perubahan tersebut, bukannya membiarkan ia terlepas pandang di dalam diff yang besar.

Berapa kerapkah saya perlu menjana semula AGENTS.md?

Pada pull request yang menyebabkan ia menjadi tidak tepat. Perubahan struktur dan dokumentasinya perlu berada dalam satu diff yang sama, kerana itu adalah satu-satunya masa 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 rutin akan menulis semula 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 kekurangan latar belakang, kerana pada ketika itu rantaian dokumen tersebut melakukan kerja yang tidak dilakukan oleh mana-mana individu.