Pelajari Claude Code untuk drift dokumentasi agar README, dokumentasi API, dan runbook selaras dengan kode—dengan menghasilkan diff dan menandai kontradiksi.
Drift dokumentasi adalah pemisahan perlahan antara apa yang dikatakan dokumen Anda dan apa yang sebenarnya dilakukan kode. Itu dimulai sebagai ketidaksesuaian kecil, lalu berubah menjadi kebingungan "kami yakin ini bekerja bulan lalu".
Dalam tim nyata, drift terlihat seperti ini: README mengatakan Anda bisa menjalankan layanan dengan satu perintah, tetapi sekarang diperlukan variabel lingkungan baru. Dokumentasi API menampilkan endpoint dengan field yang diganti namanya. Runbook memberi tahu on-call untuk me-restart "worker-a", tetapi proses sekarang terbagi menjadi dua layanan.
Drift terjadi bahkan dengan niat baik karena perangkat lunak berubah lebih cepat daripada kebiasaan menulis dokumentasi. Orang mengirim perbaikan dengan tekanan, menyalin contoh lama, atau menganggap orang lain akan memperbarui dokumen nanti. Drift juga tumbuh ketika Anda memiliki terlalu banyak tempat yang terlihat seperti "sumber kebenaran": file README, referensi API, halaman wiki internal, tiket, dan pengetahuan tribal.
Biayanya nyata:
Mempercantik tulisan tidak memperbaiki drift jika faktanya salah. Yang membantu adalah memperlakukan dokumen seperti sesuatu yang bisa Anda verifikasi: bandingkan dengan kode saat ini, konfigurasi, dan keluaran nyata, lalu tunjukkan kontradiksi ketika dokumen menjanjikan perilaku yang tidak lagi dimiliki kode.
Drift biasanya muncul dalam dokumen yang orang anggap sebagai "referensi cepat". Mereka diperbarui sekali, lalu kode terus bergerak. Mulailah dengan tiga ini karena mereka berisi janji konkret yang bisa Anda cek.
README drift ketika perintah sehari-hari berubah. Flag baru ditambahkan, yang lama dihapus, atau variabel lingkungan diganti nama, tetapi bagian setup masih menunjukkan kenyataan lama. Rekan baru menyalin-tempel instruksi, menemui error, dan menganggap proyek rusak.
Versi terburuk adalah "hampir benar". Satu variabel lingkungan yang hilang bisa membuang lebih banyak waktu daripada README yang benar-benar usang, karena orang terus mencoba variasi kecil alih-alih mempertanyakan dokumen.
API docs drift ketika field request atau response berubah. Bahkan pergeseran kecil (kunci berganti nama, default berbeda, header wajib baru) dapat merusak klien. Seringkali daftar endpoint benar sementara contohnya salah, dan itulah yang orang salin.
Sinyal khas:
Runbook drift ketika langkah deployment, rollback, atau operasional berubah. Satu perintah usang, nama layanan yang salah, atau prasyarat yang hilang bisa mengubah perbaikan rutin menjadi downtime.
Mereka juga bisa "akurat tapi tidak lengkap": langkah masih bekerja, tetapi melewatkan migrasi baru, pembersihan cache, atau toggle feature flag. Saat itu penanggap mengikuti runbook dengan sempurna dan tetap terkejut.
Claude Code untuk drift dokumentasi bekerja paling baik ketika Anda memperlakukan dokumen seperti kode: usulkan patch kecil yang bisa ditinjau dan jelaskan alasannya. Alih-alih memintanya "memperbarui README", minta agar menghasilkan diff terhadap file-file tertentu. Reviewer mendapat before/after yang jelas dan bisa melihat perubahan yang tidak disengaja dengan cepat.
Pemeriksaan drift yang baik menghasilkan dua hal:
Saat memberi prompt, minta bukti dari repo: jalur file dan detail seperti route, nilai konfigurasi, atau tes yang menunjukkan perilaku saat ini.
Berikut pola prompt yang menjaga semuanya terlandas:
Check these docs for drift: README.md, docs/api.md, runbooks/deploy.md.
Compare them to the current repo.
Output:
1) Contradictions list (doc claim -> repo evidence with file path and line range)
2) Unified diffs for the smallest safe edits
Rules: do not rewrite sections that are still accurate.
Jika Claude mengatakan "the API uses /v2", minta ia mendukungnya dengan menunjuk ke router, OpenAPI spec, atau tes integrasi. Jika tidak menemukan bukti, harus mengatakan demikian.
Drift biasanya dimulai dari satu perubahan kode yang diam-diam memengaruhi banyak dokumen. Biarkan Claude dulu menentukan cakupan: apa yang berubah, di mana berubah, dokumen mana yang kemungkinan rusak, dan tindakan pengguna apa yang terpengaruh.
Contoh: Anda mengganti nama variabel lingkungan dari API_KEY menjadi SERVICE_TOKEN. Laporan yang berguna menemukan setiap tempat nama lama muncul (setup README, contoh API, bagian rahasia di runbook), lalu menghasilkan diff ketat yang hanya memperbarui baris itu dan perintah contoh yang sekarang akan gagal.
Jika Anda mengarahkan model ke "semua dokumen" tanpa aturan, seringkali Anda mendapat penulisan ulang yang masih berisi fakta yang salah. Alur kerja sederhana menjaga perubahan kecil, dapat diulang, dan mudah ditinjau.
Mulailah dengan satu set dokumen: README, referensi API, atau satu runbook yang benar-benar dipakai. Memperbaiki satu area dari ujung ke ujung mengajarkan sinyal apa yang bisa dipercaya sebelum memperluasnya.
Tulis dengan kata-kata sederhana, dari mana fakta harus diambil untuk set dokumen itu.
Setelah Anda menamai sumber-sumber itu, prompt jadi lebih tajam: "Bandingkan README dengan output CLI saat ini dan default konfigurasi, lalu buat patch."
Sepakati format keluaran sebelum siapa pun menjalankan pemeriksaan pertama. Mencampur format membuatnya lebih sulit melihat apa yang berubah dan mengapa.
Aturan sederhana:
Satu kebiasaan praktis: tambahkan catatan kecil ke setiap PR dokumen seperti "Sumber kebenaran dicek: routes + tests" sehingga reviewer tahu apa yang dibandingkan. Itu mengubah pembaruan dokumen dari "terlihat baik" menjadi "terverifikasi terhadap sesuatu yang nyata".
Anggap setiap perubahan kode sebagai investigasi dokumen kecil. Tujuannya menangkap kontradiksi lebih awal dan menghasilkan patch minimal yang bisa dipercaya reviewer.
Mulai dengan memilih file yang tepat untuk diperiksa dan pertanyaan drift yang jelas. Contoh: "Apakah kita mengubah variabel lingkungan, flag CLI, route HTTP, atau kode error yang masih disebutkan di dokumen?" Spesifik membuat model tidak menulis ulang seluruh bagian.
Selanjutnya, minta Claude Code mengekstrak fakta keras dari kode dulu. Mintalah agar ia hanya mencantumkan item konkret: perintah yang dijalankan pengguna, endpoint dan method, field request dan response, kunci konfigurasi, variabel lingkungan yang wajib, dan langkah operasional yang dirujuk oleh skrip atau konfigurasi. Jika sesuatu tidak ditemukan di kode, ia harus mengatakan "tidak ditemukan" daripada menebak.
Lalu minta tabel perbandingan sederhana: klaim dokumen, apa yang ditunjukkan kode, dan status (cocok, tidak cocok, hilang, tidak jelas). Itu menjaga diskusi tetap beralasan.
Setelah itu, minta unified diff dengan edit minimal. Suruh agar hanya mengubah baris yang diperlukan untuk menyelesaikan ketidaksesuaian, pertahankan gaya dokumen yang ada, dan hindari menambah janji yang tidak didukung oleh kode.
Akhiri dengan ringkasan singkat untuk reviewer: apa yang berubah, mengapa berubah, dan apa yang perlu diperiksa ulang (misalnya variabel lingkungan yang diganti nama atau header wajib baru).
API docs drift ketika kode berubah diam-diam: route diganti nama, field menjadi wajib, atau bentuk error berubah. Hasilnya adalah integrasi klien yang rusak dan waktu debug yang terbuang.
Dengan Claude Code untuk drift dokumentasi, tugasnya adalah membuktikan apa yang API lakukan dari repo, lalu menunjuk ketidaksesuaian di dokumen. Minta agar ia mengekstrak inventaris dari routing dan handler (path, method, model request dan response) dan membandingkannya dengan klaim di referensi API.
Fokus pada apa yang orang benar-benar salin-tempel: perintah curl, header, payload contoh, kode status, dan nama field. Dalam satu prompt, mintalah ia memeriksa:
Ketika menemukan ketidaksesuaian, terima hanya diff yang bisa menunjuk bukti dari kode (definisi route yang persis, perilaku handler, atau skema). Itu menjaga patch tetap kecil dan bisa ditinjau.
Contoh: kode sekarang mengembalikan 201 pada POST /widgets dan menambahkan field name yang wajib. Dokumentasi masih menunjukkan 200 dan menghilangkan name. Keluaran yang baik menunjuk kedua kontradiksi dan hanya memperbarui status code endpoint tersebut dan JSON contoh, membiarkan sisanya tetap.
Runbook gagal dengan cara yang paling mahal: terlihat lengkap, tetapi langkah tidak lagi cocok dengan apa yang dilakukan sistem hari ini. Perubahan kecil seperti variabel lingkungan yang diganti nama atau perintah deploy baru bisa membuat insiden melambat karena penanggap mengikuti instruksi yang tidak bisa bekerja.
Perlakukan runbook seperti kode: minta diff terhadap repo saat ini dan wajibkan penunjuk kontradiksi. Bandingkan dengan apa yang sistem gunakan sekarang: skrip, default konfigurasi, dan tooling Anda saat ini.
Fokus pada titik gagal yang menyebabkan banyak kekacauan saat insiden:
Tambahkan juga pemeriksaan cepat dan keluaran yang diharapkan supaya penanggap tahu apakah mereka berada di jalur yang benar. "Verifikasi berhasil" tidak cukup; sertakan sinyal tepat yang diharapkan (baris status, string versi, atau respons health check).
Jika Anda membangun dan mendeploy aplikasi pada platform seperti Koder.ai, ini menjadi lebih penting karena snapshot dan rollback hanya berguna ketika runbook menyebutkan tindakan yang benar dan mencerminkan jalur pemulihan saat ini.
Cara tercepat membuat drift dokumentasi adalah memperlakukan dokumen sebagai "prosa yang bagus" alih-alih sekumpulan klaim yang harus sesuai dengan kode.
Kesalahan umum adalah meminta penulisan ulang terlebih dahulu. Saat Anda melewatkan pemeriksaan kontradiksi, Anda bisa mendapatkan redaksi yang lebih halus yang masih menjelaskan perilaku yang salah. Selalu mulai dengan menanyakan klaim dokumen, apa yang kode lakukan, dan di mana mereka berbeda.
Kesalahan lain adalah membiarkan model menebak. Jika perilaku tidak terlihat dalam kode, tes, atau konfigurasi, anggap itu tidak diketahui. "Mungkin" adalah cara janji README tercipta dan runbook berubah jadi fiksi.
Masalah-masalah ini sering muncul dalam pembaruan sehari-hari:
Sebuah handler berubah dari mengembalikan 401 menjadi 403 untuk token kadaluarsa, dan nama header beralih dari X-Token ke Authorization. Jika Anda hanya menulis ulang bagian otorisasi, Anda mungkin melewatkan bahwa contoh API masih menunjukkan header lama, dan runbook masih memberitahu on-call mencari lonjakan 401.
Saat Anda menghasilkan diff, tambahkan satu baris keputusan singkat seperti: "Gagal auth sekarang mengembalikan 403 untuk membedakan kredensial tidak valid vs hilang." Itu mencegah orang berikutnya "memperbaiki" dokumen kembali ke perilaku lama.
Anggap setiap pembaruan dokumen sebagai audit kecil. Tujuannya lebih sedikit kejutan ketika seseorang mengikuti instruksi minggu depan.
Sebelum klik merge, scan README, API docs, dan runbook untuk klaim konkret dan verifikasi satu per satu:
Jika Anda menemukan dua atau lebih klaim tidak diketahui dalam dokumen yang sama, hentikan merge. Tambahkan bukti (jalur file dan nama fungsi) atau potong dokumen kembali ke yang pasti.
Tim kecil memperbarui otorisasi: alih-alih mengirim API key sebagai X-API-Key, klien sekarang mengirim token jangka pendek sebagai Authorization: Bearer <token>. Kode dikirim, tes lulus, dan tim bergerak.
Dua hari kemudian, pengembang baru mengikuti README. README masih mengatakan "set X-API-Key di environment Anda" dan menunjukkan contoh curl dengan header lama. Mereka tidak bisa menjalankan lokal dan mengira layanan mati.
Sementara itu, API docs juga usang. Mereka menjelaskan header lama dan masih menunjukkan field respons bernama user_id, padahal API sekarang mengembalikan userId. Tidak ada yang salah dengan tulisannya, tetapi itu bertentangan dengan kode, sehingga pembaca menyalin hal yang salah.
Lalu insiden terjadi. On-call mengikuti langkah runbook "rotate the API key and restart workers". Itu tidak membantu karena masalah sebenarnya adalah verifikasi token yang gagal setelah perubahan konfigurasi. Runbook mengarahkan mereka ke arah yang salah selama 20 menit.
Di sinilah Claude Code untuk drift dokumentasi berguna ketika ia menghasilkan diff dan penunjuk kontradiksi, bukan penulisan ulang penuh. Anda bisa memintanya membandingkan middleware auth dan handler route terhadap cuplikan README, contoh API, dan langkah runbook, lalu mengusulkan patch minimal:
- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>
- { "user_id": "..." }
+ { "userId": "..." }
Bagian pentingnya adalah ia menandai ketidaksesuaian, menunjuk tempat yang tepat, dan hanya mengubah apa yang repo buktikan usang.
Dokumentasi tetap akurat ketika pemeriksaannya membosankan dan dapat diulang. Pilih frekuensi yang sesuai dengan seberapa berisiko perubahan Anda. Untuk kode yang cepat bergerak, lakukan pada setiap PR. Untuk layanan stabil, pembersihan mingguan plus pengecekan pra-rilis sering cukup.
Anggap drift dokumentasi seperti kegagalan tes, bukan tugas menulis. Gunakan Claude Code untuk drift dokumentasi untuk menghasilkan diff kecil dan daftar kontradiksi singkat, lalu perbaiki hal terkecil yang membuat dokumen benar lagi.
Rutinitas ringan yang bertahan:
Buat ringkasan diff itu mudah ditemukan kemudian. Catatan singkat seperti "Dokumen diperbarui untuk mencocokkan endpoint /v2 baru, menghapus header yang deprecated, memperbarui response contoh" membantu ketika seseorang bertanya bulan kemudian mengapa dokumen berubah.
Terapkan pemikiran "snapshot dan rollback" juga ke dokumen. Jika sebuah instruksi tidak pasti, ubah di satu tempat, verifikasi cepat, lalu salin versi yang terkonfirmasi ke tempat lain.
Jika Anda membangun dengan cepat, membantu untuk menghasilkan aplikasi dan draf awal dokumennya bersama di Koder.ai (koder.ai), kemudian ekspor kode sumber dan simpan perubahan agar bisa ditinjau di alur kerja biasa. Tujuannya bukan prosa sempurna. Tujuannya adalah menjaga apa yang orang lakukan (perintah, endpoint, langkah) selaras dengan apa yang kode lakukan.
Dokumentasi drift adalah ketika dokumen Anda perlahan tidak lagi sesuai dengan apa yang sebenarnya dilakukan kode. Biasanya dimulai dari perubahan kecil (variabel lingkungan berganti nama, field baru menjadi wajib, kode status berbeda) yang tidak pernah tercermin dalam README, contoh API, atau runbook.
Karena kode berubah di bawah tekanan dan dokumentasi tidak mendapat pengawasan yang sama.
Penyebab umum:
Mulailah dengan dokumen yang orang benar-benar jalankan, bukan yang sekadar “bagus untuk dimiliki.” Urutan praktis:
Memperbaiki bagian-bagian itu terlebih dahulu menghilangkan kegagalan dengan biaya tertinggi.
Karena prose yang lebih rapi tetap bisa salah. Drift terutama soal klaim yang tidak benar.
Pendekatan yang lebih baik adalah menganggap dokumen sebagai pernyataan yang bisa diuji: “jalankan perintah ini,” “panggil endpoint ini,” “setel variabel ini,” lalu verifikasi klaim tersebut terhadap repo saat ini, konfigurasi, dan keluaran nyata.
Minta dua keluaran:
Juga persyaratkan: jika tidak menemukan bukti di repo, harus menyatakan “tidak ditemukan” daripada menebak.
Karena reviewer bisa memvalidasi diff dengan cepat. Diff menunjukkan tepat apa yang berubah, dan mencegah penulisan ulang “membantu” yang memperkenalkan janji baru.
Default yang baik: satu file per diff bila memungkinkan, dan setiap perubahan mendapat satu kalimat alasan yang terkait bukti dari repo.
Minta supaya mengutip bukti.
Aturan praktis:
Periksa bagian yang orang copy-paste:
Jika daftar endpoint benar tetapi contohnya salah, pengguna tetap gagal—jadi anggap contoh sebagai prioritas tinggi.
Runbook menjadi usang ketika realitas operasional berubah.
Pemeriksaan berdampak tinggi:
Jika responder tidak bisa memverifikasi kemajuan, mereka akan buang waktu saat insiden.
Gunakan aturan “sumber kebenaran” sederhana per jenis dokumen:
Lalu masukkan ke alur kerja: jalankan pemeriksaan drift pada dokumen yang terpengaruh per PR, dan jaga perubahan tetap kecil serta mudah ditinjau.