Agent Operable Codebase

Image: AI generated

שאלה אחת

פתחו את הקובץ הארוך ביותר בפרויקט שלכם. כמה פונקציות יש בו?

בקשו מסוכן AI לתקן פונקציה אחת בקובץ הזה. הסוכן יקרא את הקובץ כולו. הוא פתח אותו בשביל פונקציה אחת, אבל 19 פונקציות מיותרות הגיעו איתה.

כאן מתחילה הבעיה.

קוד שבני אדם קוראים, קוד שסוכנים עובדים עליו

עד היום, קוד נכתב כדי שבני אדם יקראו אותו. שמות משתנים טובים, הערות, תיעוד – הכול כדי להפחית את העומס הקוגניטיבי האנושי.

בעידן הסוכנים, השאלה משתנה. האם קוד שקל לקריאה לבני אדם זהה לקוד שנוח לעבודת סוכן?

לא.

בן אדם גולל קובץ בן 2,000 שורות והאינטואיציה אומרת: “אל תיגע בחלק הזה.” לסוכן אין אינטואיציה כזו. קריאת 2,000 שורות פירושה 1,950 שורות של זיהום הקשרי.

מחקרים מאשרים זאת. כאשר מידע לא רלוונטי מעורבב, ביצועי ה-AI יורדים ב-30~85%. גם כשהטוקנים המיותרים הם רווחים, הביצועים נפגעים. הקשר קצר יותר עדיף – זו לא אינטואיציה, אלא תוצאה ניסויית.

אל תכניסו רובוט למשרד של בני אדם. בנו מפעל שבו הרובוט יכול לעבוד.

שלושה דברים שסוכן צריך

כדי שסוכן יעבוד בצורה יציבה על בסיס קוד, שלושה תנאים נדרשים.

1. לדעת לקרוא – בלי רעש

קובץ אחד, מושג אחד. שם הקובץ הוא שם המושג.

before: read utils.go → 20 פונקציות, 19 מיותרות
after:  read check_one_file_one_func.go → פונקציה 1, בדיוק מה שצריך

filefunc פותר את הבעיה הזו. 22 כללי מבנה מפרידים קוד ליחידות סמנטיות. בפריימוורק Hono (star 23k+), 186 קבצים פוצלו ל-626. 4,419 טסטים, אף אחד לא נשבר. מספר הקבצים גדל פי 3.4, אבל אף שורת לוגיקה לא השתנתה.

“לא יהיו יותר מדי קבצים?” – סוכנים לא פותחים תיקיות. הם מחפשים. בין אם 500 קבצים ובין אם 1,000 – grep אחד מספיק. חשוב יותר לא לפתוח 295 קבצים מיותרים מאשר לתפוס את 5 הנדרשים.

2. לדעת לאמת – מכנית

אם משנים פונקציה בלי טסטים, אף אחד לא יודע מה נשבר. גם הסוכן לא יודע. נלכד ב-doom loop.

before: 0 טסטים, לא ידוע מה נשבר בעת שינוי
after:  527 פונקציות עם טסטים, שינוי התנהגות מזוהה מיידית

tsma פותר את הבעיה הזו. מאנדקס את כל הפונקציות בפרויקט, מזהה קיום טסטים, מודד כיסוי, ומחזיר מספרי שורות של ענפים לא מכוסים.

בלי משוב, אם מבקשים מ-LLM לכתוב טסטים, הכיסוי נעצר ב-60~70%. אם אומרים “line 41, 44, 70 לא מכוסות”, הכיסוי מגיע ל-100%. אותו מודל. ההבדל: רק ברזולוציה של המשוב.

בניסוי עם פרויקט בן 527 פונקציות: TODO הגיע ל-0. הסוכן האוטונומי עצר ב-40 והכריז “סיימתי.” עם ratchet, כל 527 הושלמו.

3. מפרטים חייבים להיות ניתנים לאימות צולב

סכמת API, סכמת מסד נתונים, מדיניות אבטחה ומעברי מצב חייבים להיבדק מכנית לעקביות. כשמשנים אחד, חייבים לדעת לפני הקומפילציה אם נוצרת סתירה.

before: 200 endpoints, עקביות בין מפרטים נבדקת על ידי בני אדם
after:  operationId אחד משרשר את כל השכבות, המכונה מזהה drift

