איך כותבים PR description לקוד שסוכן AI כתב?
בפוסט שלי על האחריות לשינוי כתבתי שכבר בנינו בצוות אוטומציות לפתיחת PR, ל-self review, לתיקון קונפליקטים ולעבודה על הערות review. הדגש שלי עבר להסבר הבעיה, ההחלטה והסיכונים. המדריך הזה מציע דרך להפוך את הדגש הזה לתהליך שאפשר לחזור עליו.
בקצרה
מתחילים מהבעיה ומההחלטה, אחר כך מתארים את השינוי, הסיכונים וראיות הבדיקה. נותנים למי שעושה review דרך להבין למה השינוי צריך להיכנס לפני שהוא קורא את ה-diff. הסוכן יכול להכין את הטיוטה, ובעל השינוי בודק שהיא מתארת את מה שקרה בפועל.
כותבים הסבר, לא רשימת קבצים
רשימה כמו "עודכנו שלושה קבצים ונוספו בדיקות" עוזרת להתמצא, אבל משאירה את ההחלטה מחוץ לתמונה. מה הייתה ההתנהגות הבעייתית? למה הפתרון הזה מתאים? מה השתנה עבור מי שמשתמש במערכת?
בתיאור PR טוב אפשר להפריד בין שני דברים: ההחלטה שאפשר לדון בה והקוד שמממש אותה. אם ההחלטה עדיין פתוחה, ציינו זאת. תיאור בטוח בעצמו אינו הופך הנחה להסכמה.
תבנית שאפשר להתחיל ממנה
הטקסט הבא הוא תבנית מוצעת, לא תיאור של PR אמיתי:
הבעיה: מה המשתמש או המערכת אינם יכולים לעשות היום?
ההחלטה: איזה פתרון נבחר, ולמה? איזו חלופה נשקלה ומה הוויתור?
השינוי: מה ההתנהגות החדשה, ואילו רכיבים מושפעים?
גבולות: מה נשאר כפי שהיה ומה במפורש מחוץ לשינוי?
ראיות: אילו בדיקות או תרחישים הורצו בפועל, על איזו גרסה ומה הייתה התוצאה?
סיכונים: מה עלול להישבר, איך נזהה זאת ואיך אפשר לחזור לאחור?
שאלות פתוחות: אילו החלטות או בדיקות עדיין חסרות?
התבנית צריכה להתאים לשינוי. תיקון קטן אינו דורש מסמך ארוך. שינוי בהרשאות, במידע או בממשק חיצוני מצדיק הסבר נוסף גם אם ה-diff קצר.
מבקשים מהסוכן ראיות שאפשר לבדוק
הסוכן יכול לקרוא את ה-diff ואת תוצאות ההרצה ולהציע טיוטה. בקשו ממנו להבדיל בין "הרצתי" לבין "מומלץ להריץ". כל שורה על בדיקה צריכה להתבסס על פלט או תוצאה שאפשר לאתר, לא על רשימת בדיקות שהוא התכוון לבצע.
המחשה: שינוי בטיפול בחשבונית צריך לתאר מה קורה לחשבונית ששולמה בזמן שהעבודה הייתה בתור. פלט של בדיקות יחידה עוזר, אבל אינו מוכיח בפני עצמו שהחיבור לספק התשלומים נבדק. זו דוגמה מוצעת, לא מקרה לקוח.
אם הסוכן השתמש בנתוני בדיקה או בתחליף לשירות, ציינו זאת. אם בדיקת אינטגרציה לא הורצה, השאירו את המגבלה גלויה במקום לכתוב "הכול עובד".
משאירים את האחריות אצל בעל השינוי
לפני פתיחת ה-PR, קראו את התיאור בלי ה-diff. האם אתם יכולים להסביר את ההחלטה במילים שלכם? האם יש טענה שלא בדקתם? האם נשאר סיכון שמישהו אחר צריך להחליט עליו?
הסוכן הוא כותב טיוטה. מי שמביא את השינוי לצוות צריך להחזיק את ההסבר. אם אי אפשר לענות למה נבחר פתרון מסוים, חוזרים לשיחה על ההחלטה ולא מוסיפים עוד מילים לתיאור.
הופכים את התבנית לחלק מהמאגר
לפי תיעוד GitHub, תבנית PR במאגר מוצגת אוטומטית בגוף ה-PR כשפותחים אותו. אפשר לשמור אותה בקובץ .github/pull_request_template.md. כדי להיות זמינה, התבנית צריכה להיות ממוזגת לענף ברירת המחדל. קיימת גם תמיכה בכמה תבניות, כשסוגי השינויים דורשים שאלות שונות.
התבנית מזכירה מה להסביר. היא אינה מוכיחה שההסבר נכון ואינה מחליפה בדיקה או review. בדקו מדי פעם אילו שדות חוזרים על עצמם בלי להוסיף מידע ואילו שאלות חשובות נשארות מחוץ לה.
מתחילים מהחלטה אחת שאפשר לבקר
הצלחה כאן היא שמי שעושה review יכול לזהות את הבעיה, להבין את הבחירה ולמצוא ראיה לבדיקה, בלי לנחש מתוך שמות הקבצים. אם השאלה החשובה עולה רק אחרי קריאת מאות שורות, כדאי להעביר אותה קדימה לתיאור או לדיון שלפני המימוש.
מקורות ופרטים נוספים
ההמלצות הן דרך עבודה מוצעת. ההמחשות מובחנות מטענות על ניסיון ותוצאות בפועל. המקורות הטכניים נבדקו ב-13.10.2026.
שאלות נפוצות
האם הסוכן יכול לכתוב את תיאור ה-PR?
כן, כטיוטה מתוך ה-diff וראיות ההרצה. בעל השינוי בודק את ההחלטות, העובדות ומה שעדיין לא אומת.
מה עושים אם בדיקה לא הורצה?
מציינים שהיא לא הורצה, למה ומה עדיין דורש בדיקה. כוונה להריץ אינה תוצאת בדיקה.
האם צריך תבנית ארוכה לכל שינוי?
מתאימים את ההסבר לסיכון ולמשמעות השינוי. גם PR קטן יכול להשפיע על הרשאות או מידע.