Cara Menjaga AGENTS.md Tetap Mutakhir dengan dox

Mengapa AGENTS.md Anda salah tiga minggu kemudian

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

Agent membacanya dan menganggap isinya benar. Di situlah masalahnya. Repositori tanpa AGENTS.md membuat coding agent memeriksa kondisi terlebih dahulu sebelum bertindak. Repositori dengan AGENTS.md yang salah membuatnya berhenti memeriksa karena jawabannya sudah tersedia. Agent menjalankan command yang disebutkan file tersebut, shell menjawab Missing script: "test", lalu agent mulai menebak. Sering kali agent mengedit package.json untuk menambahkan script yang dijanjikan oleh dokumentasi Anda. File yang usang tersebut tidak gagal secara diam-diam. File itu menyebabkan perubahan yang tidak Anda inginkan.

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

Apa itu dox dan apa yang bukan

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

Hal ini penting karena istilah generator mengisyaratkan adanya program yang mengurai kode Anda. Tidak ada yang mengurai kode Anda. dox adalah kontrak yang dibaca oleh coding agent Anda: agent tersebut adalah generator, sedangkan dox adalah kumpulan instruksi yang memberi tahu agent kapan harus membaca dokumentasi, kapan harus menulis ulang dokumentasi, dan bagaimana bentuk setiap dokumen.

File ini memiliki sepuluh bagian, dan dua di antaranya menjalankan fungsi utama. "Baca Sebelum Mengedit" memberi tahu agent untuk menelusuri dari root repository ke setiap path yang akan disentuhnya, serta membaca setiap AGENTS.md di sepanjang rute tersebut, dalam sesi saat ini, tanpa mengandalkan memori. "Perbarui Setelah Mengedit" memberi tahu agent bahwa setiap perubahan yang bermakna memerlukan pass DOX, yaitu langkah pembaruan dokumentasi yang harus dijalankan sebelum tugas dianggap selesai. Pass tersebut memperbarui dokumen pemilik terdekat ketika tujuan, struktur, alur kerja, izin, atau preferensi pengguna berubah.

Bagian lainnya menentukan struktur. AGENTS.md anak memiliki urutan bagian default: Tujuan, Kepemilikan, Kontrak Lokal, Panduan Kerja, Verifikasi, dan Indeks Child DOX. File root memuat aturan yang berlaku di seluruh proyek serta Indeks Child DOX tingkat teratas, yang digunakan agent untuk menemukan dokumen anak. "Penyelesaian" adalah checklist yang dijalankan agent di akhir tugas: memeriksa ulang path yang berubah terhadap rantai tersebut, memperbarui dokumen pemilik terdekat, menyegarkan setiap indeks yang terdampak, menghapus kontradiksi, menjalankan verifikasi yang sudah ada, dan melaporkan dokumen mana yang sengaja tidak diubah.

Pin dox ke satu commit, bukan ke main

Repositori ini tidak memiliki tag maupun rilis, sehingga tidak ada nomor versi yang dapat dipin. Pin commit-nya sebagai gantinya. AGENTS.md saat ini berada pada 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 seharusnya mencetak 3906. Angka lain berarti Anda belum mengambil file yang dijelaskan dalam panduan ini, jadi baca file tersebut sebelum mempercayainya. Jika hash commit salah diketik, -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 sama sekali, 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 sudah ada, pertahankan aturan Anda di bawahnya, lalu baca hasilnya sekali dari awal sampai akhir. Dua dokumen yang saling bertentangan membuat agent mengikuti baris yang dibacanya paling akhir.

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

Initialize DOX tree for this project now.

Perintah ini 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 keluaran find tersebut harus tercantum di suatu Child DOX Index di bagian sebelumnya. Dokumen turunan yang tidak disebutkan dalam 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

