Jika coding agent Anda terus memperbaiki hal yang salah di codebase besar, jika membaca satu file membawa 19 fungsi tidak relevan yang mencemari context, jika Anda ragu apakah konvensi seperti “1 file 1 konsep” benar-benar efektif — di sinilah hasil pengukuran dari framework produksi bintang 23k.
“Bukankah File Jadi Terlalu Banyak?”
Itulah pertanyaan yang paling sering diterima tentang filefunc. Memecah 186 file menjadi 626 — bukankah itu tidak bisa dikelola?
Jawabannya ada di Hono. Framework web ultra-ringan yang berjalan di Cloudflare Workers, Deno, Bun, dan Node.js. Bintang 23k+, unduhan mingguan npm 1 juta+. Kode produksi yang telah tervalidasi di dunia nyata. Kami merefaktor kode ini menggunakan filefunc. Semua 4419 tes lolos. (Bisa diverifikasi langsung di fork park-jun-woo/hono)
Angka-Angka
| Metrik | Asli | Setelah Refaktor |
|---|---|---|
| File sumber | 186 | 626 |
| Total baris | 24.653 | 30.244 |
| Pelanggaran filefunc | 397 | 0 |
| vitest lolos | 4419 | 4419 |
| vitest gagal | 4 | 4 (cacat lama) |
| vitest dilewati | 33 | 33 |
File bertambah 3,4 kali lipat. Baris bertambah 23%. Pelanggaran turun dari 397 menjadi 0. Tidak satu tes pun yang rusak — tepatnya sama seperti aslinya, 4 tes gagal (cacat yang sudah ada sejak versi awal). Kenaikan 23% baris berasal dari anotasi (//ff:func, //ff:what) dan re-export hub. Tidak satu baris logika pun berubah. Refaktor murni struktural.
Kuncinya Bukan Jumlah File, Melainkan ‘Panjang Baca’
“Pelanggaran 0, 626 file” sebenarnya hanyalah sebuah proksi. Tujuan sejati filefunc bukan memecah file menjadi sekecil mungkin — melainkan memastikan agen hanya membaca konsep yang dibutuhkan, tidak lebih panjang dari yang perlu. Maka angka yang sebenarnya harus dibuktikan bukan jumlah pelanggaran, melainkan panjang baca per file. Kami mengukurnya.
| Baris per file | Asli | Setelah Refaktor |
|---|---|---|
| Median | 60,0 | 17,5 (−71%) |
| p90 | 305 | 119 (−61%) |
| Maksimum | 2.778 | 1.051 (−62%) |
| Proporsi file ≤20 baris | 26% | 54% |
Ketika agen membuka satu konsep, dulu ia menelan rata-rata 60 baris, kini hanya 18. Bahkan kasus terburuk (p90) turun dari 305 baris menjadi 120. Panjang fungsi itu sendiri tidak berubah (median 11→12 baris) — wajar saja. Yang kami lakukan bukan menulis ulang fungsi, melainkan memposisikan ulang. Yang berkurang adalah “kode sekitar yang terpaksa ikut terbaca saat membuka satu konsep.”
Mengapa ini penting? Context yang panjang tidak gratis. LLM secara sistematis melewatkan informasi yang terkubur di tengah input yang panjang (Liu et al., Lost in the Middle, TACL 2023, arXiv:2307.03172). Pada tugas coding, performa anjlok tajam seiring bertambahnya panjang konteks — dalam satu benchmark, akurasi Claude 3.5 Sonnet runtuh dari 29% menjadi 3% (Rando et al., LongCodeBench, 2025, arXiv:2505.07897). Dan memberikan potongan tepat per konsep alih-alih seluruh file menghasilkan kualitas code completion yang lebih tinggi (Yusuf et al., 2025, arXiv:2510.06606). Mempersingkat panjang baca bukan soal selera — ini adalah pertahanan akurasi.
Masalah types.ts
Mari kita lihat konkretnya, bukan abstrak. src/types.ts asli Hono berisi lebih dari 20 antarmuka dan tipe.
Apa yang terjadi ketika agen AI membuka file ini hanya untuk mencari satu tipe HonoRequest? Sembilan belas tipe tidak relevan ikut terbawa. Pencemaran context.
Setelah refaktor, setiap tipe menjadi file tersendiri. Untuk HonoRequest, cukup buka hono_request.ts saja. types.ts asli dipertahankan sebagai re-export hub sehingga jalur import lama tetap terjaga.
# Asli
import { HonoRequest } from './types' // 20+ tipe ikut masuk
# Setelah refaktor
import { HonoRequest } from './types' // jalur sama, perilaku sama
// di balik layar: types.ts → re-export dari hono_request.ts
Dari luar, tidak ada yang berubah. Dari sudut pandang agen AI, semuanya berubah.
Dari Kedalaman 6 Menjadi 2
Algoritma router Hono itu kompleks. Node.search di trie-router memiliki nesting depth 6.
for → if → if → for → if → if // depth 6
Apakah depth 6 itu kode yang buruk? Tidak. Penelusuran trie memang pada dasarnya dalam. Namun agar agen AI memahami fungsi ini, ia harus memasukkan 6 level nesting ke dalam memorinya sekaligus. Begitu pula manusia. filefunc mengekstrak logika internal ke private method dan fungsi panah di level modul. Depth 6 → 2. Setiap potongan hanya memiliki satu alur kontrol. Keseluruhan algoritma tetap sama.
# Asli: search monolitik
Node.search() // depth 6, 100+ baris
# Setelah refaktor: dipecah menjadi bagian-bagian
Node.search() // depth 2, hanya mengorkestrasi
→ matchParam() // depth 1, pencocokan parameter
→ matchWildcard() // depth 1, penanganan wildcard
→ mergeHandlers() // depth 1, penggabungan handler
F1 TypeScript dan Ekor yang Jujur
Aturan inti F1 filefunc adalah “satu file, satu fungsi.” Dalam Go, ini intuitif. Namun saat memecah file di TypeScript, sistem modul bisa rusak. Memindahkan method kelas ke file eksternal menghilangkan binding this. Itulah mengapa parser TypeScript filefunc (ts_ast.js) hanya menghitung deklarasi function dan tidak menghitung fungsi panah const. Prinsipnya adalah “satu file, satu konsep,” bukan “tepat satu function secara sintaksis.”
Di sini kita harus jujur. Pendekatan ini memisahkan kasus mudah (tipe, helper tunggal) dengan bersih, tetapi tidak semua bisa dipisahkan. Jika kita mengukur ulang hasil refaktor:
- 90% dari 626 file (566 file) memiliki fungsi ≤1 — memenuhi “1 file 1 konsep.” (Aslinya 70%.)
- Namun 60 file (9,6%) masih menyimpan 2 fungsi atau lebih bersama-sama. Dan ironisnya itulah yang panjang — median baris dari 60 file ini adalah 151. Misalnya
src/utils/url.tsmengandung 14 fungsi dalam 319 baris.
Artinya, teknik const panah lolos penghitung tapi hanya sebagian mencapai tujuan. Jika banyak fungsi panah tersisa dalam satu file, agen masih membaca beberapa konsep ketika membuka file itu. Begitu metrik menjadi tujuan, metrik itu rusak (Goodhart). filefunc tidak terkecuali — sebagian besar risiko read-length yang tersisa terkonsentrasi di 10% ekor ini. Tidak mengangkat angka “pelanggaran 0” sebagai jawaban final, dan tetap mengukur apa yang belum selesai — itulah validasi.
“Jadi Apa yang Lebih Baik?”
Dengan 626 file, manusia mungkin tidak nyaman. Buka direktori, file berhamburan. Namun agen AI tidak membuka direktori. Ia melakukan grep.
rg '//ff:func' --glob '*.ts' -l | head -20 # ekstrak file kandidat
rg '//ff:what.*router' --glob '*.ts' # hanya fungsi terkait router
Jika 186 file masing-masing berisi rata-rata 3–4 fungsi, grep menemukan file tapi saat dibaca fungsi yang tidak perlu ikut masuk. Jika 626 file masing-masing berisi 1 konsep, file yang ditemukan grep = konsep yang dibutuhkan. Langkah perantara hilang. Dalam eksplorasi kode oleh agen, “lokalisasi” (menemukan posisi relevan) adalah bottleneck untuk pemecahan masalah hilir (Chen et al., LocAgent, 2025, arXiv:2503.09089), dan filefunc membuat pencarian ini deterministik dengan menyelaraskan konsep dengan batas file.
Apakah Unit Fungsi Selalu Jawaban yang Tepat?
Mari kita lihat bukti yang bertentangan dengan jujur. Satu eksperimen terkontrol melaporkan bahwa “chunking berbasis fungsi 3,6–5,6pp lebih rendah dari strategi lain dan bukan Pareto-optimal” untuk RAG code completion (Wu et al., 2026, arXiv:2605.04763). Unit fungsi bukan obat mujarab.
Namun ini adalah diskusi pada lapisan yang berbeda. Eksperimen itu berada dalam konteks autocomplete di mana retriever memotong kode dan menyusunnya ke dalam prompt. filefunc berurusan dengan unit operasional di mana agen memilih dan membuka file secara langsung. Strategi chunking (retrieval chunk) dan unit operasional (file yang dibuka agen) adalah lapisan berbeda. Meski begitu, penting untuk menyatakan perbedaan ini secara eksplisit — “semakin kecil semakin baik tanpa syarat” bukan klaim filefunc. Klaimnya adalah “ketika unit yang dibaca agen selaras dengan konsep, panjang baca memendek,” dan angka di atas menunjukkannya.
Batasan adalah Kebebasan
Satu hal yang terkonfirmasi dari merefaktor Hono dengan filefunc.
Batasan struktural tidak membatasi kode. Ia membebaskan eksplorasi.
Bertambahnya jumlah file adalah biaya. Namun ketika setiap file hanya memuat satu konsep, agen membaca tepat apa yang dibutuhkan dan tidak tercemar context yang tidak perlu — pengukuran yang menunjukkan panjang baca turun dari 60 baris menjadi 18 adalah buktinya. Begitu pula manusia. Ketika nama fungsi adalah nama file, direktori menjadi daftar isi.
397 pelanggaran menjadi 0, dan 4419 tes lolos sama seperti versi aslinya. Hasilnya bisa dijalankan ulang oleh siapa saja melalui laporan refaktor di README. Inilah bukti bahwa “1 file 1 konsep” bukan teori melainkan praktik nyata. Termasuk 9,6% ekor yang tersisa.
Artikel Terkait
- Codebase yang Dapat Dioperasikan Agen — “20 fungsi dalam satu file menurunkan performa agen 30–85%”, premis yang menjadi fondasi artikel ini
- filefunc: Satu File, Satu Konsep — Definisi konvensi itu sendiri. Artikel ini adalah demonstrasi skalanya
- Membangun Sistem yang Dapat Dioperasikan Agen — Narasi makro tentang membuat legacy terkunci dapat dibuka oleh agen
- Ratchet Pattern — Gate deterministik yang membuat 4419 tes “terus berjalan sampai mesin menyuruh berhenti”
Bacaan lanjutan (eksternal)
- Effective context engineering for AI agents — Anthropic. Sumber primer yang mengidentifikasi “context rot” dan anggaran atensi yang terbatas sebagai masalah inti — landasan yang sama dengan alasan filefunc mengurangi context yang tidak perlu.
- Strategies and Tactics for working with Coding Agents — Brian Kihoon Lee. Argumen untuk merancang sendiri eksplorasi berbasis grep dan arsitektur informasi — terhubung langsung dengan konvensi struktur file yang membuat agen “hanya membaca target.”
- The Vibes Don’t Scale — Paul Stack. Mekanisme di mana vibe coding runtuh menjadi architectural drift di skala besar — kesadaran masalah “codebase besar yang merusak agen” yang ingin diselesaikan filefunc.
- Agentic Engineering Patterns — Simon Willison. Pola manajemen context seperti Context Quarantine/Pruning — memperluas klaim agent-operable filefunc ke dalam bahasa pola praktis.
- Agent Harness Engineering — Addy Osmani. Performa agen lebih ditentukan oleh infrastruktur sekitar daripada model itu sendiri — mengontekstualisasikan ulang konvensi struktur kode sebagai salah satu poros harness.
Bibliografi
- Liu et al. “Lost in the Middle: How Language Models Use Long Contexts” (TACL 2023, arXiv:2307.03172)
- Rando et al. “LongCodeBench: Evaluating Coding LLMs at 1M Context Windows” (2025, arXiv:2505.07897)
- Yusuf et al. “Beyond More Context: How Granularity and Order Drive Code Completion Quality” (2025, arXiv:2510.06606)
- Chen et al. “LocAgent: Graph-Guided LLM Agents for Code Localization” (2025, arXiv:2503.09089)
- Wu et al. “How Does Chunking Affect Retrieval-Augmented Code Completion? A Controlled Empirical Study” (2026, arXiv:2605.04763)
- Verifikasi hasil refaktor: park-jun-woo/hono (filefunc Refactoring Report di README) · Konvensi: filefunc
- Gambar utama: dihasilkan AI (Google Gemini)