Wenn ein Coding-Agent in einer großen Codebasis immer wieder das Falsche ändert, wenn man ihn eine Datei lesen lässt und 19 irrelevante Funktionen den context verschmutzen, wenn man bezweifelt, ob Konventionen wie „1 Datei, 1 Konzept" wirklich etwas bringen — hier sind die Messergebnisse aus einem Praxis-Framework mit 23k Stars.
„Werden es nicht zu viele Dateien?"
Das ist die häufigste Frage zu filefunc. 186 Dateien auf 626 aufzuteilen — ob das nicht unverwaltbar wird.
Die Antwort steckt in Hono. Ein ultraleichtes Webframework, das auf Cloudflare Workers, Deno, Bun und Node.js läuft. Über 23k Stars, mehr als 1 Million npm-Downloads pro Woche. Praxiserprobter Code aus der Produktion. Diesen Code haben wir mit filefunc refaktoriert. 4419 Tests — alle bestanden. (Direkt nachprüfbar im Fork park-jun-woo/hono)
Die Zahlen
| Kennzahl | Original | Nach Refaktorierung |
|---|---|---|
| Quelldateien | 186 | 626 |
| Gesamtzeilen | 24.653 | 30.244 |
| filefunc-Verstöße | 397 | 0 |
| vitest bestanden | 4419 | 4419 |
| vitest fehlgeschlagen | 4 | 4 (vorhandene Defekte) |
| vitest übersprungen | 33 | 33 |
Dateien: 3,4-fach mehr. Zeilen: 23 % mehr. Verstöße: von 397 auf 0. Kein einziger Test brach — genauer gesagt schlugen exakt dieselben 4 Tests fehl wie im Original (vorhandene Defekte). Die 23 % mehr Zeilen kommen von Annotationen (//ff:func, //ff:what) und re-export hubs. Kein einziges Bit Logik wurde verändert. Reine Strukturrefaktorierung.
Nicht die Dateianzahl, sondern die Leselänge ist entscheidend
„0 Verstöße, 626 Dateien" ist eigentlich nur ein Proxy. Das eigentliche Ziel von filefunc ist nicht, Dateien zu zerkleinern — es geht darum, dass ein Agent beim Lesen eines Konzepts genau dieses Konzept liest, nicht länger als nötig. Die Zahl, die wirklich zählt, ist daher nicht die Anzahl der Verstöße, sondern die Leselänge pro Datei. Wir haben sie gemessen.
| Zeilen pro Datei | Original | Nach Refaktorierung |
|---|---|---|
| Median | 60,0 | 17,5 (−71 %) |
| p90 | 305 | 119 (−61 %) |
| Maximum | 2.778 | 1.051 (−62 %) |
| Anteil Dateien ≤ 20 Zeilen | 26 % | 54 % |
Öffnet ein Agent ein Konzept, schluckt er bisher im Schnitt 60 Zeilen — jetzt 18. Selbst im schlechtesten Fall (p90) fiel der Wert von 305 auf 120 Zeilen. Die Länge der Funktionen selbst blieb gleich (Median 11→12 Zeilen) — logisch, denn die Funktionen wurden nicht neu geschrieben, sondern neu angeordnet. Was schrumpfte, ist der „Umgebungscode, den man zwangsläufig mitliest, wenn man ein Konzept sucht".
Warum das wichtig ist: Langer context ist nicht kostenlos. LLMs verpassen systematisch Informationen, die in der Mitte langer Eingaben vergraben sind (Liu et al., Lost in the Middle, TACL 2023, arXiv:2307.03172). Bei Coding-Aufgaben bricht die Leistung mit wachsendem context ein — in einem Benchmark fiel die Genauigkeit von Claude 3.5 Sonnet von 29 % auf 3 % (Rando et al., LongCodeBench, 2025, arXiv:2505.07897). Und die Qualität der Code-Vervollständigung steigt, wenn man genau die benötigten Teile in konzeptuellen Einheiten anstatt ganze Dateien liefert (Yusuf et al., 2025, arXiv:2510.06606). Die Leselänge zu kürzen ist kein ästhetisches Ideal, sondern Genauigkeitsverteidigung.
Das types.ts-Problem
Statt Abstraktion: ein konkretes Beispiel. Die ursprüngliche src/types.ts von Hono enthielt über 20 Interfaces und Typen.
Wenn ein KI-Agent diesen einen Typ HonoRequest sucht und die Datei liest, schleppen sich 19 unnötige Typen mit. context-Verschmutzung.
Nach der Refaktorierung ist jeder Typ eine eigene Datei. Braucht man nur HonoRequest, liest man nur hono_request.ts. Die ursprüngliche types.ts bleibt als re-export hub erhalten, sodass bestehende Import-Pfade unverändert funktionieren.
# Original
import { HonoRequest } from './types' // 20+ Typen kommen mit
# Nach Refaktorierung
import { HonoRequest } from './types' // gleicher Pfad, gleiches Verhalten
// intern: types.ts → hono_request.ts re-export
Von außen hat sich nichts geändert. Für den KI-Agenten hat sich alles geändert.
Verschachtelungstiefe von 6 auf 2
Der Router-Algorithmus von Hono ist komplex. Node.search im trie-router hatte eine Verschachtelungstiefe von 6.
for → if → if → for → if → if // Tiefe 6
Ist Tiefe 6 schlechter Code? Nein. Trie-Suche ist von Natur aus tief verschachtelt. Aber damit ein KI-Agent diese Funktion versteht, muss er 6 Schachtelungsebenen auf einmal im Kopf behalten. Für Menschen gilt dasselbe. filefunc extrahierte die interne Logik in private Methoden und Pfeilfunktionen auf Modulebene. Tiefe 6 → 2. Jedes Teilstück hat genau einen Kontrollfluss. Der Gesamtalgorithmus ist identisch.
# Original: monolithisches search
Node.search() // Tiefe 6, 100+ Zeilen
# Refaktoriert: in Teile zerlegt
Node.search() // Tiefe 2, nur Komposition
→ matchParam() // Tiefe 1, Parameter-Matching
→ matchWildcard() // Tiefe 1, Wildcard-Verarbeitung
→ mergeHandlers() // Tiefe 1, Handler-Zusammenführung
TypeScripts F1 und ein ehrlicher Schwanz
Die Kernregel F1 von filefunc lautet: „Eine Datei, eine Funktion." In Go ist das intuitiv. Aber in TypeScript zerbricht das Modulsystem, wenn man Dateien aufteilt. Klassenmethoden in externe Dateien zu ziehen zerstört this-Bindungen. Deshalb zählt der TypeScript-Parser von filefunc (ts_ast.js) nur function-Deklarationen und ignoriert const-Pfeilfunktionen. Das Prinzip lautet „eine Datei, ein Konzept" — nicht „syntaktisch genau eine function".
Hier muss man ehrlich sein. Dieser Ansatz trennte einfache Fälle (Typen, einzelne Helfer) sauber — aber nicht alles ließ sich trennen. Misst man das Ergebnis nochmals:
- Von 626 Dateien haben 90 % (566 Dateien) ≤ 1 Funktion — „1 Datei, 1 Konzept" ist erfüllt. (Im Original waren es 70 %.)
- Aber 60 Dateien (9,6 %) beherbergen noch 2 oder mehr Funktionen gleichzeitig. Und ausgerechnet diese sind lang — der Zeilen-Median dieser 60 Dateien beträgt 151. Zum Beispiel enthält
src/utils/url.ts14 Funktionen in 319 Zeilen.
Das const-Pfeilfunktions-Verfahren passiert den Zähler, erreicht das Ziel aber nur teilweise. Bleiben mehrere Pfeilfunktionen in einer Datei, liest der Agent beim Öffnen dieser Datei noch immer mehrere Konzepte. Sobald eine Metrik zum Ziel wird, verrät sie ihren Zweck (Goodhart). filefunc ist keine Ausnahme — der Großteil des verbleibenden Leselängenrisikos konzentriert sich in diesem 10 %-Schwanz. Nicht die Zahl „0 Verstöße" zur endgültigen Antwort zu erklären, sondern auch zu messen, was noch nicht erreicht ist — das ist Verifikation.
„Was verbessert sich konkret?"
Wenn es 626 Dateien gibt, können Menschen sich unwohl fühlen. Ein Verzeichnis öffnen und Dateien strömen herein. Aber KI-Agenten öffnen keine Verzeichnisse. Sie grep-pen.
rg '//ff:func' --glob '*.ts' -l | head -20 # Kandidatendateien extrahieren
rg '//ff:what.*router' --glob '*.ts' # Nur router-bezogene Funktionen
Wenn 186 Dateien je 3–4 Funktionen enthalten, liefert grep zwar die Datei, aber beim Lesen schleppen sich unnötige Funktionen mit. Wenn 626 Dateien je ein Konzept enthalten, ist die von grep gefundene Datei = das benötigte Konzept. Der Zwischenschritt entfällt. Bei der Codesuche von Agenten ist „relevante Stellen finden (Lokalisierung)" der Flaschenhals für nachgelagerte Problemlösung (Chen et al., LocAgent, 2025, arXiv:2503.09089). filefunc macht diese Suche deterministisch, indem es Konzepte mit Dateigrenzen in Deckung bringt.
Ist die Funktionseinheit immer die richtige Wahl?
Gegenevidenzen sollen ebenfalls ehrlich betrachtet werden. Ein kontrolliertes Experiment berichtet, dass „Funktionseinheits-Chunking bei RAG-Code-Autovervollständigung 3,6–5,6 Prozentpunkte unter anderen Strategien liegt und nicht Pareto-optimal ist" (Wu et al., 2026, arXiv:2605.04763). Funktionseinheiten sind kein Allheilmittel.
Allerdings handelt es sich hier um eine andere Ebene. Jenes Experiment betrifft den Autovervollständigungs-context, in dem ein Retriever Code zerschneidet und ins Prompt stopft. filefunc behandelt nicht das Chunking durch den Retriever, sondern die Betriebseinheit, bei der ein Agent eine Datei selbst auswählt und liest. Chunking-Strategie (retrieval chunk) und Betriebseinheit (file an agent opens) sind verschiedene Schichten. Trotzdem ist es wichtig, diese Unterscheidung explizit zu machen — „kleiner teilen ist immer besser" ist eine Übertreibung, die filefunc nicht behauptet. Die Aussage lautet: „Wenn die Einheit, die ein Agent liest, mit einem Konzept übereinstimmt, verkürzt sich die Leselänge" — und die obigen Zahlen zeigen genau das.
Einschränkung ist Freiheit
Was die Refaktorierung von Hono mit filefunc bestätigte, ist eine einzige Erkenntnis.
Strukturelle Einschränkung begrenzt den Code nicht. Sie befreit die Navigation.
Mehr Dateien sind ein Kostenfaktor. Aber wenn jede Datei nur ein Konzept trägt, liest der Agent genau das, was er braucht, und bleibt frei von unnötigem context — die Messung, dass die Leselänge von 60 auf 18 Zeilen sank, ist der Beweis. Für Menschen gilt dasselbe: Wenn der Funktionsname der Dateiname ist, wird das Verzeichnis zum Inhaltsverzeichnis.
397 Verstöße wurden zu 0, 4419 Tests bestanden — identisch wie im Original. Und das Ergebnis kann jeder im Refactoring Report des README selbst nachvollziehen. Das ist der Beweis, dass „1 Datei, 1 Konzept" nicht Theorie, sondern Praxis ist. Einschließlich der verbleibenden 9,6 % im Schwanz.
Verwandte Artikel
- Eine agent-operable Codebasis — „20 Funktionen in einer Datei senken die Agentenleistung um 30–85 %", die übergeordnete These dieses Artikels
- filefunc: Eine Datei, ein Konzept — Die Definition der Konvention selbst. Dieser Artikel ist deren großangelegte empirische Bestätigung
- Agent-operable Systeme bauen — Die Makro-Erzählung, wie man gesperrte Legacy-Systeme für Agenten öffnet
- Ratchet Pattern — Das deterministische Gate, das sicherstellt, dass 4419 Tests „bis die Maschine stoppt" durchlaufen
Weiterführende Lektüre (extern)
- Effective context engineering for AI agents — Anthropic. Benennt „context rot" und begrenzte Aufmerksamkeitsbudgets als Kernproblem — dieselbe Grundlage, auf der filefunc unnötigen context reduziert.
- Strategies and Tactics for working with Coding Agents — Brian Kihoon Lee. Plädiert dafür, grep-basierte Navigation und Informationsarchitektur bewusst zu gestalten — direkt verbunden mit Dateistrukturkonventionen, die Agenten „nur das Ziel lesen" lassen.
- The Vibes Don’t Scale — Paul Stack. Der Mechanismus, durch den Vibe Coding im großen Maßstab an Architektur-Drift zerbricht — das Problembewusstsein, das filefunc angeht: „große Codebasen brechen Agenten."
- Agentic Engineering Patterns — Simon Willison. Context Quarantine/Pruning und weitere context-Management-Muster — erweitert filefuncs agent-operable-Anspruch in eine praktische Mustersprache.
- Agent Harness Engineering — Addy Osmani. Agentenleistung entscheidet sich mehr in der umgebenden Infrastruktur als im Modell — rekontextualisiert Codestrukturkonventionen als eine Achse des Harness.
Bibliographie
- 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)
- Refaktorierungsergebnis verifizierbar unter: park-jun-woo/hono (filefunc Refactoring Report im README) · Konvention: filefunc
- Titelbild: KI-generiert (Google Gemini)