Menjaga Dokumentasi Tetap Sinkron dengan Codebase Anda

Skenario 1: Dokumentasi awal proyek

Anda telah menerima repositori dengan dokumentasi yang sangat minim. Anggota tim baru kesulitan memahami codebase, dan Anda perlu membuat dokumentasi yang komprehensif dengan cepat.

Siapkan ruang kerja Anda

1. Buka repositori di IBM Bob IDE.
2. Buka antarmuka chat Bob: Option + Command + B (macOS) atau Ctrl + Alt + B (Windows)

Hasilkan konteks yang dapat dibaca AI dengan /init

Langkah pertama adalah memberikan pengetahuan kepada Bob tentang proyek Anda. Beralih ke mode Agent dan jalankan:

/init

Bob memindai repositori Anda dan menghasilkan:

• AGENTS.md di root repositori (konteks proyek utama)
• .bob/rules-code/AGENTS-code.md (konteks spesifik mode Code)
• .bob/rules-plan/AGENTS-plan.md (konteks spesifik mode Plan)
• .bob/rules-ask/AGENTS-ask.md (konteks spesifik mode Ask)

File-file ini berisi:

• Struktur kode dan direktori utama
• Stack teknologi dan dependensi
• Perintah build, test, dan lint
• Pola dan konvensi kode

Mengapa ini penting: File AGENTS.md ini berfungsi sebagai basis pengetahuan yang dirujuk Bob dalam setiap percakapan. Alih-alih menganalisis ulang seluruh codebase Anda setiap saat, Bob memiliki konteks yang persisten tentang proyek Anda.

Tinjau konteks yang dihasilkan

Buka AGENTS.md dan tinjau apa yang ditemukan oleh Bob:

cat AGENTS.md

Anda akan melihat ringkasan terstruktur dari proyek Anda. Jika Bob melewatkan detail penting (aturan bisnis, konvensi deployment, praktik tim), edit AGENTS.md secara manual untuk menambahkannya. File ini memang dirancang untuk disesuaikan.

Buat mode Docs Architect

Sekarang buat mode kustom yang menghasilkan dokumentasi yang ditujukan bagi pengguna. Mode ini akan menggunakan konteks dari AGENTS.md untuk membuat dokumentasi bagi manusia, bukan AI.

1. Klik ikon settings di panel Bob untuk membuka Pengaturan (Settings).
2. Pilih tab Modes.
3. Klik ikon + untuk membuat mode baru.
4. Isi nilai-nilai berikut:

Untuk bidang Mode-specific Custom Instructions, salin dan tempel teks berikut:

Ketika mendokumentasikan proyek:
1. Tinjau file AGENTS.md untuk memahami struktur proyek dan detail teknis
2. Buat dokumentasi yang ditujukan bagi pengguna (README, panduan memulai cepat, tutorial)
3. Hindari menduplikasi detail teknis dari AGENTS.md (perintah build, pola kode)
4. Fokus pada alur kerja pengguna, tinjauan konseptual, dan contoh kode praktis
5. Sertakan blok kode dengan penjelasan yang jelas
6. Tambahkan docstring dan komentar JSDoc untuk meningkatkan kualitas kode

Hasilkan:
- README.md yang menjelaskan tujuan proyek dan navigasi
- CONTRIBUTING.md dengan langkah-langkah onboarding untuk kontributor baru
- Panduan memulai cepat dengan cuplikan kode
- Dokumentasi konseptual yang menjelaskan keputusan arsitektur

Klik Save.

Bob membuat file custom_modes.yaml di dalam folder .bob yang berisi konfigurasi mode Docs Architect tersebut. Anda dapat mengedit file ini secara langsung untuk melakukan perubahan di masa mendatang.

Hasilkan dokumentasi awal

Beralih ke mode Docs Architect dan berikan prompt berikut:

Saya telah menjalankan /init untuk membangun konteks proyek. Tolong buat dokumentasi yang komprehensif untuk proyek ini:

1. Tinjau AGENTS.md untuk memahami struktur proyek
2. Buat README.md yang berisi:
   - Tinjauan umum dan tujuan proyek
   - Panduan memulai cepat (quick start) dengan contoh kode
   - Penjelasan struktur proyek
   - Tautan ke dokumentasi tambahan
3. Buat CONTRIBUTING.md yang berisi:
   - Instruksi penyiapan lingkungan pengembangan
   - Cara menjalankan pengujian (test)
   - Cara mengirimkan pull request
   - Panduan gaya penulisan kode (code style)
4. Identifikasi celah dalam codebase yang membutuhkan dokumentasi lebih baik (docstring yang hilang, fungsi yang tidak jelas)

Fokuskan untuk membuat detail teknis dari AGENTS.md mudah dipahami bagi developer baru.

Bob akan menghasilkan file dokumentasi. Tinjau keakuratannya, lakukan penyesuaian jika diperlukan, lalu lakukan commit:

git add AGENTS.md .bob/ README.md CONTRIBUTING.md
git commit -m "docs: initial project documentation with AI assistance"