Agent yang membuat tree Anda membaca repository. Karena itu, semua hal di dalam repository dapat dimasukkan ke inventaris: tata letak direktori, manifest package dan lockfile, script dalam package.json atau Makefile atau pyproject.toml, file alur kerja CI, Dockerfile, entry point, serta CODEOWNERS jika Anda memilikinya. Inventaris yang dibuat dari sumber tersebut benar-benar dapat dipelihara secara otomatis. Jika sebuah package dipindahkan, proses berikutnya akan memindahkan baris yang mendeskripsikannya.

Semua hal berikut harus Anda nyatakan sendiri karena tidak terdapat di repository untuk dibaca:

• alasan sebuah aturan dibuat, yang mencegah agent menghapusnya sebagai kompleksitas yang tidak perlu
• jalur mana dari dua jalur yang berfungsi yang didukung, dan jalur mana yang menunggu untuk dihapus
• apa pun yang berada di luar repository, seperti environment staging atau alasan sebuah dependency dipatok dua versi lebih lama
• rencana Anda untuk minggu depan, yang membedakan file yang masih aktual dari file yang berguna

dox mengetahui hal ini tentang dirinya sendiri. Aturannya menyatakan bahwa Work Guidance harus mencerminkan standar project saat ini atau instruksi pengguna. Jika belum ada standar atau instruksi, biarkan bagian tersebut kosong. Verification harus mencerminkan pemeriksaan yang sudah ada. Jadi, jika repository tidak memiliki test framework, bagian tersebut tetap kosong sampai test framework tersedia. File hasil generate yang mengarang sebuah standar lebih buruk daripada bagian kosong karena agent kemudian akan menegakkan standar yang dikarang tersebut.

Jangan masukkan maksud yang ditulis manual ke dalam inventaris yang dihasilkan

Inilah kegagalan yang membuat orang menyerah pada dokumentasi yang dihasilkan secara 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 dari empat puluh baris, yang sebagian besar hanya mengubah urutan nama file, dan tidak ada yang menyadarinya.

Gunakan dua mekanisme berikut.

Pertama, pindahkan maksud yang perlu dipertahankan ke file lain. Keputusan desain dan alasannya harus ditempatkan dalam DESIGN.md yang ditulis untuk agent, sedangkan catatan untuk manusia harus ditempatkan di lokasi pemisahan HUMAN.md dari AGENTS.md. Dengan demikian, AGENTS.md berisi inventaris dan kontrak lokal, yaitu bagian 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 bagian yang dikelola 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 secara jelas. Jalankan pemeriksaan berikut 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 mencetak apa pun dan keluar dengan kode 0 jika blok tersebut tidak berubah. Output apa pun berarti proses tersebut telah menulis ulang teks yang dikelola manusia, sehingga seseorang harus menyetujuinya atau mengembalikannya. Pemeriksaan ini tetap berlaku tanpa mengharuskan siapa pun mengingatnya.

Regenerasi pada pull request, bukan berdasarkan timer

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

Pemeriksaan blocking yang memberlakukan hal 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 repository Anda. Manfaatnya adalah pemeriksaan gagal pada branch, saat perbaikannya masih murah, dan gagal karena alasan yang dapat ditindaklanjuti oleh reviewer.

Jadwal adalah cadangan, bukan mekanisme utama. Job mingguan menangkap hal-hal yang tidak diketahui siapa pun pada 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 server kecil, server 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, dan tidak ada yang melihat error tersebut. Lengkapi perintah itu, lalu jalankan script secara manual satu kali sebelum menjadwalkannya. || exit 0 juga penting: git commit keluar dengan status non-zero menggunakan nothing to commit, working tree clean jika tree sudah mutakhir. Dalam set -e, kondisi tersebut akan dilaporkan sebagai kegagalan meskipun proses berjalan dengan baik.

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

Monorepo: banyak kontrak, satu indeks

Satu AGENTS.md di root dalam repositori dengan empat puluh paket 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 turunannya, sedangkan setiap batas permanen memiliki filenya sendiri. Cara menyusun struktur tersebut dan tool mana yang membaca file bertingkat dibahas dalam file AGENTS.md bertingkat untuk monorepo.

