docs: add AGENTS and sync AI agent guides for ASO
This commit is contained in:
182
AGENTS.md
Normal file
182
AGENTS.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# AGENTS.md
|
||||
|
||||
File ini berisi instruksi untuk AI coding agent yang bekerja di repository ini.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Project name: ASO (Laravel + Modules)
|
||||
Purpose: Platform operasional health insurance/managed care untuk pengelolaan member, corporate policy, claim, monitoring, livechat, dan pelaporan.
|
||||
Main users: Tim internal operasional, portal client corporate, portal hospital.
|
||||
Business domain: Healthtech / asuransi kesehatan / manajemen klaim dan layanan kesehatan.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
Backend: PHP 8+, Laravel 9, `nwidart/laravel-modules`.
|
||||
Frontend: React + TypeScript + Vite (utama di `frontend/dashboard` dan `frontend/client-portal`), plus aset root Laravel (`resources/`, Vite/Mix).
|
||||
Database: MySQL/MariaDB (via Eloquent ORM + Laravel migrations).
|
||||
Queue/background jobs: Laravel Queue (`jobs` table tersedia; default testing `sync`).
|
||||
Cache: Laravel cache (driver mengikuti `.env`, testing pakai `array`).
|
||||
Auth: Laravel Sanctum, Spatie Permission (`role`/`permission` middleware), sebagian flow JWT untuk integrasi tertentu.
|
||||
Deployment: Build frontend ke `public/dashboard` dan `public/client-portal`; backend Laravel standar.
|
||||
Package manager: Composer (PHP), npm/yarn/pnpm (frontend, mixed antar subproject).
|
||||
|
||||
## Local Setup
|
||||
|
||||
Install dependencies:
|
||||
|
||||
```bash
|
||||
composer install
|
||||
npm install
|
||||
cd frontend/dashboard && yarn install
|
||||
cd ../client-portal && yarn install
|
||||
```
|
||||
|
||||
Run app:
|
||||
|
||||
```bash
|
||||
php artisan serve
|
||||
npm run dev
|
||||
cd frontend/dashboard && yarn start
|
||||
cd ../client-portal && yarn start
|
||||
```
|
||||
|
||||
Run tests:
|
||||
|
||||
```bash
|
||||
php artisan test
|
||||
```
|
||||
|
||||
Run lint:
|
||||
|
||||
```bash
|
||||
cd frontend/dashboard && yarn lint
|
||||
cd ../client-portal && yarn lint
|
||||
```
|
||||
|
||||
Run typecheck:
|
||||
|
||||
```bash
|
||||
# Belum ada script typecheck standar di root/subproject.
|
||||
# Jika diperlukan, gunakan tsc manual per frontend setelah konfirmasi tim.
|
||||
```
|
||||
|
||||
Run build:
|
||||
|
||||
```bash
|
||||
npm run production
|
||||
cd frontend/dashboard && yarn build
|
||||
cd ../client-portal && yarn build
|
||||
```
|
||||
|
||||
Run migrations:
|
||||
|
||||
```bash
|
||||
php artisan migrate
|
||||
```
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```text
|
||||
app/ # Core Laravel app (models, services, middleware, controllers)
|
||||
routes/ # Root web/api routes
|
||||
Modules/ # Domain/module-based backend (Client, Internal, Linksehat, Primaya, HospitalPortal)
|
||||
Modules/*/Routes/ # Route entry point tiap module
|
||||
Modules/*/Http/Controllers/Api/
|
||||
database/migrations/ # Root migrations
|
||||
frontend/dashboard/ # React TS admin/internal dashboard
|
||||
frontend/client-portal/ # React TS client portal
|
||||
resources/ # Blade/views/assets untuk app Laravel utama
|
||||
public/ # Public assets + output build frontend
|
||||
tests/ # PHPUnit tests (Feature/Unit)
|
||||
```
|
||||
|
||||
## Architecture Rules
|
||||
|
||||
- Tempatkan business logic di layer service/domain yang sudah ada (`app/Services`, `Modules/*/Services`) dan jaga controller tetap tipis.
|
||||
- API layer mengikuti pemisahan module: endpoint module didefinisikan di `Modules/<ModuleName>/Routes/api.php` dengan controller module terkait.
|
||||
- Untuk perubahan schema, gunakan migration baru; jangan ubah migration lama kecuali ada instruksi eksplisit.
|
||||
- Untuk frontend, ikuti pattern existing per app (`src/pages`, `src/components`, `src/hooks`, `src/sections`) dan hindari cross-import antar app dashboard/client-portal.
|
||||
- Testing backend utama menggunakan PHPUnit (`tests/Feature`, `tests/Unit`); tambah regression test untuk perubahan behavior penting.
|
||||
|
||||
## Coding Standards
|
||||
|
||||
- Ikuti pattern existing project sebelum membuat pattern baru.
|
||||
- Buat perubahan kecil dan fokus.
|
||||
- Jangan lakukan refactor yang tidak berhubungan.
|
||||
- Jangan hardcode secrets.
|
||||
- Jangan bypass validation.
|
||||
- Jangan bypass auth/permission checks.
|
||||
- Pilih code yang eksplisit dan mudah dibaca dibanding code yang terlalu clever.
|
||||
- Tambahkan atau update test jika behavior berubah.
|
||||
|
||||
## Git Rules
|
||||
|
||||
- Jangan commit kecuali user secara eksplisit meminta.
|
||||
- Jangan push kecuali user secara eksplisit meminta.
|
||||
- Jangan rewrite git history kecuali user secara eksplisit meminta.
|
||||
- Tampilkan file yang berubah di final response.
|
||||
|
||||
## Security Rules
|
||||
|
||||
- Jangan pernah print secrets.
|
||||
- Jangan ubah nilai `.env` asli kecuali diminta secara eksplisit.
|
||||
- Gunakan `.env-example`/`.env.example` untuk dokumentasi environment variables.
|
||||
- Validasi auth, permissions, dan scoping corporate/member untuk protected data.
|
||||
- Untuk endpoint API, pertahankan middleware auth yang ada (`auth:sanctum`, role/permission, middleware khusus module).
|
||||
- Minta konfirmasi sebelum destructive data changes.
|
||||
|
||||
## Database Rules
|
||||
|
||||
- Gunakan migration system project ini.
|
||||
- Jangan edit historical migrations kecuali project ini memang mengizinkan.
|
||||
- Sertakan rollback/safety notes untuk schema changes.
|
||||
- Pertimbangkan existing production data.
|
||||
- Perhatikan migrasi dapat berasal dari root `database/migrations` dan modul tertentu.
|
||||
|
||||
## Testing Rules
|
||||
|
||||
Sebelum selesai, jalankan command yang relevan:
|
||||
|
||||
```bash
|
||||
php artisan test
|
||||
cd frontend/dashboard && yarn lint
|
||||
cd frontend/client-portal && yarn lint
|
||||
```
|
||||
|
||||
Jika command tidak bisa dijalankan, jelaskan alasannya dan command apa yang harus dijalankan manual.
|
||||
|
||||
## AI Agent Workflow
|
||||
|
||||
Untuk feature work:
|
||||
|
||||
1. Baca file ini.
|
||||
2. Inspect pattern yang sudah ada.
|
||||
3. Tulis plan singkat untuk pekerjaan non-trivial.
|
||||
4. Tanya klarifikasi jika requirement kurang jelas.
|
||||
5. Implement perubahan kecil dan fokus.
|
||||
6. Jalankan test/lint/typecheck/build yang relevan.
|
||||
7. Rangkum file yang berubah, command yang dijalankan, dan risiko.
|
||||
|
||||
Untuk debugging:
|
||||
|
||||
1. Reproduce atau inspect issue.
|
||||
2. Identifikasi root cause sebelum mengubah code.
|
||||
3. Buat fix minimal yang aman.
|
||||
4. Tambahkan regression test jika memungkinkan.
|
||||
5. Jalankan verification.
|
||||
|
||||
## Final Response Format
|
||||
|
||||
```text
|
||||
Summary:
|
||||
- ...
|
||||
|
||||
Files changed:
|
||||
- ...
|
||||
|
||||
Commands run:
|
||||
- ...
|
||||
|
||||
Risks / notes:
|
||||
- ...
|
||||
```
|
||||
Reference in New Issue
Block a user