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

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

Disarankan ditambah:

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

## Command Operasional (Aktual Repo Ini)

Install dependencies:

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

Menjalankan aplikasi lokal:

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

Testing backend:

```bash
php artisan test
```

Lint frontend:

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

Build frontend:

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

Migration:

```bash
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

```text
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

```text
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

```text
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

```text
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:

```text
Summary:
- ...

Files changed:
- ...

Commands run:
- ...

Risks / notes:
- ...
```