איכות קוד עם בינה מלאכותית: כללי agent.md של פביאן סנגלאר

המתכנת פביאן סנגלאר פרסם ב-21 באוגוסט 2026 פוסט בשם "My agent.md to improve LLM-assisted code quality", ובו שיתף את קובץ ה-agent.md שלו — מסמך שכלי קידוד טוענים אוטומטית בראשית כל סשן.

מניסיון כושל לתהליך עבודה

סנגלאר נזכר בניסיון הראשון באמצע 2025: הוא עבד אז על libadbmdns, מימוש של mDNS ב-Rust, והקוד שנוצר לא עבר קומפילציה כלל. בינואר 2026 הוא שב למודלי שפה — הפעם המודל כתב מחלקה מורכבת של ערימה בינארית מאונדקסת, ואף איתר באג נסתר בחבילת polling שנבע ממימוש ה-IOCP של Windows.

אולם איכות הקוד הייתה גרועה: ספגטי בלי הערות ובלי מבנה. במרץ 2026 הוא עבר ל-IDE סוכניים כמו Antigravity ותוסף Claude Code של VS Code, שאיפשרו לעבור על הקוד באופן איטרטיבי. האיכות השתפרה באופן דרמטי — קרוב מאוד למה שהיה כותב בעצמו — אבל לחזור על אותן הצעות בכל סשן חדש היה מתיש.

מה יש בקובץ

את agent.md ממקמים בשורש הפרויקט; אפשר לקשר אליו בקישור סמלי את gemini.md או claude.md כדי שהכללים יחולו בכל מקום. בין הכללים של סנגלאר: להשתמש במינימום מילים בכל טקסט שמיועד לבני אדם; בלי שבחים — "תן לי את האמת הקרה"; להחליף מספרים קסומים בקבועים תיאוריים או ב-enum; לצמצם הזחה ולהימנע מדפוס החץ באמצעות return מוקדם; לשמור על שמות פונקציות קצרים מ-30 תווים; להשתמש ב-enum ולא ב-boolean בפרמטרים; להוסיף שורות ריקות בין בלוקים לוגיים; לכתוב הערות קצרות שמסבירות מה ולמה, ובמידת הצורך תרשימי ASCII; להתייחס לשינוי הרשאת גישה כאל שינוי עיצובי מחייב ולבקש אישור לפני הפיכת שדה או פונקציה ל-public; לתכנת לפי רמות הפשטה עם שכבת דרייבר נפרדת; לא לגעת בבלוקים לא קשורים ולמזער את מספר השורות שהשתנו; לכבד את היררכיית השכבות ולא "לנקב חורים" בהן; ולהשתמש תמיד בסוגריים מסולסלים, גם ב-if של שורה אחת.

הודעות קומיט ובדיקות

הקובץ כולל גם שבעה כללים להודעות קומיט: להפריד בין שורת הנושא לגוף בשורה ריקה; להגביל את הנושא ל-50 תווים (72 הוא הגבול המוחלט); לפתוח באות גדולה; בלי נקודה בסוף; להשתמש בלשון ציווי, עם מבחן ההשלמה של המשפט "If applied, this commit will..."; לשבור את גוף ההודעה ב-72 תווים; ולהסביר בגוף את ה"מה" וה"למה" ולא את ה"איך". בתיקון באגים הכלל הוא תהליכי: קודם לכתוב את הבדיקה, לראות שהיא נכשלת, ואז לכתוב את התיקון ולראות שהיא עוברת.

מגבלות: הזיות ודילול הקשר

סנגלאר מדגיש שזה אינו כדור קסם. מודלי שפה מהזים כל הזמן ואין לתת בהם אמון, ולכן עדיין צריך לבדוק ולעדכן — אלא שכעת הוא מתמקד בארכיטקטורה ובעיצוב ולא בסגנון הקוד. בעיה שנייה היא דילול ההקשר או הקשב, המתואר במאמר Lost in the Middle: ככל שההקשר גדל, המודל מקדיש פחות קשב להוראות שבאמצע ויותר למה שנמצא בהתחלה ובסוף.

הוא מצא שתי דרכים לצמצם את ההשפעה: לשמור על הקשר קצר על ידי פתיחת סשן חדש לכל פיצ'ר, ולבקש מפורשות מהכלי לטעון מחדש את agent.md כשהאיכות יורדת — הצירוף "Reload agent.md" מספיק. כדי להוסיף כלל אין צורך לפתוח עורך: הוא מבקש מהסוכן לעדכן את agent.md בעצמו.