aso/docs/ai-agent-guide.id.md

Panduan Penggunaan AI Agent (ASO)

Panduan ini menjelaskan cara tim ASO menyiapkan dan memakai AI coding agent secara aman di repository ini.

Tujuan utamanya adalah memberi AI konteks project, command yang benar, dan batasan safety agar AI membantu lebih cepat tanpa merusak codebase.

Prinsip Utama

1. Human tetap pemilik keputusan final.
2. AI wajib mengikuti konvensi project ASO.
3. AI tidak boleh commit/push kecuali diminta eksplisit.
4. AI harus membuat rencana singkat sebelum perubahan besar/berisiko.
5. AI harus menjalankan verifikasi relevan sebelum menyatakan selesai.
6. Human wajib review area kritikal: security, auth/permission, scoping corporate/member, migration, payments, data deletion, production config.
7. Repository ini wajib memiliki AGENTS.md di root.

Konteks Project Ini

ASO adalah platform operasional health insurance/managed care untuk pengelolaan corporate, member, claim, monitoring, livechat, dan pelaporan.

Stack utama saat ini:

• Backend: Laravel 9 (app/) + modular backend nwidart/laravel-modules (Modules/)
• Frontend: frontend/dashboard dan frontend/client-portal (React + TS + Vite), plus assets root Laravel (resources/, Vite/Mix)
• Auth/Permission: Sanctum + Spatie Permission (role, permission) + beberapa flow JWT untuk integrasi tertentu
• Testing backend: PHPUnit (tests/Feature, tests/Unit)

AI Agent Ready untuk Repo ASO

Repository ini dianggap AI Agent Ready jika AI bisa cepat menjawab:

• Struktur backend modular dan batas tiap module
• Command setup/run/test/lint/build yang benar untuk root + dua frontend app
• Aturan peletakan business logic
• Aturan auth/permission/scoping corporate-member pada endpoint terlindungi
• Aturan migration aman
• Aturan git (tidak commit/push tanpa instruksi)

File Minimum yang Harus Ada

.
├── AGENTS.md
├── README.md
├── .env-example (dan/atau .env.example)
└── docs/
    └── ai-agent-guide.id.md

Disarankan ditambah:

docs/architecture.md
docs/testing.md
docs/database.md
docs/api-contracts.md

Command Operasional (Aktual Repo Ini)

Install dependencies:

composer install
npm install
cd frontend/dashboard && yarn install
cd ../client-portal && yarn install

Menjalankan aplikasi lokal:

php artisan serve
npm run dev
cd frontend/dashboard && yarn start
cd ../client-portal && yarn start

Testing backend:

php artisan test

Lint frontend:

cd frontend/dashboard && yarn lint
cd ../client-portal && yarn lint

Build frontend:

npm run production
cd frontend/dashboard && yarn build
cd ../client-portal && yarn build

Migration:

php artisan migrate

Catatan:

• Script typecheck standar belum tersedia konsisten di root/subproject; jika perlu, jalankan tsc manual sesuai kebutuhan task.
• Repo ini memiliki lockfile campuran (package-lock.json, pnpm-lock.yaml, yarn.lock). Ikuti lockfile dan package manager yang sudah dipakai pada subproject yang disentuh.

Struktur Repository Penting

app/                               # Core Laravel app
routes/                            # Root routes (web/api)
Modules/                           # Module domain (Client, Internal, Linksehat, Primaya, HospitalPortal)
Modules/*/Routes/api.php           # API route per module
database/migrations/               # Root migrations
frontend/dashboard/                # Internal/admin frontend
frontend/client-portal/            # Client portal frontend
resources/                         # View/assets Laravel utama
public/                            # Public assets + output build frontend
tests/                             # PHPUnit tests

Aturan Arsitektur untuk Agent

• Gunakan pattern yang sudah ada sebelum menambah pattern baru.
• Jaga controller tetap tipis; letakkan logic di service/domain yang sudah ada (app/Services, Modules/*/Services).
• Untuk API module, tambahkan route dan controller dalam module yang sesuai; hindari menaruh logic module di tempat acak.
• Jangan cross-import antar frontend app (dashboard vs client-portal) kecuali memang sudah ada kontrak eksplisit.
• Jika mengubah perilaku endpoint protected, review middleware terkait (auth:sanctum, role/permission, middleware custom module).

Workflow AI Harian

1. Mulai Task

• Baca AGENTS.md.
• Pahami pattern existing di area yang akan diubah.
• Buat plan singkat untuk task non-trivial.
• Klarifikasi requirement jika masih ambigu.

2. Feature Work

• Implement perubahan kecil dan fokus.
• Hindari refactor unrelated.
• Tambah/update test saat behavior berubah.
• Jalankan verifikasi relevan.

3. Bug Fixing

• Reproduce/inspeksi issue terlebih dahulu.
• Temukan root cause.
• Terapkan fix minimal dan aman.
• Tambah regression test jika memungkinkan.

4. Review Sebelum PR

Periksa:

• correctness
• security
• auth/permission/scoping
• migration safety
• missing tests
• lint/type/build impact
• perubahan unrelated

Definition of Done untuk Task AI

Task AI belum selesai sampai:

• Perubahan mengikuti pattern existing.
• Tidak ada perubahan unrelated.
• Test/lint/build relevan sudah dijalankan atau alasannya dijelaskan.
• Risiko migration/auth/scoping dijelaskan jika relevan.
• File berubah dan command yang dijalankan dicatat.

Safety Rules (Wajib)

AI agent tidak boleh:

• Commit/push/rewrite history tanpa instruksi eksplisit.
• Mengubah .env asli tanpa instruksi eksplisit.
• Print secrets ke output/chat.
• Menghapus data/folder besar tanpa konfirmasi.
• Mengubah schema DB tanpa migration baru dan catatan safety.
• Menambah dependency besar tanpa alasan jelas dan dampak.

Prompt Siap Pakai untuk Repo Ini

Setup / Sinkronisasi Dokumentasi

Baca AGENTS.md dan docs/ai-agent-guide.id.md.
Sinkronkan dokumentasi AI agent dengan kondisi codebase saat ini.
Validasi command setup/test/lint/build berdasarkan file konfigurasi aktual.
Jangan commit perubahan.

Feature Work

Implement feature berikut: [jelaskan].
Rules:
- Baca AGENTS.md terlebih dahulu.
- Ikuti pattern existing repo ASO.
- Jangan commit.
- Jalankan verifikasi relevan.
Output akhir wajib: Summary, Files changed, Commands run, Risks/notes.

Bug Fixing

Fix bug berikut: [jelaskan].
Gunakan systematic debugging:
1. Reproduce/inspeksi issue
2. Temukan root cause
3. Terapkan fix minimal aman
4. Tambah regression test jika memungkinkan
5. Jalankan verifikasi
Jangan commit.

Format Final Response Standar

Gunakan format ini:

Summary:
- ...

Files changed:
- ...

Commands run:
- ...

Risks / notes:
- ...