amaliadwiy
d299484a98
- lib/api.ts (879 baris) → 13 file di lib/api/ per domain - constants/Styles.ts (1.275 baris) → 10 file di constants/styles/ per domain - tambah docs/FILE-HEALTH.md dan referensinya ke CLAUDE.md - kedua file lama tetap sebagai re-export — zero breaking changes
134 lines
4.4 KiB
Markdown
134 lines
4.4 KiB
Markdown
# 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`.* |