Perubahan yang dilakukan dox adalah mempersempit cakupan review. Pull request yang menyentuh packages/api seharusnya hanya menghasilkan diff dokumentasi di dalam packages/api:

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

Jika perintah tersebut mencantumkan enam file untuk perubahan pada satu paket, struktur tersebut salah. Batasnya mungkin terlalu luas, atau aturan yang seharusnya berada di root telah disalin ke setiap child. dox menyatakan perbaikannya secara langsung: aturan umum ditempatkan di dokumentasi parent, sedangkan detail konkret ditempatkan di dokumentasi child. Aturan yang diduplikasi menyebabkan satu proses rutin menulis ulang semuanya. Jika aturan yang sama memang berlaku di beberapa repositori terpisah, itu adalah masalah yang berbeda, dan berbagi skill agent di berbagai repositori merupakan tool yang lebih tepat untuk itu.

Tinjau diff seperti meninjau kode

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

• perintah yang kini disebutkan dalam file 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 menyerupai kredensial
• entri inventaris untuk sesuatu yang sudah tidak ada, yang dapat ls selesaikan dalam hitungan 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 chain ini adalah agent membaca bagian kecil yang relevan, bukan semuanya.

Saat terjadi masalah

Pass menghapus blok intent Anda. Pemeriksaan diff di atas menampilkan baris yang dihapus. Pulihkan file dari branch point dengan git restore --source=origin/main AGENTS.md, lalu jalankan kembali pass dengan instruksi yang lebih sempit dan menyebutkan section yang boleh diubah.

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

Agent sepenuhnya mengabaikan file. Periksa nama file yang sebenarnya dibaca tool Anda. Jika tool membaca file lain, arahkan tool ke konten yang sama dengan ln -s AGENTS.md CLAUDE.md dan commit symlink tersebut agar Anda memiliki satu sumber, bukan dua dokumen yang isinya dapat berbeda. Jika nama file sudah benar tetapi aturan tetap dilewati, jalankan diagnosis mengapa coding agent mengabaikan instruksi Anda sebelum menulis ulang dokumen.

Tree memiliki child yang tidak diindeks. Bandingkan output find . -name AGENTS.md dengan entri indeks pada dokumen induk. Child yang tidak disebutkan oleh indeks mana pun dapat dilewati begitu saja oleh agent.

Kapan generator berlebihan

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

dox layak digunakan ketika repository memiliki batasan yang tidak dapat diingat oleh satu orang: beberapa package dengan aturan yang berbeda, atau kontributor yang bergabung tanpa memahami latar belakangnya. Nilainya bukan pada teks yang dihasilkan. Nilainya adalah dokumentasi tersebut menjadi sesuatu yang dapat menyebabkan pull request gagal, dan itu satu-satunya alasan file apa pun dalam repository tetap mutakhir.

FAQ

Apakah saya perlu menginstal sesuatu untuk menggunakan dox?

Tidak. dox adalah satu file Markdown berlisensi MIT, dan per 11 August 2026 repositori tersebut tidak menyediakan package atau releases. Anda menyalin isinya ke AGENTS.md milik proyek, lalu coding agent Anda mengikuti aturan tersebut. Tetapkan commit yang Anda salin, f34ec7ad1055d3393887e5a2670e8cb7320c9165 pada saat penulisan, dan cantumkan namanya dalam pesan commit agar nantinya Anda dapat mengetahui versi aturan yang menjadi dasar tree tersebut.

Bagaimana cara mencegah regenerasi menghapus aturan yang saya tulis sendiri?

Pisahkan intent dari inventory. Simpan penalaran yang perlu dipertahankan dalam dokumen terpisah, dan simpan apa pun yang harus tetap berada di dalam AGENTS.md dalam blok bertanda. Selanjutnya, periksa blok tersebut dalam CI: ekstrak blok dari branch dan dari origin/main menggunakan sed, bandingkan keduanya dengan 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 regenerasi AGENTS.md?

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

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

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

Apakah dox sepadan untuk repositori kecil?

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