dox: Perbarui AGENTS.md Otomatis

Mengapa AGENTS.md Anda sudah salah tiga minggu kemudian

File AGENTS.md menjadi usang karena tidak terhubung dengan kode. Anda menulisnya sekali secara manual, pada saat repository memiliki kondisi tertentu. Kemudian test runner berubah, sebuah package diganti namanya, sebuah service dihapus, tetapi file tersebut masih menjelaskan kondisi bulan Juni. Tidak ada yang gagal karena tidak ada langkah build yang membacanya.

Agent membaca file itu dan mempercayainya. Di situlah masalahnya. Repository tanpa AGENTS.md membuat coding agent memeriksa kondisi repository sebelum bertindak. Repository dengan AGENTS.md yang salah membuatnya berhenti memeriksa karena sudah memiliki jawaban. Agent menjalankan perintah yang tercantum dalam file tersebut, shell mengembalikan Missing script: "test", lalu agent mulai menebak. Sering kali agent mengedit package.json untuk menambahkan script yang dijanjikan dokumentasi Anda. File yang usang tidak gagal secara diam-diam. File tersebut menyebabkan perubahan yang tidak Anda inginkan.

dox adalah salah satu solusinya. dox merupakan sekumpulan aturan yang ditulis untuk agent. Aturan ini menjadikan pembaruan dokumentasi sebagai bagian dari penyelesaian pekerjaan. Dengan demikian, file berubah dalam commit yang sama dengan kode yang membuatnya menjadi salah.

Apa itu dox dan apa yang bukan

dox adalah satu file Markdown. Repositorinya adalah agent0ai/dox, berlisensi MIT, dan per 11 August 2026 seluruh proyek ini terdiri atas satu AGENTS.md berukuran 3906-byte, satu README, satu LICENSE, dan dua gambar. Tidak ada package yang perlu diinstal dan tidak ada runtime.

Hal ini penting karena istilah generator mengisyaratkan program yang mem-parsing kode Anda. Tidak ada yang mem-parsing kode Anda. dox adalah kontrak yang dibaca coding agent Anda: agent Anda adalah generatornya, sedangkan dox adalah set instruksi yang memberi tahu agent kapan harus membaca dokumentasi, kapan harus menulis ulang dokumentasi, dan seperti apa bentuk setiap dokumen.

File ini memiliki sepuluh bagian, dan dua di antaranya menjalankan fungsi utama. "Read Before Editing" memerintahkan agent untuk menelusuri dari root repositori hingga setiap path yang akan diubah, serta membaca setiap AGENTS.md di sepanjang setiap rute, dalam sesi saat ini, tanpa mengandalkan memori. "Update After Editing" memerintahkannya bahwa setiap perubahan yang bermakna memerlukan DOX pass, yaitu langkah pembaruan dokumentasi yang harus dijalankan sebelum tugas dianggap selesai. Pass ini memperbarui dokumen pemilik terdekat ketika tujuan, struktur, alur kerja, izin, atau preferensi pengguna berubah.

Bagian lainnya mengatur bentuk dokumen. AGENTS.md turunan memiliki urutan bagian default: Purpose, Ownership, Local Contracts, Work Guidance, Verification, dan Child DOX Index. File root berisi aturan yang berlaku di seluruh proyek serta Child DOX Index tingkat teratas. Index ini digunakan agent untuk menemukan dokumen turunan. "Closeout" adalah checklist yang dijalankan agent di akhir tugas: memeriksa ulang path yang diubah terhadap rantai tersebut, memperbarui dokumen pemilik terdekat, menyegarkan setiap index yang terdampak, menghapus kontradiksi, menjalankan verifikasi yang sudah ada, dan melaporkan dokumen yang sengaja tidak diubah.

Sematkan dox ke satu commit, bukan ke main

Repositori ini tidak memiliki tag atau rilis, sehingga tidak ada nomor versi yang dapat disematkan. Sematkan commit sebagai gantinya. AGENTS.md saat ini adalah commit f34ec7ad1055d3393887e5a2670e8cb7320c9165, bertanggal 1 August 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 harus mencetak 3906. Nomor yang berbeda berarti Anda tidak mengambil file yang dijelaskan dalam panduan ini, jadi baca file tersebut sebelum mempercayainya. Jika Anda salah mengetik hash commit, -f membuat curl berhenti dengan curl: (22) The requested URL returned error: 404 dan tidak menulis konten apa pun, lalu wc -c mencetak 0. File yang terpotong lebih buruk daripada tidak ada file, karena agent mengikuti sebagian kontrak tanpa menyadarinya.

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 ditujukan untuk repositori yang belum memiliki AGENTS.md. Jika Anda sudah memilikinya, jangan timpa file tersebut. Letakkan bagian dox di atas konten yang ada, pertahankan aturan Anda di bawahnya, lalu baca hasilnya sekali dari awal hingga akhir. Dua dokumen yang saling bertentangan membuat agent mengikuti baris yang terakhir dibacanya.

