Documentation Governance Rules for AI Agents¶
Aturan wajib untuk semua agen AI yang bekerja pada codebase Scola agar dokumentasi tetap terpusat dan tidak bertambah tak terkontrol.
Versi: 1.0
Berlaku: 2026-03-16
Lokasi: docs/ai-guidelines/DOCUMENTATION_GOVERNANCE.md
🚫 LARANGAN MUTLAK¶
| Larangan | Sanksi |
|---|---|
Membuat file .md baru di root docs/ |
Dokumen akan diarsipkan, agent diminta perbaiki |
| Membuat direktori tanpa README.md | Struktur ditolak, wajib tambahkan README |
| Menghapus file dokumen | DILARANG KERAS — hanya arsipkan ke _archive/ |
| Duplikasi topik yang sudah ada di domain/ | Merge ke domain SSOT yang relevan |
| Membuat dokumen implementation plan terpisah | Tambahkan sebagai section "Implementation Plan" di domain SSOT |
✅ ATURAN WAJIB¶
1. Lokasi Dokumen¶
| Tipe Dokumen | Lokasi Wajib | Contoh |
|---|---|---|
| Dokumen domain/fitur | docs/domains/<domain>/README.md atau sub-file |
docs/domains/cbt/cbt-contract.md |
| Dokumen arsitektur | docs/architecture/ |
docs/architecture/new-pattern.md |
| API reference | docs/api/ |
docs/api/endpoints.md |
| Panduan pengembangan | docs/development/ |
docs/develpment/react-patterns.md |
| Panduan operasional | docs/operations/ |
docs/operations/deploy-new-env.md |
| QA/testing | docs/qa/ |
docs/qa/new-test-strategy.md |
| AI guidelines | docs/ai-guidelines/ |
docs/ai-guidelines/prompting-guide.md |
| User guide | docs/user-guide/ |
docs/user-guide/admin-guide.md |
| Audit production | docs/audit/production-readiness/ |
docs/audit/production-readiness/<domain>-audit.md |
| Portal MkDocs config | scola-fe-v2/mkdocs.yml + scripts/build-docs.sh |
Deploy ke https://docs.gcgscola.id |
| Backend module docs | gcgscola/docs/modules/ (repo backend, branch main) |
gcgscola/docs/modules/scola_*.md |
| Navigation/RBAC | docs/navigation/ |
docs/navigation/menu-changes.md |
2. Pattern Domain SSOT (WAJIB)¶
Setiap domain doc HARUS mengikuti struktur ini:
# Domain: [Nama]
> SSOT untuk [deskripsi singkat]
**Last verified:** YYYY-MM-DD
## 1. Visi & Best Practice
### 1.1 Regulasi/Standar Acuan
### 1.2 Kondisi Ideal
## 2. Arsitektur & Data Model
### 2.1 Backend Modules
### 2.2 Frontend Structure
### 2.3 Capabilities
### 2.4 API Endpoints
## 3. Fitur & Status Implementasi
| Fitur | Status | Catatan |
## 4. Gap Analysis & Backlog
### P1 — Important
### P2 — Nice to Have
## 5. File References
3. Update vs Create Baru¶
PRIORITAS: UPDATE > CREATE
| Situasi | Tindakan |
|---|---|
| Fitur baru di domain existing | UPDATE section "Fitur & Status" di domain SSOT |
| Gap ditemukan | UPDATE section "Gap Analysis" di domain SSOT |
| Implementasi selesai | UPDATE status ✅ di domain SSOT |
| Dokumen lama tidak relevan | MOVE ke _archive/superseded/, jangan hapus |
| Domain benar-benar baru | CREATE domain SSOT baru dengan pattern lengkap |
4. Checklist Sebelum Commit¶
Setiap task yang melibatkan dokumentasi HARUS melalui checklist ini:
## Pre-Commit Documentation Checklist
- [ ] Tidak ada file .md baru di root `docs/`
- [ ] Jika membuat direktori baru: sudah ada `README.md` di dalamnya
- [ ] Jika update domain: mengikuti pattern SSOT (Visi → Arsitektur → Fitur → Gap)
- [ ] Jika memindahkan doc lama: destination adalah `_archive/`, bukan delete
- [ ] Jika menambah fitur: status di-update di "Fitur & Status" table
- [ ] Jika menutup gap: pindahkan dari "Gap Analysis" ke "Fitur & Status"
- [ ] Semua internal links valid (tidak broken)
- [ ] Tanggal "Last verified" di-update
🔧 WORKFLOW DOKUMENTASI¶
Saat Memulai Task Baru¶
- Cek domain terkait di
docs/domains/<domain>/README.md - Jangan buat doc baru — cari section yang relevan untuk di-update
- Jika perlu jelaskan implementasi detail: tambahkan subsection di section 2 atau 3
Saat Menemukan Gap¶
❌ SALAH: Membuat "GAPS_IN_PAYMENT_SYSTEM.md" di root docs/
✅ BENAR: Update "Gap Analysis & Backlog" di docs/domains/keuangan/README.md
Saat Implementasi Selesai¶
❌ SALAH: Membuat "IMPLEMENTATION_SUMMARY.md" terpisah
✅ BENAR: Update status ✅ di "Fitur & Status" table domain terkait
Saat Membuat Domain Baru¶
- Buat direktori
docs/domains/<new-domain>/ - Buat
README.mddengan pattern SSOT lengkap - Update
docs/domains/README.md— tambahkan link ke domain baru - Update
docs/README.mdhub — tambahkan ke "Domain Reference Cards"
📋 ESKALASI¶
Jika agent menemukan situasi yang tidak sesuai aturan:
| Situasi | Tindakan |
|---|---|
| Tidak yakin lokasi doc | Tanya user atau masukkan ke _archive/unclassified/ sementara |
| Doc existing bertentangan dengan pengetahuan baru | Update "Last verified" dan tambahkan catatan perubahan |
| Perlu restructure besar | Buat task khusus untuk restructuring, jangan lakukan ad-hoc |
| Konflik dengan doc lain | Merge/update, jangan duplikat |
🎯 CONTOH SCENARIOS¶
Scenario 1: Menambah Fitur CBT Baru¶
❌ SALAH:
- Membuat "CBT_NEW_PROCTORING_FEATURE.md"
- Diisi detail teknis implementasi
✅ BENAR:
- Buka docs/domains/cbt/README.md
- Tambahkan baris di "Fitur & Status":
| AI Proctoring | 🔄 In Progress | Face detection integration |
- Tambahkan subsection di "Arsitektur" jika perlu
- Update "Gap Analysis" kalau sebelumnya ada di situ
Scenario 2: Menemukan Bug/Workaround¶
❌ SALAH:
- Membuat "BUG_FIX_SUMMARY_2026_03.md"
- Isi langkah-langkah fix
✅ BENAR:
- Update status fitur terkait di domain SSOT (⚠️ Partial dengan catatan)
- Jika ephemeral (debug log sementara): masukkan ke `_archive/fix-summaries/`
- Jika permanent workaround: dokumentasikan di section "Catatan" fitur terkait
Scenario 3: Integrasi dengan Sistem Eksternal¶
❌ SALAH:
- Membuat "MIDTRANS_INTEGRATION_GUIDE.md"
- Isi lengkap cara integrasi
✅ BENAR:
- Buka docs/domains/keuangan/README.md (karena payment masuk keuangan)
- Tambahkan di "Gap Analysis & Backlog" P1:
| Payment gateway integration | Midtrans/Xendit API integration |
- Tambahkan subsection di "Arsitektur" tentang external API pattern
🔄 REVIEW PROCESS¶
Setiap PR yang menyentuh docs/ harus dicek:
- Jumlah file baru: Apakah reasonable? (Red flag jika >3 file .md baru)
- Lokasi: Apakah di direktori yang benar?
- Pattern: Apakah mengikuti SSOT structure untuk domain?
- Link: Apakah semua internal link valid?
- Archive: Apakah doc lama yang superseded diarsipkan (bukan dihapus)?
Referensi: - docs/DOCUMENTATION_CONSOLIDATION_PLAN.md — Rencana konsolidasi - docs/domains/ — Contoh domain SSOT docs