📘 תיעוד 43

מצב תכנון

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

#מה מצב תכנון עושה

כאשר מצב תכנון פעיל, הסוכן:

1. קורא ומחפש בבסיס הקוד כדי להבין דפוסים וארכיטקטורה קיימים
2. מעצב גישת יישום וכותב אותה לקובץ התוכנית
3. עשוי להשתמש ב-ask_user_question כדי להבהיר שאלות ספציפיות
4. קורא ל-exit_plan_mode כדי להציג את התוכנית לאישורך

מצב תכנון הוא לקריאה בלבד למעט קובץ התוכנית: עריכות של קובץ התוכנית (plan.md בספריית ההפעלה) מאושרות אוטומטית, ועריכות של כל קובץ אחר נדחות באופן מוחלט, קריאת הכלי נכשלת עם הודעה קצרה המציינת את קובץ התוכנית בתור הנתיב היחיד שניתן לעריכה. הדבר תקף בכל מצב הרשאות, כולל always-approve. הפרדת התכנון מהיישום מאפשרת לך לבדוק ולתקן את הגישה לפני שנכתב קוד כלשהו.

#כיצד להיכנס למצב תכנון

#כניסה ביוזמת הסוכן

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

טריגרים טובים למצב תכנון:

• "Add user authentication to the app": עמימות אמיתית (session לעומת JWT, אחסון אסימונים, מבנה middleware)
• "Redesign the data pipeline": ארגון מחדש משמעותי שבו גישה שגויה מבזבזת מאמץ רב
• "Add caching to the API": מספר גישות סבירות (Redis לעומת in-memory לעומת מבוסס קבצים)
• "Add real-time updates": החלטה ארכיטקטונית (WebSockets לעומת SSE לעומת polling)

לא מתאים למצב תכנון:

• "Add a delete button to the user profile": נתיב יישום ברור
• "Fix the typo in the README": פשוט וישיר
• "Update the error handling in the API": התחל לעבוד, שאל שאלות ספציפיות במידת הצורך
• "Can we work on the search feature?": המשתמש רוצה להתחיל לעבוד, לא לתכנן

#כניסה ביוזמת המשתמש

אתה יכול להיכנס למצב תכנון בעצמך בשתי דרכים:

• /plan: כניסה למצב תכנון. מצב תכנון מופעל כאשר אתה שולח את הפרומפט הבא שלך. הרץ /plan <description> כדי להיכנס למצב תכנון ולהתחיל תור עם התיאור הזה בשלב אחד.
• Shift+Tab: מעבר בין מצבי ההפעלה: Normal, לאחר מכן Plan, לאחר מכן Always-approve, ולאחר מכן חזרה ל-Normal. מתוך Normal, לחיצה בודדת מגיעה אל Plan.

לאחר שקיימת תוכנית, הרץ /view-plan (כינויים: /show-plan, /plan-view) כדי לפתוח מחדש את התצוגה המקדימה השמורה שלה.

#קובץ התוכנית

התוכנית נכתבת אל plan.md בתוך ספריית ההפעלה (~/.grok/sessions/<cwd>/<session-id>/plan.md, כאשר <cwd> הוא שם ספרייה מקודד, ולא הנתיב המילולי).

קובץ התוכנית מכיל:

• סעיף Context המסביר מדוע השינוי מבוצע
• הגישה המומלצת (לא כל חלופה)
• הנתיבים של קבצים קריטיים לשינוי
• פונקציות וכלי עזר קיימים לשימוש חוזר, יחד עם נתיבי הקבצים שלהם
• סעיף אימות המתאר כיצד לבדוק את השינויים מקצה לקצה

#אישור התוכנית

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

אם הסוכן יוצא מבלי לכתוב תוכנית (plan.md ריק או חסר), אותו משטח אישור עדיין נפתח עם הודעת מצב ריק ברורה, כך שתוכל לאשר ולהתחיל ביישום, לבקש שינויים (להחזיר את הסוכן לתכנון), או לצאת. במצב מינימלי הודעת המצב הריק נרשמת אל ה-scrollback וכותרת רצועת הפקדים מציגה No plan written yet.

