2.4 מצב תכנון הרצאה

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

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

מה זה מצב תכנון - plan mode¶

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

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

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

מתי להשתמש - when to use it¶

לא כל משימה צריכה תכנון. לבקשה קטנה ומוגדרת ("תוסיף בדיקת null בשורה הזאת") מצב תכנון הוא בזבוז זמן. השתמשו בו כשמתקיים אחד מאלה:

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

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

איך נכנסים - entering plan mode¶

יש שתי דרכים עיקריות להיכנס למצב תכנון. הראשונה היא ללחוץ Shift+Tab עד שמגיעים למצב plan (במחזור: default, ואז acceptEdits, ואז plan). המצב הנוכחי מופיע בשורת המצב.

הדרך השנייה היא לקבוע אותו בהפעלה, דרך דגל:

claude --permission-mode plan

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

[plan mode active]

> I want to add support for signing in via OAuth.
  Read src/auth/ and understand how we handle sessions,
  then prepare a plan.

  Read  src/auth/session.py
  Read  src/auth/login.py
  Grep  "session" src/
  ...
  [the agent investigates without editing anything]

שימו לב שהagent מריץ Read ו-Grep - tools של קריאה - אבל שום Edit או Write. זה מצב התכנון בפעולה.

לסקור ולאשר תוכנית - review and approve¶

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

Plan for adding OAuth:

1. Add a dependency on the authlib library to requirements.txt
2. Create src/auth/oauth.py with the OAuth flow
3. Register a new route /auth/callback in src/app.py
4. Extend session.py to store OAuth tokens
5. Add tests in tests/test_oauth.py

How would you like to proceed?
> 1. Approve, and start in auto mode
  2. Approve, and start in acceptEdits mode
  3. Approve, and review every edit manually
  4. Keep planning with feedback

לאישור יש כמה אפשרויות, וההבדל ביניהן הוא באיזה מצב הagent ימשיך אחרי האישור:

אשר והתחל במצב auto - הagent יבצע את התוכנית עם פחות בקשות (בכפוף לבדיקות הבטיחות של auto).
אשר במצב acceptEdits - יבצע ויערוך בלי לשאול על כל עריכה, כך שתסקרו בסוף.
אשר וסקור כל עריכה ידנית - יבצע, אבל יבקש אישור על כל עריכה, כמו במצב Manual.
המשך לתכנן - לא מאשר עדיין; נותן משוב והagent מעדכן את התוכנית.

כשמאשרים, הסשן יוצא ממצב תכנון ועובר למצב שבחרתם, והagent מתחיל לערוך. אם תרצו לתכנן שוב מאוחר יותר, חוזרים למצב תכנון עם Shift+Tab.

לתקן תוכנית לפני שנוגעים בקוד - iterating¶

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

> 4. Keep planning with feedback

> Don't use authlib, we already use requests-oauthlib
  elsewhere in the code. Also add handling for an expired token error.

  [the agent updates the plan based on the feedback]

Updated plan:
1. Use requests-oauthlib (already installed)
2. Create src/auth/oauth.py ...
4. Add token refresh when it expires
...

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

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

1. Shift+Tab until plan mode       -> enter planning
2. Describe the task                -> the agent investigates (read-only)
3. The agent presents a plan        -> review it
4. Feedback and revision (repeats)  -> "keep planning"
5. Approval + choose the follow-up mode -> the agent starts editing
6. Review the edits and verify      -> like a regular session

דוגמה מלאה מקצה לקצה - a worked example¶

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

[Shift+Tab until plan mode]

> I want to add pagination to the GET /users endpoint.
  Investigate how the code is built today and prepare a plan.

  Read  src/routes/users.js
  Read  src/services/userService.js
  Read  src/db/userQueries.js
  Grep  "findAll" src/

  Found it: the route calls userService.getAllUsers, which calls
  userQueries.findAll, which fetches all users in a single query
  with no LIMIT. There's currently no pagination mechanism.

עכשיו הagent מציג תוכנית, ואנחנו סוקרים אותה:

Plan:
1. userQueries.findAll -> add limit and offset parameters to the query
2. userService.getAllUsers -> pass the parameters along,
   and also return the total count
3. The route -> read query params (page, pageSize) and convert to limit/offset
4. Also return total and page in the response so the client knows how many pages there are
5. Add tests for edge cases: first page, last page, page past the end

How would you like to proceed?

נניח שאנחנו רוצים לחדד. במקום לאשר, נבחר "המשך לתכנן" וניתן משוב:

> Don't return total on every request, it's an expensive count query.
  Return it only if the client explicitly asked with ?withTotal=true.

  [the agent updates steps 2 and 4 of the plan]

רק אחרי שהתוכנית נכונה, אנחנו מאשרים - נניח במצב acceptEdits - והagent מבצע את כל חמשת הצעדים ברצף, בזמן שאנחנו סוקרים את התוצאה ב-git diff בסוף. שימו לב מה קרה כאן: תפסנו החלטת עיצוב לא רצויה (שאילתת ספירה יקרה בכל בקשה) לפני שהיא הפכה לקוד. אילו עבדנו בלי תכנון, הagent היה כותב את הקוד עם הספירה, ואנחנו היינו מגלים את הבעיה רק בסקירה, אחרי שכבר נכתבו חמישה קבצים.

מה מצב תכנון הוא לא - common misconceptions¶

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

זה לא "מצב בטוח" כללי: מצב תכנון מונע עריכות של המקור, אבל הוא לא מכבה את מנגנון ההרשאות. אם החקירה דורשת פקודה בעלת השלכות, תישאלו. אל תתייחסו אליו כהיתר לרוץ בלי מחשבה.
זה לא מחליף בקשה טובה: תוכנית טובה מתחילה בבקשה ברורה. אם תיתנו לagent משימה מעורפלת, גם התוכנית תהיה מעורפלת. מצב תכנון מגביר את הערך של בקשה טובה, לא מחליף אותה.
אישור אינו סוף הסיפור: אחרי שאישרתם תוכנית, הagent עדיין יכול להיתקל בהפתעות בביצוע. סקירת העריכות והאימות בסוף חשובים כמו תמיד. התוכנית מקטינה סיכון, לא מבטלת אותו.
אפשר לחזור לתכנן: אם באמצע הביצוע מתברר שהכיוון שגוי, אפשר לעצור (Esc), לחזור למצב תכנון עם Shift+Tab, ולתכנן מחדש. אתם לא נעולים בתוכנית שאישרתם.

לקבוע תכנון כברירת מחדל - default to plan¶

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

{
  "permissions": {
    "defaultMode": "plan"
  }
}

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

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

למה זה עובד טוב - the two-phase advantage¶

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

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

סיכום¶

מצב תכנון הוא מצב הרשאה של קריאה בלבד: הagent חוקר ומרכיב תוכנית, אבל לא עורך את קוד המקור.
בקשות הרשאה עדיין חלות במצב תכנון; ההבטחה הספציפית היא שהמקור לא ישתנה בזמן התכנון.
משתמשים בו כשהמשימה גדולה, מסוכנת, לא מוכרת, או כשלא בטוחים בגישה. ככל שעלות הטעות גבוהה יותר, כך התכנון משתלם יותר.
נכנסים עם Shift+Tab (עד מצב plan) או עם הדגל --permission-mode plan.
כשהתוכנית מוכנה, מאשרים ובוחרים באיזה מצב הagent ימשיך: auto, acceptEdits, או סקירה ידנית - או ממשיכים לתכנן עם משוב.
היכולת המרכזית: לתקן את התוכנית לפני שנוגעים בקוד. כל סבב משוב מתקן רעיון, לא עשרה קבצים. אפשר גם לערוך את התוכנית ישירות עם Ctrl+G.
הגישה הדו-שלבית עובדת כי היא מוסיפה נקודת עצירה אנושית בין הבנה לפעולה, ונותנת לagent מפה ברורה לביצוע.