# FILE-HEALTH — Aturan Ukuran & Struktur File

Aturan ini berlaku untuk semua file dalam project ini.
Tujuan: menjaga file tetap kecil, kohesif, dan mudah diproses oleh AI maupun manusia.

---

## Batas Ukuran File

| Tipe File | Maks Baris | Maks Karakter | Keterangan |
|-----------|-----------|---------------|------------|
| Route handler | 150 | 6.000 | Satu file = satu resource |
| Service / use-case | 300 | 12.000 | Satu file = satu domain logic |
| Repository / query | 250 | 10.000 | Pisah per entity |
| Schema / validation | 200 | 8.000 | Pisah per domain |
| Types / interfaces | 300 | 10.000 | Boleh agregat, tapi per modul |
| Utility / helper | 200 | 8.000 | Satu concern per file |
| Config | 100 | 4.000 | Tidak ada logic bisnis |
| Test file | 400 | 16.000 | Satu file test per satu unit |

> **Hard limit global:** Tidak ada file yang boleh melebihi **500 baris** atau **20.000 karakter**,
> kecuali file yang di-generate otomatis (migration, seed, generated types).

---

## Aturan Wajib

### 1. Satu File, Satu Tanggung Jawab
- Setiap file harus bisa dijelaskan dalam satu kalimat pendek.
- Jika penjelasannya butuh kata "dan" lebih dari sekali → **pecah file-nya**.

### 2. Tidak Ada "God File"
- Dilarang menaruh lebih dari satu route group dalam satu file handler.
- Dilarang mencampur business logic dengan transport layer (HTTP, WS, queue).
- Dilarang mencampur type definition dengan implementation dalam satu file yang panjang.

### 3. Penamaan File Harus Eksplisit
- Nama file harus mencerminkan isi secara tepat.
- Hindari nama generik: `utils.ts`, `helpers.ts`, `common.ts`, `misc.ts`.
- Gunakan pola: `[domain].[layer].ts` → contoh: `user.service.ts`, `payment.repository.ts`.

### 4. Index File Hanya Untuk Re-export
- File `index.ts` hanya boleh berisi re-export, **bukan** implementasi.
- Maksimal 50 baris untuk file index.

### 5. Tidak Ada Barrel Import yang Dalam
- Hindari barrel yang mengimpor dari barrel lain lebih dari 2 level.
- Ini membuat AI sulit trace dependency dengan akurat.

---

## Kapan Harus Pecah File

Pecah file segera jika salah satu kondisi ini terpenuhi:

- [ ] File melebihi batas karakter/baris di tabel di atas
- [ ] Ada dua fungsi/class yang tidak saling bergantung dalam satu file
- [ ] File mengandung lebih dari 3 exported symbol utama
- [ ] File sulit diberi nama yang spesifik tanpa kata "dan"
- [ ] Edit di satu bagian file sering menyebabkan konflik di bagian lain

---

## Pola Pemecahan File yang Dianjurkan

### Service yang Terlalu Besar
```
// SEBELUM: user.service.ts (600 baris)

// SESUDAH:
user.service.ts          // orchestration, max 150 baris
user.query.service.ts    // read operations
user.command.service.ts  // write operations
user.notification.service.ts // side effects
```

### Handler yang Terlalu Besar
```
// SEBELUM: user.route.ts (400 baris)

// SESUDAH:
user.route.ts            // route registration only
user.handler.ts          // handler functions
user.middleware.ts        // route-specific middleware
```

### Types yang Terlalu Besar
```
// SEBELUM: types.ts (500 baris)

// SESUDAH:
types/user.types.ts
types/payment.types.ts
types/shared.types.ts
```

---

## Instruksi Khusus untuk AI

Ketika bekerja dalam project ini, **Claude wajib**:

1. **Menolak menambah kode** ke file yang sudah mendekati atau melebihi batas,
   kecuali penambahannya memang sangat kecil (< 10 baris) dan kohesif.

2. **Proaktif menyarankan refactor** saat mendeteksi file yang tumbuh tidak sehat,
   sebelum menambahkan fitur baru ke file tersebut.

3. **Tidak membuat "helper dump"** — setiap helper harus punya file sendiri
   yang namanya spesifik, bukan ditumpuk ke file utils yang ada.

4. **Selalu buat file baru** jika implementasi baru tidak secara alami masuk
   ke salah satu file yang sudah ada.

5. **Periksa ukuran file saat ini** sebelum mengedit — jika sudah > 80% dari
   batas, sarankan pecah terlebih dahulu.

---

## Pengecualian

File berikut **dikecualikan** dari aturan batas ukuran:

- `*.generated.ts` — file hasil code generation (Prisma, tRPC, dll)
- `*.migration.ts` / `*_migration.sql` — file migrasi database
- `*.seed.ts` — file seeding data
- File di folder `__fixtures__/` atau `__mocks__/`

Pengecualian **tidak berlaku** untuk file konfigurasi runtime seperti
`elysia.config.ts`, `app.ts`, atau `server.ts` — file ini tetap harus ringkas.

---

*Letakkan file ini di root project atau sertakan referensinya di `CLAUDE.md`.*