Selanjutnya, minta agent Anda melakukan tahap pertama dari dalam repositori. README berisi kata-kata yang tepat:

Initialize DOX tree for this project now.

Perintah tersebut membuat file AGENTS.md turunan dan indeks yang mengarah ke file-file tersebut. Periksa hasilnya sebelum mempercayainya:

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

Setiap file dalam output find tersebut harus muncul di suatu Child DOX Index di bagian atasnya. Dokumen turunan yang tidak disebutkan oleh indeks dapat terlewat oleh agent, karena indeks adalah cara agent menemukan dokumen yang tidak berada langsung pada path yang sedang ditelusurinya.

Hal yang dapat dilihat dox dan hal yang tidak dapat diketahuinya

Agen yang membuat pohon Anda membaca repositori. Karena itu, semua hal di dalam repositori dapat masuk ke inventaris: tata letak direktori, manifes paket dan lockfile, skrip di package.json atau Makefile atau pyproject.toml, file alur kerja CI, Dockerfile, entry point, dan CODEOWNERS jika Anda memilikinya. Inventaris yang dibuat dari sumber tersebut benar-benar dapat memelihara dirinya sendiri. Saat sebuah paket dipindahkan, proses berikutnya akan memindahkan baris yang menjelaskannya.

Semua hal berikut harus Anda nyatakan sendiri karena tidak tersedia di repositori untuk dibaca:

• alasan sebuah aturan dibuat, yang mencegah agen menghapusnya sebagai kompleksitas yang tidak diperlukan
• jalur mana dari dua jalur yang berfungsi yang didukung, dan jalur mana yang menunggu untuk dihapus
• segala hal di luar repositori, seperti lingkungan staging atau alasan dependensi dikunci dua versi lebih lama
• rencana Anda untuk minggu depan, yang membedakan file yang masih mutakhir dari file yang berguna

dox mengetahui hal ini tentang dirinya sendiri. Aturannya sendiri menyatakan bahwa Work Guidance harus mencerminkan standar proyek saat ini atau instruksi pengguna. Jika belum ada standar atau instruksi, biarkan bagian tersebut kosong. Verification harus mencerminkan pemeriksaan yang sudah ada. Karena itu, jika repositori tidak memiliki framework pengujian, bagian tersebut tetap kosong sampai framework tersedia. File yang dibuat secara otomatis dan mengarang suatu standar lebih buruk daripada bagian yang kosong, karena agen kemudian akan menegakkan standar tersebut.

Pertahankan maksud yang ditulis manual di luar inventaris yang dibuat otomatis

Inilah kegagalan yang membuat orang berhenti menggunakan dokumentasi yang dibuat otomatis. Anda menulis paragraf yang menjelaskan bahwa antrean job harus tetap menggunakan satu consumer. Tiga minggu kemudian, sebuah proses menulis ulang file tersebut dan paragraf Anda hilang di dalam diff yang terdiri atas 40 baris, yang sebagian besar hanya mengubah urutan nama file. Tidak ada yang menyadarinya.

Gunakan dua mekanisme berikut.

Pertama, pindahkan maksud yang perlu dipertahankan ke file lain. Keputusan desain dan alasannya harus ditulis di DESIGN.md yang ditujukan untuk agent, sedangkan catatan untuk manusia harus ditempatkan di HUMAN.md yang dipisahkan dari AGENTS.md. AGENTS.md kemudian berisi inventaris dan kontrak lokal. Bagian inilah yang memang harus berubah ketika kode berubah.

Kedua, lindungi maksud yang harus tetap berada di dalam AGENTS.md. Bungkus maksud tersebut dengan marker dan perlakukan blok itu 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 -->

Komentar Markdown tidak ditampilkan pada halaman, tetapi tetap dibaca oleh agent. Selanjutnya, buat keberadaan blok tersebut dapat diperiksa agar proses yang menghapusnya gagal dengan jelas. Jalankan pemeriksaan ini di 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 menampilkan apa pun dan keluar dengan kode 0 jika blok tidak berubah. Output apa pun berarti proses tersebut menulis ulang teks milik manusia. Dalam kondisi itu, seseorang harus menyetujuinya atau mengembalikannya. Pemeriksaan ini tetap berjalan tanpa bergantung pada ingatan siapa pun.

Regenerasi pada pull request, bukan berdasarkan timer

Waktu terbaik untuk memperbarui dokumen adalah saat commit yang membuatnya tidak lagi benar. Jalankan proses DOX dalam pull request yang sama dengan perubahan struktural agar diff tetap cukup kecil untuk benar-benar ditinjau.