#סקירת התוכנית

גלול את התוכנית באמצעות מקשי החצים או j/k. שורת הפעולות מציגה את קיצורי המקשים הבאים:

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

בזמן שתצוגת אישור התוכנית פתוחה, Ctrl+P (לוח פקודות: command palette → model) עדיין עובד להחלפת מודל לפני שאתה לוחץ על a כדי לאשר.

#מתן משוב

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

• Preview: גלילה בתוכנית ובחירת שורות כדי להעיר עליהן.
• Commenting: הוספת הערה בגוף הטקסט (inline) לטווח השורות שנבחר (לחץ על c, או על Enter בשורה).
• Prompt: הקלדת הערות לתיקון בטקסט חופשי.

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

#עזיבת תצוגת האישור

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

#מחזור החיים של מצב תכנון

למכונת המצבים של מצב תכנון יש ארבעה מצבים:

מעברים:

Inactive    --> Active   (הכלי enter_plan_mode נקרא ואושר, מדלג על Pending)
Inactive    --> Pending  (הפעלת מצב תכנון באמצעות /plan או Shift+Tab)
Pending     --> Active   (הפרומפט הראשון שלך מפעיל את מצב תכנון)
Active      --> Inactive (אישור exit_plan_mode, או כיבוי מצב תכנון במצב סרק)
Active      --> ExitPending (כיבוי מצב תכנון בזמן שתור נמצא בתהליך)
ExitPending --> Inactive (לאחר השלמת התור)

מצב תכנון נשמר בדיסק ושורד הפעלות מחדש של התהליך. מצבים זמניים (Pending, ExitPending) קורסים ל-Inactive בעת הפעלה מחדש, מכיוון שהם תלויים באינטראקציות שנמצאות בתהליך.

#עריכות במהלך מצב תכנון

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

אכיפה זו אינה תלויה במצב ההרשאות:

• always-approve (yolo) נשאר דרוך מתחת למצב תכנון. כלים שאינם כלי עריכה (פקודות bash, קריאות, כלי MCP) עדיין פועלים אוטומטית, אך עריכות קבצים נחסמות עד שתאשר את היציאה ממצב תכנון. ברגע שהתוכנית מאושרת, always-approve מתחדש לצורך היישום.
• פקודות bash אינן נבדקות לאיתור כתיבת קבצים: מצב תכנון חוסם את כלי העריכה, ולא הפניה מחדש של המעטפת (shell redirection).
• תת-סוכנים אינם מכוסים על ידי שער העריכה של מצב תכנון של הפעלת האב. כל תת-סוכן מתחיל עם מעקב מצב תכנון חדש (Inactive), כך שתת-סוכן מסוג general-purpose (או בעל יכולת כתיבה אחרת) יכול לערוך קבצים בזמן שהאב עדיין במצב תכנון, והוא יורש את מצב ההרשאות של האב (כולל always-approve). סוגים לקריאה בלבד כמו explore נשארים מוגבלים על ידי ערכת הכלים שלהם בלבד.

דגל הסטטוס מציג plan כאשר מצב תכנון פעיל. אם always-approve מופעל מתחת, הדגל שלו מופיע שוב כאשר יוצאים ממצב תכנון.

#מצב תכנון ודחיסה

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

#מתי מתאים להשתמש במצב תכנון

השתמש במצב תכנון עבור:

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

דלג על מצב תכנון עבור:

• משימות עם נתיב יישום ברור
• תיקוני באגים שבהם התיקון ברור ברגע שמבינים את הבאג
• הוספת תכונות שעוקבות אחר מוסכמות קיימות
• שינויים פשוטים וישירים (שינוי שמות, עיצוב, הוספת בדיקות)
• משימות מחקר וחקירה (השתמש בתת-סוכנים במקום זאת)