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

מה זה AGENTS.md?

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

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

קובץ AGENTS.md שימושי מפנה לראיות

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

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

• מטרה: איזה תהליך עסקי המודול משרת.
• אילוץ: איזו התנהגות המשימה חייבת לשמר.
• ראיות: מיקום המפרט המתוחזק והבדיקות.
• אימות: תיקיית העבודה והפקודה המדויקות.
• אי־ודאות: מי מכריע בסתירה בין הקוד למדיניות המתועדת.

מפרידים ידע קבוע מהמשימה של היום

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

CLAUDE.md הוא המנגנון המתועד של Claude Code להנחיות מתמשכות. התיעוד מבחין בין כללים שנכתבו במפורש לבין הערות שנצברות בזיכרון האוטומטי. כשכמה כלים עובדים באותו מאגר, בדקו כיצד הם טוענים הנחיות בפועל ושמרו מקור מתוחזק אחד לעובדות המשותפות. אל תניחו שמנגנון האיתור או סדר העדיפויות זהים רק מפני ששני כלים יכולים לקרוא Markdown.

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

הנחיות מכוונות את העבודה; בקרות אוכפות גבולות

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

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

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

תחזוקת ההקשר היא חלק מהאחריות למערכת

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

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