איך גרמתי ל-AI להפסיק להזות על בסיס הקוד שלנו
כלי קוד מבוססי AI נכשלים בפרויקטים אמיתיים בסביבת ייצור (production). הם עובדים טוב על קוד חדש, אך מתפרקים מול קוד ישן עם היסטוריה.
לפרויקט הפינטק שלנו יש שלוש שנות היסטוריה. יש לו שני frontends ב-React, פאנל ניהול (admin panel), ו-backend ב-FastAPI. מסד הנתונים מורכב, עם טבלאות רבות ו-joins כבדים.
ניסינו להשתמש ב-AI כדי להתקדם מהר יותר. זה נכשל.
ביקשתי מה-AI ליצור טבלת אנשי קשר (contacts). הוא יצר עמודות חדשות לשמות ואימיילים, מבלי להבין שכבר יש לנו אותם בטבלת המשתמשים (users table). הוא הכפיל נתונים במקום להשתמש במפתח זר (foreign key).
ה-AI לא היה טיפש. פשוט לא היה לו הקשר (context). הוא קיבל החלטה עם מידע חסר.
הפסקתי לשאול איך לקבל קוד טוב יותר. התחלתי לשאול איזה הקשר ה-AI צריך כדי לקבל החלטות טובות.
בנינו תהליך עבודה מובנה. ה-AI טוב רק ככל שההקשר שאתם מספקים לו טוב יותר. הפכנו את ההקשר הזה למפורש.
הנה המבנה שלנו:
- תיקיית ADR: יצרנו תיקייה עבור Architecture Decision Records. קבצים אלו מסבירים מדוע קיבלנו החלטות מסוימות. קובץ אחד מורה ל-AI לבדוק טבלאות קיימות לפני יצירת חדשות, ואוסר על הכפלת נתוני משתמשים.
- context.md: קובץ זה מסביר את המונחים הספציפיים שלנו. הוא אומר ל-AI איך המילים הייחודיות שלנו קשורות זו לזו.
- plot.md: מספק מפה ברמה גבוהה של הפרויקט וכיצד החלקים השונים מתחברים.
- בדיקות חובה: כל נתיב API חדש דורש מקרי בדיקה (test cases).
זה שינה הכל. פעם אחת, ה-AI שינה פונקציית עזר (utility function) משותפת. השינוי שבר שמונה חלקים אחרים במערכת. מערכת הבדיקות (test suite) תפסה זאת מיד. ה-AI זיהה את הכשל ותיקן את הטעות שלו על ידי יצירת גרסה שמטפלת גם בדרישות הישנות וגם בחדשות.
ללא בדיקות, הבאג הזה היה מגיע לסביבת ייצור.
התייחסו ל-AI כמו למפתח חדש. אתם לא מאשימים עובד חדש על כך שהוא לא מכיר את בסיס הקוד שלכם. אתם מספקים תיעוד ותהליך קליטה (onboarding). עשינו את אותו הדבר עבור ה-AI.
המבנה שלנו:
- docs/context.md: מונחי פרויקט וקשרים ביניהם.
- docs/plot.md: מפה ברמה גבוהה של בסיס הקוד.
- docs/adr/: כללים ספציפיים כמו יצירת טבלאות ומבנה ה-API.
שלושה כללים לצוות שלכם:
- היו ספציפיים ב-ADRs. השתמשו בהוראות ברורות במקום בעצות מעורפלות.
- הפכו את התיעוד לסמכותי. אמרו ל-AI שהכללים הללו קודמים לכל.
- הפכו טעויות לכללים. בכל פעם שה-AI נכשל, כתבו ADR חדש.
המערכת הזו לא הופכת את ה-AI למושלם. היא הופכת אותו לצפוי. אנחנו רוצים בסיס קוד שבו ה-AI עקבי, כדי שהצוות יוכל להתקדם מהר יותר.