Gunakan pemeriksaan pemblokir yang menegakkan aturan ini:

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

Sesuaikan path dengan repositori Anda. Nilainya terletak pada kegagalan di branch, saat perbaikannya masih mudah, dan pada pesan kegagalan yang dapat ditindaklanjuti oleh reviewer.

Schedule adalah cadangan, bukan mekanisme utama. Job mingguan menangkap masalah yang tidak diperhatikan siapa pun di branch: file yang dipindahkan oleh rebase, package yang dihapus dalam merge, atau dokumen yang merujuk ke direktori yang sudah tidak ada. Jalankan job ini pada mesin kecil, mesin yang sama yang mungkin Anda gunakan untuk menjalankan coding agent pada VPS, lalu minta job tersebut membuka pull request, bukan 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

Komentar tersebut sengaja menjadi placeholder. Setiap agent memiliki CLI (command line interface) dan flag non-interaktifnya sendiri. Perintah yang disalin dari halaman web tetapi tidak sesuai dengan versi Anda akan gagal di dalam cron, saat tidak ada orang yang melihat error tersebut. Lengkapi perintahnya, lalu jalankan script secara manual sekali sebelum menjadwalkannya. || exit 0 juga penting: git commit keluar dengan status non-zero menggunakan nothing to commit, working tree clean saat tree sudah mutakhir. Di bawah set -e, kondisi tersebut akan dilaporkan sebagai kegagalan meskipun proses berhasil.

Setiap proses menggunakan token karena prinsip "Read Before Editing" membuat agent membaca seluruh rangkaian pada setiap tugas. Itulah trade-off-nya, dan hal ini layak dipantau jika Anda sudah menghitung biaya setiap proses yang dijalankan agent Anda.

Monorepo: banyak kontrak, satu indeks

Satu AGENTS.md di root pada repositori dengan empat puluh package menghasilkan diff regenerasi yang tidak dibaca siapa pun serta dokumen yang sebagian besar tidak relevan dengan pekerjaan agent saat ini. Jawaban dox adalah Child DOX Index: root menyimpan aturan yang berlaku di seluruh repositori dan menunjuk ke child-nya, sedangkan setiap batas permanen memiliki file sendiri. Cara menyusun tree tersebut dan tool mana saja yang membaca file bertingkat dibahas dalam file AGENTS.md bertingkat untuk monorepo.

dox mengubah cakupan review. Pull request yang menyentuh packages/api seharusnya hanya menghasilkan diff dokumentasi di dalam packages/api:

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

Jika command tersebut menampilkan enam file untuk perubahan pada satu package, tree-nya salah. Batasnya mungkin terlalu luas, atau aturan yang seharusnya berada di root disalin ke setiap child. dox menyatakan perbaikannya secara langsung: aturan umum ditempatkan di dokumen parent, sedangkan detail konkret ditempatkan di dokumen child. Aturan yang diduplikasi menyebabkan proses rutin menulis ulang semuanya. Jika aturan yang sama memang berlaku di beberapa repositori terpisah, itu merupakan masalah yang berbeda, dan berbagi agent skills antar-repositori adalah tool yang lebih tepat.

Tinjau diff seperti kode

Diff dokumentasi yang dihasilkan mudah disetujui tanpa dibaca. Inilah cara file yang salah dapat dirilis. Bacalah dengan kecurigaan yang sama seperti saat meninjau kode yang dihasilkan, lalu cari empat hal berikut.

• perintah yang kini disebutkan oleh file tersebut dan harus Anda jalankan sendiri sebelum melakukan merge. Instruksi build yang dibuat-buat merupakan kegagalan yang paling umum.
• baris yang dihapus dan memuat maksud tertentu. Penambahan mudah dilakukan. Kehilangan biasanya terjadi pada penghapusan.
• path absolut, hostname, URL internal, atau apa pun yang bentuknya menyerupai kredensial
• entri inventaris untuk sesuatu yang sudah tidak ada, yang dapat ls selesaikan dalam satu detik

Kemudian periksa ukurannya dengan wc -l AGENTS.md. File root yang melebihi dua ratus baris merupakan tanda bahwa file tersebut perlu dipecah, karena seluruh manfaat rantai ini adalah agent membaca bagian kecil yang relevan, bukan semuanya.

Jika terjadi kerusakan

Proses tersebut menghapus blok intent Anda. Pemeriksaan diff di atas menampilkan baris yang dihapus. Pulihkan file dari titik percabangan dengan git restore --source=origin/main AGENTS.md, lalu jalankan ulang proses tersebut menggunakan instruksi yang lebih spesifik dan menyebutkan bagian yang boleh diubah.