Hasil: Anda telah beralih dari dokumentasi minim ke dokumentasi komprehensif dalam hitungan menit, bukan jam.

Skenario 2: Mendokumentasikan fitur baru

Anda baru saja mengimplementasikan fitur baru. Kodenya berfungsi dengan baik, tetapi README, panduan kontribusi, dan dokumen API Anda masih menggambarkan status proyek yang lama. Ini adalah titik paling umum di mana dokumentasi mulai tertinggal — fiturnya selesai, tetapi dokumen belum diperbarui.

Berikut cara mengatasi celah tersebut menggunakan Bob.

Tulis fitur dengan bantuan Bob

Saat mengembangkan fitur, beralihlah ke mode Agent agar Bob dapat membantu dalam implementasinya. Karena Bob sudah memiliki konteks proyek dari /init yang Anda jalankan di Skenario 1, Bob memahami struktur kode, dependensi, dan konvensi Anda — membuat sarannya jauh lebih relevan dibandingkan memulai dari awal.

Tulis fitur seperti biasa, menggunakan Bob untuk pelengkapan kode (code completion), refactoring, atau mengajukan pertanyaan tentang codebase yang ada.

Jalankan kembali /init untuk memperbarui konteks AI

Setelah fitur selesai diimplementasikan, konteks yang dimiliki Bob menjadi usang — karena konteks tersebut dibuat sebelum kode baru Anda ada. Perbarui konteks tersebut:

/init

Bob memindai ulang repositori dan memperbarui AGENTS.md untuk mencerminkan apa yang telah berubah — modul baru, dependensi yang diperbarui, dan pola kode baru apa pun yang terdeteksi.

Konfirmasikan bahwa pembaruan tersebut menangkap perubahan Anda:

git diff AGENTS.md .bob/

Jika diff menunjukkan fitur baru Anda, Bob siap menghasilkan dokumentasi yang akurat. Jika ada hal penting yang hilang, edit AGENTS.md secara manual sebelum melanjutkan.

Hasilkan dokumentasi untuk fitur baru

Sekarang beralihlah ke mode Docs Architect. Karena Anda baru saja memperbarui AGENTS.md, Bob memiliki gambaran akurat tentang fitur baru tersebut dan dapat menghasilkan dokumentasi yang mencerminkan implementasi nyata — bukan sekadar tebakan.

Berikan prompt kepada Bob tentang apa yang perlu diperbarui:

Saya telah menambahkan fitur baru ke proyek. Tolong perbarui dokumentasinya:

1. Tambahkan bagian ke README.md yang menjelaskan:
   - Apa kegunaan fitur tersebut
   - Cara mengonfigurasi dan menggunakannya
   - Cuplikan kode yang menunjukkan penggunaan dasar
2. Perbarui CONTRIBUTING.md jika alur kerja pengembangan berubah
3. Buat halaman dokumentasi khusus yang membahas:
   - Cara kerja fitur tersebut
   - Endpoint API atau antarmuka yang relevan
   - Contoh kode untuk kasus penggunaan umum
   - Penjelasan kode untuk logika yang tidak jelas
   - Tips pemecahan masalah (troubleshooting)

Sertakan blok kode dengan penjelasan yang jelas. Tambahkan docstring ke fungsi apa pun yang belum memilikinya.

Tinjau dokumentasi yang dihasilkan untuk memastikan keakuratannya — periksa apakah contoh kode benar-benar cocok dengan implementasi Anda — lalu lakukan commit semuanya bersama-sama:

git add src/ AGENTS.md .bob/ README.md CONTRIBUTING.md docs/
git commit -m "feat: add [feature name] with documentation"

Hasil: Fitur Anda dan dokumentasinya dikembangkan bersama dan dicommit dalam pull request yang sama.

Skenario 3: Code review dengan pemeriksaan dokumentasi

Seorang anggota tim mengirimkan pull request yang menambahkan endpoint API baru. Anda perlu memastikan dokumentasinya ikut diperbarui.

Tinjau perubahan kode

git diff main feature-branch

Anda melihat endpoint API baru tetapi tidak ada pembaruan dokumentasi.

Periksa apakah /init sudah dijalankan

git diff main feature-branch -- AGENTS.md .bob/

Jika tidak ada perubahan pada AGENTS.md, berarti developer tersebut tidak menjalankan /init. Minta mereka untuk:

1. Menjalankan /init untuk memperbarui konteks AI
2. Menggunakan Docs Architect untuk memperbarui dokumen yang ditujukan bagi pengguna

Hasilkan dokumentasi yang hilang

Jika Anda sedang meninjau PR tersebut, Anda dapat menghasilkan dokumentasinya sendiri:

git checkout feature-branch

Di dalam Bob, jalankan /init, lalu beralihlah ke mode Docs Architect:

Saya sedang meninjau pull request yang menambahkan endpoint API baru. Tolong perbarui dokumentasinya:

1. Tinjau endpoint baru di src/api/
2. Perbarui README.md dengan menyebutkan secara singkat endpoint baru tersebut
3. Perbarui docs/api.md dengan:
   - Deskripsi endpoint
   - Contoh permintaan/tanggapan (request/response) dengan blok kode
   - Persyaratan autentikasi
   - Kode kesalahan (error codes)
