filefunc × Hono — קוד שסוכן קורא בבת אחת: מ-60 שורות ל-18

אם סוכן הקידוד שלכם שוב ושוב מתקן את הדבר הלא נכון בבסיס קוד גדול, אם ביקשתם ממנו לקרוא קובץ אחד וחזרו 19 פונקציות לא רלוונטיות שזיהמו את ה-context, אם אתם מפקפקים אם קונבנציה כמו “קובץ אחד — מושג אחד” באמת מועילה — הנה התוצאות ממדידה על פריימוורק מוכח של 23k כוכבים.

“לא יהיו יותר מדי קבצים?”

זו השאלה שמקבלים הכי הרבה על filefunc. אם מחלקים 186 קבצים ל-626 — האם זה לא בלתי ניתן לניהול?

התשובה נמצאת ב-Hono. פריימוורק אינטרנט קל-משקל שרץ על Cloudflare Workers, Deno, Bun ו-Node.js. 23k+ כוכבים, מיליון+ הורדות שבועיות מ-npm. קוד מוכח בייצור. ריפקטרנו את הקוד הזה עם filefunc. 4419 טסטים — כולם עברו. (ניתן לאמת ישירות ב-fork park-jun-woo/hono)

המספרים

הקבצים גדלו פי 3.4. השורות גדלו ב-23%. ההפרות ירדו מ-397 לאפס. אף טסט לא נשבר — ליתר דיוק, בדיוק אותם 4 טסטים נכשלו (פגמים שהיו קיימים במקור). עליית ה-23% בשורות מגיעה מ-annotations‏ (//ff:func, //ff:what) ומ-re-export hub. הלוגיקה לא השתנתה בשורה אחת. ריפקטרינג מבני טהור.

העיקר הוא לא מספר הקבצים — אלא אורך הקריאה

“0 הפרות, 626 קבצים” הוא למעשה proxy. המטרה האמיתית של filefunc אינה לפצל קבצים לפירורים — אלא לגרום לכך שכשסוכן קורא מושג אחד, הוא קורא רק אותו מושג, בלי שהקריאה תהיה ארוכה מדי. לכן המספר האמיתי שצריך להוכיח אינו מספר ההפרות — אלא אורך הקריאה לקובץ. מדדנו.

כשסוכן פותח מושג אחד, לפני כן היה בולע בממוצע 60 שורות — עכשיו 18. גם במקרה הגרוע (p90) ירד מ-305 שורות ל-120. אורך הפונקציות עצמן לא השתנה (חציון 11→12 שורות) — כמובן שלא. לא כתבנו מחדש את הפונקציות — סידרנו אותן מחדש. מה שהצטמצם הוא “הקוד הסביבתי שנאלצים לקרוא כדי להגיע למושג אחד”.

מדוע זה חשוב? context ארוך אינו בחינם. LLM מפספס בשיטתיות מידע שקבור באמצע קלט ארוך (Liu et al., Lost in the Middle, TACL 2023, arXiv:2307.03172). במשימות קידוד, כשה-context מתארך הביצועים צונחים בחדות — בבנצ’מרק אחד דיוק Claude 3.5 Sonnet קרס מ-29% ל-3% (Rando et al., LongCodeBench, 2025, arXiv:2505.07897). ולתת קוד חתוך לפי מושגים בדיוק — במקום לתת קבצים שלמים — משפר את איכות השלמת הקוד (Yusuf et al., 2025, arXiv:2510.06606). קיצור אורך הקריאה אינו העדפה אסתטית — הוא הגנה על דיוק.

בעיית types.ts

בואו נדבר בקונקרטי, לא באבסטרקטי. ב-src/types.ts המקורי של Hono היו יותר מ-20 ממשקים וטיפוסים.

אם סוכן AI רצה למצוא טיפוס HonoRequest אחד וקרא את הקובץ הזה? 19 טיפוסים לא רלוונטיים הגיעו איתו. זיהום context.

לאחר הריפקטרינג, כל טיפוס הוא קובץ עצמאי. אם צריך רק HonoRequest — קוראים רק את hono_request.ts. ה-types.ts המקורי נשמר כ-re-export hub כדי לשמר את נתיבי ה-import הקיימים.

# מקורי
import { HonoRequest } from './types'  // מגיעים 20+ טיפוסים

# לאחר ריפקטרינג
import { HonoRequest } from './types'  // אותו נתיב, אותה התנהגות
// פנימית: types.ts → re-export מ-hono_request.ts

מבחוץ — כלום לא השתנה. מבחינת סוכן AI — הכל השתנה.

מעומק 6 לעומק 2

אלגוריתם הניתוב של Hono מורכב. Node.search של trie-router היה בעומק קינון 6.

for → if → if → for → if → if   // depth 6

האם עומק 6 הוא קוד רע? לא. חיפוש trie מטבעו עמוק. אבל כדי שסוכן AI יבין את הפונקציה הזו, עליו להכניס לראש שש שכבות קינון בבת אחת. בני אדם גם כן. filefunc חילץ את הלוגיקה הפנימית לשיטות private ולפונקציות חץ ברמת המודול. עומק 6 → 2. כל חתיכה מכילה רק זרימת שליטה אחת. האלגוריתם הכולל זהה.

# מקורי: search מונוליתי
Node.search()   // depth 6, 100+ שורות

# לאחר ריפקטרינג: פירוק לחתיכות
Node.search()           // depth 2, אחראי על הרכבה בלבד
  → matchParam()        // depth 1, התאמת פרמטרים
  → matchWildcard()     // depth 1, טיפול ב-wildcard
  → mergeHandlers()     // depth 1, מיזוג handlers

הכלל F1 של TypeScript וזנב כנה

כלל הליבה F1 של filefunc הוא “קובץ אחד — פונקציה אחת”. ב-Go זה אינטואיטיבי. אבל ב-TypeScript, כשמפצלים קבצים, מערכת המודולים נשברת. אם מוציאים שיטת מחלקה לקובץ חיצוני, ה-this binding נעלם. לכן פרסר TypeScript של filefunc‏ (ts_ast.js) סופר רק הצהרות function ולא פונקציות חץ const arrow. העיקרון הוא “קובץ אחד — מושג אחד”, לא “דקדוקית function אחת בדיוק”.

כאן צריך להיות כנים. הגישה הזו הצליחה להפריד בנקיות את המקרים הקלים (טיפוסים, עוזרים בודדים), אבל לא הצליחה להפריד הכל. מדידה חוזרת לאחר הריפקטרינג מגלה:

• 90% מתוך 626 (566 קבצים) מכילים פונקציה ≤1 — מקיימים “קובץ 1 מושג 1”. (במקורי היה 70%.)
• אבל 60 קבצים (9.6%) עדיין מאכסנים 2+ פונקציות ביחד. וממש הם הארוכים — חציון השורות של 60 הקבצים הללו הוא 151. לדוגמה, src/utils/url.ts מכיל 14 פונקציות ב-319 שורות.

כלומר, טכניקת חץ const עוברת את המונה אבל מממשת את המטרה רק חלקית. אם נשארות מספר פונקציות חץ בקובץ אחד, הסוכן שפותח אותו עדיין קורא מספר מושגים. ברגע שמדד הופך למטרה, המדד מתדרדר (Goodhart). filefunc אינו יוצא מן הכלל — רוב סיכון read-length שנותר מרוכז ב-10% הזנב הזה. לא להעלות את מספר “0 הפרות” לדרגת תשובה מוחלטת, ולמדוד גם מה עדיין לא הושג — זו אמת מידה.

“אז מה בדיוק משתפר?”

כשיש 626 קבצים, בני אדם עשויים לחוש אי-נוחות. פותחים תיקייה — ושטף קבצים. אבל סוכן AI לא פותח תיקיות. הוא מריץ grep.

rg '//ff:func' --glob '*.ts' -l | head -20    # חילוץ קבצי מועמדים
rg '//ff:what.*router' --glob '*.ts'            # רק פונקציות הקשורות לניתוב

כשב-186 קבצים יש בממוצע 3-4 פונקציות, גם אם grep מוצא את הקובץ — הקריאה מביאה פונקציות מיותרות. כשב-626 קבצים יש מושג אחד לכל קובץ, הקובץ שמוצא grep = המושג הדרוש. שלב ביניים נעלם. ב"מציאת הקוד הרלוונטי (localization)" של סוכן — שהיא צוואר הבקבוק בפתרון בעיות downstream (Chen et al., LocAgent, 2025, arXiv:2503.09089) — filefunc מיישר מושגים עם גבולות קבצים והופך את החיפוש לדטרמיניסטי.

האם יחידת הפונקציה תמיד הנכונה?

בואו נסתכל גם על ראיות נגדיות בכנות. ניסוי מבוקר אחד מדווח שב-RAG להשלמת קוד “חלוקה לפי פונקציות נמוכה ב-3.6–5.6 נקודות אחוז ממדדים אחרים ואינה פארטו-אופטימלית” (Wu et al., 2026, arXiv:2605.04763). יחידת הפונקציה אינה פתרון קסמים.

אלא שמדובר בשכבה שונה לחלוטין. אותו ניסוי עוסק בהקשר שמנגנון חיפוש חותך קוד ודוחף לפרומפט — השלמה אוטומטית. filefunc עוסק ביחידת ההפעלה שבה סוכן בוחר ישירות קובץ וקורא אותו, לא ב-chunks שמנגנון חיפוש יוצר. אסטרטגיית chunking (retrieval chunk) ויחידת הפעלה (file an agent opens) הן שכבות שונות. ובכל זאת חשוב לציין את ההבחנה הזו מפורשות — “ככל שיחידה קטנה יותר תמיד טוב” אינה טענת filefunc. הטענה היא “כשהיחידה שסוכן קורא מתאימה למושג, אורך הקריאה מתקצר” — והמספרים לעיל מוכיחים זאת.

מגבלה היא חופש

מה שהתאשר בעת ריפקטרינג Hono עם filefunc הוא דבר אחד.

מגבלה מבנית אינה מגבילה קוד. היא משחררת חיפוש.

ריבוי קבצים הוא עלות. אבל כשכל קובץ מכיל מושג אחד בלבד, הסוכן קורא בדיוק את מה שנחוץ ואינו מזוהם מ-context מיותר — המדידה שאורך הקריאה ירד מ-60 שורות ל-18 היא הראיה לכך. בני אדם גם כן: כששם הפונקציה הוא שם הקובץ, התיקייה הופכת לתוכן עניינים.

397 הפרות הפכו ל-0, ו-4419 טסטים עברו בדיוק כמו המקור. ותוצאות אלו ניתן לאמת מחדש בדוח ריפקטרינג שב-README — כל אחד יכול להריץ. זו הראיה ש-“קובץ אחד — מושג אחד” אינה תיאוריה — היא פרקטיקה. כולל 9.6% הזנב שנותר.

מאמרים קשורים

• בסיס קוד שסוכן יכול להפעיל — “20 פונקציות בקובץ → ירידת ביצועים של 30–85%”, ההנחה הגבוהה יותר של מאמר זה
• filefunc: קובץ אחד — מושג אחד — הגדרת הקונבנציה עצמה; מאמר זה הוא ההוכחה בקנה מידה גדול
• בניית מערכות שסוכנים יכולים להפעיל — הסיפור הגדול של הפיכת ירושת קוד נעולה לנגישה לסוכנים
• Ratchet Pattern — שער דטרמיניסטי שגורם ל-4419 טסטים “להגיע עד הסוף כשהמכונה אומרת לעצור”

לקריאה נוספת (חיצוני)

• Effective context engineering for AI agents — Anthropic. מצביע על “context rot” ותקציב קשב מוגבל כבעיות מרכזיות — אותה תשתית שעליה filefunc מפחית context מיותר.
• Strategies and Tactics for working with Coding Agents — Brian Kihoon Lee. טוען לניווט מבוסס grep ועיצוב אדריכלות המידע ביד — ישירות מחובר לקונבנציית מבנה קבצים שגורמת לסוכן “לקרוא רק את המטרה”.
• The Vibes Don’t Scale — Paul Stack. המנגנון שבו vibe coding קורס לדריפט ארכיטקטוני בקנה מידה — “בעיית המודעות” שבסיס קוד גדול שובר סוכנים, שfilefunc מנסה לפתור.
• Agentic Engineering Patterns — Simon Willison. דפוסי ניהול context כמו Context Quarantine/Pruning — מרחיב את הטענה agent-operable של filefunc לשפת דפוסים מעשית.
• Agent Harness Engineering — Addy Osmani. ביצועי סוכן נקבעים מהתשתית הסביבתית יותר מהמודל — ממסגר קונבנציית מבנה קוד כציר אחד של ה-harness.

ביבליוגרפיה

• 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)
• אימות תוצאות ריפקטרינג: park-jun-woo/hono (filefunc Refactoring Report ב-README) · קונבנציה: filefunc
• תמונה ראשית: נוצרה על ידי AI‏ (Google Gemini)