Dua branch membuat ulang file yang sama. Anda akan mendapatkan CONFLICT (content): Merge conflict in AGENTS.md dan penanda konflik <<<<<<< HEAD di dalam file. Jangan mengedit penanda tersebut secara manual. File ini dibuat secara otomatis, jadi resolusi yang benar adalah menjalankan proses baru pada tree hasil merge.

Agent mengabaikan file sepenuhnya. Periksa nama file yang sebenarnya dibaca oleh tool Anda. Jika tool membaca file lain, arahkan tool tersebut ke konten yang sama dengan ln -s AGENTS.md CLAUDE.md, lalu commit symlink tersebut agar Anda hanya memiliki satu sumber, bukan dua dokumen yang isinya dapat berbeda.

Tree memiliki child yang tidak diindeks. Bandingkan output find . -name AGENTS.md dengan entri indeks dalam dokumen induk. Child yang tidak disebutkan dalam indeks dapat dilewati langsung oleh agent.

Saat generator tidak diperlukan

Satu package, satu perintah pengujian, dan dua orang yang sama-sama memahami repository: tulis 20 baris tersebut secara manual. AGENTS.md sepanjang 20 baris tidak cepat usang sehingga tidak perlu dibuatkan tree, index, pemeriksaan CI, dan job mingguan. Baca ulang file tersebut saat Anda mengubah proses build. Itulah seluruh biaya pemeliharaannya, dan biayanya lebih kecil daripada biaya untuk memelihara seluruh mekanisme pendukungnya.

dox layak digunakan jika repository memiliki batasan yang tidak dapat diingat sepenuhnya oleh satu orang: beberapa package dengan aturan berbeda, atau kontributor yang bergabung tanpa latar belakang yang diperlukan. Nilainya bukan pada teks yang dihasilkan. Nilainya terletak pada dokumentasi yang dapat menjadi sesuatu yang menyebabkan pull request gagal. Itulah satu-satunya alasan file apa pun dalam repository tetap diperbarui.

FAQ

Apakah saya perlu menginstal sesuatu untuk menggunakan dox?

Tidak. dox adalah satu file Markdown berlisensi MIT, dan per 11 Agustus 2026, repositori ini tidak menyediakan package maupun releases. Salin isinya ke dalam AGENTS.md proyek Anda, lalu coding agent Anda akan mengikuti aturan tersebut. Tetapkan commit yang Anda salin, f34ec7ad1055d3393887e5a2670e8cb7320c9165 pada saat penulisan, dan cantumkan commit tersebut dalam pesan commit agar nantinya Anda dapat mengetahui versi aturan yang digunakan untuk membangun tree tersebut.

Bagaimana cara mencegah regeneration menghapus aturan yang saya tulis sendiri?

Pisahkan intent dan inventory. Simpan penalaran yang perlu dipertahankan dalam dokumen terpisah, dan letakkan apa pun yang harus tetap berada di dalam AGENTS.md dalam blok bertanda. Kemudian periksa blok tersebut di CI: ekstrak blok dari branch dan dari origin/main dengan sed, bandingkan keduanya menggunakan diff, lalu gagalkan build jika terdapat perbedaan. Setelah itu, seseorang dapat menyetujui atau mengembalikan perubahan tersebut, bukan membiarkannya lolos tanpa disadari di dalam diff yang besar.

Seberapa sering saya harus melakukan regeneration AGENTS.md?

Lakukan pada pull request yang menyebabkan isinya menjadi tidak benar. Perubahan struktural dan dokumentasinya harus berada dalam satu diff, karena hanya pada saat itu seseorang memiliki konteks untuk meninjau keduanya. Pass terjadwal mingguan menjadi cadangan untuk drift yang lolos dari sebuah branch, dan pass tersebut harus membuka pull request, bukan melakukan commit ke main.

Apakah perintah build harus ditempatkan di AGENTS.md root atau di child?

Tempatkan di dokumen terdekat yang mengelolanya. Aturan seluruh repositori dan child index berada di root. Perintah yang berlaku untuk satu package ditempatkan di AGENTS.md package tersebut. dox menyelesaikan konflik berdasarkan jarak: dokumen yang lebih dekat mengendalikan detail lokal, dan child tidak boleh memperlemah aturan parent. Menyalin perintah yang sama ke setiap child akan menyebabkan pass rutin menulis ulang seluruh tree.

Apakah dox layak digunakan untuk repositori kecil?

Biasanya tidak. Satu package dengan satu perintah test dan AGENTS.md sepanjang dua puluh baris akan mengalami perubahan secara perlahan, dan Anda dapat memperbaikinya dalam satu menit setelah menyadarinya. dox sepadan dengan biayanya ketika repositori memiliki beberapa batas dengan aturan yang berbeda atau kontributor yang tidak memiliki latar belakang yang diperlukan, karena dalam kondisi tersebut rangkaian dokumen melakukan pekerjaan yang tidak dilakukan oleh satu orang pun.