4. Tambahkan komentar JSDoc ke handler endpoint jika belum ada

Fokuskan untuk membuat API ini mudah dipahami bagi developer lain.

Commit pembaruan dokumentasi tersebut:

git add AGENTS.md .bob/ README.md docs/api.md src/api/
git commit -m "docs: add documentation for new API endpoints"
git push

Hasil: Dokumentasi menjadi bagian dari proses tinjauan kode Anda, bukan hal yang dipikirkan belakangan.

Skenario 4: Melakukan onboarding anggota tim baru

Seorang developer baru bergabung dengan tim Anda. Mereka perlu memahami codebase dengan cepat.

Minta mereka menjalankan /init

Developer baru tersebut mengklon repositori dan menjalankan:

/init

Bob menghasilkan file AGENTS.md baru yang mencerminkan status codebase saat ini. Developer baru tersebut kini dapat:

1. Membaca AGENTS.md untuk memahami struktur proyek
2. Membaca README.md untuk instruksi memulai cepat
3. Membaca CONTRIBUTING.md untuk alur kerja pengembangan

Gunakan mode Ask untuk eksplorasi

Developer baru dapat menggunakan mode Ask dari Bob untuk mengeksplorasi codebase:

@src/auth Jelaskan cara kerja autentikasi dalam proyek ini

@src/api Endpoint API apa saja yang tersedia dan apa fungsinya?

@tests Bagaimana cara menjalankan pengujian (test) untuk modul tertentu?

Bob menjawab menggunakan konteks dari AGENTS.md dan kode sumber yang sebenarnya.

Hasilkan dokumen onboarding yang dipersonalisasi

Jika proyek Anda kekurangan dokumentasi onboarding, gunakan Docs Architect:

Buat panduan onboarding untuk developer baru yang bergabung dengan proyek ini:

1. Prasyarat (alat, akun, akses)
2. Langkah-langkah penyiapan awal dengan blok kode
3. Cara menjalankan proyek secara lokal
4. Cara menjalankan pengujian (test)
5. Ringkasan struktur codebase
6. Tugas pengembangan umum dengan contoh
7. Di mana mencari bantuan

Buat panduan ini praktis dan sertakan cuplikan kode untuk setiap langkah.

Hasil: Anggota tim baru dapat mulai bekerja secara produktif dalam hitungan jam, bukan hari.

Skenario 5: Memelihara dokumentasi dari waktu ke waktu

Proyek Anda telah dikembangkan selama berbulan-bulan. Kode telah berubah secara signifikan, dan dokumentasi mulai terasa usang (drift).

Deteksi dokumentasi yang usang

Jalankan /init untuk melihat apa yang berubah:

/init

Tinjau diff kodenya:

git diff AGENTS.md .bob/

Perubahan besar menunjukkan evolusi kode yang signifikan. Ini adalah sinyal bahwa dokumentasi yang ditujukan bagi pengguna perlu diperbarui.

Perbarui dokumentasi secara sistematis

Gunakan Docs Architect untuk menyegarkan dokumentasi:

Saya telah menjalankan /init dan melihat perubahan signifikan pada struktur proyek. Tolong tinjau dan perbarui dokumentasinya:

1. Tinjau perubahan AGENTS.md untuk memahami apa saja yang berbeda
2. Perbarui README.md untuk mencerminkan struktur proyek saat ini
3. Perbarui CONTRIBUTING.md jika alur kerja pengembangan telah berubah
4. Identifikasi fitur baru apa pun yang belum memiliki dokumentasi
5. Hapus dokumentasi untuk fitur yang sudah tidak digunakan (deprecated)
6. Perbarui contoh kode agar sesuai dengan API saat ini

Fokuskan pada keakuratan — pastikan dokumentasi cocok dengan codebase saat ini.

Buat jadwal pemeliharaan berkala

Tambahkan pembaruan dokumentasi ke dalam alur kerja reguler Anda:

• Bulanan: Jalankan /init dan tinjau perubahan
• Sebelum rilis: Perbarui semua dokumentasi
• Setelah refactor besar: Buat ulang dokumentasi yang terpengaruh
• Dalam tinjauan kode (code review): Periksa apakah /init sudah dijalankan dan dokumen telah diperbarui

Otomatisasi deteksi dokumentasi usang (lanjutan)

Untuk tim yang ingin menegakkan kepatuhan dokumentasi di CI, tambahkan pemeriksaan pull request yang memverifikasi bahwa AGENTS.md dan .bob/ adalah yang terbaru. Pemeriksaan tersebut akan menjalankan /init pada cabang (branch), lalu gagal jika outputnya berbeda dari apa yang dicommit — menandakan bahwa developer lupa memperbarui konteks AI sebelum membuka PR. Pasangkan ini dengan checklist PR template dari bagian praktik terbaik untuk menjadikan pembaruan dokumentasi sebagai bagian wajib dari proses tinjauan Anda.

Hasil: Dokumentasi tetap sinkron dengan kode melalui pemeliharaan yang teratur.