yongol פותר את הבעיה הזו. 10 SSOT (OpenAPI, DDL, sqlc, SSaC, Rego, Hurl ועוד) משורשרים על ידי operationId אחד ומאומתים צולבים על ידי ~287 כללים. user_id הוא string ב-OpenAPI אבל BIGINT ב-DDL – סתירות כאלה בין שכבות לא נתפסות בכלים קיימים.

מבנה אחד שחוצה שלושה כלים

filefunc, tsma, yongol הם כלים עצמאיים, אבל יש להם מבנה משותף.

filefunc:  22 כללי מבנה → validate → תיקון → חזרה
tsma:      מדידת כיסוי → משוב על ענפים לא מכוסים → תיקון → חזרה
yongol:    אימות צולב → זיהוי drift → תיקון → חזרה

הכול אותה לולאה.

LLM מייצר → כלי דטרמיניסטי שופט → התוצאה חוזרת ל-LLM → חזרה

Symbolic Feedback Loop. מבנה מחזורי שבו כלי דטרמיניסטי מתקן את הייצור ההסתברותי של LLM. לא AI מאמת AI, אלא מכונה מאמתת AI.

תנו דעה, והוא יחניף. תנו עובדה, והוא יתקן. שאלו “הקוד בסדר?” והוא יענה “כן, מצוין.” אמרו “line 41: field name mismatch” והוא מתקן מיד. משוב בלי אובייקט לחנופה – כי מספרים ומיקומים אינם רגשות.

מלגאסי ל-agent-operable

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

שלב 1 – לעשות קריא

מתחילים עם הקובץ הארוך ביותר. מריצים filefunc validate ומורידים הפרות ל-0. כל הטסטים הקיימים חייבים לעבור.

שלב 2 – לעשות ניתן לאימות

חוזרים על tsma next. מוסיפים טסטים לפונקציות ללא טסטים, ממלאים ענפים לא מכוסים. אם הסוכן מת באמצע, ההתקדמות נשמרת. סוכן חדש מריץ tsma next וממשיך.

שלב 3 – אימות צולב

מכניסים SSOT ומריצים yongol validate. המכונה תופסת סתירות בין שכבות.

כל שלב עצמאי. אפשר לעשות שלב 2 בלי שלב 1, או שלב 1 בלי שלב 2. אבל כששלושתם מתחברים, טווח העבודה האוטונומית של הסוכן מתרחב באופן דרמטי.

החלפת מערכת ההפעלה

Agent-operable codebase זה לא סתם lint או tooling. זו החלפת מערכת ההפעלה של בסיס הקוד.

הרבה אנשים מנסים להאיץ את הרכבת. מודלים גדולים יותר, סוכנים חכמים יותר, פרומפטים טובים יותר.

ככל שהרכבת מהירה יותר, כך הפסים חשובים יותר. אנשים שמניחים פסים כמעט ואינם.

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

• filefunc – קובץ אחד, מושג אחד – מוסכמת מבנה קוד שמסירה זיהום הקשרי של LLM עם 22 כללי מבנה
• tsma – קו ההגנה מפני רגרסיה בקוד לגאסי – אוטומציית טסטים מבוססת ratchet: 527 פונקציות עד TODO 0
• למה סוכני קידוד עובדים ולמה הם קורסים – ניתוח מבני של Symbolic Feedback Loop
• טופולוגיית משוב חשובה מ-IQ של מודל – למה אותו מודל נעצר ב-40 או משלים 527
• whyso – מה ש-git blame לא מראה – חילוץ אוטומטי של היסטוריית שינויים לפי קובץ

מקורות

• Stanford, “Lost in the Middle: How Language Models Use Long Contexts” (2024) – ירידת ביצועים של 30%+ כשמידע רלוונטי קבור באמצע ההקשר
• Amazon, “Context Length Alone Hurts LLM Performance” (2025) – ירידת ביצועים של 13.9~85% גם כשהטוקנים המיותרים הם רווחים
• הוכחה אמפירית מפריימוורק Hono – 186 קבצים → 626 קבצים, כל 4,419 הטסטים עברו
• הוכחה אמפירית tsma, 527 פונקציות – PASS 246 (46.7%), DONE 281 (53.3%), TODO 0
• ניסוי Ratchet Pattern – סוכן אוטונומי 40/527 (7.6%) לעומת ratchet CLI 527/527 (100%)