From d10f731839fd2d6befca4ec72ecbb1f0d0d54558 Mon Sep 17 00:00:00 2001
From: Yoga Pangestu <ypangestu976@gmail.com>
Date: Fri, 7 Aug 2026 11:40:09 +0700
Subject: [PATCH] feat: enhance documentation with workflow tracing and session
 notes guidelines

---
 AGENTS.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 0e483eb..cf01ebd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -20,6 +20,80 @@ ## ⚠️ WAJIB BACA SEBELUM KERJA
 
 **Jangan pernah skip membaca `.ai/` folder** — semua aturan ada di sana.
 
+**Catatan Penting:**
+- File `.ai/` adalah **contoh best practice & referensi**, bukan berarti semua pola di situ sudah ada di project
+- Jika pola di `.ai/` belum ada di project → **ikuti pola yang sudah ada di codebase**
+- Jangan buang waktu mencari file/pattern yang belum tentu ada
+
+---
+
+## Workflow: Trace Codebase
+
+Sebelum mengubah/menambah fitur, **pahami dulu alur kode yang sudah ada**.
+
+### Cara Trace:
+
+Mulai dari file yang relevan (Route/Controller/Service), lalu **ikuti setiap pemanggilan**:
+
+- Jika ada `use ... Service` → baca file Service
+- Jika ada `use ... Model` → baca file Model
+- Jika ada `use ... Trait` → baca file Trait
+- Jika ada `use ... Enum` → baca file Enum
+- Jika ada Form Request → baca file Form Request
+
+### Contoh Trace:
+
+```
+ProductController
+  └── panggil ProductService → baca
+        └── panggil Product model → baca
+              └── pakai HasFactory trait → baca
+```
+
+**Ikuti terus sampai semua pemanggilan dipahami. Jangan ubah kode tanpa memahami alur yang sudah ada.**
+
+---
+
+## Documentation: Catatan Session Kerja
+
+Setiap kali bekerja pada suatu fitur, **WAJIB** buat/dokumentasi di `/docs` folder.
+
+### Format: `/docs/{nama-fitur}.md`
+
+Isi dokumen:
+1. **Tujuan** — fitur apa yang dibuat/diubah
+2. **File yang dibaca** — daftar file + ringkasan singkat
+3. **Pola yang ditemukan** — struktur kode, relasi, flow
+4. **Perubahan yang dilakukan** — apa saja yang diubah
+
+### Contoh:
+
+```markdown
+# Fitur: Transfer Stok Produk
+
+## Tujuan
+Menambah fitur perpindahan stok dari gudang baik ke reject
+
+## File yang Dibaca
+- `routes/web.php` → ProductController di route `admin.manage.products`
+- `app/Http/Controllers/Admin/Manage/ProductController.php` → ada method `index`, `store`, `update`
+- `app/Services/Admin/Manage/ProductService.php` → panggil Product model, pakai `HasStockAdjustment` trait
+- `app/Models/Product.php` → relasi `stocks()`, accessor `formatted_stock`
+
+## Pola yang Ditemukan
+- Service handle logic, Controller zero logic
+- Pakai trait `HasStockAdjustment` untuk adjust stock
+- Stock ada di tabel `stocks` dengan relasi ke product
+
+## Perubahan
+- Tambah method `transferStock()` di ProductService
+- Tambah route `POST /products/{product}/transfer-stock`
+```
+
+### Kapan harus update?
+- Saat mulai sesi baru → buat dokumen baru
+- Saat lanjut sesi sebelumnya → baca dulu dokumen yang sudah ada
+
 ---
 
 ## Backend